greprag 5.80.0 → 5.82.0

package/dist/commands/repodoc.js

@@ -0,0 +1,433 @@
+"use strict";
+/** `greprag repodoc` — give a repository's own markdown a stable identity that
+ *  survives editing.
+ *
+ *  The problem this solves: greprag's corpus matcher pairs a stored chunk with a
+ *  new one only when they are byte-identical, which is right for a source that
+ *  is re-fetched whole and mostly grows at the end. Repository documents are not
+ *  that. An ADR gains a dated entry, a skill has a paragraph reworded, a design
+ *  doc has a section split in two — and under the corpus matcher every one of
+ *  those looks like a death and a birth. The chunk re-enriches at model cost and
+ *  anything pointing at it dangles.
+ *
+ *  So each document keeps a node graph beside it, under `.greprag/node-identity/`,
+ *  mirroring the tree. `adr/thing.md` gets `.greprag/node-identity/adr/thing.md.json`.
+ *  The graph is committed with the repo, so identity travels across machines and
+ *  through git. The document itself is never written to — its own head stays
+ *  clean, which matters because agents read these files constantly and a
+ *  fifty-entry array at the top of every skill would land in context every time.
+ *
+ *  The matching engine is @greprag/core's node-identity, built into
+ *  dist/node-identity.bundle.js on every CLI build (see
+ *  scripts/bundle-node-identity.mjs) because the CLI cannot import core.
+ *
+ *  Reporting is the default and writing is opt-in. This is the first thing
+ *  greprag writes into a user's own repository, so seeing the change precedes
+ *  making it.
+ *
+ *  adr: adr/node-identity-port.md · docs/node-identity-port.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRepoDoc = runRepoDoc;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const client_1 = require("./corpus/client");
+const repodoc_client_1 = require("../repodoc-client");
+/** Loaded lazily so `--help` works even if the bundle is missing from a partial
+ *  build, and so the failure names the real cause instead of a module error. */
+function engine() {
+    const path = (0, path_1.join)(__dirname, '..', 'node-identity.bundle.js');
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error('node-identity.bundle.js is missing — run `npm run build` in packages/cli ' +
+            '(scripts/bundle-node-identity.mjs produces it from @greprag/core).');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require(path);
+}
+// ---------- repo + file discovery -------------------------------------------
+/** Walk up for the `.git` that marks the repository root. Everything is
+ *  recorded relative to it so a graph means the same thing on any machine. */
+function findRepoRoot(start) {
+    let dir = (0, path_1.resolve)(start);
+    for (;;) {
+        if ((0, fs_1.existsSync)((0, path_1.join)(dir, '.git')))
+            return dir;
+        const parent = (0, path_1.dirname)(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** The repository's name, which decides which store its documents land in.
+ *
+ *  Taken from the COMMON git directory, not the working tree, so a worktree and
+ *  the checkout it was cut from share one store. Cutting a worktree must not
+ *  fork a repository's identity into a second, empty store named after a branch. */
+function repoName(repoRoot) {
+    try {
+        const common = (0, child_process_1.execFileSync)('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+            cwd: repoRoot, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (common)
+            return (0, path_1.basename)((0, path_1.dirname)(common));
+    }
+    catch { /* not a git checkout, or git is absent — fall through */ }
+    return (0, path_1.basename)(repoRoot);
+}
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.greprag']);
+/** Every INDEXABLE markdown file under a path, or the path itself if it is one.
+ *
+ *  Eligibility is `isRepoDocEligible`, the same predicate the Stop hook uses to
+ *  decide what it will keep rebuilt. Anything this command indexes must be
+ *  something the hook will maintain — a document indexed once and never
+ *  refreshed is frozen at whatever it said that day, which is worse than not
+ *  indexing it. That is why the filter lives in one module and not two. */
+function collectMarkdown(target, repoRoot) {
+    if (!(0, fs_1.existsSync)(target))
+        return [];
+    const eligible = (abs) => {
+        const rel = (0, path_1.relative)(repoRoot, abs).split(path_1.sep).join('/');
+        if (!rel || rel.startsWith('..'))
+            return false;
+        if (!(0, repodoc_client_1.isRepoDocEligible)(rel))
+            return false;
+        try {
+            return !(0, repodoc_client_1.isGeneratedAdapter)((0, fs_1.readFileSync)(abs, 'utf-8'));
+        }
+        catch {
+            return false;
+        }
+    };
+    if ((0, fs_1.statSync)(target).isFile())
+        return eligible(target) ? [target] : [];
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of (0, fs_1.readdirSync)(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                    continue;
+                walk((0, path_1.join)(dir, entry.name));
+            }
+            else if (entry.name.endsWith('.md') && eligible((0, path_1.join)(dir, entry.name))) {
+                out.push((0, path_1.join)(dir, entry.name));
+            }
+        }
+    };
+    walk(target);
+    return out;
+}
+function reconcileFile(eng, repoRoot, absPath, write, keepBlocks = false) {
+    const relPath = (0, path_1.relative)(repoRoot, absPath).split(path_1.sep).join('/');
+    const sidecarRel = eng.sidecarPathFor(relPath);
+    const base = {
+        relPath, sidecarPath: sidecarRel || '', blocks: 0, preserved: 0, fresh: 0,
+        orphaned: 0, firstSight: false, changed: false, skipped: false,
+    };
+    if (!sidecarRel) {
+        return { ...base, skipped: true, error: 'path escapes the repository root' };
+    }
+    const body = (0, fs_1.readFileSync)(absPath, 'utf-8');
+    const sidecarAbs = (0, path_1.join)(repoRoot, sidecarRel);
+    let stored = null;
+    let storedText = null;
+    if ((0, fs_1.existsSync)(sidecarAbs)) {
+        storedText = (0, fs_1.readFileSync)(sidecarAbs, 'utf-8');
+        stored = eng.parseNodeGraph(storedText);
+        if (stored === null) {
+            // Unreadable or from a version we do not know. Re-bootstrapping loses id
+            // continuity for this one document but never corrupts it, which is the
+            // right trade — see adr/node-identity-port.md.
+            base.error = 'stored graph unreadable, re-bootstrapping';
+        }
+    }
+    const firstSight = stored === null;
+    const result = eng.reconcile(stored, eng.markdownToBlocks(body), { path: relPath, body });
+    const s = result.match.summary;
+    const outcome = {
+        ...base,
+        blocks: s.totalBlocks,
+        preserved: s.preserved,
+        fresh: s.fresh,
+        orphaned: s.orphanedCount,
+        firstSight,
+        changed: result.changed,
+        ...(keepBlocks ? { resolved: result.blocks } : {}),
+    };
+    if (write && result.changed) {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(sidecarAbs), { recursive: true });
+        (0, fs_1.writeFileSync)(sidecarAbs, eng.serializeNodeGraph(result.graph), 'utf-8');
+    }
+    return outcome;
+}
+// ---------- reporting --------------------------------------------------------
+function pad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+function reportIndex(outcomes, write) {
+    const width = Math.min(60, Math.max(20, ...outcomes.map(o => o.relPath.length)));
+    const interesting = outcomes.filter(o => o.changed || o.skipped || o.error);
+    const quiet = outcomes.length - interesting.length;
+    for (const o of interesting) {
+        if (o.skipped) {
+            console.log(`  skip  ${pad(o.relPath, width)}  ${o.error}`);
+            continue;
+        }
+        const detail = o.firstSight
+            ? `${o.blocks} blocks, first sight`
+            : `${o.blocks} blocks · kept ${o.preserved} · new ${o.fresh} · gone ${o.orphaned}`;
+        console.log(`  ${write ? 'wrote' : 'would'} ${pad(o.relPath, width)}  ${detail}${o.error ? `  (${o.error})` : ''}`);
+    }
+    if (quiet > 0) {
+        console.log(`  ${quiet} unchanged (no graph written)`);
+    }
+    const totals = outcomes.reduce((acc, o) => ({
+        files: acc.files + (o.skipped ? 0 : 1),
+        blocks: acc.blocks + o.blocks,
+        preserved: acc.preserved + o.preserved,
+        fresh: acc.fresh + o.fresh,
+        orphaned: acc.orphaned + o.orphaned,
+        changed: acc.changed + (o.changed ? 1 : 0),
+    }), { files: 0, blocks: 0, preserved: 0, fresh: 0, orphaned: 0, changed: 0 });
+    console.log('');
+    console.log(`  ${totals.files} files · ${totals.blocks} blocks · ` +
+        `kept ${totals.preserved} · new ${totals.fresh} · gone ${totals.orphaned}`);
+    if (!write) {
+        console.log(`  ${totals.changed} graph${totals.changed === 1 ? '' : 's'} would be written under .greprag/node-identity/`);
+        console.log('  nothing was written — pass --write to persist');
+    }
+    else {
+        console.log(`  ${totals.changed} graph${totals.changed === 1 ? '' : 's'} written under .greprag/node-identity/`);
+    }
+}
+// ---------- push --------------------------------------------------------------
+/** One request carries at most this many documents; the server caps at the same
+ *  number. A repository of any size is therefore several requests. */
+const DOCS_PER_REQUEST = 100;
+/** Ship resolved blocks to the repodoc store.
+ *
+ *  The ids travel with the blocks. That is the whole point: every other ingest
+ *  path re-derives identity server-side with the byte-identical matcher, which
+ *  would throw away what the graph in this repository already settled. */
+async function pushDocuments(outcomes, project, all) {
+    const cfg = (0, client_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, client_1.abortNotConfigured)();
+    const candidates = outcomes.filter(o => !o.skipped && o.resolved && o.resolved.length > 0);
+    if (candidates.length === 0) {
+        console.log('  nothing to push');
+        return null;
+    }
+    // Ship what actually needs shipping. A document whose graph did not move and
+    // whose chunks the store already holds would be deleted and re-inserted
+    // byte-for-byte — pushing a whole repository would rewrite every row on every
+    // run. `changed` covers edits; the store listing covers a document that was
+    // reconciled on an earlier run but never made it into the store (an
+    // interrupted push, or a graph written by `index` before the first push).
+    let shippable = candidates;
+    let skipped = 0;
+    if (!all) {
+        let stored = new Set();
+        try {
+            const listing = await (0, client_1.apiGet)(`${cfg.apiUrl}/v1/repodoc/${encodeURIComponent(project)}`, cfg.apiKey);
+            stored = new Set(listing.documents.map(d => d.path));
+        }
+        catch {
+            // Cannot tell what the store holds — ship everything rather than guess.
+            stored = new Set();
+        }
+        shippable = candidates.filter(o => o.changed || !stored.has(o.relPath));
+        skipped = candidates.length - shippable.length;
+    }
+    if (shippable.length === 0) {
+        console.log(`  nothing to push — all ${candidates.length} documents are already stored and unchanged`);
+        return { storeName: '', inserted: 0, replaced: 0, documents: 0, skipped };
+    }
+    let storeName = '';
+    let inserted = 0;
+    let replaced = 0;
+    for (let start = 0; start < shippable.length; start += DOCS_PER_REQUEST) {
+        const batch = shippable.slice(start, start + DOCS_PER_REQUEST);
+        const res = await (0, client_1.apiCall)(`${cfg.apiUrl}/v1/repodoc/${encodeURIComponent(project)}`, cfg.apiKey, {
+            documents: batch.map(o => ({
+                path: o.relPath,
+                blocks: (o.resolved || []).map(b => ({
+                    id: b.id,
+                    position: b.position,
+                    type: b.type,
+                    text: b.text,
+                    parentPosition: b.parentPosition,
+                    ordinalInParent: b.ordinalInParent,
+                    ...(b.level !== undefined ? { level: b.level } : {}),
+                    ...(b.language !== undefined ? { language: b.language } : {}),
+                    headingPath: b.headingPath,
+                })),
+            })),
+        });
+        storeName = res.storeName;
+        inserted += res.totals.inserted;
+        replaced += res.totals.replaced;
+        console.log(`  pushed ${Math.min(start + batch.length, shippable.length)}/${shippable.length} documents`);
+    }
+    return { storeName, inserted, replaced, documents: shippable.length, skipped };
+}
+function reportStatus(outcomes) {
+    const tracked = outcomes.filter(o => !o.firstSight && !o.skipped);
+    const untracked = outcomes.filter(o => o.firstSight && !o.skipped);
+    const stale = tracked.filter(o => o.changed);
+    console.log(`  tracked    ${tracked.length}`);
+    console.log(`  untracked  ${untracked.length}${untracked.length ? '  (run `greprag repodoc index <path> --write`)' : ''}`);
+    console.log(`  stale      ${stale.length}${stale.length ? '  (edited since their graph was written)' : ''}`);
+    for (const o of stale.slice(0, 20)) {
+        console.log(`             ${o.relPath}  kept ${o.preserved} · new ${o.fresh} · gone ${o.orphaned}`);
+    }
+    if (stale.length > 20)
+        console.log(`             … and ${stale.length - 20} more`);
+}
+// ---------- entry ------------------------------------------------------------
+const HELP = `
+greprag repodoc — stable identity for a repository's own markdown
+
+  Each document keeps a node graph under .greprag/node-identity/, mirroring the
+  tree, committed alongside the repo. Blocks keep their ids through edits,
+  splits, merges, moves, retypes and paste-backs, so re-indexing an edited
+  document costs only the genuinely new content. The documents themselves are
+  never modified.
+
+Usage
+  greprag repodoc index <path>... [--write]   reconcile documents against their graphs
+  greprag repodoc push <path>...              reconcile, write the graphs, and store the chunks
+  greprag repodoc status <path>...            what is tracked, untracked, or stale
+  greprag repodoc list                        what the store currently holds
+
+Search what you have pushed with the ordinary corpus search:
+  greprag corpus search "<query>" --kind repodoc
+
+Options
+  --write            persist the graphs. index only; push always writes them,
+                     because chunks whose graph was not saved would be re-minted
+                     with different ids on the next push.
+  --root <dir>       repository root. Defaults to the nearest ancestor with .git.
+  --project <name>   store name. Defaults to the repository's own name, taken
+                     from the common git directory so a worktree shares the
+                     checkout's store rather than forking a new one.
+  --all              push every document, not only the ones whose graph moved or
+                     that the store does not hold yet. Rarely needed.
+
+Examples
+  greprag repodoc index adr                   see what indexing the ADRs would do
+  greprag repodoc index adr --write           write their graphs
+  greprag repodoc push adr                    write the graphs and store the chunks
+  greprag repodoc status adr docs             what has drifted since last time
+`;
+async function runRepoDoc(args) {
+    const fail = (message) => {
+        console.error(message);
+        process.exitCode = 1;
+    };
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        console.log(HELP.trim());
+        return;
+    }
+    if (sub !== 'index' && sub !== 'status' && sub !== 'push' && sub !== 'list') {
+        return fail(`unknown subcommand "${sub}". Try: greprag repodoc --help`);
+    }
+    const rest = args.slice(1);
+    // push always writes the graphs. Storing chunks whose graph was not saved
+    // would make the next push re-bootstrap and mint different ids for the same
+    // prose — the exact churn this system exists to prevent.
+    const write = rest.includes('--write') || sub === 'push';
+    const rootFlag = rest.indexOf('--root');
+    const rootArg = rootFlag >= 0 ? rest[rootFlag + 1] : undefined;
+    const projectFlag = rest.indexOf('--project');
+    const projectArg = projectFlag >= 0 ? rest[projectFlag + 1] : undefined;
+    const valueFlagIndexes = new Set([rootFlag, projectFlag].filter(i => i >= 0).map(i => i + 1));
+    const targets = rest.filter((a, i) => !a.startsWith('--') && !valueFlagIndexes.has(i));
+    if (sub === 'list') {
+        const cfg = (0, client_1.getConfig)();
+        if (!cfg.apiKey)
+            (0, client_1.abortNotConfigured)();
+        const root = rootArg ? (0, path_1.resolve)(rootArg) : findRepoRoot(process.cwd());
+        const project = projectArg || (root ? repoName(root) : (0, path_1.basename)(process.cwd()));
+        try {
+            const res = await (0, client_1.apiGet)(`${cfg.apiUrl}/v1/repodoc/${encodeURIComponent(project)}`, cfg.apiKey);
+            console.log(`\n${res.storeName} — ${res.totals.documents} documents · ${res.totals.nodes} chunks · ${res.totals.words} words\n`);
+            for (const d of res.documents) {
+                console.log(`  ${pad(d.path, 52)} ${String(d.nodes).padStart(5)} chunks`);
+            }
+            console.log('');
+        }
+        catch (err) {
+            return fail(String(err instanceof Error ? err.message : err));
+        }
+        return;
+    }
+    if (targets.length === 0) {
+        return fail('name at least one file or directory. Try: greprag repodoc --help');
+    }
+    const repoRoot = rootArg ? (0, path_1.resolve)(rootArg) : findRepoRoot((0, path_1.resolve)(targets[0]));
+    if (!repoRoot) {
+        return fail('could not find a repository root (no .git above the target). Pass --root.');
+    }
+    const files = [];
+    for (const t of targets) {
+        const found = collectMarkdown((0, path_1.resolve)(t), repoRoot);
+        if (found.length === 0)
+            console.error(`  nothing indexable under ${t}`);
+        files.push(...found);
+    }
+    if (files.length === 0)
+        return fail('nothing indexable found under any target.');
+    let eng;
+    try {
+        eng = engine();
+    }
+    catch (err) {
+        return fail(String(err instanceof Error ? err.message : err));
+    }
+    console.log(`\nrepodoc ${sub} — ${files.length} document${files.length === 1 ? '' : 's'} under ${repoRoot}\n`);
+    const outcomes = [];
+    for (const file of files) {
+        try {
+            // `status` never writes, whatever flags were passed. `push` keeps the
+            // resolved blocks so it can ship them without walking anything twice.
+            outcomes.push(reconcileFile(eng, repoRoot, file, sub !== 'status' && write, sub === 'push'));
+        }
+        catch (err) {
+            outcomes.push({
+                relPath: (0, path_1.relative)(repoRoot, file).split(path_1.sep).join('/'),
+                sidecarPath: '', blocks: 0, preserved: 0, fresh: 0, orphaned: 0,
+                firstSight: false, changed: false, skipped: true,
+                error: String(err instanceof Error ? err.message : err),
+            });
+        }
+    }
+    if (sub === 'status') {
+        reportStatus(outcomes);
+    }
+    else {
+        reportIndex(outcomes, write);
+    }
+    if (sub === 'push') {
+        const project = projectArg || repoName(repoRoot);
+        console.log('');
+        try {
+            const pushed = await pushDocuments(outcomes, project, rest.includes('--all'));
+            if (pushed && pushed.documents > 0) {
+                console.log('');
+                console.log(`  ${pushed.documents} documents → ${pushed.storeName}: ` +
+                    `${pushed.inserted} chunks stored, ${pushed.replaced} replaced` +
+                    (pushed.skipped ? `, ${pushed.skipped} unchanged and skipped` : ''));
+                console.log(`  search them: greprag corpus search "<query>" --kind repodoc`);
+            }
+        }
+        catch (err) {
+            console.log('');
+            return fail(`  push failed: ${String(err instanceof Error ? err.message : err)}`);
+        }
+    }
+    console.log('');
+    if (outcomes.some(o => o.skipped))
+        process.exitCode = 1;
+}

package/dist/commands/search.js

@@ -0,0 +1,149 @@
+"use strict";
+/** greprag search — one lexical search across everything greprag holds.
+ *
+ *  The engine for this already existed, reachable only as
+ *  `greprag corpus search "<q>" --all`. Nothing about it was corpus-specific,
+ *  and nobody would guess to look there, so it went unused. This is the front
+ *  door: no flags needed, and the default scope is every store holding
+ *  retrievable prose — reference banks, repo markdown, skills, episodic memory.
+ *
+ *  Queues and registries are excluded by the server (SEARCHABLE_KINDS in
+ *  @greprag/core). Name a kind explicitly to reach one.
+ *
+ *  adr: adr/searchable-store-kinds.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSearch = runSearch;
+const client_1 = require("./corpus/client");
+const VALUE_FLAGS = new Set(['--limit', '--kind', '--store', '--tag', '--section', '--rerank-model']);
+const USAGE = `Usage: greprag search "<query>" [options]
+
+  Searches everything: reference banks, repo markdown, skills, episodic memory.
+
+  --limit N        results to return (default 8)
+  --kind K         only stores of this kind (repodoc, docs, memory, skill, ...)
+  --store REF      only this store; repeatable
+  --tag T          only stores carrying this tag
+  --section "H"    only chunks under this heading
+  --json           machine-readable output
+  --rerank         opt-in LLM relevance rerank (costs money; off by default)
+
+  greprag search "how do deploy locks work"
+  greprag search "secure enclave" --kind repodoc
+  greprag search "watcher arm check" --kind memory --limit 15`;
+/** Where a hit came from, in words rather than store-naming conventions. The
+ *  point of one search over everything is knowing which body answered. */
+function sourceLabel(storeName, kind) {
+    if (kind === 'repodoc')
+        return storeName.replace(/^repodoc:/, 'repo ');
+    if (kind === 'memory')
+        return 'memory';
+    if (kind === 'skill')
+        return storeName.replace(/^skill:(global:|project:[^:]+:)?/, 'skill ');
+    if (storeName.startsWith('docmirror:'))
+        return 'project docs';
+    return storeName;
+}
+const scoreTag = (n) => n.confidence != null && Number.isFinite(n.confidence)
+    ? `conf=${n.confidence.toFixed(2)}`
+    : `score=${n.score.toFixed(3)}`;
+async function runSearch(args) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+        console.log(USAGE);
+        return;
+    }
+    const cfg = (0, client_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, client_1.abortNotConfigured)();
+    const json = args.includes('--json');
+    const rerank = args.includes('--rerank');
+    const rerankModel = (0, client_1.getFlag)(args, '--rerank-model');
+    const limit = parseInt((0, client_1.getFlag)(args, '--limit') || '8', 10);
+    const kind = (0, client_1.getFlag)(args, '--kind');
+    const tag = (0, client_1.getFlag)(args, '--tag');
+    const section = (0, client_1.getFlag)(args, '--section');
+    const storeRefs = (0, client_1.getFlags)(args, '--store');
+    const queryText = (0, client_1.extractPositionals)(args, VALUE_FLAGS)[0];
+    if (!queryText) {
+        console.error(USAGE);
+        process.exit(1);
+    }
+    if (!Number.isFinite(limit) || limit < 1) {
+        console.error('--limit must be a positive number.');
+        process.exit(1);
+    }
+    // Scope. Nothing named = every searchable store, decided server-side so the
+    // CLI never has to carry its own copy of which kinds hold prose.
+    let storeIds;
+    if (storeRefs.length > 0) {
+        storeIds = [];
+        for (const ref of storeRefs)
+            storeIds.push((await (0, client_1.resolveStore)(ref, cfg.apiUrl, cfg.apiKey)).id);
+    }
+    else if (kind || tag) {
+        const params = new URLSearchParams();
+        if (kind)
+            params.set('kind', kind);
+        if (tag)
+            params.set('tag', tag);
+        const list = await (0, client_1.apiGet)(`${cfg.apiUrl}/v1/stores?${params.toString()}`, cfg.apiKey);
+        storeIds = list.stores.map(s => s.id);
+        if (storeIds.length === 0) {
+            console.error(`Nothing to search${kind ? ` with kind "${kind}"` : ''}${tag ? ` tagged "${tag}"` : ''}.`);
+            process.exit(1);
+        }
+    }
+    const body = {
+        queries: [queryText], limit, adjacencyWindow: 3, adjacencyAlpha: 0.3,
+    };
+    if (storeIds)
+        body.storeIds = storeIds;
+    if (section)
+        body.filters = { section };
+    if (rerank) {
+        body.rerank = true;
+        if (rerankModel)
+            body.rerankModel = rerankModel;
+    }
+    const t0 = Date.now();
+    const result = await (0, client_1.apiCall)(`${cfg.apiUrl}/v1/search`, cfg.apiKey, body);
+    if (!result.ok || !result.nodes)
+        throw new Error(result.error || 'search failed');
+    const ms = Date.now() - t0;
+    // Store names for labeling. One listing call covers every hit.
+    const list = await (0, client_1.apiGet)(`${cfg.apiUrl}/v1/stores`, cfg.apiKey);
+    const byId = new Map(list.stores.map(s => [s.id, s]));
+    if (json) {
+        console.log(JSON.stringify({
+            ok: true, query: queryText, latencyMs: ms, reranked: !!result.reranked,
+            hits: result.nodes.map(n => {
+                const s = byId.get(n.storeId);
+                return {
+                    nodeId: n.nodeId, storeId: n.storeId,
+                    store: s?.name ?? n.storeId, kind: s?.kind ?? null,
+                    source: sourceLabel(s?.name ?? n.storeId, s?.kind ?? ''),
+                    score: n.score, confidence: n.confidence ?? null,
+                    headingPath: n.headingPath ?? [], content: n.content,
+                };
+            }),
+        }, null, 2));
+        return;
+    }
+    const scope = storeIds ? `${storeIds.length} store${storeIds.length === 1 ? '' : 's'}` : 'everything';
+    const rerankTag = result.reranked ? ' · reranked' : (rerank ? ' · rerank unavailable, lexical only' : '');
+    console.log(`\nSearch (${scope}) <- "${queryText}"${rerankTag}`);
+    console.log(`  ${result.nodes.length} hit${result.nodes.length === 1 ? '' : 's'} in ${ms}ms\n`);
+    if (result.nodes.length === 0) {
+        console.log('  Nothing matched. Every word has to appear in the same chunk —');
+        console.log('  try fewer words, or quote a phrase.\n');
+        return;
+    }
+    for (const n of result.nodes) {
+        const s = byId.get(n.storeId);
+        const source = sourceLabel(s?.name ?? n.storeId.slice(0, 8), s?.kind ?? '');
+        const heading = n.headingPath?.length ? ` · ${n.headingPath.join(' / ')}` : '';
+        const snippet = n.content.length > 240 ? n.content.slice(0, 237) + '...' : n.content;
+        console.log(`  [${source} · ${n.nodeId}] ${scoreTag(n)}${heading}`);
+        console.log(`    ${snippet.replace(/\n/g, ' ')}\n`);
+    }
+}