@shrkcrft/cli 0.1.0-alpha.11 → 0.1.0-alpha.12

package/dist/commands/move-plan.command.js

@@ -0,0 +1,360 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { flagBool, resolveCwd } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+/**
+ * `shrk move-plan <source> <target>` — emit a structured plan for
+ * moving a source file to a new location. Read-only: NEVER moves
+ * anything itself, never rewrites imports. The agent (or a human)
+ * uses the plan to do the actual work.
+ *
+ * Covers:
+ *   - graph-traced importer rewrites (relative + package-name imports)
+ *   - exports to revisit if the source was re-exported from an index
+ *   - cross-package warnings (layer-order risks)
+ *   - a rollback plan that's the literal reverse of the move
+ *   - validation commands to run after applying
+ *
+ * Limitations:
+ *   - single-file only. Directory moves can be approximated by
+ *     listing the directory and running this command per file, or
+ *     wait for a `--folder` follow-up.
+ *   - `from '@shrkcrft/pkg/sub'` deep-import rewrites are best-effort;
+ *     ambiguous cases get reported as `review-manually`.
+ */
+export const movePlanCommand = {
+    name: 'move-plan',
+    description: 'Plan a file move: graph-traced importer rewrites, export touch-ups, cross-package warnings. Read-only.',
+    usage: 'shrk move-plan <source-file> <target-file> [--json]',
+    async run(args) {
+        const sourceArg = args.positional[0]?.trim();
+        const targetArg = args.positional[1]?.trim();
+        if (!sourceArg || !targetArg) {
+            process.stderr.write('Usage: shrk move-plan <source-file> <target-file> [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const json = flagBool(args, 'json');
+        const sourceRel = relativize(cwd, sourceArg);
+        const targetRel = relativize(cwd, targetArg);
+        if (!existsSync(nodePath.join(cwd, sourceRel))) {
+            process.stderr.write(`Source file does not exist: ${sourceRel}\n`);
+            return 1;
+        }
+        if (existsSync(nodePath.join(cwd, targetRel))) {
+            process.stderr.write(`Target already exists (won't propose moving on top of it): ${targetRel}\n`);
+            return 1;
+        }
+        const store = new GraphStore(cwd);
+        if (!store.exists()) {
+            process.stderr.write('No SharkCraft graph found. Run `shrk graph build` so move-plan can trace importers.\n');
+            return 1;
+        }
+        const api = GraphQueryApi.fromStore(cwd);
+        const sourcePackage = resolveOwningPackage(cwd, sourceRel);
+        const targetPackage = resolveOwningPackage(cwd, targetRel);
+        const crossesPackages = sourcePackage?.name !== targetPackage?.name;
+        const importerNodes = (() => {
+            const fileNode = api.findFile(sourceRel);
+            if (!fileNode)
+                return [];
+            return api.importersOf(fileNode.id)
+                .map((n) => n.path)
+                .filter((p) => typeof p === 'string' && p.length > 0);
+        })();
+        const importsToRewrite = [];
+        const exportsToUpdate = [];
+        for (const importerPath of importerNodes) {
+            const abs = nodePath.join(cwd, importerPath);
+            if (!existsSync(abs))
+                continue;
+            let body;
+            try {
+                body = readFileSync(abs, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const rewrites = computeRewritesForFile({
+                importerPath,
+                importerBody: body,
+                sourceRel,
+                targetRel,
+                sourcePackage,
+                targetPackage,
+            });
+            importsToRewrite.push(...rewrites);
+            // If the importer is `<pkg>/src/index.ts` and re-exports the source,
+            // it likely needs to drop / move that export.
+            if (/(^|\/)index\.[jt]sx?$/.test(importerPath) && body.includes(sourceBaseSpecifier(sourceRel))) {
+                exportsToUpdate.push({
+                    file: importerPath,
+                    action: 'review-manually',
+                    reason: `index file re-exports something from "${sourceRel}"; relocate the re-export to point at "${targetRel}" or drop it.`,
+                });
+            }
+        }
+        // Also check if the source file itself is referenced from its own
+        // package's index.ts.
+        if (sourcePackage) {
+            const sourceIndex = nodePath.join(cwd, sourcePackage.dir, 'src/index.ts');
+            const sourceIndexRel = nodePath.relative(cwd, sourceIndex);
+            const alreadyFlagged = exportsToUpdate.some((e) => e.file === sourceIndexRel);
+            if (!alreadyFlagged && existsSync(sourceIndex)) {
+                try {
+                    const body = readFileSync(sourceIndex, 'utf8');
+                    if (body.includes(sourceBaseSpecifier(sourceRel))) {
+                        exportsToUpdate.push({
+                            file: sourceIndexRel,
+                            action: 'edit',
+                            reason: crossesPackages
+                                ? `index re-exports the moved file; drop the export (the file now lives in another package) or replace with a forwarding re-export.`
+                                : `index re-exports the moved file; update the relative path to point at the new location.`,
+                        });
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        const affectedPackages = unique([
+            ...importerNodes.map((p) => resolveOwningPackage(cwd, p)?.name ?? null),
+            sourcePackage?.name ?? null,
+            targetPackage?.name ?? null,
+        ].filter((n) => typeof n === 'string'));
+        const risks = [];
+        if (crossesPackages) {
+            risks.push(`Cross-package move: ${sourcePackage?.name ?? '(no package)'} → ${targetPackage?.name ?? '(no package)'}. Run \`shrk check boundaries\` after the move to confirm the new home is layered correctly.`);
+        }
+        if (importerNodes.length > 30) {
+            risks.push(`${importerNodes.length} importer(s) — large blast radius. Consider scripting the rewrites or moving in smaller chunks.`);
+        }
+        if (exportsToUpdate.some((e) => e.action === 'review-manually')) {
+            risks.push('Some index re-exports were flagged for manual review — automatic rewriting could lose intent.');
+        }
+        const movePlan = [
+            {
+                order: 1,
+                title: 'Move the file',
+                details: `git mv "${sourceRel}" "${targetRel}"  (then verify content unchanged)`,
+            },
+            ...importsToRewrite.map((rw, i) => ({
+                order: 2 + i,
+                title: `Rewrite import in ${rw.file}`,
+                details: `Replace \`from '${rw.fromImport}'\` with \`from '${rw.toImport}'\`. Reason: ${rw.reason}`,
+            })),
+            ...(exportsToUpdate.length > 0
+                ? [
+                    {
+                        order: 2 + importsToRewrite.length,
+                        title: 'Reconcile index re-exports',
+                        details: exportsToUpdate
+                            .map((e) => `${e.file} (${e.action}): ${e.reason}`)
+                            .join('  ||  '),
+                    },
+                ]
+                : []),
+        ];
+        const rollbackPlan = [
+            { order: 1, title: 'Restore file', details: `git mv "${targetRel}" "${sourceRel}"` },
+            {
+                order: 2,
+                title: 'Revert import rewrites',
+                details: importsToRewrite.length === 0
+                    ? 'No importers to revert.'
+                    : `git restore ${unique(importsToRewrite.map((r) => r.file)).join(' ')}`,
+            },
+        ];
+        const validationCommands = [
+            'bun x tsc -p tsconfig.base.json --noEmit',
+            'shrk check boundaries',
+            'shrk check imports',
+            'bun test',
+        ];
+        const status = importsToRewrite.length === 0 && exportsToUpdate.length === 0
+            ? 'no-importers'
+            : crossesPackages
+                ? 'cross-package'
+                : 'in-package';
+        const handoff = status === 'no-importers'
+            ? `Move is trivial — no importers reference "${sourceRel}". Just run the file move + validation.`
+            : status === 'cross-package'
+                ? `Move crosses packages. Apply each importsToRewrite[] edit, then revisit exportsToUpdate[], then run validationCommands. Re-run \`shrk check boundaries\` to confirm layering.`
+                : `In-package move with ${importsToRewrite.length} importer rewrite(s). Safe but worth applying mechanically.`;
+        const report = {
+            schema: 'sharkcraft.move-plan/v1',
+            source: { path: sourceRel, package: sourcePackage?.name ?? null },
+            target: { path: targetRel, package: targetPackage?.name ?? null },
+            crossesPackages,
+            movePlan,
+            importsToRewrite,
+            exportsToUpdate,
+            affectedPackages,
+            risks,
+            rollbackPlan,
+            validationCommands,
+            handoffForClaude: handoff,
+        };
+        if (json) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        renderText(report);
+        return 0;
+    },
+};
+function relativize(cwd, raw) {
+    const cleaned = raw.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (nodePath.isAbsolute(cleaned)) {
+        return nodePath.relative(cwd, cleaned).replace(/\\/g, '/');
+    }
+    return cleaned;
+}
+const PACKAGE_CACHE = new Map();
+function listPackages(cwd) {
+    const cached = PACKAGE_CACHE.get(cwd);
+    if (cached)
+        return cached;
+    const out = [];
+    for (const root of ['packages', 'libs', 'apps']) {
+        const rootAbs = nodePath.join(cwd, root);
+        if (!existsSync(rootAbs))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(rootAbs);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const dir = nodePath.join(root, entry);
+            const pkgJson = nodePath.join(cwd, dir, 'package.json');
+            if (!existsSync(pkgJson))
+                continue;
+            try {
+                const parsed = JSON.parse(readFileSync(pkgJson, 'utf8'));
+                if (parsed.name)
+                    out.push({ name: parsed.name, dir });
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    PACKAGE_CACHE.set(cwd, out);
+    return out;
+}
+function resolveOwningPackage(cwd, fileRel) {
+    const packages = listPackages(cwd);
+    let best = null;
+    for (const p of packages) {
+        const dirSlash = p.dir.replace(/\\/g, '/') + '/';
+        if (fileRel.startsWith(dirSlash)) {
+            if (!best || p.dir.length > best.dir.length)
+                best = p;
+        }
+    }
+    return best;
+}
+function sourceBaseSpecifier(sourceRel) {
+    // The plain basename without extension — usable as a fuzzy substring
+    // match against `from '../foo'` re-exports.
+    const ext = nodePath.extname(sourceRel);
+    return nodePath.basename(sourceRel, ext);
+}
+function computeRewritesForFile(input) {
+    const out = [];
+    const seen = new Set();
+    const importerDir = nodePath.dirname(input.importerPath);
+    const expectedRelativeBefore = toRelativeSpecifier(importerDir, input.sourceRel);
+    const expectedRelativeAfter = toRelativeSpecifier(importerDir, input.targetRel);
+    // Pattern 1: relative imports that resolve to the source file.
+    // Try both with-extension and without-extension forms.
+    const candidates = [expectedRelativeBefore, stripJsTsExt(expectedRelativeBefore)];
+    for (const cand of candidates) {
+        if (cand.length === 0)
+            continue;
+        if (!input.importerBody.includes(`'${cand}'`) && !input.importerBody.includes(`"${cand}"`))
+            continue;
+        const targetCand = stripJsTsExt(expectedRelativeAfter);
+        const key = `rel:${cand}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            file: input.importerPath,
+            fromImport: cand,
+            toImport: targetCand,
+            reason: 'relative-path rewrite (importer-relative)',
+        });
+    }
+    // Pattern 2: package-name imports `@shrkcrft/xxx` when the source is
+    // inside that package and the target is in a different one.
+    if (input.sourcePackage && input.targetPackage && input.sourcePackage.name !== input.targetPackage.name) {
+        const fromSpec = input.sourcePackage.name;
+        const toSpec = input.targetPackage.name;
+        if ((input.importerBody.includes(`'${fromSpec}'`) || input.importerBody.includes(`"${fromSpec}"`)) &&
+            // and the package-name import is actually exposing the moved symbol
+            // (we can't know for sure without re-resolving — flag as review).
+            input.importerPath !== fromIndexPath(input.sourcePackage)) {
+            const key = `pkg:${fromSpec}->${toSpec}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push({
+                    file: input.importerPath,
+                    fromImport: fromSpec,
+                    toImport: toSpec,
+                    reason: 'package-name import: importer likely consumes the symbol via the old package. Verify the target package re-exports the symbol from its public index before applying.',
+                });
+            }
+        }
+    }
+    return out;
+}
+function fromIndexPath(pkg) {
+    return nodePath.join(pkg.dir, 'src/index.ts');
+}
+function toRelativeSpecifier(fromDir, toRel) {
+    const rel = nodePath.relative(fromDir, toRel).replace(/\\/g, '/');
+    if (!rel.startsWith('.'))
+        return `./${rel}`;
+    return rel;
+}
+function stripJsTsExt(p) {
+    return p.replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '');
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+function renderText(r) {
+    process.stdout.write(header(`move-plan: ${r.source.path} → ${r.target.path}${r.crossesPackages ? ' (cross-package)' : ''}`));
+    process.stdout.write(`affected packages: ${r.affectedPackages.join(', ') || '(none)'}\n\n`);
+    process.stdout.write(`move plan (${r.movePlan.length} step(s)):\n`);
+    for (const s of r.movePlan) {
+        process.stdout.write(`  ${s.order}. ${s.title} — ${s.details}\n`);
+    }
+    if (r.importsToRewrite.length > 0) {
+        process.stdout.write(`\nimport rewrites (${r.importsToRewrite.length}):\n`);
+        for (const rw of r.importsToRewrite) {
+            process.stdout.write(`  ${rw.file}\n    from '${rw.fromImport}' → to '${rw.toImport}'\n    (${rw.reason})\n`);
+        }
+    }
+    if (r.exportsToUpdate.length > 0) {
+        process.stdout.write('\nexports to update:\n');
+        for (const e of r.exportsToUpdate) {
+            process.stdout.write(`  ${e.file} [${e.action}] — ${e.reason}\n`);
+        }
+    }
+    if (r.risks.length > 0) {
+        process.stdout.write('\nrisks:\n');
+        for (const r2 of r.risks)
+            process.stdout.write(`  - ${r2}\n`);
+    }
+    process.stdout.write('\nvalidation commands:\n');
+    for (const c of r.validationCommands)
+        process.stdout.write(`  $ ${c}\n`);
+    process.stdout.write(`\nhandoff: ${r.handoffForClaude}\n`);
+}

package/dist/commands/scaffold-validate.command.d.ts

@@ -0,0 +1,22 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk scaffold-validate <plan-file>` — verify that the files
+ * recorded in a saved generation plan actually exist on disk and
+ * look like they came from the template.
+ *
+ * Read-only: never writes, never re-runs the template. Designed to
+ * run after `shrk apply` (or after a human manually copied a plan
+ * into place) to catch:
+ *   - missing files (apply was interrupted, or somebody deleted)
+ *   - shrunken files (someone replaced the body with `// TODO`)
+ *   - mismatched operation type (plan said `create`, disk shows
+ *     something else)
+ *
+ * NOT a full template-replay check — we can't know the exact
+ * expected body without re-rendering the template, which would
+ * be far more expensive and would couple this command to every
+ * template's variable resolution. Sizes + existence + type catches
+ * 95% of real-world failures.
+ */
+export declare const scaffoldValidateCommand: ICommandHandler;
+//# sourceMappingURL=scaffold-validate.command.d.ts.map

package/dist/commands/scaffold-validate.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-validate.command.d.ts","sourceRoot":"","sources":["../../src/commands/scaffold-validate.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAkGrC,CAAC"}

package/dist/commands/scaffold-validate.command.js

@@ -0,0 +1,215 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { readPlanFromFile } from '@shrkcrft/generator';
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+import { printError } from "../output/print-error.js";
+/**
+ * `shrk scaffold-validate <plan-file>` — verify that the files
+ * recorded in a saved generation plan actually exist on disk and
+ * look like they came from the template.
+ *
+ * Read-only: never writes, never re-runs the template. Designed to
+ * run after `shrk apply` (or after a human manually copied a plan
+ * into place) to catch:
+ *   - missing files (apply was interrupted, or somebody deleted)
+ *   - shrunken files (someone replaced the body with `// TODO`)
+ *   - mismatched operation type (plan said `create`, disk shows
+ *     something else)
+ *
+ * NOT a full template-replay check — we can't know the exact
+ * expected body without re-rendering the template, which would
+ * be far more expensive and would couple this command to every
+ * template's variable resolution. Sizes + existence + type catches
+ * 95% of real-world failures.
+ */
+export const scaffoldValidateCommand = {
+    name: 'scaffold-validate',
+    description: 'Verify that the files recorded in a saved generation plan exist on disk and match the planned type/size envelope.',
+    usage: 'shrk scaffold-validate <plan-file> [--json] [--shrink-tolerance N]',
+    async run(args) {
+        const planArg = args.positional[0]?.trim();
+        if (!planArg) {
+            process.stderr.write('Usage: shrk scaffold-validate <plan-file> [--json] [--shrink-tolerance N]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const json = flagBool(args, 'json');
+        const shrinkTolerance = typeof args.flags.get('shrink-tolerance') === 'string'
+            ? Number(args.flags.get('shrink-tolerance'))
+            : 0.25;
+        const planFile = nodePath.isAbsolute(planArg) ? planArg : nodePath.resolve(cwd, planArg);
+        if (!existsSync(planFile)) {
+            process.stderr.write(`Plan file not found: ${planFile}\n`);
+            return 1;
+        }
+        const loaded = readPlanFromFile(planFile);
+        if (!loaded.ok) {
+            printError(loaded.error);
+            return 1;
+        }
+        const plan = loaded.value;
+        const projectRoot = nodePath.isAbsolute(plan.projectRoot)
+            ? plan.projectRoot
+            : nodePath.resolve(cwd, plan.projectRoot);
+        const expected = plan.expectedChanges ?? [];
+        const findings = [];
+        for (const change of expected) {
+            findings.push(checkChange(projectRoot, change, shrinkTolerance));
+        }
+        const folderFindings = (plan.folderOps ?? []).map((op) => {
+            const target = nodePath.join(projectRoot, op.targetPath);
+            if (op.kind === 'rename-folder') {
+                // After apply, the renamed folder should be at newPath, and
+                // the old path should not exist (unless human reverted).
+                const newPath = op.newPath ? nodePath.join(projectRoot, op.newPath) : '';
+                if (newPath && existsSync(newPath)) {
+                    return { kind: op.kind, targetPath: op.targetPath, status: 'compliant' };
+                }
+                return {
+                    kind: op.kind,
+                    targetPath: op.targetPath,
+                    status: 'missing',
+                    detail: `rename target "${op.newPath ?? '?'}" not found`,
+                };
+            }
+            if (op.kind === 'delete-folder') {
+                if (!existsSync(target)) {
+                    return { kind: op.kind, targetPath: op.targetPath, status: 'compliant' };
+                }
+                return {
+                    kind: op.kind,
+                    targetPath: op.targetPath,
+                    status: 'missing',
+                    detail: 'folder still present (delete not applied)',
+                };
+            }
+            return { kind: String(op.kind), targetPath: op.targetPath, status: 'missing' };
+        });
+        const totals = {
+            expected: expected.length,
+            compliant: findings.filter((f) => f.status === 'compliant').length,
+            missing: findings.filter((f) => f.status === 'missing').length,
+            shrunk: findings.filter((f) => f.status === 'shrunk').length,
+            unexpectedType: findings.filter((f) => f.status === 'unexpected-type').length,
+        };
+        const hasFailures = totals.missing > 0 || totals.unexpectedType > 0;
+        const hasWarnings = totals.shrunk > 0;
+        const status = hasFailures
+            ? 'failed'
+            : hasWarnings || folderFindings.some((f) => f.status === 'missing')
+                ? 'partial'
+                : 'ok';
+        const report = {
+            schema: 'sharkcraft.scaffold-validate/v1',
+            planFile,
+            templateId: plan.templateId,
+            ...(plan.name !== undefined ? { name: plan.name } : {}),
+            projectRoot,
+            totals,
+            findings,
+            folderOpFindings: folderFindings,
+            status,
+            handoffForClaude: handoffFor(status, totals, folderFindings.length),
+        };
+        if (json) {
+            process.stdout.write(asJson(report) + '\n');
+            return status === 'failed' ? 1 : 0;
+        }
+        renderText(report);
+        return status === 'failed' ? 1 : 0;
+    },
+};
+function checkChange(projectRoot, change, shrinkTolerance) {
+    const abs = nodePath.join(projectRoot, change.relativePath);
+    const base = {
+        relativePath: change.relativePath,
+        type: change.type,
+        status: 'compliant',
+        expectedSizeBytes: change.sizeBytes,
+    };
+    // delete-file plans expect the file NOT to exist after apply.
+    if (change.type === 'delete') {
+        if (existsSync(abs)) {
+            return { ...base, status: 'unexpected-type', detail: 'file is still present after delete plan' };
+        }
+        return base;
+    }
+    if (!existsSync(abs)) {
+        return { ...base, status: 'missing', detail: 'file not found on disk' };
+    }
+    let stat;
+    try {
+        stat = statSync(abs);
+    }
+    catch (e) {
+        return { ...base, status: 'missing', detail: e.message };
+    }
+    if (!stat.isFile()) {
+        return { ...base, status: 'unexpected-type', detail: 'path is not a regular file' };
+    }
+    // Read first chunk to detect "the file was reduced to a stub by hand"
+    // (`// TODO`, `export {}`, empty). We compare against the planned size
+    // with a tolerance — humans naturally grow files, but shrinking past
+    // tolerance is suspicious.
+    const actualSize = stat.size;
+    base.actualSizeBytes = actualSize;
+    if (change.sizeBytes > 0) {
+        const ratio = actualSize / change.sizeBytes;
+        if (ratio < 1 - shrinkTolerance) {
+            let snippet = '';
+            try {
+                snippet = readFileSync(abs, 'utf8').slice(0, 200).replace(/\s+/g, ' ');
+            }
+            catch {
+                /* ignore */
+            }
+            return {
+                ...base,
+                status: 'shrunk',
+                detail: `actual ${actualSize}B is < ${Math.round((1 - shrinkTolerance) * 100)}% of expected ${change.sizeBytes}B${snippet ? ` (head: "${snippet}")` : ''}`,
+            };
+        }
+    }
+    else if (actualSize === 0) {
+        return { ...base, status: 'no-content', detail: 'file is empty' };
+    }
+    return base;
+}
+function handoffFor(status, totals, folderCount) {
+    if (status === 'failed') {
+        return `Scaffold integrity failed: ${totals.missing} missing, ${totals.unexpectedType} type mismatch. Re-run \`shrk apply <plan>\` or investigate manually.`;
+    }
+    if (status === 'partial') {
+        const bits = [];
+        if (totals.shrunk > 0)
+            bits.push(`${totals.shrunk} file(s) shrunk past tolerance`);
+        if (folderCount > 0)
+            bits.push(`folder op(s) inconsistent`);
+        return `Scaffold OK but with warnings: ${bits.join(', ')}. Probably fine but worth a glance.`;
+    }
+    return 'Scaffold looks intact — every planned file is on disk with the expected envelope.';
+}
+function renderText(r) {
+    process.stdout.write(header(`scaffold-validate — ${r.templateId}${r.name ? ` (${r.name})` : ''}`));
+    process.stdout.write(`plan:        ${r.planFile}\n`);
+    process.stdout.write(`status:      ${r.status}\n`);
+    process.stdout.write(`summary:     ${r.totals.compliant}/${r.totals.expected} compliant, ` +
+        `${r.totals.missing} missing, ${r.totals.shrunk} shrunk, ${r.totals.unexpectedType} type-mismatch\n`);
+    process.stdout.write('\n');
+    for (const f of r.findings) {
+        const marker = f.status === 'compliant' ? '✓' : f.status === 'missing' ? '✗' : f.status === 'shrunk' ? '⚠' : '?';
+        process.stdout.write(`  ${marker} ${f.relativePath} [${f.type}]`);
+        if (f.detail)
+            process.stdout.write(` — ${f.detail}`);
+        process.stdout.write('\n');
+    }
+    if (r.folderOpFindings.length > 0) {
+        process.stdout.write('\nfolder ops:\n');
+        for (const f of r.folderOpFindings) {
+            const marker = f.status === 'compliant' ? '✓' : '✗';
+            process.stdout.write(`  ${marker} ${f.kind} ${f.targetPath}${f.detail ? ` — ${f.detail}` : ''}\n`);
+        }
+    }
+    process.stdout.write(`\nhandoff: ${r.handoffForClaude}\n`);
+}

package/dist/commands/smart-context.command.d.ts

@@ -0,0 +1,30 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * Gemini-backed context enrichment.
+ *
+ * Sits next to `shrk ask` as an explicit, opt-in AI surface — the
+ * deterministic engine (`shrk context`, `shrk brief`, MCP tools) stays
+ * AI-free. See docs/smart-context.md and the
+ * `.claude/skills/shrk-smart-context/` skill for the agent workflow.
+ *
+ * Verbs:
+ *   - `smart-context "<task>"`               — single brief (default).
+ *   - `smart-context "<task>" --plan`        — single structured plan.
+ *   - `smart-context "<task>" --ai-plan`     — two-stage AI-assisted plan.
+ *   - `smart-context "<task>" --save`        — persist under .sharkcraft/smart-context/.
+ *   - `smart-context plan-ahead "t1" "t2"`   — batch-save plans for an upcoming queue.
+ *   - `smart-context list`                   — list saved entries.
+ *   - `smart-context show <slug>`            — print a saved entry.
+ */
+export declare const smartContextCommand: ICommandHandler;
+/** `shrk smart-context plan-ahead "task1" "task2" ...` — batch-saves plans. */
+export declare const smartContextPlanAheadCommand: ICommandHandler;
+/** `shrk smart-context list` — list saved entries. */
+export declare const smartContextListCommand: ICommandHandler;
+/** `shrk smart-context show <slug>` — print a saved entry. */
+export declare const smartContextShowCommand: ICommandHandler;
+/** `shrk smart-context embeddings build` — (re)build the semantic index. */
+export declare const smartContextEmbeddingsBuildCommand: ICommandHandler;
+/** `shrk smart-context embeddings-status` — freshness report (no model load). */
+export declare const smartContextEmbeddingsStatusCommand: ICommandHandler;
+//# sourceMappingURL=smart-context.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6BhC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA+JjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAgHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC"}