{"id":50216300,"url":"https://github.com/rogerchappel/airgapquery","last_synced_at":"2026-05-26T09:04:29.018Z","repository":{"id":355522675,"uuid":"1228287593","full_name":"rogerchappel/airgapquery","owner":"rogerchappel","description":"Local-first document inspection and retrieval smoke tests for air-gapped QA workflows.","archived":false,"fork":false,"pushed_at":"2026-05-18T19:14:24.000Z","size":61,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T21:23:40.933Z","etag":null,"topics":["airgap","cli","fixtures","local-first","offline","privacy","rag","retrieval","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rogerchappel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-03T20:49:36.000Z","updated_at":"2026-05-18T19:12:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rogerchappel/airgapquery","commit_stats":null,"previous_names":["rogerchappel/airgapquery"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rogerchappel/airgapquery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Fairgapquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Fairgapquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Fairgapquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Fairgapquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rogerchappel","download_url":"https://codeload.github.com/rogerchappel/airgapquery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerchappel%2Fairgapquery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33512343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["airgap","cli","fixtures","local-first","offline","privacy","rag","retrieval","typescript"],"created_at":"2026-05-26T09:04:12.401Z","updated_at":"2026-05-26T09:04:29.011Z","avatar_url":"https://github.com/rogerchappel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# airgapquery\n\nPrivacy-first offline document inspection and retrieval smoke tests for developers and agents.\n\n`airgapquery` is a tiny TypeScript CLI/library for answering one practical question before you trust a document-QA stack with private files: **can the local ingestion and retrieval path run with no hidden network calls?**\n\nIt does not call LLM APIs, run embeddings, send telemetry, crawl credentials, or publish anything. The MVP uses deterministic token scoring over local text fixtures so it is easy to inspect, test, and replace.\n\n## Why this exists\n\nAir-gapped RAG demos often hide the boring-but-critical parts: what files were read, what was skipped, and whether the smoke test can run after egress is blocked. `airgapquery` keeps V1 deliberately small:\n\n- inspect a local folder of text documents;\n- chunk and tokenize supported files deterministically;\n- query the local chunks with transparent scores and citations;\n- emit JSON or Markdown evidence for review;\n- provide fixture-backed tests and a real CLI smoke.\n\nInspired by the public `airgapped-offfline-rag` idea noted in [docs/PRD.md](docs/PRD.md), but this repository is an original TypeScript implementation with a narrower local-first verification focus.\n\n## Install\n\n```sh\nnpm install\nnpm run build\n```\n\nFor local CLI development:\n\n```sh\nnpm link\nairgapquery --help\n```\n\nOr run directly from the repo after building:\n\n```sh\nnode dist/src/cli.js --help\n```\n\n## Quickstart\n\nInspect the included fixture corpus:\n\n```sh\nnpm run build\nnode dist/src/cli.js inspect fixtures/sample --format markdown\n```\n\nWrite a JSON evidence report:\n\n```sh\nnode dist/src/cli.js inspect fixtures/sample --format json --output out/inspect.json\n```\n\nAsk a local-only retrieval question:\n\n```sh\nnode dist/src/cli.js query fixtures/sample \\\n  --question \"How do agents prove there are no hidden network calls?\" \\\n  --format markdown \\\n  --top 3\n```\n\nExample output includes the cited file path, line range, matched terms, score, and chunk excerpt.\n\n## CLI\n\n```text\nairgapquery inspect \u003cdirectory\u003e [--format json|markdown] [--output \u003cfile\u003e]\nairgapquery query \u003cdirectory\u003e --question \u003ctext\u003e [--top \u003cn\u003e] [--format json|markdown]\n```\n\nUseful options:\n\n- `--max-chunk-chars \u003cn\u003e`: cap chunk size for deterministic retrieval.\n- `--max-file-bytes \u003cn\u003e`: skip unexpectedly large files.\n- `--extensions \u003clist\u003e`: comma-separated allow-list such as `md,txt,json`.\n- `--include-hidden`: include dotfiles and hidden directories; off by default.\n\n## Library\n\n```ts\nimport { buildIndex, queryIndex, renderQueryMarkdown } from \"airgapquery\";\n\nconst index = await buildIndex({ rootDir: \"fixtures/sample\" });\nconst response = queryIndex(index, \"What evidence is required?\", 3);\nconsole.log(renderQueryMarkdown(response));\n```\n\n## Safety boundaries\n\n`airgapquery` is intentionally boring:\n\n- reads only files under the directory you pass;\n- skips hidden paths unless `--include-hidden` is set;\n- limits supported extensions and maximum file size;\n- performs no runtime network calls, telemetry, model calls, credential discovery, or publishing;\n- produces deterministic JSON/Markdown evidence you can diff in review.\n\nIt does **not** prove your whole machine is air-gapped. Use host controls such as firewall rules, VM networking, or physical disconnection when you need hard egress guarantees.\n\n## Verify\n\n```sh\nnpm test\nnpm run check\nnpm run build\nnpm run smoke\nbash scripts/validate.sh\n```\n\nA real fixture CLI smoke used during development:\n\n```sh\nnode dist/src/cli.js query fixtures/sample \\\n  --question \"What safety evidence blocks hidden network calls?\" \\\n  --format json \\\n  --top 3\n```\n\n## Project status\n\nMVP. The current scope is deterministic fixture-backed inspection/query and practical safety documentation. Future versions may add pluggable embedding backends, but local-only defaults and explicit network boundaries should remain non-negotiable.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Keep changes small, test with local fixtures, and avoid adding runtime network behavior without an explicit design discussion.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md). Please do not post sensitive corpus examples or vulnerability details publicly.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogerchappel%2Fairgapquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frogerchappel%2Fairgapquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogerchappel%2Fairgapquery/lists"}