@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/commands/trace.command.js

@@ -6,8 +6,9 @@
  * shared query resolver and prints structured trace output.
  */
 import { findSymbolInProject, inspectSharkcraft, QueryMatchKind, resolveQuery, } from '@shrkcrft/inspector';
-import { traceLiteral, TraceRole, } from '@shrkcrft/boundaries';
+import { describeUnread, traceLiteral, TraceRole, } from '@shrkcrft/boundaries';
 import { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 function describeMatch(m) {
     return `${m.kind.padEnd(12)} ${m.id}${m.label && m.label !== m.id ? ` — ${m.label}` : ''} [${m.score.toFixed(0)}]`;
@@ -26,8 +27,15 @@ function renderTraceLiteral(report, limit) {
     if (report.aliases.length > 0) {
         process.stdout.write(kv('const aliases', report.aliases.join(', ')) + '\n');
     }
+    // A matched file the reader did not read (over the read cap) was never
+    // searched: name it, and never claim "no occurrences" over it.
+    const unread = report.unread ?? [];
+    if (unread.length > 0)
+        process.stdout.write(kv('not read', describeUnread(unread)) + '\n');
     if (report.total === 0) {
-        process.stdout.write('\nNo occurrences of that exact string literal in scope.\n');
+        process.stdout.write(unread.length > 0
+            ? `\nNot verified: ${describeUnread(unread)} were not read, so an occurrence there was never checked.\n`
+            : '\nNo occurrences of that exact string literal in scope.\n');
         return;
     }
     // Mirror `shrk registry <name> where`'s `<role>  file:line` line idiom so the
@@ -80,6 +88,16 @@ function runTraceLiteral(args) {
 }
 export const traceCommand = {
     name: 'trace',
+    // The positionals are a free-form query; `literal` is dispatched here.
+    positionals: PositionalMode.Free,
+    subverbs: [
+        {
+            name: 'literal',
+            description: "Trace an exact string literal's declare → register → consume chain across layers (alias-resolved).",
+            usage: 'shrk trace literal "<string>" [--glob <g>] [--no-aliases] [--limit <n>] [--json]',
+            positionals: PositionalMode.Free,
+        },
+    ],
     description: 'Fuzzy trace — accept any free-form query (file path, construct id, symbol, plugin key, helper id, template id, knowledge id, command). `trace literal "<string>"` traces an exact string literal\'s declare→register→consume chain across layers (alias-resolved). Read-only.',
     usage: 'shrk trace <query> | shrk trace literal "<string>" [--glob <g>] [--no-aliases] [--limit <n>] [--kind ...] [--deep] [--json]',
     booleanFlags: new Set(['json', 'deep', 'no-aliases']),
@@ -107,7 +125,7 @@ export const traceCommand = {
                     }
                 }
                 process.stdout.write('\nNext commands:\n');
-                process.stdout.write(`  shrk find "${symbol}"\n`);
+                process.stdout.write(`  shrk search "${symbol}"\n`);
                 return 1;
             }
             for (const m of symReport.exactMatches) {
@@ -144,9 +162,16 @@ export const traceCommand = {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const limit = flagNumber(args, 'limit');
+        // Command matches rank against THE command index (injected — it lives
+        // above the inspector). It used to read a property no inspection has.
+        const { buildCommandIndex, getActiveCommandIndex } = await import("../surface/command-index.js");
+        const commandIndex = getActiveCommandIndex() ?? buildCommandIndex();
         const resolution = resolveQuery(inspection, query, {
             ...(kinds.length > 0 ? { kinds: kinds } : {}),
             ...(typeof limit === 'number' ? { limit } : {}),
+            commands: commandIndex.entries
+                .filter((e) => !e.path.startsWith('-'))
+                .map((e) => ({ id: e.path, name: `shrk ${e.path}`, description: e.description })),
         });
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(resolution) + '\n');
@@ -202,7 +227,7 @@ export const traceCommand = {
                 process.stdout.write(`  shrk policy get ${best.id}\n`);
             }
             else if (best.kind === QueryMatchKind.Command) {
-                process.stdout.write(`  shrk commands get ${best.id}\n`);
+                process.stdout.write(`  shrk help ${best.id}\n`);
             }
         }
         return 0;

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

@@ -1 +1 @@
-{"version":3,"file":"watch.command.d.ts","sourceRoot":"","sources":["../../src/commands/watch.command.ts"],"names":[],"mappings":"AAwBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2ChC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,eAkL1B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,EAAE,eAwD9B,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,eA4C9B,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC"}
+{"version":3,"file":"watch.command.d.ts","sourceRoot":"","sources":["../../src/commands/watch.command.ts"],"names":[],"mappings":"AAwBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4ChC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,eAoL1B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,EAAE,eAwD9B,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,eA4C9B,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC"}

package/dist/commands/watch.command.js

@@ -4,6 +4,7 @@ import * as nodePath from 'node:path';
 import { buildTaskPacket, inspectSharkcraft } from '@shrkcrft/inspector';
 import { SemanticIndex, buildFocusedContext, classifyTask, parseTaskTypeOverride, } from '@shrkcrft/embeddings';
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson } from "../output/format-output.js";
 const FEED_DIR = nodePath.join('.sharkcraft', 'feed');
 const DEFAULT_DEBOUNCE_MS = 750;
@@ -53,6 +54,8 @@ function isProcessAlive(pid) {
  */
 export const watchCommand = {
     name: 'watch',
+    // `shrk watch "<task>"`: the positional is the free-form task.
+    positionals: PositionalMode.Free,
     description: 'Emit a focused-context packet on stdout JSONL each time the workspace changes (or every --interval seconds). No LLM calls.',
     usage: 'shrk watch "<task>" [--interval N] [--debounce ms] [--task-type <type>] [--once] [--quiet] [--json]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"why.command.d.ts","sourceRoot":"","sources":["../../src/commands/why.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,UAAU,EAAE,eA+BxB,CAAC"}
+{"version":3,"file":"why.command.d.ts","sourceRoot":"","sources":["../../src/commands/why.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC,eAAO,MAAM,UAAU,EAAE,eAiCxB,CAAC"}

package/dist/commands/why.command.js

@@ -21,9 +21,12 @@
  */
 import { buildWhyReport, inspectSharkcraft, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header } from "../output/format-output.js";
 export const whyCommand = {
     name: 'why',
+    // The positional is a file (or a fuzzy query) — never refused by the guard.
+    positionals: PositionalMode.Free,
     description: 'Explain the constraints that apply to a file: package / layer, path conventions, rules, boundary rules, and related knowledge. Read-only. Pure composition — no LLM, no shell.',
     usage: 'shrk why <file> [--limit 10] [--json]',
     async run(args) {

package/dist/commands/wiring.command.d.ts

@@ -1,11 +1,25 @@
 import { type IWiringExplain } from '@shrkcrft/boundaries';
 import { type ICommandHandler } from '../command-registry.js';
+import type { ISettledVerdict } from '../gates/settled-verdict.js';
+/**
+ * The explained rule's verdict, SETTLED — through the same `settleVerdict` the
+ * gate envelope uses, over the engine's own coverage for the rule. An `errors`
+ * verdict proposes 1; anything else proposes 0 and the coverage vetoes it to 2
+ * on a shortfall. `check wiring --explain` returns this exit (it runs under a
+ * verdict verb, so its `$?` and trailer must not read 0 over a partial rule);
+ * the renderer prints its final line from it.
+ */
+export declare function settleWiringExplain(report: IWiringExplain): ISettledVerdict;
 /**
  * Render an {@link IWiringExplain} to stdout. Shared by `wiring explain`,
- * `wiring test`, and `check wiring --explain` so all three speak the same
- * dialect. JSON emits the full payload; text mirrors `search tuning explain`
- * (header → loaded sets → per-site detail → the set-difference → verdict).
- * Always returns 0 — explain is informational, the verdict is in the output.
+ * `wiring test`, `gates explain` and `check wiring --explain` so all four speak
+ * the same dialect. JSON emits the full payload; text mirrors `search tuning
+ * explain` (header → loaded sets → per-site detail → the set-difference →
+ * verdict). The status, coverage and final line come from the settled rule
+ * (see {@link settleWiringExplain}), so explain can never read clean over a
+ * rule `gates check` reports partial.
+ * Always returns 0 — explain is informational; a verdict verb that wants the
+ * rule's exit reads {@link settleWiringExplain}.
  */
 export declare function renderWiringExplain(report: IWiringExplain, wantJson: boolean): number;
 export declare const wiringCommand: ICommandHandler;

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

@@ -1 +1 @@
-{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAwFrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}
+{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAWL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAY9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAMnE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAQ3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CA+HrF;AAonBD,eAAO,MAAM,aAAa,EAAE,eA+C3B,CAAC"}