fix(knowledge-base): expand ~ in --knowledge-base paths

[rohanpoudel2]

Fixes #247

Problem

prepareKnowledgeBase() resolves each requested path with no home expansion:

const path = resolve(requested);

so a literal ~ is treated as a directory segment under the current working directory and the scan fails before any work starts. Calling prepareKnowledgeBase(["~/docs"]) from the package root, with a real ~/docs containing one Markdown file:

ERR  ~/docs -> ENOENT: no such file or directory, lstat '<repo>/sdk/typescript/~/docs'
OK   <home>/docs -> sources=["<home>/docs"]

A bare ~/docs on the command line is expanded by the shell, so this hides until the value arrives from somewhere that does not do word expansion: a quoted argument, a config file, a CI variable, a Makefile.

Change

One line, at the point where the path is resolved:

const path = resolve(expandHome(requested));

reusing the exported expandHome from src/runtime.ts — the same helper --plugin-path, --python and --output-dir go through, including its ~\ handling for Windows. No new helper, and no import cycle: src/runtime.ts does not import src/knowledge-base.ts, and src/api.ts already imports both.

Why not expand at the CLI option boundary

The repo's convention for path options is to expand inside the consuming function, not in src/cli.ts: --plugin-path expands in resolvePluginPath, --python in usablePython, --output-dir in validateOutputDir. Expanding at the CLI boundary would also have to be done twice, because — contrary to the issue's "bulk-scan has no --knowledge-base option at all" — it does have one, and it reaches the same function.

bulk-scan is covered by this one-line change. The full chain, read from the code on this branch: src/cli.ts:1281 defines the option, src/cli.ts:1405 passes it to runMultiscan on both the CSV and the wizard branch, src/multiscan.ts:185 forwards it verbatim into each per-repository security.run, and src/api.ts:385 calls prepareKnowledgeBase. Nothing in between re-resolves or validates the strings, and src/api.ts:385 is the only prepareKnowledgeBase call site in src/. Each link already has a test. tests-ts/cli.test.ts:663 drives the real main() with bulk-scan repositories.csv --output-dir results --knowledge-base /shared/architecture.pdf --knowledge-base=/shared/threat-models and asserts the per-repository scan options carry both values verbatim, through the real runMultiscan; tests-ts/multiscan.test.ts:359 and :480 pin the same forwarding directly; and the new test below covers the expansion itself. Fixing the shared callee covers scan, bulk-scan, and SDK callers passing knowledgeBasePaths directly.

The third producer is scan-recipe replay, and expansion there is a verified no-op. src/api.ts:615 builds the recipe from knowledgeBase?.sources, which are realpath() results and therefore absolute; expandHome returns any value not equal to ~ and not starting with ~/ or ~\ unchanged, which I confirmed by running it over absolute inputs including /Users/someone/~docs and /Users/someone/docs/~/nested.

Why not mutate process.env.HOME in the test

os.homedir() does not re-read a live-mutated HOME in-process under Bun; I measured it — setting process.env.HOME and calling homedir() in the same test returns the unchanged real home. The test stubs node:os with mock.module instead.

That stub needs care. mock.module hot-swaps the live node:os namespace object, so restoring with mock.module("node:os", () => os) re-installs the already-mocked homedir and leaves it mocked for the rest of the bun process — measured: after that "restore", homedir() still returns the stub, and a second test file loaded afterwards sees the stub too. The test therefore snapshots the original exports before the first mock, restores from the snapshot, and asserts os.homedir() is back to the real value.

Impact, stated plainly

--knowledge-base ~/docs (quoted, or supplied by anything other than a shell) now reads <home>/docs instead of failing with ENOENT, for scan and for bulk-scan alike. Absolute and ordinary relative paths resolve exactly as before, and the symlink, extension, permission and extraction checks are untouched — only the string handed to resolve() changes.

~other/docs is deliberately not expanded: there is no portable way to resolve another account's home from Node, so it stays a literal path segment under the working directory and fails with ENOENT naming ~other. That matches every other path option in the repo.

One behavior change worth naming: a relative path whose first segment is literally ~, i.e. an actual directory named ~ in the working directory, is now read as the home directory. That is the same trade the other path options already made, and such a directory is almost always the residue of this bug rather than something intentional.

scan --dry-run still echoes --knowledge-base values unexpanded, because preflight() returns options.knowledgeBasePaths verbatim (src/api.ts:312) and never calls prepareKnowledgeBase. That is pre-existing — a dry run has never validated knowledge-base paths — and is left alone rather than widened into this PR.

Recipe replay, scan --path, and the bulk-scan positional/--output-dir arguments are unchanged by this PR.

Verification

One test in tests-ts/knowledge-base.test.ts covering ~/docs, bare ~, an absolute path, and the unexpanded ~other/docs, with node:os restored from a pre-mock snapshot and the restore asserted.

• With the fix: 774 pass / 5 skip / 0 fail (779 across 34 files, 5543 expect() calls), bun test --timeout 30000 ./tests-ts.
• Without the fix (expansion and its import both removed): 773 pass / 5 skip / 1 fail — only the new test, with the ENOENT above.
• Without the restore fix alone (both mock.module calls pointed back at the live namespace): 7 pass / 1 fail in tests-ts/knowledge-base.test.ts, on expect(os.homedir()).toBe(realHomeDirectory) receiving the deleted temporary home.
• pnpm --dir sdk/typescript run types (generate:models --check plus tsc --noEmit) exits 0, and pnpm --dir sdk/typescript run format reports all matched files use Prettier code style.