@shrkcrft/cli 0.1.0-alpha.2

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

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const testCommand: ICommandHandler;
+//# sourceMappingURL=test.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"test.command.d.ts","sourceRoot":"","sources":["../../src/commands/test.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6QhC,eAAO,MAAM,WAAW,EAAE,eA4BzB,CAAC"}

package/dist/commands/test.command.js

@@ -0,0 +1,262 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildTaskPacket, inspectSharkcraft, loadAgentContractTests, loadContextTests, runAgentContractTest, runContextTest, } from '@shrkcrft/inspector';
+import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+import { maybeRunInWatchMode } from "../output/watch-loop.js";
+async function runContextTests(args) {
+    const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+    const all = await loadContextTests(inspection);
+    const filter = flagString(args, 'id');
+    const tests = filter ? all.filter((t) => t.id === filter) : all;
+    if (tests.length === 0) {
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ tests: 0, results: [] }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Context tests'));
+        process.stdout.write('No context tests configured.\n');
+        return 0;
+    }
+    const results = tests.map((t) => runContextTest(inspection, t));
+    const failed = results.filter((r) => !r.passed);
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: results.length, failed: failed.length, results }) + '\n');
+        return failed.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header(`Context tests (${results.length})`));
+    for (const r of results) {
+        const tag = r.passed ? 'PASS' : 'FAIL';
+        process.stdout.write(`  ${tag}  ${r.id.padEnd(36)} task: ${r.task}\n`);
+        if (!r.passed) {
+            if (r.missingInclude.length) {
+                process.stdout.write(`         missing must-include: ${r.missingInclude.join(', ')}\n`);
+            }
+            if (r.unexpectedInclude.length) {
+                process.stdout.write(`         unexpected: ${r.unexpectedInclude.join(', ')}\n`);
+            }
+            for (const d of r.diagnostics ?? []) {
+                process.stdout.write(`         · ${d.id} (${d.existsInRegistry ? 'exists' : 'missing from registry'}):\n`);
+                for (const s of d.suggestions)
+                    process.stdout.write(`             - ${s}\n`);
+                if (d.topAlternatives?.length) {
+                    process.stdout.write('             top-ranked instead:\n');
+                    for (const a of d.topAlternatives.slice(0, 3)) {
+                        process.stdout.write(`               [${a.score}] ${a.id} — ${a.reasons.join('; ')}\n`);
+                    }
+                }
+            }
+        }
+    }
+    process.stdout.write(`\nSummary: ${results.length - failed.length}/${results.length} passed.\n`);
+    return failed.length > 0 ? 1 : 0;
+}
+async function runAgentTests(args) {
+    const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+    const all = await loadAgentContractTests(inspection);
+    const filter = flagString(args, 'id');
+    const tests = filter ? all.filter((t) => t.id === filter) : all;
+    if (tests.length === 0) {
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ tests: 0, results: [] }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Agent contract tests'));
+        process.stdout.write('No agent contract tests configured.\n');
+        return 0;
+    }
+    // Pre-load policy / construct / playbook id sets so the runner can
+    // evaluate strict expectations accurately.
+    const { loadAgentContractRegistries } = await import('@shrkcrft/inspector');
+    const registries = await loadAgentContractRegistries(inspection);
+    const results = tests.map((t) => runAgentContractTest(inspection, t, registries));
+    const failed = results.filter((r) => !r.passed);
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: results.length, failed: failed.length, results }) + '\n');
+        return failed.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header(`Agent contract tests (${results.length})`));
+    for (const r of results) {
+        const tag = r.passed ? 'PASS' : 'FAIL';
+        process.stdout.write(`  ${tag}  ${r.id.padEnd(36)} task: ${r.task}\n`);
+        if (!r.passed) {
+            if (r.expectedPipeline) {
+                process.stdout.write(`         expected pipeline: ${r.expectedPipeline}\n`);
+                process.stdout.write(`         actual pipelines:  ${r.actualPipelines?.join(', ') ?? '(none)'}\n`);
+            }
+            if ((r.missingTemplates ?? []).length)
+                process.stdout.write(`         missing templates: ${r.missingTemplates.join(', ')}\n`);
+            if ((r.missingRules ?? []).length)
+                process.stdout.write(`         missing rules: ${r.missingRules.join(', ')}\n`);
+            if ((r.missingForbiddenActions ?? []).length)
+                process.stdout.write(`         missing forbidden: ${r.missingForbiddenActions.join('; ')}\n`);
+            if ((r.missingVerificationCommands ?? []).length)
+                process.stdout.write(`         missing verification: ${r.missingVerificationCommands.join('; ')}\n`);
+            if ((r.missingHelpers ?? []).length)
+                process.stdout.write(`         missing helpers: ${r.missingHelpers.join(', ')}\n`);
+            if ((r.missingPlaybooks ?? []).length)
+                process.stdout.write(`         missing playbooks: ${r.missingPlaybooks.join(', ')}\n`);
+            if ((r.missingPolicies ?? []).length)
+                process.stdout.write(`         missing policies: ${r.missingPolicies.join(', ')}\n`);
+            if ((r.missingConstructs ?? []).length)
+                process.stdout.write(`         missing constructs: ${r.missingConstructs.join(', ')}\n`);
+            if ((r.missingCommands ?? []).length)
+                process.stdout.write(`         missing commands: ${r.missingCommands.join(', ')}\n`);
+            if ((r.missingKnowledge ?? []).length)
+                process.stdout.write(`         missing knowledge: ${r.missingKnowledge.join(', ')}\n`);
+            if ((r.unexpectedlyIncluded ?? []).length)
+                process.stdout.write(`         unexpectedly included: ${r.unexpectedlyIncluded.join(', ')}\n`);
+            for (const d of r.diagnostics ?? []) {
+                process.stdout.write(`         · ${d.kind}: ${d.id} (${d.existsInRegistry ? 'exists' : 'missing from registry'}):\n`);
+                for (const s of d.suggestions)
+                    process.stdout.write(`             - ${s}\n`);
+            }
+        }
+    }
+    process.stdout.write(`\nSummary: ${results.length - failed.length}/${results.length} passed.\n`);
+    return failed.length > 0 ? 1 : 0;
+}
+async function generateContextTest(args) {
+    const task = args.positional.join(' ').trim();
+    if (!task) {
+        process.stderr.write('Usage: shrk test generate context "<task>"\n');
+        return 2;
+    }
+    const cwd = resolveCwd(args);
+    const inspection = await inspectSharkcraft({ cwd });
+    const packet = buildTaskPacket(inspection, task, { maxTokens: 3000 });
+    const id = `inferred.context.${slug(task)}`;
+    const body = renderContextTestDraft(id, task, packet);
+    return writeDraft(args, cwd, 'context-tests.draft.ts', body, { id, task });
+}
+async function generateAgentTest(args) {
+    const task = args.positional.join(' ').trim();
+    if (!task) {
+        process.stderr.write('Usage: shrk test generate agent "<task>" [--pipeline <id>] [--template <id>] [--rule <id>]\n');
+        return 2;
+    }
+    const cwd = resolveCwd(args);
+    const inspection = await inspectSharkcraft({ cwd });
+    const packet = buildTaskPacket(inspection, task, { maxTokens: 3000 });
+    const id = `inferred.agent.${slug(task)}`;
+    const pipeline = flagString(args, 'pipeline') ?? packet.recommendedPipelines[0]?.pipelineId;
+    const templates = flagList(args, 'template');
+    const rules = flagList(args, 'rule');
+    const templatePicks = templates.length > 0 ? templates : packet.relevantTemplates.slice(0, 3).map((t) => t.id);
+    const rulePicks = rules.length > 0 ? rules : packet.relevantRules.slice(0, 3).map((r) => r.id);
+    const body = renderAgentTestDraft(id, task, {
+        pipeline: pipeline ?? undefined,
+        templates: templatePicks,
+        rules: rulePicks,
+        forbiddenActions: packet.forbiddenActions,
+        verificationCommands: packet.verificationCommands,
+    });
+    return writeDraft(args, cwd, 'agent-tests.draft.ts', body, { id, task });
+}
+function writeDraft(args, cwd, filename, body, summary) {
+    const wantJson = flagBool(args, 'json');
+    const wantWrite = flagBool(args, 'write');
+    const outDir = nodePath.join(cwd, 'sharkcraft', 'test-drafts');
+    const outFile = nodePath.join(outDir, filename);
+    if (!wantWrite) {
+        if (wantJson) {
+            process.stdout.write(asJson({ mode: 'dry-run', outFile, ...summary, bytes: body.length }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Test draft (dry-run): ${summary.id}`));
+        process.stdout.write(kv('outFile', outFile) + '\n');
+        process.stdout.write(kv('task', summary.task) + '\n\n');
+        process.stdout.write(body);
+        return 0;
+    }
+    mkdirSync(outDir, { recursive: true });
+    if (!outFile.startsWith(outDir + nodePath.sep)) {
+        process.stderr.write('Refusing to write outside test-drafts dir.\n');
+        return 1;
+    }
+    writeFileSync(outFile, body, 'utf8');
+    if (wantJson) {
+        process.stdout.write(asJson({ mode: 'write', outFile, ...summary, bytes: body.length }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Test draft written: ${summary.id}`));
+    process.stdout.write(kv('outFile', outFile) + '\n');
+    return 0;
+}
+function renderContextTestDraft(id, task, packet) {
+    const lines = [];
+    lines.push('// Context-test draft. Move into sharkcraft/context-tests.ts after review.');
+    lines.push('export default [');
+    lines.push(`  {`);
+    lines.push(`    id: '${id}',`);
+    lines.push(`    task: ${JSON.stringify(task)},`);
+    lines.push(`    mustInclude: [`);
+    for (const r of packet.relevantRules.slice(0, 5)) {
+        lines.push(`      '${r.id}',`);
+    }
+    for (const t of packet.relevantTemplates.slice(0, 3)) {
+        lines.push(`      '${t.id}',`);
+    }
+    lines.push(`    ],`);
+    lines.push(`    mustNotInclude: [],`);
+    lines.push(`  },`);
+    lines.push('];');
+    return lines.join('\n') + '\n';
+}
+function renderAgentTestDraft(id, task, picks) {
+    const lines = [];
+    lines.push('// Agent-contract test draft. Move into sharkcraft/agent-tests.ts after review.');
+    lines.push('export default [');
+    lines.push(`  {`);
+    lines.push(`    id: '${id}',`);
+    lines.push(`    task: ${JSON.stringify(task)},`);
+    if (picks.pipeline)
+        lines.push(`    expectedPipeline: '${picks.pipeline}',`);
+    lines.push(`    expectedTemplates: ${JSON.stringify(picks.templates)},`);
+    lines.push(`    expectedRules: ${JSON.stringify(picks.rules)},`);
+    if (picks.forbiddenActions.length > 0) {
+        lines.push(`    expectedForbiddenActions: ${JSON.stringify([...picks.forbiddenActions])},`);
+    }
+    if (picks.verificationCommands.length > 0) {
+        lines.push(`    expectedVerificationCommands: ${JSON.stringify([...picks.verificationCommands])},`);
+    }
+    lines.push(`  },`);
+    lines.push('];');
+    return lines.join('\n') + '\n';
+}
+function slug(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32);
+}
+export const testCommand = {
+    name: 'test',
+    description: 'Run or generate SharkCraft regression tests: `test context` / `test agent`, or `test generate context|agent "<task>"`.',
+    usage: 'shrk [--cwd <dir>] test <context|agent|generate> [args...] [--id <id>] [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        const sliced = { ...args, positional: args.positional.slice(1) };
+        if (sub === 'context')
+            return runContextTests(sliced);
+        if (sub === 'agent') {
+            const watchExit = await maybeRunInWatchMode(sliced, runAgentTests);
+            if (watchExit !== null)
+                return watchExit;
+            return runAgentTests(sliced);
+        }
+        if (sub === 'generate') {
+            const which = args.positional[1];
+            const sliced2 = { ...args, positional: args.positional.slice(2) };
+            if (which === 'context')
+                return generateContextTest(sliced2);
+            if (which === 'agent')
+                return generateAgentTest(sliced2);
+            process.stderr.write('Usage: shrk test generate <context|agent> "<task>" [--write]\n');
+            return 2;
+        }
+        process.stderr.write('Usage: shrk test <context|agent|generate> [--id <id>]\n');
+        return 2;
+    },
+};

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

@@ -0,0 +1,5 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const testsImpactCommand: ICommandHandler;
+export declare const testsSuggestCommand: ICommandHandler;
+export declare const testsMissingCommand: ICommandHandler;
+//# sourceMappingURL=tests.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tests.command.d.ts","sourceRoot":"","sources":["../../src/commands/tests.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiChC,eAAO,MAAM,kBAAkB,EAAE,eAyBhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAajC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAgBjC,CAAC"}

package/dist/commands/tests.command.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { analyzeTestImpact, inspectSharkcraft, readFeatureBundle, suggestTestPathFor, } from '@shrkcrft/inspector';
+import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+function collectFiles(cwd, args) {
+    const files = flagList(args, 'files');
+    const planFile = flagString(args, 'plan');
+    const bundleId = flagString(args, 'bundle');
+    const out = [...files];
+    if (planFile) {
+        const path = nodePath.isAbsolute(planFile) ? planFile : nodePath.join(cwd, planFile);
+        if (existsSync(path)) {
+            try {
+                const parsed = JSON.parse(readFileSync(path, 'utf8'));
+                const changes = parsed.changes ?? parsed.plan?.changes ?? [];
+                for (const c of changes)
+                    if (c.relativePath)
+                        out.push(c.relativePath);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    if (bundleId) {
+        const b = readFeatureBundle(cwd, bundleId);
+        if (b) {
+            for (const f of b.affectedFiles)
+                out.push(f);
+            for (const p of b.plans)
+                for (const t of p.expectedTargets)
+                    out.push(t);
+        }
+    }
+    return [...new Set(out)];
+}
+export const testsImpactCommand = {
+    name: 'impact',
+    description: 'Test impact analysis for changed files / plan / bundle.',
+    usage: 'shrk tests impact [--files a,b] [--plan <plan>] [--bundle <id>] "<task>"',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const task = args.positional.join(' ').trim() || undefined;
+        const files = collectFiles(cwd, args);
+        const result = analyzeTestImpact(inspection, {
+            ...(task ? { task } : {}),
+            files,
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(result) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Test impact (${files.length} files)`));
+        process.stdout.write(`Likely tests: ${result.likelyTestFiles.length}\n`);
+        for (const f of result.likelyTestFiles.slice(0, 10))
+            process.stdout.write(`  + ${f}\n`);
+        process.stdout.write(`Missing tests: ${result.missingTestFiles.length}\n`);
+        for (const f of result.missingTestFiles.slice(0, 10))
+            process.stdout.write(`  - ${f}\n`);
+        process.stdout.write(`Confidence: ${result.confidence}%\n`);
+        return 0;
+    },
+};
+export const testsSuggestCommand = {
+    name: 'suggest',
+    description: 'Suggest where a test for a given file should live.',
+    usage: 'shrk tests suggest <file>',
+    run(args) {
+        const file = args.positional[0];
+        if (!file) {
+            process.stderr.write('Usage: shrk tests suggest <file>\n');
+            return 2;
+        }
+        process.stdout.write(suggestTestPathFor(file) + '\n');
+        return 0;
+    },
+};
+export const testsMissingCommand = {
+    name: 'missing',
+    description: 'Show missing test files for the given inputs.',
+    usage: 'shrk tests missing --files a,b',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const files = collectFiles(cwd, args);
+        const r = analyzeTestImpact(inspection, { files });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ missing: r.missingTestFiles }) + '\n');
+            return 0;
+        }
+        for (const f of r.missingTestFiles)
+            process.stdout.write(f + '\n');
+        return 0;
+    },
+};

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

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const traceCommand: ICommandHandler;
+//# sourceMappingURL=trace.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,YAAY,EAAE,eAsG1B,CAAC"}

package/dist/commands/trace.command.js

@@ -0,0 +1,121 @@
+/**
+ * Top-level fuzzy `shrk trace <query>`.
+ *
+ * Accepts a free-form query (file path, construct id, plugin key, symbol,
+ * helper id, template id, knowledge id, command name). Resolves via the
+ * shared query resolver and prints structured trace output.
+ */
+import { findSymbolInProject, inspectSharkcraft, QueryMatchKind, resolveQuery, } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header } 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)}]`;
+}
+export const traceCommand = {
+    name: 'trace',
+    description: 'Fuzzy trace — accept any free-form query (file path, construct id, symbol, plugin key, helper id, template id, knowledge id, command). Read-only.',
+    usage: 'shrk trace <query> [--limit <n>] [--kind file|construct|knowledge|template|helper|playbook|policy|command] [--deep] [--json]',
+    async run(args) {
+        // Direct symbol trace via --symbol <Name>
+        const symbol = flagString(args, 'symbol');
+        if (symbol) {
+            const cwd = resolveCwd(args);
+            const language = (flagString(args, 'language') ?? 'auto');
+            const symReport = findSymbolInProject(cwd, symbol, { language });
+            if (flagBool(args, 'json')) {
+                process.stdout.write(asJson(symReport) + '\n');
+                return symReport.exactMatches.length > 0 ? 0 : 1;
+            }
+            process.stdout.write(header(`Trace symbol: ${symbol}`));
+            if (symReport.exactMatches.length === 0) {
+                process.stdout.write('  no exact-export or exact-local matches.\n');
+                if (symReport.textMatches.length > 0) {
+                    process.stdout.write(`  ${symReport.textMatches.length} probable-text matches:\n`);
+                    for (const t of symReport.textMatches.slice(0, 8)) {
+                        process.stdout.write(`    • ${t.relativePath}\n`);
+                    }
+                }
+                process.stdout.write('\nNext commands:\n');
+                process.stdout.write(`  shrk find "${symbol}"\n`);
+                return 1;
+            }
+            for (const m of symReport.exactMatches) {
+                process.stdout.write(`  ${m.resolution.padEnd(13)} ${m.relativePath}${m.line ? `:${m.line}` : ''}\n`);
+            }
+            if (symReport.primaryFile) {
+                process.stdout.write(`\nPrimary file: ${symReport.primaryFile}\n`);
+                process.stdout.write(`\nNext commands:\n`);
+                process.stdout.write(`  shrk impact --symbol ${symbol}\n`);
+                process.stdout.write(`  shrk impact ${symReport.primaryFile}\n`);
+            }
+            else {
+                process.stdout.write(`\nAmbiguous — ${symReport.exactMatches.length} exact matches.\n`);
+            }
+            return 0;
+        }
+        const query = args.positional.join(' ').trim();
+        if (!query) {
+            process.stderr.write('Usage: shrk trace <query> | shrk trace --symbol <Name>\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const limit = flagNumber(args, 'limit');
+        const resolution = resolveQuery(inspection, query, {
+            ...(typeof limit === 'number' ? { limit } : {}),
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(resolution) + '\n');
+            return resolution.bestMatch ? 0 : 1;
+        }
+        process.stdout.write(header(`Trace: ${query}`));
+        if (!resolution.bestMatch) {
+            process.stdout.write('  no matches found.\n');
+            return 1;
+        }
+        process.stdout.write(`Confidence: ${resolution.confidence}\n`);
+        process.stdout.write(`Best:    ${describeMatch(resolution.bestMatch)}\n`);
+        if (resolution.bestMatch.reason) {
+            process.stdout.write(`         reason: ${resolution.bestMatch.reason}\n`);
+        }
+        if (resolution.alternatives.length > 0) {
+            process.stdout.write('Alternatives:\n');
+            for (const alt of resolution.alternatives) {
+                process.stdout.write(`  • ${describeMatch(alt)}\n`);
+            }
+        }
+        if (flagBool(args, 'deep')) {
+            const best = resolution.bestMatch;
+            process.stdout.write('\nFollow-up commands:\n');
+            if (best.kind === QueryMatchKind.Construct) {
+                process.stdout.write(`  shrk constructs trace ${best.id} --deep\n`);
+                process.stdout.write(`  shrk constructs impact ${best.id} --json\n`);
+            }
+            else if (best.kind === QueryMatchKind.File) {
+                process.stdout.write(`  shrk impact ${best.id}\n`);
+            }
+            else if (best.kind === QueryMatchKind.Knowledge) {
+                process.stdout.write(`  shrk knowledge get ${best.id}\n`);
+            }
+            else if (best.kind === QueryMatchKind.Template) {
+                process.stdout.write(`  shrk templates get ${best.id}\n`);
+                process.stdout.write(`  shrk templates preview ${best.id}\n`);
+            }
+            else if (best.kind === QueryMatchKind.Helper) {
+                process.stdout.write(`  shrk helper get ${best.id}\n`);
+                process.stdout.write(`  shrk helper plan ${best.id} --json\n`);
+            }
+            else if (best.kind === QueryMatchKind.Playbook) {
+                process.stdout.write(`  shrk playbooks get ${best.id}\n`);
+                process.stdout.write(`  shrk playbooks runbook ${best.id}\n`);
+            }
+            else if (best.kind === QueryMatchKind.Policy) {
+                process.stdout.write(`  shrk policy get ${best.id}\n`);
+            }
+            else if (best.kind === QueryMatchKind.Command) {
+                process.stdout.write(`  shrk commands get ${best.id}\n`);
+            }
+        }
+        return 0;
+    },
+};

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

@@ -0,0 +1,4 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const upgradeCheckCommand: ICommandHandler;
+export declare const upgradePlanCommand: ICommandHandler;
+//# sourceMappingURL=upgrade.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.command.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.command.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,mBAAmB,EAAE,eAwBjC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAWhC,CAAC"}

package/dist/commands/upgrade.command.js

@@ -0,0 +1,43 @@
+import { buildUpgradeAdvice, inspectSharkcraft, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+export const upgradeCheckCommand = {
+    name: 'check',
+    description: 'Check for SharkCraft schema migrations. Read-only; never auto-migrates.',
+    usage: 'shrk upgrade check [--from <ver>] [--to <ver>] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const report = buildUpgradeAdvice(inspection, {
+            ...(flagString(args, 'from') ? { from: flagString(args, 'from') } : {}),
+            ...(flagString(args, 'to') ? { to: flagString(args, 'to') } : {}),
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        process.stdout.write(`=== Upgrade advisor ===\n  from ${report.fromVersion}\n  to   ${report.toVersion}\n`);
+        process.stdout.write('Detected schemas:\n');
+        for (const [k, v] of Object.entries(report.detectedSchemas))
+            process.stdout.write(`  ${k.padEnd(48)} ${v}\n`);
+        process.stdout.write('Findings:\n');
+        for (const f of report.findings)
+            process.stdout.write(`  [${f.severity}] ${f.id} — ${f.message}\n  → ${f.suggestedAction}\n`);
+        process.stdout.write('Recommended steps:\n');
+        for (const s of report.recommendedSteps)
+            process.stdout.write(`  $ ${s}\n`);
+        return 0;
+    },
+};
+export const upgradePlanCommand = {
+    name: 'plan',
+    description: 'Plan a SharkCraft upgrade — alias for `upgrade check`, surfaces JSON.',
+    usage: 'shrk upgrade plan [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const report = buildUpgradeAdvice(inspection);
+        process.stdout.write(asJson(report) + '\n');
+        return 0;
+    },
+};

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

@@ -0,0 +1,3 @@
+import type { ICommandHandler } from '../command-registry.js';
+export declare const versionCommand: ICommandHandler;
+//# sourceMappingURL=version.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.command.d.ts","sourceRoot":"","sources":["../../src/commands/version.command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,eAAO,MAAM,cAAc,EAAE,eAQ5B,CAAC"}

package/dist/commands/version.command.js

@@ -0,0 +1,10 @@
+import { SHARKCRAFT_VERSION } from '@shrkcrft/shared';
+export const versionCommand = {
+    name: 'version',
+    description: 'Show SharkCraft version.',
+    usage: 'shrk version',
+    run() {
+        process.stdout.write(`SharkCraft v${SHARKCRAFT_VERSION}\n`);
+        return 0;
+    },
+};

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

@@ -0,0 +1,24 @@
+/**
+ * `shrk why <file>` — closes the dangling promise from
+ * `ide.command.ts:112`. For any file path under the project root,
+ * surface:
+ *
+ *   - inferred package / layer
+ *   - path conventions whose canonical path matches
+ *   - rules whose scope / tags / appliesWhen overlap with the file's
+ *     path tokens (top-N by priority)
+ *   - boundary rules whose `from` glob matches the file (these dictate
+ *     what the file is allowed to import)
+ *   - knowledge entries that reference the file or its basename
+ *   - suggested next commands
+ *
+ * Read-only. Pure composition over the live inspection — no LLM,
+ * no shell, no writes.
+ *
+ * Symbol queries (`shrk why <symbol>`) intentionally route to
+ * `shrk knowledge search` instead of trying to ground a symbol
+ * without an AST pass. Honest about scope.
+ */
+import { type ICommandHandler } from '../command-registry.js';
+export declare const whyCommand: ICommandHandler;
+//# sourceMappingURL=why.command.d.ts.map

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

@@ -0,0 +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"}