@shrkcrft/cli 0.1.0-alpha.2

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"gen.command.d.ts","sourceRoot":"","sources":["../../src/commands/gen.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC,eAAO,MAAM,UAAU,EAAE,eAmJxB,CAAC"}

package/dist/commands/gen.command.js

@@ -0,0 +1,136 @@
+import { inspectSharkcraft } from '@shrkcrft/inspector';
+import { buildSavedPlan, FileChangeType, generate, OverwriteStrategy, savePlanToFile, signPlan, } from '@shrkcrft/generator';
+import { flagBool, flagString, flagVars, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+import { printError } from "../output/print-error.js";
+const CHANGE_LABEL = {
+    [FileChangeType.Create]: 'CREATE',
+    [FileChangeType.Update]: 'UPDATE',
+    [FileChangeType.Skip]: 'SKIP  ',
+    [FileChangeType.Conflict]: 'CONFL ',
+    [FileChangeType.Append]: 'APPEND',
+    [FileChangeType.InsertAfter]: 'INSAFT',
+    [FileChangeType.InsertBefore]: 'INSBEF',
+    [FileChangeType.Replace]: 'REPL  ',
+    [FileChangeType.Export]: 'EXPORT',
+    [FileChangeType.RenameFolder]: 'RMFLDR',
+    [FileChangeType.DeleteFolder]: 'DELFLD',
+};
+export const genCommand = {
+    name: 'gen',
+    description: 'Generate code from a template. Defaults to dry-run.',
+    usage: 'shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--force] [--save-plan <file>] [--json]',
+    async run(args) {
+        const templateId = args.positional[0];
+        const name = args.positional[1];
+        if (!templateId) {
+            process.stderr.write('Usage: shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--save-plan <file>]\n');
+            return 2;
+        }
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const template = inspection.templateRegistry.get(templateId);
+        if (!template) {
+            process.stderr.write(`No template with id "${templateId}".\n`);
+            return 1;
+        }
+        const write = flagBool(args, 'write');
+        const force = flagBool(args, 'force');
+        const overwrite = force
+            ? OverwriteStrategy.Overwrite
+            : flagString(args, 'overwrite') ?? OverwriteStrategy.Never;
+        const variables = flagVars(args);
+        const savePlanPath = flagString(args, 'save-plan');
+        const result = generate(template, {
+            templateId: template.id,
+            name,
+            variables,
+            projectRoot: inspection.projectRoot,
+            overwriteStrategy: overwrite,
+            write,
+        });
+        if (!result.ok) {
+            printError(result.error);
+            return 1;
+        }
+        const { plan, summary, written } = result.value;
+        // --save-plan is allowed regardless of write/dry-run, but we refuse to
+        // save plans that have conflicts (since `shrk apply` would refuse them too).
+        if (savePlanPath) {
+            if (plan.hasConflicts) {
+                process.stderr.write('Refusing to save a plan with conflicts. Resolve conflicts first.\n');
+                return 1;
+            }
+            let saved = buildSavedPlan({
+                templateId: template.id,
+                name: name ?? undefined,
+                variables,
+                projectRoot: inspection.projectRoot,
+                plan,
+            });
+            if (flagBool(args, 'sign')) {
+                const signed = signPlan(saved);
+                if (!signed.ok) {
+                    printError(signed.error);
+                    return 1;
+                }
+                saved = signed.value;
+            }
+            const saveResult = savePlanToFile(saved, savePlanPath);
+            if (!saveResult.ok) {
+                printError(saveResult.error);
+                return 1;
+            }
+            const signedSuffix = saved.signature ? ' [signed]' : '';
+            process.stdout.write(`Saved plan${signedSuffix} → ${savePlanPath}\n`);
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                plan,
+                summary,
+                written: written.map((w) => w.relativePath),
+                savedPlanPath: savePlanPath ?? null,
+            }) + '\n');
+            return plan.hasConflicts ? 1 : 0;
+        }
+        process.stdout.write(header(write ? `Generation: ${template.id}` : `Dry-run: ${template.id}`));
+        if (plan.warnings.length) {
+            process.stdout.write('Warnings:\n');
+            for (const w of plan.warnings)
+                process.stdout.write(`  - ${w}\n`);
+            // Best-effort hint when warnings look like missing required variables.
+            const missingVarNames = plan.warnings
+                .map((w) => w.match(/^(\w+):\s+Variable\s+'\w+'\s+is required/)?.[1])
+                .filter((v) => typeof v === 'string');
+            if (missingVarNames.length > 0) {
+                process.stdout.write('\nSee `shrk templates vars ' + template.id + '` for required variables.\n');
+                const sampleVars = template.variables
+                    .map((v) => `--var ${v.name}=${v.examples?.[0] ?? v.default ?? '<value>'}`)
+                    .join(' ');
+                process.stdout.write(`Example:\n  $ shrk gen ${template.id} <name> ${sampleVars} --dry-run\n`);
+            }
+            if (!plan.changes.length)
+                return 1;
+        }
+        for (const change of plan.changes) {
+            process.stdout.write(`${CHANGE_LABEL[change.type]} ${change.relativePath} (${change.sizeBytes} bytes) — ${change.reason}\n`);
+        }
+        if (plan.postGenerationNotes.length) {
+            process.stdout.write('\nPost-generation notes:\n');
+            for (const note of plan.postGenerationNotes)
+                process.stdout.write(`  • ${note}\n`);
+        }
+        const updateLike = plan.changes.filter((c) => c.type === FileChangeType.Append ||
+            c.type === FileChangeType.InsertAfter ||
+            c.type === FileChangeType.InsertBefore ||
+            c.type === FileChangeType.Replace ||
+            c.type === FileChangeType.Export);
+        if (updateLike.length > 0) {
+            process.stdout.write(`\nHUMAN REVIEW REQUIRED — ${updateLike.length} update entry/entries modify existing files.\n`);
+        }
+        process.stdout.write(`\nSummary: written=${summary.written}, skipped=${summary.skipped}, conflicts=${summary.conflicts}\n`);
+        if (!write && !savePlanPath) {
+            process.stdout.write('\nRe-run with --write to apply, or --save-plan <file> + `shrk apply`.\n');
+        }
+        return plan.hasConflicts ? 1 : 0;
+    },
+};

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

@@ -0,0 +1,6 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const gitChangedCommand: ICommandHandler;
+export declare const gitRootCommand: ICommandHandler;
+export declare const gitBranchCommand: ICommandHandler;
+export declare const gitStatusSummaryCommand: ICommandHandler;
+//# sourceMappingURL=git.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git.command.d.ts","sourceRoot":"","sources":["../../src/commands/git.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,iBAAiB,EAAE,eAuB/B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,eAc5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAc9B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAoBrC,CAAC"}

package/dist/commands/git.command.js

@@ -0,0 +1,81 @@
+import { getChangedFiles, getGitBranch, getGitRoot, getStatusSummary, isGitRepo, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+export const gitChangedCommand = {
+    name: 'changed',
+    description: 'List changed files (read-only git diff).',
+    usage: 'shrk git changed [--since <ref>] [--staged] [--include-worktree] [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        if (!isGitRepo(cwd)) {
+            process.stderr.write('Not a git repo.\n');
+            return 1;
+        }
+        const opts = {};
+        const since = flagString(args, 'since');
+        if (since)
+            opts.since = since;
+        if (flagBool(args, 'staged'))
+            opts.staged = true;
+        if (flagBool(args, 'include-worktree'))
+            opts.includeWorktree = true;
+        const files = getChangedFiles(cwd, opts);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ files }) + '\n');
+        }
+        else {
+            for (const f of files)
+                process.stdout.write(`${f}\n`);
+        }
+        return 0;
+    },
+};
+export const gitRootCommand = {
+    name: 'root',
+    description: 'Print the git repo root.',
+    usage: 'shrk git root',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const r = getGitRoot(cwd);
+        if (!r) {
+            process.stderr.write('Not a git repo.\n');
+            return 1;
+        }
+        process.stdout.write(r + '\n');
+        return 0;
+    },
+};
+export const gitBranchCommand = {
+    name: 'branch',
+    description: 'Print the current git branch.',
+    usage: 'shrk git branch',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const b = getGitBranch(cwd);
+        if (!b) {
+            process.stderr.write('Not a git repo.\n');
+            return 1;
+        }
+        process.stdout.write(b + '\n');
+        return 0;
+    },
+};
+export const gitStatusSummaryCommand = {
+    name: 'status-summary',
+    description: 'Compact, read-only git status summary.',
+    usage: 'shrk git status-summary [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const summary = getStatusSummary(cwd);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(summary) + '\n');
+            return 0;
+        }
+        process.stdout.write(`branch=${summary.branch ?? '(none)'} ` +
+            `ahead=${summary.ahead} behind=${summary.behind} ` +
+            `staged=${summary.staged} modified=${summary.modified} ` +
+            `untracked=${summary.untracked} conflicts=${summary.conflicts} ` +
+            `clean=${summary.clean}\n`);
+        return 0;
+    },
+};

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

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

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

@@ -0,0 +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;AAehC,eAAO,MAAM,YAAY,EAAE,eA6L1B,CAAC"}

package/dist/commands/graph.command.js

@@ -0,0 +1,287 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { analyzeImportGraph, buildKnowledgeGraph, findGraphPath, getGraphNode, inspectSharkcraft, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+const KNOWN_KINDS = [
+    'knowledge',
+    'rule',
+    'path',
+    'template',
+    'pipeline',
+    'preset',
+    'pack',
+    'boundary',
+    'doc',
+];
+export const graphCommand = {
+    name: 'graph',
+    description: 'Show the SharkCraft knowledge graph: nodes (knowledge/rules/paths/templates/pipelines/presets/packs/boundaries) and edges (related-template, preset-references, pipeline-step-references, …). Supports text|json|dot|mermaid output and an `export` subcommand for writing to file.',
+    usage: 'shrk [--cwd <dir>] graph [<id>] [--type <kind>] [--format text|json|dot|mermaid] [--output <file>] [--json] | shrk graph export --format dot|mermaid --output <file>',
+    async run(args) {
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const graph = buildKnowledgeGraph(inspection);
+        const sub = args.positional[0];
+        const typeFlag = flagString(args, 'type');
+        const formatFlag = (flagString(args, 'format') ?? 'text');
+        const outputFlag = flagString(args, 'output');
+        // `shrk graph imports` — import-graph analysis.
+        if (sub === 'imports') {
+            const cwd = resolveCwd(args);
+            const analysis = analyzeImportGraph(cwd);
+            const wantJson = flagBool(args, 'json');
+            const wantCycles = flagBool(args, 'cycles');
+            const wantFanIn = flagBool(args, 'fan-in');
+            const wantFanOut = flagBool(args, 'fan-out');
+            const wantOrphans = flagBool(args, 'orphans');
+            if (wantJson) {
+                process.stdout.write(asJson(analysis) + '\n');
+                return 0;
+            }
+            process.stdout.write(header('Import graph analysis'));
+            process.stdout.write(kv('files scanned', String(analysis.filesScanned)) + '\n');
+            process.stdout.write(kv('workspace packages', String(analysis.packageCount)) + '\n');
+            if (!wantCycles && !wantFanIn && !wantFanOut && !wantOrphans) {
+                process.stdout.write(`cycles=${analysis.cycles.length}  orphans=${analysis.orphans.length}  unused=${analysis.unusedPublicEntrypoints.length}\n`);
+                process.stdout.write('Top fan-in:\n');
+                for (const f of analysis.topFanIn.slice(0, 5))
+                    process.stdout.write(`  ${f.in}  ${f.file}\n`);
+                return 0;
+            }
+            if (wantCycles) {
+                for (const c of analysis.cycles)
+                    process.stdout.write(`cycle: ${c.nodes.join(' → ')}\n`);
+            }
+            if (wantFanIn) {
+                for (const f of analysis.topFanIn)
+                    process.stdout.write(`${f.in}\t${f.file}\n`);
+            }
+            if (wantFanOut) {
+                for (const f of analysis.topFanOut)
+                    process.stdout.write(`${f.out}\t${f.file}\n`);
+            }
+            if (wantOrphans) {
+                for (const f of analysis.orphans)
+                    process.stdout.write(`${f}\n`);
+            }
+            return 0;
+        }
+        // `shrk graph export --format dot|mermaid --output <file>`.
+        if (sub === 'export') {
+            if (formatFlag !== 'dot' && formatFlag !== 'mermaid' && formatFlag !== 'json') {
+                process.stderr.write('Usage: shrk graph export --format dot|mermaid|json --output <file>\n');
+                return 2;
+            }
+            if (!outputFlag) {
+                process.stderr.write('Usage: shrk graph export --format dot|mermaid|json --output <file>\n');
+                return 2;
+            }
+            return exportGraph(args, graph, formatFlag, outputFlag);
+        }
+        // `shrk graph why <from> <to>` — shortest-path search.
+        if (sub === 'why') {
+            const fromId = args.positional[1];
+            const toId = args.positional[2];
+            if (!fromId || !toId) {
+                process.stderr.write('Usage: shrk graph why <fromId> <toId>\n');
+                return 2;
+            }
+            const path = findGraphPath(graph, { id: fromId }, { id: toId });
+            if (flagBool(args, 'json')) {
+                process.stdout.write(asJson(path) + '\n');
+                return path.found ? 0 : 1;
+            }
+            process.stdout.write(header(`Graph why: ${fromId} → ${toId}`));
+            if (!path.found) {
+                // Prefer the kind-aware explanation when available (rules don't
+                // connect to rules directly, etc.). Fall back to the short reason
+                // for older inspectors that don't populate `explanation`.
+                process.stdout.write(`${path.explanation ?? path.reason ?? 'No path: unknown'}\n`);
+                return 1;
+            }
+            for (let i = 0; i < path.steps.length; i += 1) {
+                const s = path.steps[i];
+                if (s.via) {
+                    process.stdout.write(`  → (${s.via.relation}) ${s.via.why}\n`);
+                }
+                process.stdout.write(`  ${i + 1}. ${s.node}\n`);
+            }
+            return 0;
+        }
+        const id = sub;
+        if (id) {
+            const node = getGraphNode(graph, typeFlag ? { kind: typeFlag, id } : { id });
+            if (!node) {
+                process.stderr.write(`No graph node for "${id}".\n`);
+                return 1;
+            }
+            // Subgraph export (single node + neighbours) in dot/mermaid format.
+            if (formatFlag === 'dot' || formatFlag === 'mermaid') {
+                const body = formatFlag === 'dot' ? renderDotForNode(node) : renderMermaidForNode(node);
+                if (outputFlag) {
+                    writeOutput(args, outputFlag, body);
+                    return 0;
+                }
+                process.stdout.write(body);
+                return 0;
+            }
+            if (flagBool(args, 'json')) {
+                process.stdout.write(asJson(node) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(`Graph: ${node.node.kind}:${node.node.id}`));
+            process.stdout.write(kv('title', node.node.title) + '\n');
+            if (node.node.summary)
+                process.stdout.write(kv('summary', node.node.summary) + '\n');
+            process.stdout.write(kv('source', node.node.source) + '\n');
+            if (node.outgoing.length) {
+                process.stdout.write('\nOutgoing:\n');
+                for (const e of node.outgoing) {
+                    process.stdout.write(`  → ${e.to.padEnd(40)} (${e.relation}) ${e.why}\n`);
+                }
+            }
+            if (node.incoming.length) {
+                process.stdout.write('\nIncoming:\n');
+                for (const e of node.incoming) {
+                    process.stdout.write(`  ← ${e.from.padEnd(40)} (${e.relation}) ${e.why}\n`);
+                }
+            }
+            return 0;
+        }
+        // Whole graph summary.
+        const nodes = typeFlag
+            ? graph.nodes.filter((n) => n.kind === typeFlag)
+            : graph.nodes;
+        if (formatFlag === 'dot' || formatFlag === 'mermaid') {
+            const filteredGraph = typeFlag
+                ? {
+                    ...graph,
+                    nodes,
+                    edges: graph.edges.filter((e) => {
+                        const fromNode = graph.nodes.find((n) => n.id === e.from);
+                        const toNode = graph.nodes.find((n) => n.id === e.to);
+                        return fromNode?.kind === typeFlag || toNode?.kind === typeFlag;
+                    }),
+                }
+                : graph;
+            const body = formatFlag === 'dot' ? renderDotGraph(filteredGraph) : renderMermaidGraph(filteredGraph);
+            if (outputFlag) {
+                writeOutput(args, outputFlag, body);
+                return 0;
+            }
+            process.stdout.write(body);
+            return 0;
+        }
+        if (formatFlag === 'json' || flagBool(args, 'json')) {
+            process.stdout.write(asJson({ nodes, edges: graph.edges }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Knowledge graph'));
+        process.stdout.write(kv('nodes', String(graph.nodes.length)) + '\n');
+        process.stdout.write(kv('edges', String(graph.edges.length)) + '\n');
+        if (!typeFlag) {
+            const byKind = new Map();
+            for (const n of graph.nodes)
+                byKind.set(n.kind, (byKind.get(n.kind) ?? 0) + 1);
+            process.stdout.write('\nNodes by kind:\n');
+            for (const k of KNOWN_KINDS) {
+                process.stdout.write(`  ${k.padEnd(10)} ${byKind.get(k) ?? 0}\n`);
+            }
+        }
+        else {
+            process.stdout.write(`\n${typeFlag} nodes:\n`);
+            for (const n of nodes.slice(0, 30)) {
+                process.stdout.write(`  ${n.id.padEnd(30)} ${n.title}\n`);
+            }
+            if (nodes.length > 30) {
+                process.stdout.write(`  … (${nodes.length - 30} more)\n`);
+            }
+        }
+        return 0;
+    },
+};
+function escapeDot(value) {
+    return value.replace(/"/g, '\\"');
+}
+function renderDotGraph(graph) {
+    const lines = [];
+    lines.push('digraph SharkCraftKnowledge {');
+    lines.push('  rankdir=LR;');
+    lines.push('  node [shape=box, style="rounded,filled", fillcolor="#f5f5fa", fontname="Helvetica"];');
+    for (const n of graph.nodes) {
+        lines.push(`  "${n.kind}:${n.id}" [label="${escapeDot(n.kind + ': ' + n.id)}\\n${escapeDot(n.title)}"];`);
+    }
+    for (const e of graph.edges) {
+        lines.push(`  "${e.from}" -> "${e.to}" [label="${escapeDot(e.relation)}"];`);
+    }
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+function renderMermaidGraph(graph) {
+    const lines = [];
+    lines.push('graph LR');
+    for (const n of graph.nodes) {
+        lines.push(`  ${mermaidId(n.kind, n.id)}["${n.kind}:${n.id}"]`);
+    }
+    for (const e of graph.edges) {
+        const fromNode = graph.nodes.find((n) => n.id === e.from);
+        const toNode = graph.nodes.find((n) => n.id === e.to);
+        if (!fromNode || !toNode)
+            continue;
+        lines.push(`  ${mermaidId(fromNode.kind, fromNode.id)} -->|${escapeMermaid(e.relation)}| ${mermaidId(toNode.kind, toNode.id)}`);
+    }
+    return lines.join('\n') + '\n';
+}
+function mermaidId(kind, id) {
+    return (kind + '_' + id).replace(/[^a-zA-Z0-9_]/g, '_');
+}
+function escapeMermaid(value) {
+    return value.replace(/\|/g, '/');
+}
+function renderDotForNode(node) {
+    const lines = [];
+    lines.push('digraph SharkCraftNode {');
+    lines.push('  rankdir=LR;');
+    lines.push('  node [shape=box, style="rounded,filled", fillcolor="#f5f5fa", fontname="Helvetica"];');
+    if (node.node) {
+        lines.push(`  "${node.node.kind}:${node.node.id}" [label="${escapeDot(node.node.kind + ': ' + node.node.id)}\\n${escapeDot(node.node.title)}", fillcolor="#dde7ff"];`);
+    }
+    for (const e of node.outgoing) {
+        lines.push(`  "${node.node?.kind ?? ''}:${node.node?.id ?? ''}" -> "${e.to}" [label="${escapeDot(e.relation)}"];`);
+    }
+    for (const e of node.incoming) {
+        lines.push(`  "${e.from}" -> "${node.node?.kind ?? ''}:${node.node?.id ?? ''}" [label="${escapeDot(e.relation)}"];`);
+    }
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+function renderMermaidForNode(node) {
+    const lines = [];
+    lines.push('graph LR');
+    if (node.node) {
+        lines.push(`  ${mermaidId(node.node.kind, node.node.id)}["${node.node.kind}:${node.node.id}"]`);
+    }
+    for (const e of node.outgoing) {
+        lines.push(`  ${mermaidId(node.node?.kind ?? '', node.node?.id ?? '')} -->|${escapeMermaid(e.relation)}| ${mermaidId('node', e.to)}`);
+    }
+    for (const e of node.incoming) {
+        lines.push(`  ${mermaidId('node', e.from)} -->|${escapeMermaid(e.relation)}| ${mermaidId(node.node?.kind ?? '', node.node?.id ?? '')}`);
+    }
+    return lines.join('\n') + '\n';
+}
+function exportGraph(args, graph, format, output) {
+    const body = format === 'dot'
+        ? renderDotGraph(graph)
+        : format === 'mermaid'
+            ? renderMermaidGraph(graph)
+            : JSON.stringify({ nodes: graph.nodes, edges: graph.edges }, null, 2) + '\n';
+    writeOutput(args, output, body);
+    return 0;
+}
+function writeOutput(args, output, body) {
+    const cwd = resolveCwd(args);
+    const full = nodePath.isAbsolute(output) ? output : nodePath.resolve(cwd, output);
+    mkdirSync(nodePath.dirname(full), { recursive: true });
+    writeFileSync(full, body, 'utf8');
+    process.stdout.write(`Wrote ${body.length} bytes to ${full}\n`);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * `shrk grounding "<task>"` — thin context primer for
+ * plugin / skill consumption. Read-only. JSON-first output.
+ */
+import { type ICommandHandler } from '../command-registry.js';
+export declare const groundingCommand: ICommandHandler;
+//# sourceMappingURL=grounding.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grounding.command.d.ts","sourceRoot":"","sources":["../../src/commands/grounding.command.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,gBAAgB,EAAE,eA+C9B,CAAC"}

package/dist/commands/grounding.command.js

@@ -0,0 +1,54 @@
+/**
+ * `shrk grounding "<task>"` — thin context primer for
+ * plugin / skill consumption. Read-only. JSON-first output.
+ */
+import { buildGrounding, inspectSharkcraft } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+export const groundingCommand = {
+    name: 'grounding',
+    description: 'Emit task-relevant rules / knowledge / paths / templates / verification IDs as JSON. Read-only. Pure composition of the task-packet ranker — no LLM, no shell, no writes.',
+    usage: 'shrk grounding "<task>" [--limit 5] [--max-tokens 2500] [--json]',
+    async run(args) {
+        const task = args.positional[0];
+        if (!task || task.trim().length === 0) {
+            process.stderr.write('Usage: shrk grounding "<task>"\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const limit = flagNumber(args, 'limit') ?? 5;
+        const maxTokens = flagNumber(args, 'max-tokens') ?? 2500;
+        const report = buildGrounding(task, inspection, { limit, maxTokens });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Grounding: ${task}`));
+        process.stdout.write(`  rules:     ${report.rules.length}\n`);
+        process.stdout.write(`  knowledge: ${report.knowledge.length}\n`);
+        process.stdout.write(`  paths:     ${report.paths.length}\n`);
+        process.stdout.write(`  templates: ${report.templates.length}\n`);
+        process.stdout.write(`  verification IDs (trusted): ${report.verificationCommandIds.join(', ') || '(none)'}\n`);
+        if (report.rules.length > 0) {
+            process.stdout.write('\nRules:\n');
+            for (const r of report.rules) {
+                process.stdout.write(`  ${r.id.padEnd(40)} [${r.priority ?? '-'}] ${r.title}\n`);
+            }
+        }
+        if (report.knowledge.length > 0) {
+            process.stdout.write('\nKnowledge:\n');
+            for (const k of report.knowledge) {
+                process.stdout.write(`  ${k.id.padEnd(40)} ${k.title}\n`);
+            }
+        }
+        if (report.templates.length > 0) {
+            process.stdout.write('\nTemplates:\n');
+            for (const t of report.templates) {
+                process.stdout.write(`  ${t.id.padEnd(40)} ${t.name}\n`);
+            }
+        }
+        process.stdout.write(`\nPass --json for the structured \`sharkcraft.grounding/v1\` payload.\n`);
+        return 0;
+    },
+};

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

@@ -0,0 +1,20 @@
+import type { CommandRegistry } from '../command-registry.js';
+/**
+ * Short product start screen for bare `shrk` / `shrk --help`. Pruned
+ * to the core tier set; extended verbs live one link away via
+ * `shrk surface list`.
+ *
+ * Returns the lines (without trailing newline). Pulled into a function
+ * so tests can assert on the structure without grepping stdout.
+ */
+export declare function renderStartScreen(): string;
+export declare function makeHelpCommand(registry: CommandRegistry): {
+    name: string;
+    description: string;
+    usage: string;
+    run(args: {
+        positional: string[];
+        flags: Map<string, string | boolean>;
+    }): number;
+};
+//# sourceMappingURL=help.command.d.ts.map

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

@@ -0,0 +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;AAG9D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAuB1C;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;EA2FpF"}