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

package/dist/commands/commands.command.js

@@ -1,12 +1,13 @@
-import { flagBool, flagString } from "../command-registry.js";
+import { flagBool, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { BUILTIN_PROFILES, getProfile } from "../surface/profiles.js";
 import { buildCommandSafetyMatrix, COMMAND_CATALOG, CommandLifecycle, commandLifecycle, CommandSurface, commandSurface, commandTaskRole, defaultShowInHelp, R46_OVERLAY, renderCommandSafetyMatrixMarkdown, SafetyLevel } from "./command-catalog.js";
 import { buildCommandTaxonomy, buildPrimaryCommandsReport, renderCommandTaxonomyMarkdown, renderCommandTaxonomyText, renderPrimaryCommandsText } from '@shrkcrft/inspector';
 export function makeCommandsCommand(registry) {
     return {
         name: 'commands',
-        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | machine | legacy | overlaps | taxonomy | matrix | tree | search | suggest | explain | entrypoints | doctor | ux-check.',
-        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|suggest <p>|explain <cmd>|entrypoints|doctor|ux-check] [--all] [--safety <level>] [--category <name>] [--json]',
+        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog, or --profile <id> (e.g. agent) for the surface a profile sees. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | profile | machine | legacy | overlaps | taxonomy | matrix | tree | search | suggest | explain | entrypoints | doctor | ux-check.',
+        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|profile [<id>]|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|suggest <p>|explain <cmd>|entrypoints|doctor|ux-check] [--all] [--profile <id>] [--safety <level>] [--category <name>] [--json]',
         async run(args) {
             const sub = args.positional[0];
             if (sub === 'doctor') {
@@ -95,6 +96,12 @@ export function makeCommandsCommand(registry) {
             if (sub === 'surface') {
                 return runCommandsSurface(args);
             }
+            // `shrk commands profile [<id>]` — list surface profiles, or render the
+            // catalog as one profile sees it (the curated view, e.g. `agent`).
+            if (sub === 'profile') {
+                const id = args.positional[1];
+                return id ? runCommandsProfile(args, id) : runCommandsProfileList(args);
+            }
             if (sub === 'machine') {
                 return runCommandsMachine(args);
             }
@@ -120,8 +127,34 @@ export function makeCommandsCommand(registry) {
             if (sub === 'docs-check') {
                 return runCommandsDocsCheck(args);
             }
+            // `--profile <id>` renders the catalog curated for a surface profile
+            // (e.g. `--profile agent` hides CI/release/pack-maintenance machinery an
+            // inline agent doesn't need). Commands stay callable; this is a listing
+            // filter, not a disable.
+            const profileFilter = flagString(args, 'profile');
+            if (profileFilter) {
+                return runCommandsProfile(args, profileFilter);
+            }
             const safetyFilter = flagString(args, 'safety');
             const categoryFilter = flagString(args, 'category');
+            // Validate the filter values against real allowlists — a typo (e.g.
+            // `--safety read` or `--category typo`) previously matched nothing and
+            // returned "commands (0)" with exit 0, which reads like an empty result
+            // rather than a mistake. Reject with the valid set + exit 2 instead.
+            if (safetyFilter !== undefined) {
+                const validSafety = new Set(Object.values(SafetyLevel));
+                if (!validSafety.has(safetyFilter)) {
+                    process.stderr.write(`Unknown --safety "${safetyFilter}". Valid: ${[...validSafety].sort().join(', ')}\n`);
+                    return 2;
+                }
+            }
+            if (categoryFilter !== undefined) {
+                const validCategories = new Set(COMMAND_CATALOG.map((e) => e.category));
+                if (!validCategories.has(categoryFilter)) {
+                    process.stderr.write(`Unknown --category "${categoryFilter}". Valid: ${[...validCategories].sort().join(', ')}\n`);
+                    return 2;
+                }
+            }
             const wantsAll = flagBool(args, 'all');
             let entries = COMMAND_CATALOG;
             if (safetyFilter) {
@@ -186,6 +219,97 @@ function runCommandsSurface(args) {
     }
     return 0;
 }
+/**
+ * Pure: render the catalog as a surface profile sees it. Every command the
+ * profile lists in `hidden` is filtered out of `entries` (commands stay
+ * callable — this is a listing filter, not a disable). Returns undefined when
+ * the profile id is unknown. Exported for tests.
+ */
+export function buildCommandsProfileView(profileId, packProfiles = []) {
+    const profile = getProfile(profileId, packProfiles);
+    if (!profile)
+        return undefined;
+    const hidden = new Set(profile.hidden ?? []);
+    const entries = COMMAND_CATALOG.filter((e) => !hidden.has(e.command));
+    return { profile, entries, hidden: [...hidden].sort(), catalogTotal: COMMAND_CATALOG.length };
+}
+/**
+ * `shrk commands --profile <id>` / `shrk commands profile <id>` renders the
+ * catalog curated for a surface profile (e.g. `agent` hides
+ * CI/release/pack-maintenance machinery an inline agent doesn't need) without
+ * editing `sharkcraft.config.ts`. Builtin profiles resolve instantly; an
+ * unknown id falls back to discovering pack-contributed profiles via the
+ * surface context (best-effort — needs a workspace).
+ */
+async function runCommandsProfile(args, profileId) {
+    let view = buildCommandsProfileView(profileId);
+    let validIds = BUILTIN_PROFILES.map((p) => p.id);
+    if (!view) {
+        try {
+            const { loadSurfaceContext } = await import("../surface/load-surface-context.js");
+            const ctx = await loadSurfaceContext({ cwd: resolveCwd(args) });
+            validIds = ctx.availableProfiles.map((p) => p.id);
+            view = buildCommandsProfileView(profileId, ctx.availableProfiles);
+        }
+        catch {
+            // Pack discovery failed (e.g. outside a project) — builtin-only.
+        }
+    }
+    if (!view) {
+        process.stderr.write(`Unknown profile "${profileId}". Valid: ${[...validIds].sort().join(', ')}\n`);
+        return 2;
+    }
+    const { profile, entries, hidden, catalogTotal } = view;
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({
+            profile: profile.id,
+            description: profile.description,
+            source: profile.source,
+            total: entries.length,
+            catalogTotal,
+            hiddenCount: hidden.length,
+            hidden,
+            entries,
+        }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Commands — profile=${profile.id} (${entries.length} of ${catalogTotal} visible)`));
+    process.stdout.write(`  ${profile.description}\n`);
+    if (hidden.length > 0) {
+        process.stdout.write(`  (${hidden.length} command(s) hidden by this profile — still callable)\n`);
+    }
+    const grouped = new Map();
+    for (const e of entries) {
+        const arr = grouped.get(e.category) ?? [];
+        arr.push(e);
+        grouped.set(e.category, arr);
+    }
+    for (const [cat, items] of [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        process.stdout.write(`\n## ${cat}\n`);
+        for (const e of items.sort((a, b) => a.command.localeCompare(b.command))) {
+            process.stdout.write(`  ${safetyTag(e.safetyLevel)}  ${e.command.padEnd(34)} ${e.description}\n`);
+        }
+    }
+    return 0;
+}
+/** `shrk commands profile` (no id) lists the available surface profiles. */
+function runCommandsProfileList(args) {
+    const rows = BUILTIN_PROFILES.map((p) => ({
+        id: p.id,
+        description: p.description,
+        hides: (p.hidden ?? []).length,
+    }));
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: rows.length, profiles: rows }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Surface profiles (${rows.length})`));
+    for (const r of rows) {
+        process.stdout.write(`  ${r.id.padEnd(12)} hides=${String(r.hides).padEnd(4)} ${r.description}\n`);
+    }
+    process.stdout.write(`\nUsage: shrk commands profile <id>   |   shrk commands --profile <id>   (render the curated view)\n`);
+    return 0;
+}
 /** `shrk commands machine` lists machine-oriented commands. */
 function runCommandsMachine(args) {
     const matches = COMMAND_CATALOG.filter((e) => commandSurface(e) === CommandSurface.Machine || e.machineOnly === true);
@@ -487,6 +611,10 @@ export const commandsCommand = {
         // Keep the new views available even via the back-compat entry.
         if (sub === 'surface')
             return runCommandsSurface(args);
+        if (sub === 'profile') {
+            const id = args.positional[1];
+            return id ? runCommandsProfile(args, id) : runCommandsProfileList(args);
+        }
         if (sub === 'machine')
             return runCommandsMachine(args);
         if (sub === 'legacy')
@@ -503,6 +631,10 @@ export const commandsCommand = {
             return runCommandsRetirementPlan(args);
         if (sub === 'docs-check')
             return await runCommandsDocsCheck(args);
+        const profileFilter = flagString(args, 'profile');
+        if (profileFilter) {
+            return runCommandsProfile(args, profileFilter);
+        }
         const safetyFilter = flagString(args, 'safety');
         const categoryFilter = flagString(args, 'category');
         let entries = COMMAND_CATALOG;
@@ -882,6 +1014,33 @@ export function buildCommandsDoctorReport(registry) {
                 });
             }
         }
+        // 8. registerSubcommand-only GROUPS without a catalog entry.
+        // Check #7 above only sees depth-1 nodes that carry a handler
+        // (registry.list()). Groups registered purely via registerSubcommand
+        // (e.g. paths / pipelines / checks / audit / ownership) are handler-less
+        // group nodes — they resolve live yet never appear in list(), so the
+        // doctor reported "No issues" while those groups had zero catalog
+        // coverage. Walk listGroups() and flag any group no catalog entry
+        // covers. Pure alias groups (listGroupAliases) are skipped — their
+        // canonical target carries the entry.
+        const aliasGroups = new Set(registry.listGroupAliases().keys());
+        const catalogTopWords = new Set();
+        for (const e of COMMAND_CATALOG) {
+            const top = e.command.split(/\s+/)[0];
+            if (top)
+                catalogTopWords.add(top);
+        }
+        for (const g of registry.listGroups()) {
+            if (aliasGroups.has(g))
+                continue;
+            if (!catalogTopWords.has(g)) {
+                issues.push({
+                    code: 'missing-catalog-entry',
+                    message: `command group "${g}" is registered (registerSubcommand) but no catalog entry covers it`,
+                    severity: 'error',
+                });
+            }
+        }
     }
     const errors = issues.filter((i) => i.severity === 'error').length;
     const warnings = issues.filter((i) => i.severity === 'warning').length;

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

@@ -1 +1 @@
-{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,eAAe,EAAE,eA8F7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqEhC,eAAO,MAAM,eAAe,EAAE,eAoG7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -5,6 +5,35 @@ import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-regist
 import { asJson } from "../output/format-output.js";
 import { ccrDir, openCcrStore } from "../output/ccr-store-config.js";
 const CONTENT_TYPES = new Set(Object.values(EContentType));
+// `--type` accepts the EContentType wire strings plus ergonomic aliases. `code`
+// is an alias for `source-code`: it routes to the structure-preserving code
+// outline (ECompressionStrategy.Code), NOT the markdown line-omission a bare
+// `code` used to silently fall through to under auto-detect.
+const TYPE_ALIASES = {
+    code: EContentType.SourceCode,
+};
+// The full set of accepted `--type` tokens (content-type wire strings +
+// aliases), sorted and rendered once so the rejection message and the
+// passthrough hint advertise exactly what `resolveContentType` accepts.
+const VALID_TYPE_TOKENS = [...CONTENT_TYPES, ...Object.keys(TYPE_ALIASES)].sort().join(', ');
+/**
+ * Resolve a raw `--type` value into a forced {@link EContentType}. Unlike the
+ * old `CONTENT_TYPES.has` check — which silently dropped unknown values and let
+ * the phantom `code` fall through to auto-detect (markdown line-omission) — an
+ * unrecognized non-empty value yields an `error` so the caller can reject with a
+ * non-zero exit, and `code` is mapped to the real source-code strategy. A
+ * missing/empty value is a no-op (auto-detect).
+ */
+function resolveContentType(raw) {
+    if (raw === undefined || raw === '')
+        return {};
+    const aliased = TYPE_ALIASES[raw];
+    if (aliased)
+        return { type: aliased };
+    if (CONTENT_TYPES.has(raw))
+        return { type: raw };
+    return { error: `compress: unknown --type "${raw}". Valid types: ${VALID_TYPE_TOKENS}.` };
+}
 // Below this size a passthrough no-op isn't worth a warning (tiny snippets
 // legitimately have nothing to compress). Above it, a silent `−0%` re-emit is
 // the opposite of the tool's purpose — nudge the user toward `--type`.
@@ -36,6 +65,13 @@ export const compressCommand = {
     booleanFlags: COMPRESS_BOOLEAN_FLAGS,
     run(args) {
         const cwd = resolveCwd(args);
+        // Validate `--type` up front: an unknown value is a user error, not a
+        // silent fall-through to auto-detect — fail fast before reading input.
+        const resolvedType = resolveContentType(flagString(args, 'type'));
+        if (resolvedType.error) {
+            process.stderr.write(resolvedType.error + '\n');
+            return 1;
+        }
         let content;
         try {
             content = readInput(args);
@@ -59,9 +95,8 @@ export const compressCommand = {
             opts.maxItems = Math.floor(max);
         if (flagBool(args, 'lossless'))
             opts.lossless = true;
-        const type = flagString(args, 'type');
-        if (type && CONTENT_TYPES.has(type))
-            opts.contentType = type;
+        if (resolvedType.type)
+            opts.contentType = resolvedType.type;
         const result = compressContent(content, opts);
         const pct = Math.round(result.savings.ratio * 100);
         // A lossy result with no cached original (i.e. --no-cache) can't be undone
@@ -109,7 +144,7 @@ export const compressCommand = {
             inputBytes >= PASSTHROUGH_HINT_MIN_BYTES &&
             !flagBool(args, 'lossless')) {
             process.stderr.write(`hint: nothing was compressed — auto-detect classified this as ${result.contentType} and found no win. ` +
-                'Try `--type <content-type>` to force a strategy (json, git-diff, search-results, build-log, source-code, markdown).\n');
+                `Try \`--type <content-type>\` to force a strategy (${VALID_TYPE_TOKENS}).\n`);
         }
         return 0;
     },

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

@@ -1 +1 @@
-{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,cAAc,EAAE,eAyI5B,CAAC"}
+{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,cAAc,EAAE,eA2I5B,CAAC"}

package/dist/commands/context.command.js

@@ -1,4 +1,4 @@
-import { entrypointBanner, inspectSharkcraft } from '@shrkcrft/inspector';
+import { contextTuningBoostFor, entrypointBanner, inspectSharkcraft } from '@shrkcrft/inspector';
 import { buildContext } from '@shrkcrft/context';
 import { loadIntentBenchmark, runIntentBenchmark, STARTER_INTENT_BENCHMARK, writeBenchmarkRun, } from '@shrkcrft/context-planner';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
@@ -67,6 +67,7 @@ export const contextCommand = {
         const includeCommands = flagBool(args, 'include-commands');
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+        const contextBoost = contextTuningBoostFor(inspection, task);
         const result = buildContext(inspection.knowledgeEntries, {
             task,
             framework,
@@ -81,6 +82,7 @@ export const contextCommand = {
             includeDocs,
             includeCommands,
             projectOverview: renderOverviewText(overview),
+            ...(contextBoost ? { boostFor: contextBoost } : {}),
         });
         // Surface top commands prominently before the long context body.
         // Auto-promote commands-first for action-like tasks (rename / add /

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

@@ -1 +1 @@
-{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eA6D5B,CAAC"}
+{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eAyG5B,CAAC"}

package/dist/commands/daily.commands.js

@@ -186,14 +186,33 @@ export const explainCommand = {
         const top = inspection.knowledgeEntries
             .filter((e) => matches(topic, e.id, e.title, e.content, e.tags.join(' ')))
             .slice(0, maxEntries);
+        // Surface the matched items themselves, not just counts. `explain`
+        // otherwise duplicates `shrk search`'s job while hiding what matched.
+        const relevantRules = packet.relevantRules.map((r) => ({
+            id: r.id,
+            title: r.title,
+            priority: r.priority,
+        }));
+        const relevantPaths = packet.relevantPaths.map((p) => ({
+            id: p.id,
+            title: p.title,
+            priority: p.priority,
+        }));
+        const relevantTemplates = packet.relevantTemplates.map((t) => ({
+            id: t.id,
+            name: t.name,
+        }));
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 topic,
                 summary: {
-                    relevantRules: packet.relevantRules.length,
-                    relevantPaths: packet.relevantPaths.length,
-                    relevantTemplates: packet.relevantTemplates.length,
+                    relevantRules: relevantRules.length,
+                    relevantPaths: relevantPaths.length,
+                    relevantTemplates: relevantTemplates.length,
                 },
+                relevantRules,
+                relevantPaths,
+                relevantTemplates,
                 entries: top.map((e) => ({
                     id: e.id,
                     title: e.title,
@@ -205,11 +224,35 @@ export const explainCommand = {
             return 0;
         }
         process.stdout.write(header(`explain: ${topic}`));
-        process.stdout.write(kv('matches', `rules=${packet.relevantRules.length} paths=${packet.relevantPaths.length} templates=${packet.relevantTemplates.length}`) + '\n\n');
+        process.stdout.write(kv('matches', `rules=${relevantRules.length} paths=${relevantPaths.length} templates=${relevantTemplates.length}`) + '\n\n');
+        if (relevantRules.length > 0) {
+            process.stdout.write('Rules:\n');
+            for (const r of relevantRules) {
+                process.stdout.write(`  • [${r.priority}] ${r.id} — ${r.title}\n`);
+            }
+            process.stdout.write('\n');
+        }
+        if (relevantPaths.length > 0) {
+            process.stdout.write('Paths:\n');
+            for (const p of relevantPaths) {
+                process.stdout.write(`  • [${p.priority}] ${p.id} — ${p.title}\n`);
+            }
+            process.stdout.write('\n');
+        }
+        if (relevantTemplates.length > 0) {
+            process.stdout.write('Templates:\n');
+            for (const t of relevantTemplates) {
+                process.stdout.write(`  • ${t.id} — ${t.name}\n`);
+            }
+            process.stdout.write('\n');
+        }
         if (top.length === 0) {
-            process.stdout.write('(no matching knowledge entries)\n');
+            if (relevantRules.length + relevantPaths.length + relevantTemplates.length === 0) {
+                process.stdout.write('(no matching knowledge entries)\n');
+            }
             return 0;
         }
+        process.stdout.write('Knowledge:\n');
         for (const e of top) {
             process.stdout.write(`• [${e.priority}] ${e.id} — ${e.title}\n`);
             const body = e.content

package/dist/commands/diff-check.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0GhC,eAAO,MAAM,gBAAgB,EAAE,eAiI9B,CAAC"}
+{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6GhC,eAAO,MAAM,gBAAgB,EAAE,eAkI9B,CAAC"}

package/dist/commands/diff-check.command.js

@@ -34,9 +34,12 @@ function resolveScope(args, cwd) {
     const staged = flagBool(args, 'staged');
     const since = flagString(args, 'since');
     const filesRaw = flagString(args, 'files');
+    // Files come from `--files a,b` or as bare positional args
+    // (`shrk diff-check a.ts b.ts`). Positionals were previously ignored, which
+    // silently widened the scope back to the full worktree.
     const files = filesRaw
         ? filesRaw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
-        : [];
+        : args.positional.filter((s) => s.length > 0);
     if (files.length > 0) {
         return { mode: 'files', options: { projectRoot: cwd, files } };
     }
@@ -97,7 +100,8 @@ function deriveVerdict(env) {
 export const diffCheckCommand = {
     name: 'diff-check',
     description: 'Self-check the current git diff against this project\'s boundary + import-hygiene rules. Single-call composite of `shrk check boundaries --changed-only` + `shrk check imports --changed-only`, with one verdict and one nextAction line. Designed for AI agents to run after editing — pass --json for the structured envelope.',
-    usage: 'shrk [--cwd <dir>] diff-check [--staged | --since <ref> | --files a.ts,b.ts] [--json]',
+    usage: 'shrk [--cwd <dir>] diff-check [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
+    booleanFlags: new Set(['json', 'staged']),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');

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

@@ -1 +1 @@
-{"version":3,"file":"feedback.command.d.ts","sourceRoot":"","sources":["../../src/commands/feedback.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,qBAAqB,EAAE,eAiCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyDpC,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,eAwB7C,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eAqBtC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAiDxC,CAAC;AAGF,eAAO,MAAM,sBAAsB,EAAE,eAqBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA6BjC,CAAC"}
+{"version":3,"file":"feedback.command.d.ts","sourceRoot":"","sources":["../../src/commands/feedback.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC,eAAO,MAAM,qBAAqB,EAAE,eAiCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyDpC,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,eAwB7C,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eAqBtC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAoDxC,CAAC;AAGF,eAAO,MAAM,sBAAsB,EAAE,eAqBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA6BjC,CAAC"}

package/dist/commands/feedback.command.js

@@ -10,6 +10,7 @@ import * as nodePath from 'node:path';
 import { FeedbackBucket, ingestFeedbackFile, inspectSharkcraft, loadFeedbackRules, renderFeedbackBacklog, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { feedbackRulesDoctorHints, renderFailureHints } from "../output/failure-hints.js";
 function ingestPositional(args) {
     return args.positional[0];
 }
@@ -256,6 +257,9 @@ export const feedbackRulesDoctorCommand = {
             process.stdout.write(`  ERROR   ${e.id}: ${e.message}\n`);
         for (const w of warnings)
             process.stdout.write(`  WARN    ${w.id}: ${w.message}\n`);
+        if (errors.length > 0) {
+            process.stdout.write(renderFailureHints(feedbackRulesDoctorHints()));
+        }
         return errors.length > 0 ? 1 : 0;
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"framework.command.d.ts","sourceRoot":"","sources":["../../src/commands/framework.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC"}
+{"version":3,"file":"framework.command.d.ts","sourceRoot":"","sources":["../../src/commands/framework.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC"}

package/dist/commands/framework.command.js

@@ -1,7 +1,8 @@
 import { buildRegistryWithPacks, defaultRegistry, FrameworkQueryApi, runExtractors, } from '@shrkcrft/framework-scanners';
 import { inspectSharkcraft } from '@shrkcrft/inspector';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagPositiveInt, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { computeMtimeFreshness } from "../status/freshness.js";
 /**
  * `shrk framework` — run / inspect the framework-aware extractors.
  *
@@ -109,8 +110,20 @@ async function runStatus(args) {
     }
     const api = FrameworkQueryApi.fromStore(cwd);
     const m = api.manifest();
+    // Honest freshness: the framework store is stale once a source file changed
+    // after it was built. Mirror the `state + lastBuiltAt + drift` shape that
+    // `graph status` exposes.
+    const fresh = computeMtimeFreshness(cwd, m.lastBuiltAt);
     if (wantJson) {
-        process.stdout.write(asJson({ ok: true, manifest: m }) + '\n');
+        process.stdout.write(asJson({
+            ok: true,
+            state: fresh.state,
+            lastBuiltAt: m.lastBuiltAt,
+            lastChangedAt: fresh.lastChangedAt,
+            behindMs: fresh.behindMs,
+            ...(fresh.state === 'stale' ? { nextCommand: 'shrk framework index' } : {}),
+            manifest: m,
+        }) + '\n');
         return 0;
     }
     process.stdout.write(header('Framework status'));
@@ -120,6 +133,10 @@ async function runStatus(args) {
         process.stdout.write(kv(`  ${k}`, String(v)) + '\n');
     }
     process.stdout.write(kv('last built', m.lastBuiltAt) + '\n');
+    process.stdout.write(kv('state', fresh.state) + '\n');
+    if (fresh.state === 'stale') {
+        process.stdout.write(`! stale — source changed since last build${fresh.lastChangedAt ? ` (last change ${fresh.lastChangedAt})` : ''}; re-run \`shrk framework index\`\n`);
+    }
     return 0;
 }
 async function runList(args) {
@@ -134,7 +151,7 @@ async function runList(args) {
     const framework = flagString(args, 'framework');
     const subtype = flagString(args, 'subtype');
     const file = flagString(args, 'file');
-    const limit = Number(flagString(args, 'limit') ?? '50');
+    const limit = flagPositiveInt(args, 'limit', 50);
     const entities = api.list({
         ...(framework ? { framework } : {}),
         ...(subtype ? { subtype } : {}),

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

@@ -1 +1 @@
-{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eA0GzB,CAAC"}
+{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAiMzB,CAAC"}