@shrkcrft/cli 0.1.0-alpha.1

package/dist/commands/safety.command.js

@@ -0,0 +1,117 @@
+import { buildSafetyAudit, buildSafetyAuditDeep, inspectSharkcraft, } from '@shrkcrft/inspector';
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+import { COMMAND_CATALOG } from "./command-catalog.js";
+const PLAN_SECRET_ENV = 'SHARKCRAFT_PLAN_SECRET';
+export const safetyCommand = {
+    name: 'safety',
+    description: 'Audit the SharkCraft safety model: which commands write source, which run shell, MCP read-only invariant, pack signature status, plan-signing status. Read-only.',
+    usage: 'shrk safety audit [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub !== 'audit') {
+            process.stderr.write('Usage: shrk safety audit [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        // Lazy-load the MCP tool list to avoid a static import dependency.
+        const mcpToolList = await listMcpTools();
+        const report = buildSafetyAudit({
+            inspection,
+            catalog: COMMAND_CATALOG,
+            mcpTools: mcpToolList,
+            planSecretEnv: PLAN_SECRET_ENV,
+            planSecretConfigured: typeof process.env[PLAN_SECRET_ENV] === 'string',
+        });
+        let deep = null;
+        if (flagBool(args, 'deep')) {
+            deep = await buildSafetyAuditDeep(inspection);
+        }
+        if (flagBool(args, 'json')) {
+            const merged = deep ? { ...report, deep } : report;
+            process.stdout.write(asJson(merged) + '\n');
+            const failed = report.mcp.anyWritable || (deep ? !deep.passed : false);
+            return failed ? 1 : 0;
+        }
+        printSafetyAudit(report);
+        if (deep) {
+            process.stdout.write('\n=== Deep audit ===\n');
+            process.stdout.write(`  passed: ${deep.passed ? 'yes' : 'no'}\n`);
+            process.stdout.write(`  info-only findings: ${deep.infoOnlyFindings}\n`);
+            process.stdout.write(`  report-site external JS: ${deep.reportSiteExternalJs.length}\n`);
+            process.stdout.write(`  demo destructive lines: ${deep.demoDestructiveLines.length}\n`);
+            process.stdout.write(`  CI workflows scanned: ${deep.ciGeneratedWorkflowPermissions.length}\n`);
+            // Dev-signed packs surface as a top-level deep-audit line so it
+            // doesn't get lost in the per-check list.
+            if (deep.devSignedPacks && deep.devSignedPacks.length > 0) {
+                process.stdout.write(`  dev-signed packs: ${deep.devSignedPacks.length}\n`);
+                for (const p of deep.devSignedPacks) {
+                    process.stdout.write(`    • ${p.packageName}@${p.packageVersion}${p.signedAt ? ` (signed-at ${p.signedAt})` : ''}\n`);
+                }
+                // Dev-signed pack findings are info-level by design. The
+                // deep-audit verdict ignores them; release readiness is enforced
+                // elsewhere. Spell that out so `passed: yes` next to a non-empty
+                // dev-signed list stops reading contradictory.
+                process.stdout.write('\n  Dev-signed packs are info-level findings — the deep-audit verdict ignores them.\n' +
+                    '  Release readiness is gated by `shrk packs signature-status --release-readiness`.\n');
+            }
+            if (deep.checks.length > 0) {
+                process.stdout.write('  checks:\n');
+                for (const c of deep.checks)
+                    process.stdout.write(`    [${c.severity}] ${c.id} — ${c.message}\n`);
+            }
+        }
+        const failed = report.mcp.anyWritable || (deep ? !deep.passed : false);
+        return failed ? 1 : 0;
+    },
+};
+async function listMcpTools() {
+    try {
+        const mod = (await import('@shrkcrft/mcp-server'));
+        return [...(mod.ALL_TOOLS ?? [])].map((t) => ({ name: t.name, description: t.description }));
+    }
+    catch {
+        return [];
+    }
+}
+function printSafetyAudit(r) {
+    process.stdout.write(header('SharkCraft safety audit'));
+    process.stdout.write(kv('MCP tools', String(r.mcp.tools.length)) + '\n');
+    process.stdout.write(kv('MCP writable', r.mcp.anyWritable ? 'YES — INVARIANT VIOLATED' : 'no (read-only ✓)') + '\n');
+    process.stdout.write(kv('packs', String(r.packs.discovered)) + '\n');
+    process.stdout.write(kv('pack signatures', `verified=${r.packs.signedAndVerified} not-checked=${r.packs.signedNotVerified} unsigned=${r.packs.unsigned} invalid=${r.packs.invalid}`) + '\n');
+    process.stdout.write(kv('plan signing', r.planSigning.secretConfigured
+        ? `${r.planSigning.secretEnv} configured`
+        : `${r.planSigning.secretEnv} not set`) + '\n');
+    process.stdout.write('\nCommand safety by level:\n');
+    process.stdout.write(`  read-only:       ${r.commands.readOnly.length}\n`);
+    process.stdout.write(`  writes-session:  ${r.commands.writesSession.length}\n`);
+    process.stdout.write(`  writes-drafts:   ${r.commands.writesDrafts.length}\n`);
+    process.stdout.write(`  writes-source:   ${r.commands.writesSource.length}\n`);
+    process.stdout.write(`  runs-shell:      ${r.commands.runsShell.length}\n`);
+    if (r.commands.writesSource.length > 0) {
+        process.stdout.write('\nCommands that write source (require human approval):\n');
+        for (const c of r.commands.writesSource) {
+            process.stdout.write(`  • ${c.command.padEnd(34)} ${c.description}\n`);
+        }
+    }
+    if (r.verifications.untrusted.length > 0) {
+        process.stdout.write('\nLocal verification commands NOT marked trusted:\n');
+        for (const v of r.verifications.untrusted) {
+            process.stdout.write(`  • ${v.id.padEnd(20)} ${v.command}\n`);
+        }
+    }
+    if (r.verifications.pack.length > 0) {
+        process.stdout.write('\nPack-contributed verification commands (NOT auto-run):\n');
+        for (const v of r.verifications.pack) {
+            process.stdout.write(`  • ${v.id.padEnd(20)} (${v.packPackageName ?? '?'})\n`);
+        }
+    }
+    if (r.recommendations.length > 0) {
+        process.stdout.write('\nRecommendations:\n');
+        for (const rec of r.recommendations)
+            process.stdout.write(`  • ${rec}\n`);
+    }
+    process.stdout.write(`\nVerdict: ${r.mcp.anyWritable ? 'MCP INVARIANT VIOLATED' : 'safety model intact ✓'}\n`);
+}

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

@@ -0,0 +1,5 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const scaffoldsListCommand: ICommandHandler;
+export declare const scaffoldsGetCommand: ICommandHandler;
+export declare const scaffoldsDoctorCommand: ICommandHandler;
+//# sourceMappingURL=scaffolds.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scaffolds.command.d.ts","sourceRoot":"","sources":["../../src/commands/scaffolds.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,oBAAoB,EAAE,eA0ClC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAmCjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAwCpC,CAAC"}

package/dist/commands/scaffolds.command.js

@@ -0,0 +1,122 @@
+import { doctorScaffoldPatterns, inspectSharkcraft, loadScaffoldPatternsFromInspection, } from '@shrkcrft/inspector';
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+export const scaffoldsListCommand = {
+    name: 'list',
+    description: 'List every scaffold pattern contributed by an installed pack.',
+    usage: 'shrk scaffolds list [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const result = await loadScaffoldPatternsFromInspection(inspection);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                patterns: result.patterns.map((p) => ({
+                    id: p.pattern.id,
+                    title: p.pattern.title,
+                    templateId: p.pattern.templateId,
+                    confidence: p.pattern.confidence,
+                    matchPaths: p.pattern.matchPaths,
+                    appliesWhen: p.pattern.appliesWhen,
+                    source: p.source,
+                })),
+                warnings: result.warnings,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Scaffold patterns (${result.patterns.length})`));
+        for (const p of result.patterns) {
+            process.stdout.write(`  • ${p.pattern.id.padEnd(36)} ${p.pattern.confidence.padEnd(7)} → ${p.pattern.templateId}\n`);
+            process.stdout.write(`      ${p.pattern.title}\n`);
+            process.stdout.write(`      source: ${p.source.packageName ?? p.source.type}\n`);
+        }
+        if (result.warnings.length > 0) {
+            process.stdout.write('\nWarnings:\n');
+            for (const w of result.warnings)
+                process.stdout.write(`  ! ${w}\n`);
+        }
+        if (result.patterns.length === 0) {
+            process.stdout.write('\nNo scaffold patterns found. Packs can contribute them via `scaffoldPatternFiles`.\n');
+        }
+        return 0;
+    },
+};
+export const scaffoldsGetCommand = {
+    name: 'get',
+    description: 'Show one scaffold pattern (full content).',
+    usage: 'shrk scaffolds get <id> [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk scaffolds get <id>\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const result = await loadScaffoldPatternsFromInspection(inspection);
+        const match = result.patterns.find((p) => p.pattern.id === id);
+        if (!match) {
+            process.stderr.write(`Unknown scaffold pattern: "${id}"\n`);
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(match) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Scaffold pattern: ${match.pattern.id}`));
+        process.stdout.write(kv('title', match.pattern.title) + '\n');
+        process.stdout.write(kv('templateId', match.pattern.templateId) + '\n');
+        process.stdout.write(kv('confidence', match.pattern.confidence) + '\n');
+        process.stdout.write(kv('source', match.source.packageName ?? match.source.type) + '\n');
+        process.stdout.write(`\nMatch paths:\n`);
+        for (const m of match.pattern.matchPaths)
+            process.stdout.write(`  - ${m}\n`);
+        process.stdout.write(`\nApplies when:\n`);
+        for (const a of match.pattern.appliesWhen)
+            process.stdout.write(`  - ${a}\n`);
+        process.stdout.write(`\nVariables:\n`);
+        for (const v of match.pattern.variables)
+            process.stdout.write(`  • ${v.name}  from=${String(v.from)}\n`);
+        return 0;
+    },
+};
+export const scaffoldsDoctorCommand = {
+    name: 'doctor',
+    description: 'Validate scaffold pattern definitions (templates exist, strategies recognized, …).',
+    usage: 'shrk scaffolds doctor [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const result = await loadScaffoldPatternsFromInspection(inspection);
+        const issues = doctorScaffoldPatterns(result.patterns, inspection);
+        const errorCount = issues.filter((i) => i.severity === 'error').length;
+        const warningCount = issues.filter((i) => i.severity === 'warning').length;
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                patterns: result.patterns.length,
+                errors: errorCount,
+                warnings: warningCount,
+                issues,
+                loadWarnings: result.warnings,
+            }) + '\n');
+            return errorCount > 0 ? 1 : 0;
+        }
+        process.stdout.write(header('Scaffold pattern doctor'));
+        process.stdout.write(kv('patterns', result.patterns.length.toString()) + '\n');
+        process.stdout.write(kv('errors', errorCount.toString()) + '\n');
+        process.stdout.write(kv('warnings', warningCount.toString()) + '\n');
+        if (issues.length > 0) {
+            process.stdout.write('\nIssues:\n');
+            for (const i of issues) {
+                const tag = i.severity === 'error' ? 'ERR ' : i.severity === 'warning' ? 'WARN' : 'INFO';
+                process.stdout.write(`  ${tag}  ${i.patternId.padEnd(28)} ${i.field.padEnd(20)} ${i.message}\n`);
+            }
+        }
+        if (result.warnings.length > 0) {
+            process.stdout.write('\nLoad warnings:\n');
+            for (const w of result.warnings)
+                process.stdout.write(`  ! ${w}\n`);
+        }
+        return errorCount > 0 ? 1 : 0;
+    },
+};

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

@@ -0,0 +1,21 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const schemasListCommand: ICommandHandler;
+export declare const schemasGetCommand: ICommandHandler;
+export declare const schemasInventoryCommand: ICommandHandler;
+export declare const schemasWriteCommand: ICommandHandler;
+/**
+ * On-disk schema emission with preview-first / drift-check semantics.
+ *
+ * Default: dry-run preview lists files that would change.
+ * `--write`: writes every schema as `<name>.schema.json` plus an
+ *            `INDEX.md` enumerating the set.
+ * `--check`: exits non-zero if `<out>` is missing files, has extra
+ *            files, or any file differs from the in-memory schema.
+ *            Used by `release:preflight`.
+ *
+ * `--out` defaults to `docs/schemas/` so agents can grep `docs/` for
+ * schema ids.
+ */
+export declare const SCHEMAS_EMIT_SCHEMA = "sharkcraft.schemas-emit/v1";
+export declare const schemasEmitCommand: ICommandHandler;
+//# sourceMappingURL=schemas.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.command.d.ts","sourceRoot":"","sources":["../../src/commands/schemas.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,kBAAkB,EAAE,eAgBhC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoB/B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuDrC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA4BjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAqEhE,eAAO,MAAM,kBAAkB,EAAE,eAmHhC,CAAC"}

package/dist/commands/schemas.command.js

@@ -0,0 +1,296 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { buildSchemaInventory, findSchemaInventoryEntry, renderSchemaInventoryMarkdown, renderSchemaInventoryText, } from '@shrkcrft/inspector';
+import { ALL_SCHEMAS } from "../schemas/json-schemas.js";
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+export const schemasListCommand = {
+    name: 'list',
+    description: 'List available JSON schemas.',
+    usage: 'shrk schemas list [--json]',
+    run(args) {
+        const names = Object.keys(ALL_SCHEMAS).sort();
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ schemas: names }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`JSON schemas (${names.length})`));
+        for (const n of names)
+            process.stdout.write(`  ${n}\n`);
+        process.stdout.write('\nGet one with: `shrk schemas get <name>`\n');
+        process.stdout.write('Write them all with: `shrk schemas write --dir ./schemas`\n');
+        return 0;
+    },
+};
+export const schemasGetCommand = {
+    name: 'get',
+    description: 'Print one JSON schema.',
+    usage: 'shrk schemas get <name>',
+    run(args) {
+        const name = args.positional[0];
+        if (!name) {
+            process.stderr.write('Usage: shrk schemas get <name>\n');
+            return 2;
+        }
+        const schema = ALL_SCHEMAS[name];
+        if (!schema) {
+            process.stderr.write(`Unknown schema "${name}". Available: ${Object.keys(ALL_SCHEMAS).join(', ')}\n`);
+            return 1;
+        }
+        process.stdout.write(JSON.stringify(schema, null, 2) + '\n');
+        return 0;
+    },
+};
+export const schemasInventoryCommand = {
+    name: 'inventory',
+    description: 'Inventory of engine schema ids: known versions, current version, deprecation/back-compat status.',
+    usage: 'shrk schemas inventory [<schema-id>] [--format text|markdown|json] [--multi-version-only]',
+    run(args) {
+        const id = args.positional[0];
+        const report = buildSchemaInventory();
+        const format = flagString(args, 'format') ?? (flagBool(args, 'json') ? 'json' : 'text');
+        const multiOnly = flagBool(args, 'multi-version-only');
+        if (id) {
+            const entry = findSchemaInventoryEntry(id);
+            if (!entry) {
+                process.stderr.write(`Unknown schema id "${id}". Try \`shrk schemas inventory\` to list known ids.\n`);
+                return 1;
+            }
+            if (format === 'json') {
+                process.stdout.write(asJson(entry) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(entry.id));
+            process.stdout.write(`  current: ${entry.currentVersion}\n`);
+            process.stdout.write(`  summary: ${entry.summary}\n`);
+            if (entry.emittedBy)
+                process.stdout.write(`  emitted by: ${entry.emittedBy}\n`);
+            if (entry.docs)
+                process.stdout.write(`  docs: ${entry.docs}\n`);
+            process.stdout.write('  versions:\n');
+            for (const v of entry.versions) {
+                process.stdout.write(`    ${v.version.padEnd(6)} ${v.status}${v.note ? `  — ${v.note}` : ''}\n`);
+            }
+            return 0;
+        }
+        const filtered = multiOnly
+            ? {
+                ...report,
+                entries: report.entries.filter((e) => e.versions.length > 1),
+            }
+            : report;
+        if (format === 'json') {
+            process.stdout.write(asJson(filtered) + '\n');
+            return 0;
+        }
+        if (format === 'markdown') {
+            process.stdout.write(renderSchemaInventoryMarkdown(filtered));
+            return 0;
+        }
+        process.stdout.write(renderSchemaInventoryText(filtered));
+        return 0;
+    },
+};
+export const schemasWriteCommand = {
+    name: 'write',
+    description: 'Write all JSON schemas to <dir>. Prefer `schemas emit --write --out <dir>` for preview-first emission.',
+    usage: 'shrk schemas write --dir <output-dir>',
+    run(args) {
+        const dir = flagString(args, 'dir');
+        if (!dir) {
+            process.stderr.write('Usage: shrk schemas write --dir <output-dir>\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const absolute = dir.startsWith('/') ? dir : join(cwd, dir);
+        if (!existsSync(absolute))
+            mkdirSync(absolute, { recursive: true });
+        const written = [];
+        for (const [name, schema] of Object.entries(ALL_SCHEMAS)) {
+            const filename = `${name}.schema.json`;
+            const target = join(absolute, filename);
+            writeFileSync(target, JSON.stringify(schema, null, 2) + '\n', 'utf8');
+            written.push(target);
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ written }) + '\n');
+            return 0;
+        }
+        process.stdout.write(`Wrote ${written.length} schemas:\n`);
+        for (const w of written)
+            process.stdout.write(`  ${w}\n`);
+        return 0;
+    },
+};
+/**
+ * On-disk schema emission with preview-first / drift-check semantics.
+ *
+ * Default: dry-run preview lists files that would change.
+ * `--write`: writes every schema as `<name>.schema.json` plus an
+ *            `INDEX.md` enumerating the set.
+ * `--check`: exits non-zero if `<out>` is missing files, has extra
+ *            files, or any file differs from the in-memory schema.
+ *            Used by `release:preflight`.
+ *
+ * `--out` defaults to `docs/schemas/` so agents can grep `docs/` for
+ * schema ids.
+ */
+export const SCHEMAS_EMIT_SCHEMA = 'sharkcraft.schemas-emit/v1';
+function computeEmitPlan(absOut) {
+    const expected = {};
+    for (const [name, schema] of Object.entries(ALL_SCHEMAS)) {
+        expected[`${name}.schema.json`] = JSON.stringify(schema, null, 2) + '\n';
+    }
+    expected['INDEX.md'] = renderSchemasIndexMarkdown(Object.keys(ALL_SCHEMAS));
+    const diffs = [];
+    const onDisk = existsSync(absOut)
+        ? readdirSync(absOut).filter((f) => f.endsWith('.schema.json') || f === 'INDEX.md')
+        : [];
+    const expectedSet = new Set(Object.keys(expected));
+    for (const [file, content] of Object.entries(expected)) {
+        const abs = join(absOut, file);
+        if (!existsSync(abs)) {
+            diffs.push({ file, status: 'missing-on-disk' });
+            continue;
+        }
+        const existing = readFileSync(abs, 'utf8');
+        diffs.push({ file, status: existing === content ? 'unchanged' : 'changed' });
+    }
+    for (const file of onDisk) {
+        if (!expectedSet.has(file)) {
+            diffs.push({ file, status: 'unexpected-on-disk' });
+        }
+    }
+    return { expected, diffs };
+}
+function renderSchemasIndexMarkdown(names) {
+    const sorted = [...names].sort();
+    const lines = [];
+    lines.push('# JSON schemas');
+    lines.push('');
+    lines.push('This directory is auto-generated by `shrk schemas emit --write`. Do not edit by hand.');
+    lines.push('');
+    lines.push(`Total: **${sorted.length}** schemas.`);
+    lines.push('');
+    lines.push('| Schema | File | Source command |');
+    lines.push('| ------ | ---- | -------------- |');
+    for (const name of sorted) {
+        lines.push(`| \`${name}\` | [\`${name}.schema.json\`](${name}.schema.json) | \`shrk schemas get ${name}\` |`);
+    }
+    lines.push('');
+    lines.push('## Re-emit');
+    lines.push('');
+    lines.push('```bash');
+    lines.push('shrk schemas emit --write');
+    lines.push('```');
+    lines.push('');
+    lines.push('`release:preflight` runs `shrk schemas emit --check` and fails when this directory drifts from the in-memory registry.');
+    lines.push('');
+    return lines.join('\n');
+}
+export const schemasEmitCommand = {
+    name: 'emit',
+    description: 'Emit every JSON schema to disk (default docs/schemas/) with an INDEX.md. Preview-first — pass --write to apply, --check to fail on drift.',
+    usage: 'shrk schemas emit [--out <dir>] [--write|--check] [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const out = flagString(args, 'out') ?? 'docs/schemas';
+        const absOut = out.startsWith('/') ? out : join(cwd, out);
+        const wantJson = flagBool(args, 'json');
+        const doWrite = flagBool(args, 'write');
+        const doCheck = flagBool(args, 'check');
+        if (doWrite && doCheck) {
+            process.stderr.write('--write and --check are mutually exclusive.\n');
+            return 2;
+        }
+        const { expected, diffs } = computeEmitPlan(absOut);
+        const drifted = diffs.filter((d) => d.status !== 'unchanged');
+        if (doCheck) {
+            if (wantJson) {
+                process.stdout.write(asJson({
+                    schema: SCHEMAS_EMIT_SCHEMA,
+                    mode: 'check',
+                    out: relative(cwd, absOut),
+                    drifted: drifted.length,
+                    diffs,
+                }) + '\n');
+            }
+            else {
+                process.stdout.write(header(`schemas emit --check (${relative(cwd, absOut)})`));
+                process.stdout.write(`  expected:   ${Object.keys(expected).length} files\n`);
+                process.stdout.write(`  drifted:    ${drifted.length}\n\n`);
+                if (drifted.length > 0) {
+                    for (const d of drifted)
+                        process.stdout.write(`  • ${d.status.padEnd(22)} ${d.file}\n`);
+                    process.stdout.write('\nRun `shrk schemas emit --write` to refresh.\n');
+                }
+                else {
+                    process.stdout.write('docs/schemas/ matches the in-memory registry.\n');
+                }
+            }
+            return drifted.length === 0 ? 0 : 1;
+        }
+        if (doWrite) {
+            mkdirSync(absOut, { recursive: true });
+            for (const [file, content] of Object.entries(expected)) {
+                writeFileSync(join(absOut, file), content, 'utf8');
+            }
+            // Sweep unexpected files (e.g. a removed schema) so the directory
+            // mirrors the registry exactly.
+            for (const d of diffs) {
+                if (d.status === 'unexpected-on-disk') {
+                    // Don't delete by default — log instead, so the human can decide.
+                    // Preserves the safety contract (no destructive ops without
+                    // explicit user intent).
+                }
+            }
+            if (wantJson) {
+                process.stdout.write(asJson({
+                    schema: SCHEMAS_EMIT_SCHEMA,
+                    mode: 'write',
+                    out: relative(cwd, absOut),
+                    written: Object.keys(expected),
+                    unexpected: diffs.filter((d) => d.status === 'unexpected-on-disk').map((d) => d.file),
+                }) + '\n');
+            }
+            else {
+                process.stdout.write(header(`schemas emit --write (${relative(cwd, absOut)})`));
+                process.stdout.write(`  wrote:      ${Object.keys(expected).length} files\n`);
+                const unexpected = diffs.filter((d) => d.status === 'unexpected-on-disk');
+                if (unexpected.length > 0) {
+                    process.stdout.write(`  unexpected: ${unexpected.length} (left in place)\n`);
+                    for (const d of unexpected)
+                        process.stdout.write(`    • ${d.file}\n`);
+                    process.stdout.write('  → remove unexpected files manually if they came from a deleted schema.\n');
+                }
+            }
+            return 0;
+        }
+        // Default: preview.
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: SCHEMAS_EMIT_SCHEMA,
+                mode: 'preview',
+                out: relative(cwd, absOut),
+                expected: Object.keys(expected),
+                drifted: drifted.length,
+                diffs,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`schemas emit preview (${relative(cwd, absOut)})`));
+        process.stdout.write(`  expected:   ${Object.keys(expected).length} files\n`);
+        process.stdout.write(`  drifted:    ${drifted.length}\n`);
+        if (drifted.length > 0) {
+            process.stdout.write('\n  diffs:\n');
+            for (const d of drifted.slice(0, 20)) {
+                process.stdout.write(`    • ${d.status.padEnd(22)} ${d.file}\n`);
+            }
+            if (drifted.length > 20) {
+                process.stdout.write(`    … and ${drifted.length - 20} more\n`);
+            }
+        }
+        process.stdout.write('\n(preview only — pass --write to apply, --check to fail on drift)\n');
+        return 0;
+    },
+};

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

@@ -0,0 +1,12 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const searchCommand: ICommandHandler;
+export declare const searchTuningListCommand: ICommandHandler;
+/**
+ * Top-level `shrk search-tuning <verb>` alias.
+ *
+ * Lets users invoke `shrk search-tuning explain "<query>"` without
+ * remembering the nested `shrk search tuning explain ...` form. Routes
+ * directly through the existing handler to avoid drift.
+ */
+export declare const searchTuningTopLevelCommand: ICommandHandler;
+//# sourceMappingURL=search.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.command.d.ts","sourceRoot":"","sources":["../../src/commands/search.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0BhC,eAAO,MAAM,aAAa,EAAE,eAuG3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA+FrC,CAAC;AAwEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,eASzC,CAAC"}