@opencodehub/cli 0.1.0

package/dist/commands/code-pack.js

@@ -0,0 +1,187 @@
+/**
+ * `codehub code-pack [path]` — produce the deterministic 9-item BOM via
+ * `@opencodehub/pack`.
+ *
+ * Output goes to `<repo>/.codehub/packs/<packHash>/` so a pack's identity
+ * is encoded in its on-disk path. The function writes to a temp directory
+ * first, then renames into place once the manifest's `packHash` is known
+ * — this keeps the path-includes-hash invariant without requiring
+ * `generatePack` to know its own hash up front.
+ *
+ * Two engines are supported via the `--engine` flag:
+ *   - `pack` (DEFAULT) — `@opencodehub/pack`'s `generatePack`. Opens a
+ *     read-only graph store via `openStore({ readOnly: true })` and walks
+ *     the indexed graph to produce the 8 mandatory BOM items + manifest +
+ *     optional Parquet embeddings sidecar. The sidecar emitter lives in
+ *     `@opencodehub/pack`; cli/ passes the composed `Store` and pack
+ *     dispatches on `store.backend` (DuckDB COPY for `duck`, degraded
+ *     stamp for `lbug` v1).
+ *   - `repomix` — legacy single-file snapshot via `npx repomix`. Retained
+ *     under an opt-in flag for one milestone before removal. Internally
+ *     delegates to `runPack` so the repomix shell-out is implemented
+ *     exactly once.
+ *
+ * The CLI surface is:
+ *
+ *   codehub code-pack [path]
+ *     [--budget <N>]        token budget (default 100_000)
+ *     [--tokenizer <ID>]    "<vendor>:<name>@<pin>" (default openai:o200k_base@tiktoken-0.8.0)
+ *     [--out-dir <DIR>]     overrides the .codehub/packs/<packHash>/ default
+ *     [--engine pack|repomix]  default "pack"
+ *
+ * Exits non-zero on missing index (the pack engine requires `codehub
+ * analyze` to have already populated the graph store).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rename, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { generatePack } from "@opencodehub/pack";
+import { openStore, resolveDbPath } from "@opencodehub/storage";
+import { runPack } from "./pack.js";
+/** Default token budget when `--budget` is omitted. */
+export const DEFAULT_BUDGET_TOKENS = 100_000;
+/** Default tokenizer identifier when `--tokenizer` is omitted. */
+export const DEFAULT_TOKENIZER_ID = "openai:o200k_base@tiktoken-0.8.0";
+/** Default engine when `--engine` is omitted — the new `@opencodehub/pack` BOM. */
+export const DEFAULT_ENGINE = "pack";
+export async function runCodePack(args = {}) {
+    const repoPath = resolve(args.repo ?? process.cwd());
+    const engine = args.engine ?? DEFAULT_ENGINE;
+    if (engine === "repomix") {
+        return runRepomixEngine(repoPath, args);
+    }
+    return runPackEngine(repoPath, args);
+}
+async function runPackEngine(repoPath, args) {
+    const budget = args.budget ?? DEFAULT_BUDGET_TOKENS;
+    const tokenizer = args.tokenizer ?? DEFAULT_TOKENIZER_ID;
+    const generate = args._generatePack ?? generatePack;
+    // Production: open a read-only graph store via the backend-agnostic
+    // factory; tests inject `_store` to skip the native binding entirely.
+    const dbPath = resolveDbPath(repoPath);
+    if (args._store === undefined && !existsSync(dbPath)) {
+        throw new Error(`codehub code-pack: no graph index at ${dbPath}. ` +
+            "Run `codehub analyze` first to populate the store.");
+    }
+    const ownsStore = args._store === undefined;
+    // Composed-store envelope used only when this command owns lifecycle.
+    // Holds it here so the finally block can close graph + temporal in
+    // deterministic order without re-running the factory.
+    const owned = ownsStore
+        ? await (async () => {
+            const composed = await openStore({ path: dbPath, backend: "auto", readOnly: true });
+            await composed.graph.open();
+            return composed;
+        })()
+        : undefined;
+    // generatePack consumes `Store` (= `OpenStoreResult`) so the
+    // embeddings sidecar can dispatch on `store.backend`. Tests
+    // historically passed an `IGraphStore` stub via `_store`; route that
+    // through the `internal.graphOnly` seam which auto-wraps it into a
+    // no-op-temporal Store with `backend: "duck"` (the sidecar then
+    // resolves to absent unless the stub duck-types
+    // `exportEmbeddingsParquet` itself).
+    const composedStore = isStoreShape(args._store)
+        ? args._store
+        : (owned ?? undefined);
+    const graphOnlyStub = isStoreShape(args._store)
+        ? undefined
+        : args._store;
+    // Stage in a temp dir; we don't know `packHash` until generatePack returns,
+    // and the canonical layout puts the hash in the directory name.
+    const stagingDir = await mkdtemp(join(tmpdir(), "codehub-code-pack-"));
+    try {
+        const manifest = await generate({
+            repoPath,
+            outDir: stagingDir,
+            budgetTokens: budget,
+            tokenizerId: tokenizer,
+        }, composedStore !== undefined
+            ? { store: composedStore }
+            : { graphOnly: graphOnlyStub });
+        const finalOutDir = args.outDir !== undefined
+            ? resolve(args.outDir)
+            : join(repoPath, ".codehub", "packs", manifest.packHash);
+        // If `--out-dir` was supplied, honor it as the literal final path; otherwise
+        // build the canonical .codehub/packs/<hash>/ layout. Either way, ensure the
+        // parent exists, then move the staging dir into place.
+        await mkdir(join(finalOutDir, ".."), { recursive: true });
+        if (existsSync(finalOutDir)) {
+            // Idempotent re-runs land on the same packHash — clear the old dir so
+            // `rename` succeeds atomically. The rm is recursive because the
+            // staging contents are non-empty.
+            await rm(finalOutDir, { recursive: true, force: true });
+        }
+        await rename(stagingDir, finalOutDir);
+        // BOM item count = manifest.files[].length (skeleton, file-tree, deps,
+        // ast-chunks, xrefs, findings, licenses, [embeddings.parquet]) + 1 for
+        // the manifest itself. The readme.md is consumer-facing metadata and is
+        // not part of the manifest hash preimage; we still report it as an
+        // on-disk artifact downstream by walking the dir, but the BOM count
+        // tracks the deterministic items only.
+        const bomItemCount = manifest.files.length + 1;
+        return {
+            outDir: finalOutDir,
+            packHash: manifest.packHash,
+            bomItemCount,
+            manifest,
+            engine: "pack",
+        };
+    }
+    finally {
+        if (owned !== undefined) {
+            await owned.close();
+        }
+        // Best-effort cleanup of the staging dir if we never renamed it (e.g.
+        // generatePack threw). `rm` with `force` swallows ENOENT.
+        await rm(stagingDir, { recursive: true, force: true });
+    }
+}
+async function runRepomixEngine(repoPath, args) {
+    const repomix = args._runRepomix ?? runPack;
+    const result = await repomix(repoPath, {});
+    // Build a CodePackResult-shaped envelope so callers can reason about
+    // either engine uniformly. `packHash` is a sha256 over the file's bytes,
+    // which gives operators a deterministic identifier even though repomix
+    // does not emit a manifest. `bomItemCount` is 1 — repomix is a
+    // single-file snapshot, not the 9-item BOM.
+    const bytes = await readFile(result.outputPath);
+    const packHash = createHash("sha256").update(bytes).digest("hex");
+    return {
+        outDir: repoPath,
+        packHash,
+        bomItemCount: 1,
+        manifest: null,
+        engine: "repomix",
+        repomixOutputPath: result.outputPath,
+    };
+}
+/**
+ * Read the on-disk size of `path`. Exported so the CLI's user-facing
+ * recap can format byte counts without re-walking the dir tree.
+ */
+export function statSizeOrZero(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Discriminate between the composed {@link Store} and a bare
+ * {@link IGraphStore} stub. Tests historically passed a flat IGraphStore
+ * via `_store`; production passes the full Store envelope from
+ * {@link openStore}. We detect the envelope shape by the presence of
+ * `graph` + `temporal` + `backend` so both paths flow through the
+ * sidecar dispatch correctly.
+ */
+function isStoreShape(s) {
+    if (s === undefined)
+        return false;
+    const obj = s;
+    return typeof obj.backend === "string" && obj.graph !== undefined && obj.temporal !== undefined;
+}
+//# sourceMappingURL=code-pack.js.map

package/dist/commands/code-pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-pack.js","sourceRoot":"","sources":["../../src/commands/code-pack.ts"],"names":[],"mappings":"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"}

package/dist/commands/context.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `codehub context <symbol>` — 360-degree view of a single symbol.
+ *
+ * Resolves the target by exact name against the graph, filtering out
+ * synthetic import-tracking stubs (`filePath = '<external>'` and
+ * `kind = 'CodeElement'`) that carry no caller/callee edges. Optional
+ * `targetUid`, `filePath`, and `kind` narrow same-named candidates.
+ * When exact-name yields zero rows we fall back to the BM25 index so
+ * concept-phrase queries still work; when it yields more than one row
+ * and no disambiguator narrows the set, we surface the candidate list.
+ *
+ * This command is graph-only — the lifecycle owner
+ * (`openStoreForCommand`) constructs the composed `Store` envelope, but
+ * `runContext` reaches through `store.graph` for every read so the
+ * `IGraphStore` typed-finder surface stays the only contract.
+ */
+import { type OpenStoreResult } from "./open-store.js";
+export interface ContextOptions {
+    readonly repo?: string;
+    readonly home?: string;
+    readonly json?: boolean;
+    readonly targetUid?: string;
+    readonly filePath?: string;
+    readonly kind?: string;
+}
+export interface ContextRuntimeHooks {
+    readonly openStore?: (opts: ContextOptions) => Promise<OpenStoreResult>;
+}
+export declare function runContext(symbol: string, opts?: ContextOptions, hooks?: ContextRuntimeHooks): Promise<void>;
+//# sourceMappingURL=context.d.ts.map

package/dist/commands/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,KAAK,eAAe,EAAuB,MAAM,iBAAiB,CAAC;AAE5E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACzE;AAyJD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAmB,EACzB,KAAK,GAAE,mBAAwB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA0Hf"}

package/dist/commands/context.js

@@ -0,0 +1,237 @@
+/**
+ * `codehub context <symbol>` — 360-degree view of a single symbol.
+ *
+ * Resolves the target by exact name against the graph, filtering out
+ * synthetic import-tracking stubs (`filePath = '<external>'` and
+ * `kind = 'CodeElement'`) that carry no caller/callee edges. Optional
+ * `targetUid`, `filePath`, and `kind` narrow same-named candidates.
+ * When exact-name yields zero rows we fall back to the BM25 index so
+ * concept-phrase queries still work; when it yields more than one row
+ * and no disambiguator narrows the set, we surface the candidate list.
+ *
+ * This command is graph-only — the lifecycle owner
+ * (`openStoreForCommand`) constructs the composed `Store` envelope, but
+ * `runContext` reaches through `store.graph` for every read so the
+ * `IGraphStore` typed-finder surface stays the only contract.
+ */
+import { openStoreForCommand } from "./open-store.js";
+/**
+ * Find Process-kind partners reachable from the target via `PROCESS_STEP`
+ * edges. Mirrors the post-A-6c MCP equivalent in
+ * `packages/mcp/src/tools/context.ts:567` so the two surfaces stay in
+ * lockstep on edge semantics + ordering.
+ */
+async function fetchProcessParticipation(graph, targetId) {
+    const [outEdges, inEdges] = await Promise.all([
+        graph.listEdgesByType("PROCESS_STEP", { fromIds: [targetId] }),
+        graph.listEdgesByType("PROCESS_STEP", { toIds: [targetId] }),
+    ]);
+    const partnerIds = new Set();
+    for (const e of [...outEdges, ...inEdges]) {
+        const id = e.from === targetId ? e.to : e.from;
+        partnerIds.add(id);
+    }
+    if (partnerIds.size === 0)
+        return [];
+    const partners = await graph.listNodes({ ids: [...partnerIds] });
+    const partnerById = new Map();
+    for (const p of partners)
+        partnerById.set(p.id, p);
+    const dedup = new Map();
+    for (const e of [...outEdges, ...inEdges]) {
+        const partnerId = e.from === targetId ? e.to : e.from;
+        const partner = partnerById.get(partnerId);
+        if (!partner || partner.kind !== "Process")
+            continue;
+        if (dedup.has(partner.id))
+            continue;
+        const inferredLabelRaw = partner.inferredLabel;
+        const label = typeof inferredLabelRaw === "string" && inferredLabelRaw.length > 0
+            ? inferredLabelRaw
+            : partner.name;
+        const stepRaw = e.step;
+        const stepNum = typeof stepRaw === "number" && Number.isFinite(stepRaw) && stepRaw > 0
+            ? Math.trunc(stepRaw)
+            : null;
+        dedup.set(partner.id, { label, step: stepNum });
+    }
+    const items = Array.from(dedup.entries()).map(([id, v]) => ({
+        id,
+        label: v.label,
+        step: v.step,
+    }));
+    // Match the prior `ORDER BY r.step` then deterministic id tiebreak.
+    items.sort((a, b) => {
+        const as = a.step ?? Number.POSITIVE_INFINITY;
+        const bs = b.step ?? Number.POSITIVE_INFINITY;
+        if (as !== bs)
+            return as - bs;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    return items.slice(0, 20);
+}
+function nodeToResolved(n) {
+    return {
+        nodeId: n.id,
+        name: n.name,
+        kind: n.kind,
+        filePath: n.filePath,
+        score: 0,
+    };
+}
+function searchResultToResolvedNode(r) {
+    return {
+        nodeId: r.nodeId,
+        name: r.name,
+        kind: r.kind,
+        filePath: r.filePath,
+        score: r.score,
+    };
+}
+async function resolveTarget(graph, symbol, opts) {
+    if (opts.targetUid !== undefined && opts.targetUid.length > 0) {
+        const list = await graph.listNodes({ ids: [opts.targetUid], limit: 1 });
+        const node = list[0];
+        if (!node)
+            return { kind: "not_found" };
+        return { kind: "resolved", target: nodeToResolved(node), alternates: [] };
+    }
+    // Name-keyed lookup with optional kind narrowing. The `file_path != '<external>'
+    // AND kind != 'CodeElement'` invariants from the legacy SQL are now applied
+    // post-finder so we don't need a `NOT IN` shape. The MCP-side migration in
+    // `packages/mcp/src/tools/context.ts:418-429` pioneered this pattern.
+    const listOpts = opts.kind !== undefined && opts.kind.length > 0 ? { kinds: [opts.kind] } : {};
+    let candidates = await graph.listNodesByName(symbol, listOpts);
+    // Drop synthetic import stubs.
+    candidates = candidates.filter((n) => n.filePath !== "<external>" && n.kind !== "CodeElement");
+    // Optional file-path substring narrow (LIKE %x%).
+    if (opts.filePath !== undefined && opts.filePath.length > 0) {
+        const sub = opts.filePath;
+        candidates = candidates.filter((n) => n.filePath.includes(sub));
+    }
+    // Match prior `ORDER BY file_path LIMIT 25`.
+    const sorted = [...candidates].sort((a, b) => a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0);
+    const sliced = sorted.slice(0, 25);
+    if (sliced.length === 1) {
+        const head = sliced[0];
+        if (!head)
+            return { kind: "not_found" };
+        return { kind: "resolved", target: nodeToResolved(head), alternates: [] };
+    }
+    if (sliced.length > 1) {
+        return { kind: "ambiguous", candidates: sliced.map(nodeToResolved) };
+    }
+    const fallback = await graph.search({ text: symbol, limit: 5 });
+    if (fallback.length === 0)
+        return { kind: "not_found" };
+    const [head, ...rest] = fallback;
+    if (head === undefined)
+        return { kind: "not_found" };
+    return {
+        kind: "resolved",
+        target: searchResultToResolvedNode(head),
+        alternates: rest.map(searchResultToResolvedNode),
+    };
+}
+export async function runContext(symbol, opts = {}, hooks = {}) {
+    const openStore = hooks.openStore ?? openStoreForCommand;
+    const { store, repoPath } = await openStore(opts);
+    const graph = store.graph;
+    try {
+        const resolution = await resolveTarget(graph, symbol, opts);
+        if (resolution.kind === "not_found") {
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    repoPath,
+                    target: null,
+                    callers: [],
+                    callees: [],
+                    processes: [],
+                    alternateCandidates: [],
+                }, null, 2));
+                return;
+            }
+            console.warn(`context: no symbol matching "${symbol}" in ${repoPath}`);
+            return;
+        }
+        if (resolution.kind === "ambiguous") {
+            const candidates = resolution.candidates.slice(0, 10);
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    repoPath,
+                    ambiguous: true,
+                    candidates: resolution.candidates,
+                }, null, 2));
+                process.exitCode = 1;
+                return;
+            }
+            console.warn(`context: "${symbol}" matched ${resolution.candidates.length} symbols in ${repoPath}. Re-call with --target-uid, --file-path, or --kind.`);
+            for (let i = 0; i < candidates.length; i += 1) {
+                const c = candidates[i];
+                if (!c)
+                    continue;
+                console.warn(`  ${i + 1}. [${c.kind}] ${c.name} — ${c.filePath}  (${c.nodeId})`);
+            }
+            if (resolution.candidates.length > candidates.length) {
+                console.warn(`  … ${resolution.candidates.length - candidates.length} more`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const target = resolution.target;
+        const [up, down, processes] = await Promise.all([
+            graph.traverse({
+                startId: target.nodeId,
+                direction: "up",
+                maxDepth: 1,
+                relationTypes: ["CALLS"],
+            }),
+            graph.traverse({
+                startId: target.nodeId,
+                direction: "down",
+                maxDepth: 1,
+                relationTypes: ["CALLS"],
+            }),
+            fetchProcessParticipation(graph, target.nodeId),
+        ]);
+        if (opts.json) {
+            console.log(JSON.stringify({
+                repoPath,
+                target,
+                callers: up,
+                callees: down,
+                processes,
+                alternateCandidates: resolution.alternates,
+            }, null, 2));
+            return;
+        }
+        console.warn(`context: ${target.name} (${target.kind}) — ${target.filePath}`);
+        console.log("");
+        console.log(`Inbound (depth 1): ${up.length}`);
+        for (const r of up)
+            console.log(`  ← ${r.nodeId}`);
+        console.log("");
+        console.log(`Outbound (depth 1): ${down.length}`);
+        for (const r of down)
+            console.log(`  → ${r.nodeId}`);
+        if (processes.length > 0) {
+            console.log("");
+            console.log(`Processes (${processes.length}):`);
+            for (const p of processes) {
+                const stepLabel = p.step !== null ? `step ${p.step}` : "participant";
+                console.log(`  ⊿ ${p.label} — ${stepLabel}  (${p.id})`);
+            }
+        }
+        if (resolution.alternates.length > 0) {
+            console.log("");
+            console.log(`Other candidates for "${symbol}":`);
+            for (const c of resolution.alternates) {
+                console.log(`  - ${c.name} (${c.kind}) — ${c.filePath}`);
+            }
+        }
+    }
+    finally {
+        await store.close();
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/commands/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"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"}

package/dist/commands/detect-changes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `codehub detect-changes` — map a git diff onto affected graph symbols.
+ *
+ * Delegates to `@opencodehub/analysis.runDetectChanges`. The CLI layer
+ * only resolves the scope flag, runs git against the repo, and formats
+ * the result. Useful from CI (GitHub Actions, GitLab CI) without
+ * launching the MCP server.
+ *
+ * Exit codes:
+ *   0 — diff produced zero affected symbols (risk: LOW or empty diff).
+ *   1 — diff produced HIGH or CRITICAL risk. Operators configure CI
+ *       gates to fail on non-zero.
+ *   Any risk tier MEDIUM or below stays on exit 0 so informational runs
+ *   are non-blocking.
+ */
+export interface DetectChangesOptions {
+    readonly scope?: "unstaged" | "staged" | "all" | "compare";
+    readonly compareRef?: string;
+    readonly repo?: string;
+    readonly home?: string;
+    readonly json?: boolean;
+    /** When true, fail (exit 1) on any non-LOW risk. Default: HIGH+CRIT only. */
+    readonly strict?: boolean;
+}
+export declare function runDetectChangesCmd(opts?: DetectChangesOptions): Promise<void>;
+//# sourceMappingURL=detect-changes.d.ts.map

package/dist/commands/detect-changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-changes.d.ts","sourceRoot":"","sources":["../../src/commands/detect-changes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DxF"}

package/dist/commands/detect-changes.js

@@ -0,0 +1,73 @@
+/**
+ * `codehub detect-changes` — map a git diff onto affected graph symbols.
+ *
+ * Delegates to `@opencodehub/analysis.runDetectChanges`. The CLI layer
+ * only resolves the scope flag, runs git against the repo, and formats
+ * the result. Useful from CI (GitHub Actions, GitLab CI) without
+ * launching the MCP server.
+ *
+ * Exit codes:
+ *   0 — diff produced zero affected symbols (risk: LOW or empty diff).
+ *   1 — diff produced HIGH or CRITICAL risk. Operators configure CI
+ *       gates to fail on non-zero.
+ *   Any risk tier MEDIUM or below stays on exit 0 so informational runs
+ *   are non-blocking.
+ */
+import { runDetectChanges } from "@opencodehub/analysis";
+import { openStoreForCommand } from "./open-store.js";
+export async function runDetectChangesCmd(opts = {}) {
+    const scope = opts.scope ?? "all";
+    if (scope === "compare" && (opts.compareRef === undefined || opts.compareRef.length === 0)) {
+        console.error("codehub detect-changes: --scope=compare requires --compare-ref <git-ref> (e.g. origin/main)");
+        process.exitCode = 2;
+        return;
+    }
+    const { store, repoPath } = await openStoreForCommand(opts);
+    try {
+        const q = { scope, repoPath };
+        if (opts.compareRef !== undefined)
+            q.compareRef = opts.compareRef;
+        const result = await runDetectChanges(store.graph, q);
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            const { summary, changedFiles, affectedSymbols, affectedProcesses } = result;
+            console.log(`detect-changes: ${summary.fileCount} file(s), ${summary.symbolCount} symbol(s), ${summary.processCount} process(es) affected. Risk: ${summary.risk}.`);
+            if (changedFiles.length > 0) {
+                console.log("Changed files:");
+                for (const f of changedFiles.slice(0, 30))
+                    console.log(`  • ${f}`);
+                if (changedFiles.length > 30) {
+                    console.log(`  … ${changedFiles.length - 30} more`);
+                }
+            }
+            if (affectedSymbols.length > 0) {
+                console.log(`Affected symbols (${affectedSymbols.length}):`);
+                for (const s of affectedSymbols.slice(0, 50)) {
+                    console.log(`  • ${s.name} [${s.kind}] — ${s.filePath}`);
+                }
+                if (affectedSymbols.length > 50) {
+                    console.log(`  … ${affectedSymbols.length - 50} more`);
+                }
+            }
+            if (affectedProcesses.length > 0) {
+                console.log(`Affected processes (${affectedProcesses.length}):`);
+                for (const p of affectedProcesses) {
+                    console.log(`  ⊿ ${p.name} — ${p.entryPointFile}`);
+                }
+            }
+        }
+        const risk = result.summary.risk;
+        const blockOn = opts.strict
+            ? new Set(["MEDIUM", "HIGH", "CRITICAL"])
+            : new Set(["HIGH", "CRITICAL"]);
+        if (blockOn.has(risk)) {
+            process.exitCode = 1;
+        }
+    }
+    finally {
+        await store.close();
+    }
+}
+//# sourceMappingURL=detect-changes.js.map

package/dist/commands/detect-changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-changes.js","sourceRoot":"","sources":["../../src/commands/detect-changes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAYtD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAA6B,EAAE;IACvE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3F,OAAO,CAAC,KAAK,CACX,6FAA6F,CAC9F,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5D,IAAI,CAAC;QACH,MAAM,CAAC,GAIH,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClE,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAEtD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC;YAC7E,OAAO,CAAC,GAAG,CACT,mBAAmB,OAAO,CAAC,SAAS,aAAa,OAAO,CAAC,WAAW,eAAe,OAAO,CAAC,YAAY,gCAAgC,OAAO,CAAC,IAAI,GAAG,CACvJ,CAAC;YACF,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;gBAC9B,KAAK,MAAM,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;oBAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBACnE,IAAI,YAAY,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;oBAC7B,OAAO,CAAC,GAAG,CAAC,OAAO,YAAY,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC;gBACtD,CAAC;YACH,CAAC;YACD,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC/B,OAAO,CAAC,GAAG,CAAC,qBAAqB,eAAe,CAAC,MAAM,IAAI,CAAC,CAAC;gBAC7D,KAAK,MAAM,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;oBAC7C,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAC3D,CAAC;gBACD,IAAI,eAAe,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;oBAChC,OAAO,CAAC,GAAG,CAAC,OAAO,eAAe,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC;gBACzD,CAAC;YACH,CAAC;YACD,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjC,OAAO,CAAC,GAAG,CAAC,uBAAuB,iBAAiB,CAAC,MAAM,IAAI,CAAC,CAAC;gBACjE,KAAK,MAAM,CAAC,IAAI,iBAAiB,EAAE,CAAC;oBAClC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QACjC,MAAM,OAAO,GAAwB,IAAI,CAAC,MAAM;YAC9C,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;YACzC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;QAClC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `codehub doctor` — environment probe.
+ *
+ * Runs every `Check` registered in `CHECKS`, prints a table, and exits
+ * with a status code that maps to the worst result seen:
+ *
+ *   0  all ok
+ *   1  at least one warn (non-blocking)
+ *   2  at least one fail (blocking — something is broken)
+ *
+ * Checks are strictly diagnostic — they never auto-heal. Each one returns
+ * a `hint` string the user can copy-paste when things are off.
+ */
+export type CheckStatus = "ok" | "warn" | "fail";
+export interface CheckResult {
+    readonly status: CheckStatus;
+    readonly message: string;
+    readonly hint?: string;
+}
+export interface Check {
+    readonly name: string;
+    run(): Promise<CheckResult>;
+}
+export interface DoctorOptions {
+    /** Override HOME so tests can point at a fake dotdir. */
+    readonly home?: string;
+    /** Skip checks that rely on native bindings (e.g. in CI sandboxes). */
+    readonly skipNative?: boolean;
+    /** Override the repo root when resolving workspace packages. */
+    readonly repoRoot?: string;
+}
+export interface DoctorReport {
+    readonly rows: readonly {
+        readonly name: string;
+        readonly result: CheckResult;
+    }[];
+    readonly exitCode: 0 | 1 | 2;
+}
+/**
+ * Entry point invoked by `codehub doctor`. Prints the table and sets
+ * `process.exitCode`. Also returns the structured report so tests and
+ * acceptance scripts can assert the outcome without parsing stdout.
+ */
+export declare function runDoctor(opts?: DoctorOptions): Promise<DoctorReport>;
+/**
+ * Ordered list of environment probes. Order matters only for the output
+ * table — runs are independent, but we surface foundational checks first
+ * (Node, pnpm, native bindings) so the user can fix a broken foundation
+ * before worrying about downstream extras.
+ */
+export declare function buildChecks(opts?: DoctorOptions): readonly Check[];
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;KAAE,EAAE,CAAC;IAClF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA2B/E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,aAAkB,GAAG,SAAS,KAAK,EAAE,CA2CtE"}