@shrkcrft/cli 0.1.0-alpha.1

package/dist/commands/review.command.js

@@ -0,0 +1,380 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildReviewPacket, buildReviewPacketV2, buildReviewPacketV3, inspectSharkcraft, renderReviewComment, renderReviewCommentV2, renderReviewCommentV3, REVIEW_PACKET_V2_SCHEMA, REVIEW_PACKET_V3_SCHEMA, } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+function renderGithubActionYaml(options) {
+    const steps = [];
+    const artifacts = [
+        { name: 'sharkcraft-review-packet', path: 'review-packet.json' },
+    ];
+    steps.push('      - name: Build review packet', '        run: bun run shrk review --since origin/main --json > review-packet.json');
+    if (options.withBoundaries) {
+        steps.push('      - name: Check boundaries', '        run: bun run shrk check boundaries --json > boundaries.json');
+        artifacts.push({ name: 'sharkcraft-boundaries', path: 'boundaries.json' });
+    }
+    if (options.withCoverage) {
+        steps.push('      - name: Coverage report', '        run: bun run shrk coverage --json > coverage.json');
+        artifacts.push({ name: 'sharkcraft-coverage', path: 'coverage.json' });
+    }
+    if (options.withDrift) {
+        steps.push('      - name: Drift report', '        run: bun run shrk drift --json > drift.json');
+        artifacts.push({ name: 'sharkcraft-drift', path: 'drift.json' });
+    }
+    for (const a of artifacts) {
+        steps.push('      - uses: actions/upload-artifact@v4', '        with:', `          name: ${a.name}`, `          path: ${a.path}`);
+    }
+    if (options.commentPlaceholder && !options.artifactOnly) {
+        steps.push('      - name: Render PR comment markdown', '        run: bun run shrk review render-comment review-packet.json --output review-comment.md', '      - name: PR comment placeholder', '        run: |', '          echo "Generated review-comment.md from review-packet.json."', '          echo "Post it via \\`gh pr comment --body-file review-comment.md\\` or actions/github-script."');
+    }
+    const commentNoteIncluded = options.commentPlaceholder && !options.artifactOnly;
+    const lines = [
+        '# .github/workflows/sharkcraft-review.yml',
+        '# Generated by `shrk review scaffold github-action`.',
+        '#',
+        '# On every pull request:',
+        '#   1. Check out the PR (with origin/main available so `shrk review --since` can diff).',
+        '#   2. Install Bun and workspace deps.',
+        '#   3. Run the selected SharkCraft checks and upload their JSON artifacts.',
+        '#',
+        commentNoteIncluded
+            ? '# A comment-placeholder step is included so you can wire `actions/github-script`'
+            : '# Posting artifacts as a PR comment is left as a follow-up — wire it via',
+        commentNoteIncluded
+            ? '# or `gh pr comment` later. The artifacts above contain the full payload.'
+            : '# `actions/github-script` or `gh pr comment` once you have a stable schema.',
+        'name: SharkCraft review packet',
+        '',
+        'on:',
+        '  pull_request:',
+        '    branches: [main]',
+        '',
+        'jobs:',
+        '  review:',
+        '    runs-on: ubuntu-latest',
+        '    steps:',
+        '      - uses: actions/checkout@v4',
+        '        with:',
+        '          fetch-depth: 0',
+        "      - uses: oven-sh/setup-bun@v1",
+        '        with:',
+        "          bun-version: '1.1'",
+        '      - run: bun install',
+        ...steps,
+        '',
+    ];
+    return lines.join('\n');
+}
+function scaffoldOptionsFromArgs(args) {
+    return {
+        withBoundaries: flagBool(args, 'with-boundaries'),
+        withCoverage: flagBool(args, 'with-coverage'),
+        withDrift: flagBool(args, 'with-drift'),
+        artifactOnly: flagBool(args, 'artifact-only'),
+        commentPlaceholder: flagBool(args, 'comment-placeholder'),
+    };
+}
+export const reviewCommand = {
+    name: 'review',
+    description: 'Build a PR-review packet: changed files (via git), affected path conventions, relevant rules/templates/pipelines, boundary violations on those files, missing-test heuristic, verification commands. Also: `shrk review scaffold github-action` prints a workflow template with optional `--with-boundaries / --with-coverage / --with-drift / --artifact-only / --comment-placeholder` flags. `shrk review render-comment <packet.json>` renders a Markdown PR comment from a saved packet.',
+    usage: 'shrk [--cwd <dir>] review [--since <ref>] [--staged] [--files a,b] [--json] | shrk review scaffold github-action [...] | shrk review render-comment <packet.json> [--output <file>]',
+    async run(args) {
+        if (args.positional[0] === 'scaffold') {
+            const which = args.positional[1] ?? 'github-action';
+            if (which !== 'github-action') {
+                process.stderr.write(`Unknown scaffold "${which}". Available: github-action\n`);
+                return 2;
+            }
+            const body = renderGithubActionYaml(scaffoldOptionsFromArgs(args));
+            process.stdout.write(body);
+            return 0;
+        }
+        if (args.positional[0] === 'render-comment') {
+            return runRenderComment(args);
+        }
+        if (args.positional[0] === 'packet') {
+            return runPacket(args);
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const since = flagString(args, 'since');
+        if (since) {
+            const { verifyGitRef } = await import('@shrkcrft/inspector');
+            const verify = verifyGitRef(cwd, since);
+            if (!verify.valid) {
+                process.stderr.write(`error: --since ref "${since}" does not resolve to a commit in this repository.\n` +
+                    (verify.suggestions && verify.suggestions.length > 0
+                        ? `\nDid you mean:\n${verify.suggestions.map((s) => `  --since ${s}`).join('\n')}\n`
+                        : '') +
+                    '\nUse `git branch -a` to list available refs.\n');
+                return 2;
+            }
+        }
+        const files = flagList(args, 'files');
+        const packet = buildReviewPacket(inspection, {
+            ...(since ? { since } : {}),
+            ...(flagBool(args, 'staged') ? { staged: true } : {}),
+            ...(files.length ? { files } : {}),
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(packet) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Review packet'));
+        process.stdout.write(kv('changed files', String(packet.changedFiles.length)) + '\n');
+        process.stdout.write(kv('affected paths', String(packet.affectedPaths.length)) + '\n');
+        process.stdout.write(kv('boundary violations', String(packet.boundaryViolations.length)) + '\n\n');
+        if (packet.changedFiles.length === 0) {
+            process.stdout.write('No changed files detected. Try `--since HEAD~1` or `--staged`.\n');
+            return 0;
+        }
+        process.stdout.write('Changed files:\n');
+        for (const f of packet.changedFiles.slice(0, 10))
+            process.stdout.write(`  • ${f}\n`);
+        if (packet.changedFiles.length > 10) {
+            process.stdout.write(`  … (${packet.changedFiles.length - 10} more)\n`);
+        }
+        if (packet.relevantRules.length) {
+            process.stdout.write('\nRelevant rules:\n');
+            for (const r of packet.relevantRules)
+                process.stdout.write(`  • ${r.id} — ${r.title}\n`);
+        }
+        if (packet.relevantTemplates.length) {
+            process.stdout.write('\nRelevant templates:\n');
+            for (const t of packet.relevantTemplates)
+                process.stdout.write(`  • ${t.id} ${t.name}\n`);
+        }
+        if (packet.boundaryViolations.length) {
+            process.stdout.write('\nBoundary violations in this change set:\n');
+            for (const v of packet.boundaryViolations) {
+                process.stdout.write(`  ${v.severity.toUpperCase().padEnd(8)} ${v.file}:${v.line}  ${v.importSpecifier}  (${v.ruleId})\n`);
+            }
+        }
+        if (packet.missingTestsHeuristic.length) {
+            process.stdout.write('\nMissing tests heuristic:\n');
+            for (const m of packet.missingTestsHeuristic)
+                process.stdout.write(`  • ${m}\n`);
+        }
+        if (packet.verificationCommands.length) {
+            process.stdout.write('\nVerification commands:\n');
+            for (const c of packet.verificationCommands)
+                process.stdout.write(`  $ ${c}\n`);
+        }
+        process.stdout.write('\n' + packet.reviewerInstructions + '\n');
+        return 0;
+    },
+};
+async function runRenderComment(args) {
+    const inputPath = args.positional[1];
+    if (!inputPath) {
+        process.stderr.write('Usage: shrk review render-comment <packet.json> [--output <file>] [--title <title>]\n');
+        return 2;
+    }
+    const full = nodePath.isAbsolute(inputPath)
+        ? inputPath
+        : nodePath.resolve(resolveCwd(args), inputPath);
+    if (!existsSync(full)) {
+        process.stderr.write(`Review packet not found: ${full}\n`);
+        return 2;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(full, 'utf8'));
+    }
+    catch (err) {
+        process.stderr.write(`Failed to parse review packet as JSON: ${err.message}\n`);
+        return 2;
+    }
+    // Auto-detect v3 first, then v2.
+    if (isReviewPacketV3Shape(parsed)) {
+        const format = (flagString(args, 'format') ?? 'markdown');
+        const maxFiles = flagNumber(args, 'max-files');
+        const maxItems = flagNumber(args, 'max-items');
+        const out = renderReviewCommentV3(parsed, {
+            format,
+            ...(maxFiles !== undefined ? { maxFiles } : {}),
+            ...(maxItems !== undefined ? { maxItems } : {}),
+        });
+        const output = flagString(args, 'output');
+        if (output) {
+            const outFull = nodePath.isAbsolute(output)
+                ? output
+                : nodePath.resolve(resolveCwd(args), output);
+            writeFileSync(outFull, out, 'utf8');
+            process.stdout.write(`Wrote ${out.length} bytes to ${outFull}\n`);
+        }
+        else {
+            process.stdout.write(out);
+        }
+        return 0;
+    }
+    // Auto-detect v2 schema and use the v2 renderer.
+    if (isReviewPacketV2Shape(parsed)) {
+        const format = flagString(args, 'format');
+        const maxFiles = flagNumber(args, 'max-files');
+        const maxItems = flagNumber(args, 'max-items');
+        const md = renderReviewCommentV2(parsed, {
+            ...(format ? { format } : {}),
+            ...(maxFiles !== undefined ? { maxFiles } : {}),
+            ...(maxItems !== undefined ? { maxItems } : {}),
+        });
+        const output = flagString(args, 'output');
+        if (output) {
+            const outFull = nodePath.isAbsolute(output)
+                ? output
+                : nodePath.resolve(resolveCwd(args), output);
+            writeFileSync(outFull, md, 'utf8');
+            process.stdout.write(`Wrote ${md.length} bytes to ${outFull}\n`);
+        }
+        else {
+            process.stdout.write(md);
+        }
+        return 0;
+    }
+    if (!isReviewPacketShape(parsed)) {
+        process.stderr.write('Input does not look like a review packet (missing expected fields).\n');
+        return 2;
+    }
+    const title = flagString(args, 'title');
+    const format = flagString(args, 'format');
+    const maxFiles = flagNumber(args, 'max-files');
+    const maxRules = flagNumber(args, 'max-rules');
+    const includeBoundaries = flagBool(args, 'include-boundaries');
+    const includeCoverage = flagBool(args, 'include-coverage');
+    const includeDrift = flagBool(args, 'include-drift');
+    const collapseLong = flagBool(args, 'collapse-long-sections');
+    const boundariesArtifact = readArtifact(args, 'boundaries');
+    const coverageArtifact = readArtifact(args, 'coverage');
+    const driftArtifact = readArtifact(args, 'drift');
+    const md = renderReviewComment(parsed, {
+        ...(title ? { title } : {}),
+        ...(format ? { format } : {}),
+        ...(maxFiles !== undefined ? { maxFiles } : {}),
+        ...(maxRules !== undefined ? { maxRules } : {}),
+        includeBoundaries: includeBoundaries !== false ? true : false,
+        ...(includeCoverage ? { includeCoverage: true } : {}),
+        ...(includeDrift ? { includeDrift: true } : {}),
+        ...(collapseLong ? { collapseLongSections: true } : {}),
+        ...(boundariesArtifact ? { boundariesArtifact } : {}),
+        ...(coverageArtifact ? { coverageArtifact } : {}),
+        ...(driftArtifact ? { driftArtifact } : {}),
+    });
+    const output = flagString(args, 'output');
+    if (output) {
+        const outFull = nodePath.isAbsolute(output)
+            ? output
+            : nodePath.resolve(resolveCwd(args), output);
+        writeFileSync(outFull, md, 'utf8');
+        process.stdout.write(`Wrote ${md.length} bytes to ${outFull}\n`);
+    }
+    else {
+        process.stdout.write(md);
+    }
+    return 0;
+}
+function readArtifact(args, name) {
+    const flag = flagString(args, name);
+    if (!flag)
+        return undefined;
+    const full = nodePath.isAbsolute(flag) ? flag : nodePath.resolve(resolveCwd(args), flag);
+    if (!existsSync(full)) {
+        process.stderr.write(`--${name} artifact not found: ${full}\n`);
+        return undefined;
+    }
+    try {
+        return JSON.parse(readFileSync(full, 'utf8'));
+    }
+    catch (e) {
+        process.stderr.write(`Failed to parse --${name} artifact: ${e.message}\n`);
+        return undefined;
+    }
+}
+function isReviewPacketShape(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const p = v;
+    return (Array.isArray(p.changedFiles) &&
+        Array.isArray(p.boundaryViolations) &&
+        Array.isArray(p.verificationCommands));
+}
+function isReviewPacketV2Shape(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    return v.schema === REVIEW_PACKET_V2_SCHEMA;
+}
+function isReviewPacketV3Shape(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    return v.schema === REVIEW_PACKET_V3_SCHEMA;
+}
+async function runPacket(args) {
+    const cwd = resolveCwd(args);
+    const inspection = await inspectSharkcraft({ cwd });
+    const since = flagString(args, 'since');
+    if (since) {
+        const { verifyGitRef } = await import('@shrkcrft/inspector');
+        const verify = verifyGitRef(cwd, since);
+        if (!verify.valid) {
+            process.stderr.write(`error: --since ref "${since}" does not resolve to a commit in this repository.\n` +
+                (verify.suggestions && verify.suggestions.length > 0
+                    ? `\nDid you mean:\n${verify.suggestions.map((s) => `  --since ${s}`).join('\n')}\n`
+                    : '') +
+                '\nUse `git branch -a` to list available refs.\n');
+            return 2;
+        }
+    }
+    const files = flagList(args, 'files');
+    const v2 = flagBool(args, 'v2');
+    const baselineFile = flagString(args, 'quality-baseline');
+    const fmt = flagString(args, 'format') ?? 'json';
+    if (flagBool(args, 'v3')) {
+        const bundleId = flagString(args, 'bundle');
+        const packet = await buildReviewPacketV3(inspection, {
+            ...(since ? { since } : {}),
+            ...(flagBool(args, 'staged') ? { staged: true } : {}),
+            ...(files.length ? { files } : {}),
+            ...(baselineFile ? { qualityBaselineFile: baselineFile } : {}),
+            ...(bundleId ? { bundleId } : {}),
+        });
+        if (fmt === 'markdown') {
+            process.stdout.write(renderReviewCommentV3(packet, { format: 'markdown' }));
+        }
+        else if (fmt === 'html') {
+            process.stdout.write(renderReviewCommentV3(packet, { format: 'html' }));
+        }
+        else {
+            process.stdout.write(asJson(packet) + '\n');
+        }
+        return 0;
+    }
+    if (v2) {
+        const packet = await buildReviewPacketV2(inspection, {
+            ...(since ? { since } : {}),
+            ...(flagBool(args, 'staged') ? { staged: true } : {}),
+            ...(files.length ? { files } : {}),
+            ...(baselineFile ? { qualityBaselineFile: baselineFile } : {}),
+        });
+        if (fmt === 'markdown') {
+            process.stdout.write(renderReviewCommentV2(packet, { format: 'markdown' }));
+        }
+        else if (fmt === 'html') {
+            process.stdout.write(renderReviewCommentV2(packet, { format: 'html' }));
+        }
+        else {
+            process.stdout.write(asJson(packet) + '\n');
+        }
+        return 0;
+    }
+    const packet = buildReviewPacket(inspection, {
+        ...(since ? { since } : {}),
+        ...(flagBool(args, 'staged') ? { staged: true } : {}),
+        ...(files.length ? { files } : {}),
+    });
+    if (fmt === 'markdown' || fmt === 'html') {
+        process.stdout.write(renderReviewComment(packet));
+    }
+    else {
+        process.stdout.write(asJson(packet) + '\n');
+    }
+    return 0;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"risk.command.d.ts","sourceRoot":"","sources":["../../src/commands/risk.command.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAYhC,eAAO,MAAM,WAAW,EAAE,eA8CzB,CAAC"}

package/dist/commands/risk.command.js

@@ -0,0 +1,56 @@
+import { buildTaskRiskReport, inspectSharkcraft, renderTaskRiskMarkdown, renderTaskRiskText, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+function parseFilesFlag(args) {
+    const raw = flagString(args, 'files');
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+}
+export const riskCommand = {
+    name: 'risk',
+    description: 'Compute a per-task risk report (intent + impact + architecture + boundaries + ownership + tests).',
+    usage: 'shrk risk "<task>" [--files a,b,c] [--since <ref>] [--staged] [--json] [--explain] [--format text|markdown|json]',
+    async run(args) {
+        const task = args.positional.join(' ').trim();
+        if (!task) {
+            process.stderr.write('Usage: shrk risk "<task>"\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const files = parseFilesFlag(args);
+        const since = flagString(args, 'since');
+        const staged = flagBool(args, 'staged');
+        const includeMemory = flagBool(args, 'include-memory');
+        const report = await buildTaskRiskReport(task, inspection, {
+            ...(files.length > 0 ? { files } : {}),
+            ...(since ? { since } : {}),
+            ...(staged ? { staged: true } : {}),
+            ...(includeMemory ? { includeMemory: true } : {}),
+        });
+        const format = (flagString(args, 'format') ?? '').toLowerCase();
+        if (flagBool(args, 'json') || format === 'json') {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        if (format === 'markdown') {
+            process.stdout.write(renderTaskRiskMarkdown(report));
+            return 0;
+        }
+        process.stdout.write(renderTaskRiskText(report));
+        if (flagBool(args, 'explain')) {
+            process.stdout.write('\nExplanation:\n');
+            process.stdout.write(`  Score ${report.score} → ${report.riskLevel}; ` +
+                (report.humanApprovalRequired ? 'human approval required.' : 'human approval optional.') +
+                '\n');
+            for (const r of report.reasons) {
+                process.stdout.write(`  • ${r.code}: ${r.message} (+${r.weight})\n`);
+            }
+        }
+        return 0;
+    },
+};

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

@@ -0,0 +1,8 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const roundsCaptureCommand: ICommandHandler;
+export declare const roundsListCommand: ICommandHandler;
+export declare const roundsShowCommand: ICommandHandler;
+export declare const diffParentCommand: ICommandHandler;
+export declare const roundsParentCommand: ICommandHandler;
+export declare const diffRoundsCommand: ICommandHandler;
+//# sourceMappingURL=rounds.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rounds.command.d.ts","sourceRoot":"","sources":["../../src/commands/rounds.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC,eAAO,MAAM,oBAAoB,EAAE,eAgClC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAmB/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAiC/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAc/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAajC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoC/B,CAAC"}

package/dist/commands/rounds.command.js

@@ -0,0 +1,180 @@
+/**
+ * `shrk rounds capture` and `shrk diff rounds`.
+ *
+ * The rounds verb captures a snapshot of the engine surface (commands,
+ * MCP tools, docs) at HEAD and persists it under
+ * `.sharkcraft/rounds/<id>/`. The diff verb compares two snapshots and
+ * answers the "what shipped in round X vs round Y?" question without
+ * scraping git logs.
+ */
+// DX#4 — `ALL_TOOLS_FOR_AUDIT` was deleted; project ALL_TOOLS inline.
+import { ALL_TOOLS } from '@shrkcrft/mcp-server';
+import { captureRoundSnapshot, diffRounds as diffRoundSnapshots, listRoundIds, loadRoundSnapshot, renderRoundsDiffMarkdown, writeRoundSnapshot, } from '@shrkcrft/inspector';
+import { COMMAND_CATALOG } from "./command-catalog.js";
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+function collectCommandsFromCatalog() {
+    return COMMAND_CATALOG.map((e) => ({
+        name: e.command,
+        description: e.description,
+    }));
+}
+function collectMcpTools() {
+    return ALL_TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+    }));
+}
+export const roundsCaptureCommand = {
+    name: 'capture',
+    description: 'Capture a snapshot of the engine surface at HEAD under .sharkcraft/rounds/<id>/.',
+    usage: 'shrk rounds capture --id <id> [--title <text>] [--json]',
+    run(args) {
+        const id = flagString(args, 'id') ?? args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk rounds capture --id <id> [--title <text>] [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const title = flagString(args, 'title') ?? undefined;
+        const snapshot = captureRoundSnapshot({
+            projectRoot: cwd,
+            id,
+            ...(title ? { title } : {}),
+            commands: collectCommandsFromCatalog(),
+            mcpTools: collectMcpTools(),
+        });
+        const { snapshotFile, metaFile } = writeRoundSnapshot(cwd, snapshot);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ snapshot, files: { snapshotFile, metaFile } }) + '\n');
+        }
+        else {
+            process.stdout.write(header(`Round snapshot ${id}`));
+            process.stdout.write(`  commands:  ${snapshot.commands.length}\n`);
+            process.stdout.write(`  mcp tools: ${snapshot.mcpTools.length}\n`);
+            process.stdout.write(`  docs:      ${snapshot.docs.length}\n`);
+            process.stdout.write(`  files:\n    ${snapshotFile}\n    ${metaFile}\n`);
+        }
+        return 0;
+    },
+};
+export const roundsListCommand = {
+    name: 'list',
+    description: 'List captured round snapshots.',
+    usage: 'shrk rounds list [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const ids = listRoundIds(cwd);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ rounds: ids }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Captured rounds (${ids.length})`));
+        if (ids.length === 0) {
+            process.stdout.write('  (none — run `shrk rounds capture --id <id>`)\n');
+        }
+        else {
+            for (const id of ids)
+                process.stdout.write(`  • ${id}\n`);
+        }
+        return 0;
+    },
+};
+export const roundsShowCommand = {
+    name: 'show',
+    description: 'Print one captured round snapshot.',
+    usage: 'shrk rounds show <id> [--json]',
+    run(args) {
+        const id = args.positional[0] ?? flagString(args, 'id');
+        if (!id) {
+            process.stderr.write('Usage: shrk rounds show <id> [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const snap = loadRoundSnapshot(cwd, id);
+        if (!snap) {
+            if (flagBool(args, 'json')) {
+                process.stdout.write(asJson({ ok: false, error: 'round-not-found', id }) + '\n');
+            }
+            else {
+                process.stderr.write(`No snapshot found for round "${id}".\n`);
+            }
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(snap) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Round ${snap.id}${snap.title ? ` — ${snap.title}` : ''}`));
+        process.stdout.write(`  capturedAt: ${snap.capturedAt}\n`);
+        process.stdout.write(`  commands:   ${snap.commands.length}\n`);
+        process.stdout.write(`  mcp tools:  ${snap.mcpTools.length}\n`);
+        process.stdout.write(`  docs:       ${snap.docs.length}\n`);
+        return 0;
+    },
+};
+export const diffParentCommand = {
+    name: 'diff',
+    description: 'Diff two artifacts. Currently supports `diff rounds` for round-to-round snapshot diffs.',
+    usage: 'shrk diff rounds --from <id> --to <id> [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'rounds') {
+            const rest = { ...args, positional: args.positional.slice(1) };
+            return diffRoundsCommand.run(rest);
+        }
+        process.stderr.write('Usage: shrk diff rounds --from <id> --to <id> [--json]\n');
+        return 2;
+    },
+};
+export const roundsParentCommand = {
+    name: 'rounds',
+    description: 'Capture / list / show round snapshots under .sharkcraft/rounds/.',
+    usage: 'shrk rounds [capture|list|show] [args]',
+    async run(args) {
+        const sub = args.positional[0];
+        const rest = { ...args, positional: args.positional.slice(1) };
+        if (sub === 'capture')
+            return roundsCaptureCommand.run(rest);
+        if (sub === 'list')
+            return roundsListCommand.run(rest);
+        if (sub === 'show')
+            return roundsShowCommand.run(rest);
+        process.stderr.write('Usage: shrk rounds [capture|list|show] [args]\n');
+        return 2;
+    },
+};
+export const diffRoundsCommand = {
+    name: 'rounds',
+    description: 'Diff two captured round snapshots — what shipped in the target round vs the baseline.',
+    usage: 'shrk diff rounds --from <id> --to <id> [--json]',
+    run(args) {
+        const fromId = flagString(args, 'from');
+        const toId = flagString(args, 'to');
+        if (!fromId || !toId) {
+            process.stderr.write('Usage: shrk diff rounds --from <id> --to <id> [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const fromSnap = loadRoundSnapshot(cwd, fromId);
+        const toSnap = loadRoundSnapshot(cwd, toId);
+        const wantJson = flagBool(args, 'json');
+        if (!fromSnap || !toSnap) {
+            const missing = !fromSnap ? fromId : toId;
+            if (wantJson) {
+                process.stdout.write(asJson({ ok: false, error: 'round-not-found', missing }) + '\n');
+            }
+            else {
+                process.stderr.write(`No snapshot found for round "${missing}". Capture it with \`shrk rounds capture --id ${missing}\`.\n`);
+            }
+            return 1;
+        }
+        const diff = diffRoundSnapshots(fromSnap, toSnap);
+        if (wantJson) {
+            process.stdout.write(asJson(diff) + '\n');
+            return 0;
+        }
+        process.stdout.write(renderRoundsDiffMarkdown(diff));
+        return 0;
+    },
+};