@shrkcrft/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/commands/graph-code-subverbs.js

@@ -5,14 +5,14 @@
  * focused. The entry command imports each `run*` and routes when the
  * first positional matches the subverb name.
  */
-import { buildFullIndex, changedFilesSince, detectChangedAndDeleted, detectGraphFreshness, EdgeKind, GraphQueryApi, GraphStore, hasCallGraphReferences, NodeKind, updateChanged, } from '@shrkcrft/graph';
+import { buildFullIndex, changedFilesSince, detectChangedAndDeleted, detectGraphFreshness, EdgeKind, GraphQueryApi, GraphStore, hasCallGraphReferences, isGraphStoreCorruptError, NodeKind, updateChanged, } from '@shrkcrft/graph';
 import { analyzeGraphImpact } from '@shrkcrft/impact-engine';
 import { BridgeStore, RuleGraphQueryApi } from '@shrkcrft/rule-graph';
 import { FrameworkQueryApi, FrameworkStore } from '@shrkcrft/framework-scanners';
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { compactArrayToColumnar } from '@shrkcrft/compress';
-import { flagBool, flagString, resolveCwd } from "../command-registry.js";
+import { flagBool, flagNumber, flagPositiveInt, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 /**
@@ -59,6 +59,32 @@ function maybeColumnarize(payload, args) {
 }
 const STALE_HINT = `Index is missing or stale. Run 'shrk graph index' to build it.`;
 const STALE_RESULT_HINT = 'Some result files changed since the index was built — auto-refresh is on by default (you passed --no-refresh / SHRK_GRAPH_NO_REFRESH). Drop the opt-out, or run `shrk graph index --changed`, for fresh results.';
+const CORRUPT_HINT = 'code graph store is corrupt — run `shrk graph index` to rebuild.';
+/**
+ * Per-list display cap for `graph context`. The JSON payload always reports the
+ * true pre-slice count (`total<List>`) and a `<list>Truncated` flag so a
+ * high-fan-in node is never silently capped (mirrors runGraphCycles /
+ * runGraphCallers). Kept in sync with the MCP `get_graph_context` tool.
+ */
+const CONTEXT_LIST_CAP = 50;
+/**
+ * Resolve a `--limit N` per-list cap for the graph read commands. Absent → the
+ * command's `fallback` (the historical default — 50 for `context`, 200 for
+ * `callers`/`impact`); `--limit 0` (or any non-positive) → unbounded so a
+ * consumer can pull the full set off a high-fan-in barrel/hub in one call.
+ * Returns `Infinity` for the unbounded case: `arr.slice(0, Infinity)` yields
+ * every row and `len > Infinity` is `false`, so the `<list>Truncated` flag stays
+ * honest (never "truncated" when nothing was dropped). Malformed `--limit abc`
+ * (NaN) degrades to `fallback`, matching `flagPositiveInt`.
+ */
+function resolveListLimit(args, fallback) {
+    const v = flagNumber(args, 'limit');
+    if (v === undefined)
+        return fallback;
+    if (v <= 0)
+        return Number.POSITIVE_INFINITY;
+    return Math.floor(v);
+}
 /**
  * Refresh-by-default: incrementally reindex changed/deleted files BEFORE
  * querying so an agent's just-saved edits are reflected, then print a one-line
@@ -122,8 +148,31 @@ function indexBehindHint(cwd) {
         return null;
     return `Index is ${behind} file(s) behind (${f.modified.length} modified, ${f.added.length} new, ${f.deleted.length} deleted) — run \`shrk graph index --changed\` and retry.`;
 }
+/**
+ * Reject a stray positional on a subverb that takes NO file argument
+ * (status/cycles/unresolved/index). These previously printed a byte-identical
+ * global report for any/no/bogus arg, so `shrk graph status foo` silently
+ * swallowed `foo`. Returns the exit code to use (2) when an unexpected
+ * positional[1+] is present, or null when the args are clean. `subverb` is
+ * positional[0]; anything at positional[1] is the offending extra.
+ */
+function strayPositionalError(args, subverb) {
+    const extra = args.positional[1];
+    if (extra === undefined)
+        return null;
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ ok: false, error: 'unexpected-argument', argument: extra }) + '\n');
+    }
+    else {
+        process.stderr.write(`'shrk graph ${subverb}' takes no positional argument (got "${extra}"). Usage: shrk graph ${subverb} [--json]\n`);
+    }
+    return 2;
+}
 // ─── shrk graph index ─────────────────────────────────────────────────
 export async function runGraphIndex(args) {
+    const stray = strayPositionalError(args, 'index');
+    if (stray !== null)
+        return stray;
     // --watch: run the index once, then re-run on file changes. Every
     // tick after the first uses the incremental updater so a 5-file edit
     // takes < 100ms. Default watch path is the project root; pass
@@ -214,6 +263,9 @@ async function runGraphIndexOnce(args) {
 export async function runGraphCycles(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
+    const stray = strayPositionalError(args, 'cycles');
+    if (stray !== null)
+        return stray;
     const limit = parseLimit(args);
     const minSize = parseMinSize(args);
     const store = new GraphStore(cwd);
@@ -230,7 +282,9 @@ export async function runGraphCycles(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const api = GraphQueryApi.fromStore(cwd);
+    const api = loadGuarded(() => GraphQueryApi.fromStore(cwd), wantJson);
+    if (!api)
+        return 1;
     const allCycles = api.cycles();
     const filtered = allCycles.filter((c) => c.size >= minSize);
     const limited = filtered.slice(0, limit);
@@ -289,6 +343,9 @@ function parseMinSize(args) {
 export async function runGraphUnresolved(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
+    const stray = strayPositionalError(args, 'unresolved');
+    if (stray !== null)
+        return stray;
     const limit = parseLimit(args);
     const store = new GraphStore(cwd);
     if (!store.exists()) {
@@ -304,7 +361,9 @@ export async function runGraphUnresolved(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const snap = store.loadSnapshot();
+    const snap = loadGuarded(() => store.loadSnapshot(), wantJson);
+    if (!snap)
+        return 1;
     const groups = new Map();
     for (const e of snap.edges.values()) {
         if (e.kind !== EdgeKind.ImportsFile)
@@ -396,7 +455,9 @@ export async function runGraphDeps(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const api = GraphQueryApi.fromStore(cwd);
+    const api = loadGuarded(() => GraphQueryApi.fromStore(cwd), wantJson);
+    if (!api)
+        return 1;
     const pkgId = `package:${pkg}`;
     // Existence guard (mirrors the MCP tool): without it, an unknown package
     // name returns a confidently-wrong empty `dependsOn/dependedOnBy` that reads
@@ -453,6 +514,9 @@ export async function runGraphDeps(args) {
 export async function runGraphStatus(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
+    const stray = strayPositionalError(args, 'status');
+    if (stray !== null)
+        return stray;
     const store = new GraphStore(cwd);
     if (!store.exists()) {
         const payload = {
@@ -468,8 +532,20 @@ export async function runGraphStatus(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const verify = store.verifyDigest();
-    const snap = store.loadSnapshot();
+    // A corrupt store (a truncated/garbled JSONL row) must surface as a `corrupt`
+    // status line + non-zero exit, NOT a raw `Fatal: JSON Parse error` crash.
+    let verify;
+    let snap;
+    try {
+        verify = store.verifyDigest();
+        snap = store.loadSnapshot();
+    }
+    catch (err) {
+        const code = emitCorruptStore(err, wantJson);
+        if (code !== null)
+            return code;
+        throw err;
+    }
     const manifestNodeCount = sumValues(snap.manifest.nodesByKind);
     const manifestEdgeCount = sumValues(snap.manifest.edgesByKind);
     // Honest freshness vs the working tree. `corrupt` (store self-integrity) and
@@ -536,40 +612,63 @@ export async function runGraphSearch(args) {
         return 2;
     }
     const kindFlag = flagString(args, 'kind');
-    const limit = Number(flagString(args, 'limit') ?? '20');
+    // NaN-safe --limit: a fat-fingered `--limit abc` must fall back to the default,
+    // not become `Number('abc') === NaN` (which zeroed the result via a NaN slice).
+    const limit = flagPositiveInt(args, 'limit', 20);
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
         return 1;
-    let matches;
+    // Compute the TRUE pre-slice match count so `total`/`truncated` stay honest —
+    // the old code reported the post-cap length as the total, so 285 matches read
+    // as `total: 20` with no signal there was more.
+    let page;
+    let total;
     if (hasUnresolved) {
         const all = api.filesWithUnresolvedImports();
-        matches = (query
+        const filtered = query
             ? all.filter((n) => (n.path ?? '').toLowerCase().includes(query.toLowerCase()))
-            : [...all]).slice(0, limit);
+            : [...all];
+        total = filtered.length;
+        page = filtered.slice(0, limit);
     }
     else {
-        matches = collectSearchMatches(api, query, kindFlag, limit);
-    }
+        const res = collectSearchMatches(api, query, kindFlag, limit);
+        page = res.matches;
+        total = res.total;
+    }
+    // Targeted staleness over the displayed page (parity with MCP / callers): drop
+    // deleted result files, flag modified ones, and reduce `total` by the
+    // deletions we observed so a dead file is never counted.
+    const summarised = page.map(toSearchHit);
+    const fresh = resultStaleness(api, cwd, summarised.map((m) => m.path));
+    const live = summarised.filter((m) => !m.path || !fresh.deletedSet.has(m.path));
+    const adjustedTotal = total - (summarised.length - live.length);
+    const truncated = adjustedTotal > limit;
     if (wantJson) {
         process.stdout.write(asJson({
             schema: 'sharkcraft.graph-search/v1',
             query,
             kind: kindFlag ?? 'any',
-            total: matches.length,
-            matches: matches.map(toSearchHit),
+            total: adjustedTotal,
+            truncated,
+            matches: live,
+            ...(fresh.field ?? {}),
         }) + '\n');
         return 0;
     }
     const headerLabel = query ?? (hasUnresolved ? 'files with unresolved imports' : '');
-    if (matches.length === 0) {
+    if (live.length === 0) {
         process.stdout.write(`No matches for "${headerLabel}".\n`);
         return 0;
     }
     process.stdout.write(header(`Graph search: ${headerLabel}`));
-    for (const m of matches) {
+    for (const m of live) {
         process.stdout.write(`  ${m.kind.padEnd(8)} ${m.label}${m.path ? '  ' + m.path : ''}${m.line ? ':' + m.line : ''}\n`);
     }
+    if (truncated) {
+        process.stdout.write(`\n(${adjustedTotal - live.length} more — pass --limit ${adjustedTotal} to see all)\n`);
+    }
     return 0;
 }
 // ─── shrk graph context ───────────────────────────────────────────────
@@ -578,10 +677,11 @@ export async function runGraphContext(args) {
     const wantJson = flagBool(args, 'json');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph context <fileOrSymbol> [--depth N] [--no-bridge] [--no-framework]\n');
+        process.stderr.write('Usage: shrk graph context <fileOrSymbol> [--depth N] [--limit N|0] [--no-bridge] [--no-framework]\n');
         return 2;
     }
-    const depth = Math.max(1, Math.min(3, Number(flagString(args, 'depth') ?? '1')));
+    const depth = Math.min(3, flagPositiveInt(args, 'depth', 1));
+    const cap = resolveListLimit(args, CONTEXT_LIST_CAP);
     const includeBridge = !flagBool(args, 'no-bridge');
     const includeFramework = !flagBool(args, 'no-framework');
     maybeRefresh(args, cwd);
@@ -622,16 +722,18 @@ export async function runGraphContext(args) {
     const frameworkEntities = (includeFramework && frameworkStore.exists() && anchorFile?.path)
         ? FrameworkQueryApi.fromStore(cwd).forFile(anchorFile.path)
         : [];
-    const importsFromList = neighbours.out
-        .filter((o) => o.edge.kind === 'imports-file')
-        .slice(0, 50)
+    // Pre-slice the homogeneous filtered arrays so the payload can report the TRUE
+    // count + a truncated flag instead of silently capping each list at 50.
+    const importsFromAll = neighbours.out.filter((o) => o.edge.kind === 'imports-file');
+    const importedByAll = neighbours.in.filter((i) => i.edge.kind === 'imports-file');
+    const importsFromList = importsFromAll
+        .slice(0, cap)
         .map((o) => ('target' in o ? targetSummary(o.target) : { id: 'unknown', resolved: false }));
-    const importedByList = neighbours.in
-        .filter((i) => i.edge.kind === 'imports-file')
-        .slice(0, 50)
+    const importedByList = importedByAll
+        .slice(0, cap)
         .map((i) => ('source' in i ? sourceSummary(i.source) : { id: 'unknown', resolved: false }));
-    const referencedByList = references.slice(0, 50).map(nodeSummary);
-    const calledByList = callers.slice(0, 50).map(nodeSummary);
+    const referencedByList = references.slice(0, cap).map(nodeSummary);
+    const calledByList = callers.slice(0, cap).map(nodeSummary);
     // Staleness over the anchor + every referenced file: drop dead paths from the
     // usage lists, flag changed ones.
     const ctxPathOf = (x) => x.path;
@@ -649,12 +751,20 @@ export async function runGraphContext(args) {
         declaredIn: anchor.kind === NodeKind.Symbol && anchorFile ? nodeSummary(anchorFile) : null,
         depth,
         importsFrom: ctxDropDel(importsFromList),
+        totalImportsFrom: importsFromAll.length,
+        importsFromTruncated: importsFromAll.length > cap,
         importedBy: ctxDropDel(importedByList),
-        symbols: symbols.slice(0, 50).map(nodeSummary),
+        totalImportedBy: importedByAll.length,
+        importedByTruncated: importedByAll.length > cap,
+        symbols: symbols.slice(0, cap).map(nodeSummary),
         referencedBy: ctxDropDel(referencedByList),
+        totalReferencedBy: references.length,
+        referencedByTruncated: references.length > cap,
         calledBy: ctxDropDel(calledByList),
-        ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, 50).map(nodeSummary) } : {}),
-        ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, 50).map(nodeSummary) } : {}),
+        totalCalledBy: callers.length,
+        calledByTruncated: callers.length > cap,
+        ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, cap).map(nodeSummary) } : {}),
+        ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, cap).map(nodeSummary) } : {}),
         ...(fresh.field ?? {}),
         bridge: bridgeFor
             ? {
@@ -769,11 +879,11 @@ export async function runGraphImpact(args) {
     const wantFull = flagBool(args, 'full');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N] [--full]\n');
+        process.stderr.write('Usage: shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N|0] [--full]\n');
         return 2;
     }
-    const maxDepth = Math.max(1, Math.min(10, Number(flagString(args, 'max-depth') ?? '5')));
-    const limit = Math.max(1, Number(flagString(args, 'limit') ?? '200'));
+    const maxDepth = Math.min(10, flagPositiveInt(args, 'max-depth', 5));
+    const limit = resolveListLimit(args, 200);
     maybeRefresh(args, cwd);
     // --full → delegate to the impact-engine for a richer v3 payload.
     if (wantFull) {
@@ -858,7 +968,8 @@ export async function runGraphImpact(args) {
         schema: 'sharkcraft.graph-impact/v1',
         anchor: nodeSummary(anchor),
         maxDepth,
-        limit,
+        // 0 signals "unbounded" (`--limit 0`); JSON can't carry Infinity.
+        limit: Number.isFinite(limit) ? limit : 0,
         truncated: closure.truncated,
         directDependents: liveDirect,
         transitiveDependents: liveTransitive,
@@ -899,8 +1010,22 @@ export async function runGraphImpact(args) {
 export async function runGraphHubs(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
-    const limit = Math.max(1, Math.min(100, Number(flagString(args, 'limit') ?? '15')));
-    const pathScope = flagString(args, 'path');
+    const limit = Math.min(100, flagPositiveInt(args, 'limit', 15));
+    // A positional scope (`shrk graph hubs packages/cli`) is honoured the same as
+    // --path; passing BOTH is ambiguous, so error rather than silently ignoring
+    // the positional (which previously yielded a byte-identical global report).
+    const pathFlag = flagString(args, 'path');
+    const positionalPath = args.positional[1];
+    if (pathFlag && positionalPath) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'ambiguous-path', positional: positionalPath, flag: pathFlag }) + '\n');
+        }
+        else {
+            process.stderr.write(`Pass the scope path either as a positional or with --path, not both (got "${positionalPath}" and --path ${pathFlag}).\n`);
+        }
+        return 2;
+    }
+    const pathScope = pathFlag ?? positionalPath;
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
@@ -947,16 +1072,15 @@ export async function runGraphCallers(args) {
     const wantJson = flagBool(args, 'json');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--limit N] [--no-refresh]\n');
+        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--limit N|0] [--no-refresh]\n');
         return 2;
     }
     const mode = (flagString(args, 'mode') ?? 'call');
-    // --limit N: cap the returned call sites (default 200). `total` still reports
-    // the true uncapped count, so a truncated result stays honest. Guard against
-    // non-numeric input — `Number('foo')` is NaN and `slice(0, NaN)` would zero
-    // the callers list while `total` kept showing the real count.
-    const parsedLimit = Number.parseInt(flagString(args, 'limit') ?? '200', 10);
-    const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 200;
+    // --limit N: cap the returned call sites (default 200; `--limit 0` = all).
+    // `total` still reports the true uncapped count, so a truncated result stays
+    // honest. resolveListLimit guards non-numeric input (NaN → fallback) so a
+    // fat-fingered `--limit foo` can't zero the list via `slice(0, NaN)`.
+    const limit = resolveListLimit(args, 200);
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
@@ -1081,7 +1205,7 @@ export async function runGraphPath(args) {
         process.stderr.write('Usage: shrk graph path <from> <to> [--max-depth N] [--no-refresh] [--json]\n');
         return 2;
     }
-    const maxDepth = Math.max(1, Math.min(32, Number(flagString(args, 'max-depth') ?? '16')));
+    const maxDepth = Math.min(32, flagPositiveInt(args, 'max-depth', 16));
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
@@ -1183,6 +1307,45 @@ export async function runGraphPath(args) {
     return 0;
 }
 // ─── helpers ──────────────────────────────────────────────────────────
+/**
+ * Convert the typed corrupt-store error (one bad JSONL line) into a
+ * deterministic "rebuild the index" message + non-zero exit, instead of letting
+ * an unhandled `Fatal: JSON Parse error` escape the CLI. Returns the exit code
+ * (1) when `err` is a corrupt-store error, or null to signal "not mine — rethrow".
+ */
+function emitCorruptStore(err, wantJson) {
+    if (!isGraphStoreCorruptError(err))
+        return null;
+    if (wantJson) {
+        process.stdout.write(asJson({
+            ok: false,
+            state: 'corrupt',
+            nextCommand: 'shrk graph index',
+            message: CORRUPT_HINT,
+            ...(err.details ?? {}),
+        }) + '\n');
+    }
+    else {
+        process.stderr.write(CORRUPT_HINT + '\n');
+    }
+    return 1;
+}
+/**
+ * Run a store-loading thunk, mapping a corrupt store to a clean rebuild hint.
+ * Returns the loaded value, or undefined when the store was corrupt (the
+ * message + exit have already been emitted; the caller should `return 1`). Any
+ * other error is rethrown unchanged.
+ */
+function loadGuarded(load, wantJson) {
+    try {
+        return load();
+    }
+    catch (err) {
+        if (emitCorruptStore(err, wantJson) !== null)
+            return undefined;
+        throw err;
+    }
+}
 function loadOrFail(cwd, wantJson) {
     const store = new GraphStore(cwd);
     if (!store.exists()) {
@@ -1199,7 +1362,7 @@ function loadOrFail(cwd, wantJson) {
         }
         return undefined;
     }
-    return GraphQueryApi.fromStore(cwd);
+    return loadGuarded(() => GraphQueryApi.fromStore(cwd), wantJson);
 }
 function resolveAnchor(api, target) {
     // Exact node id wins.
@@ -1221,43 +1384,14 @@ function resolveAnchor(api, target) {
         return syms[0];
     return undefined;
 }
+/**
+ * Delegate to the shared {@link GraphQueryApi.searchNodes} so the CLI and the
+ * MCP `get_graph_search` tool can never disagree on results OR the honest
+ * pre-slice `total` (the two surfaces used to maintain divergent copies of this
+ * fuzzy-match logic). Returns the display page + the true match count.
+ */
 function collectSearchMatches(api, query, kind, limit) {
-    const out = [];
-    if (!kind || kind === 'file') {
-        const f = api.findFile(query);
-        if (f)
-            out.push(f);
-        // Fuzzy fallback: substring match on path/basename so `shrk graph
-        // search Foo --kind file` finds `libs/x/y/Foo.ts` without forcing the
-        // caller to type the full path. Skips the node if exact match already
-        // included it.
-        if (out.length < limit) {
-            const q = query.toLowerCase();
-            const seen = new Set(out.map((n) => n.id));
-            for (const node of api.allFiles()) {
-                if (seen.has(node.id))
-                    continue;
-                const p = node.path?.toLowerCase() ?? '';
-                const base = p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p;
-                if (base.includes(q) || p.includes(q)) {
-                    out.push(node);
-                    seen.add(node.id);
-                    if (out.length >= limit)
-                        break;
-                }
-            }
-        }
-    }
-    if (!kind || kind === 'symbol') {
-        for (const s of api.findSymbol(query, { exact: false, limit }))
-            out.push(s);
-    }
-    if (!kind || kind === 'package') {
-        const p = api.neighbours(`package:${query}`);
-        if (p)
-            out.push(p.node);
-    }
-    return out.slice(0, limit);
+    return api.searchNodes(query, { ...(kind ? { kind } : {}), limit });
 }
 function reverseClosure(api, anchor, maxDepth, limit) {
     const seen = new Set([anchor.id]);

package/dist/commands/graph.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,YAAY,EAAE,eA+M1B,CAAC"}
+{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,YAAY,EAAE,eAuN1B,CAAC"}

package/dist/commands/graph.command.js

@@ -52,6 +52,12 @@ export const graphCommand = {
         const graph = buildKnowledgeGraph(inspection);
         const sub = args.positional[0];
         const typeFlag = flagString(args, 'type');
+        // A typo'd `--type` would otherwise silently match zero nodes and return an
+        // empty summary / "no node" at exit 0/1. Reject loudly with the valid list.
+        if (typeFlag && !KNOWN_KINDS.includes(typeFlag)) {
+            process.stderr.write(`Unknown --type ${typeFlag}. Valid: ${KNOWN_KINDS.join(', ')}\n`);
+            return 2;
+        }
         const formatFlag = (flagString(args, 'format') ?? 'text');
         const outputFlag = flagString(args, 'output');
         // `shrk graph imports` — import-graph analysis.

package/dist/commands/help.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAqB9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EA2HpF"}
+{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA4B9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EAwIpF"}

package/dist/commands/help.command.js

@@ -1,5 +1,11 @@
 import { header } from "../output/format-output.js";
-import { COMMAND_CATALOG, defaultShowInHelp } from "./command-catalog.js";
+import { COMMAND_CATALOG, defaultShowInHelp, listExplainFamily } from "./command-catalog.js";
+/** First sentence of a catalog description, for the compact explain-family list. */
+function firstSentence(description) {
+    const dot = description.indexOf('. ');
+    const head = dot > 0 ? description.slice(0, dot + 1) : description;
+    return head.length > 100 ? head.slice(0, 97).trimEnd() + '…' : head;
+}
 const EXTRA_HELP_LINES = Object.freeze({
     graph: [
         '',
@@ -60,7 +66,7 @@ export function renderStartScreen() {
     lines.push('Discover the rest (everything stays callable — this screen shows ~17 of ~70 verbs):');
     lines.push('  $ shrk surface list              — full catalog by tier');
     lines.push('  $ shrk help <command>            — usage for a specific command');
-    lines.push('  $ shrk --full-help               — long, exhaustive help');
+    lines.push('  $ shrk --full-help               — long, exhaustive help (incl. the explain/dry-run family)');
     lines.push('  $ shrk --about                   — what shrk is and is not');
     lines.push('');
     lines.push('Free-form input is fine — `shrk "<task>"` routes to `shrk recommend`.');
@@ -188,6 +194,18 @@ export function makeHelpCommand(registry) {
                     process.stdout.write(`  ${group} ${s.name.padEnd(10)} — ${s.description}\n`);
                 }
             }
+            // Explain / dry-run family — several carry an Advanced surface and are
+            // filtered out of the listings above, so surface them explicitly. These
+            // show you what a gate, ranker, or graph SEES before you act; an agent
+            // would otherwise find them only by guessing (the #4.4 friction).
+            const explainFamily = listExplainFamily();
+            if (explainFamily.length > 0) {
+                process.stdout.write(header('Inspect / explain (dry-run what a gate, ranker, or graph sees)'));
+                for (const e of explainFamily) {
+                    process.stdout.write(`  ${e.command.padEnd(24)} — ${firstSentence(e.description)}\n`);
+                }
+                process.stdout.write('  (also: shrk check wiring --explain <ruleId>)\n');
+            }
             process.stdout.write('\nRun `shrk help <command>` for detailed usage.\n');
             return 0;
         },

package/dist/commands/impact.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0VhC,eAAO,MAAM,aAAa,EAAE,eA8V3B,CAAC"}
+{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2ahC,eAAO,MAAM,aAAa,EAAE,eAsW3B,CAAC"}