@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.21

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/search-structural.command.d.ts

@@ -0,0 +1,18 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk search structural` — declarative AST pattern matching with
+ * optional rewrite mode (Wave 8). Patterns are JSON (no executable
+ * predicates) — either inline via --pattern or from a file via
+ * --pattern-file.
+ *
+ * Rewrite flow:
+ *   1. Pass `--rewrite '<json>'` (a `RewriteRecipe`) to compute a
+ *      rewrite plan.
+ *   2. Preview is shown by default (no fs writes).
+ *   3. Pass `--apply` to actually write the changes.
+ *
+ * The plan can be inspected as JSON via `--json` and replayed via
+ * `--plan-in <path>` (write the plan with `--plan-out <path>` first).
+ */
+export declare const searchStructuralCommand: ICommandHandler;
+//# sourceMappingURL=search-structural.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search-structural.command.d.ts","sourceRoot":"","sources":["../../src/commands/search-structural.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAkErC,CAAC"}

package/dist/commands/search-structural.command.js

@@ -0,0 +1,376 @@
+import { readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { applyRewritePlan, PatternRegistryStore, planRewrite, runSearch, signRewritePlan, STARTER_PATTERNS, verifySignedRewritePlan, } from '@shrkcrft/structural-search';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk search structural` — declarative AST pattern matching with
+ * optional rewrite mode (Wave 8). Patterns are JSON (no executable
+ * predicates) — either inline via --pattern or from a file via
+ * --pattern-file.
+ *
+ * Rewrite flow:
+ *   1. Pass `--rewrite '<json>'` (a `RewriteRecipe`) to compute a
+ *      rewrite plan.
+ *   2. Preview is shown by default (no fs writes).
+ *   3. Pass `--apply` to actually write the changes.
+ *
+ * The plan can be inspected as JSON via `--json` and replayed via
+ * `--plan-in <path>` (write the plan with `--plan-out <path>` first).
+ */
+export const searchStructuralCommand = {
+    name: 'search-structural',
+    description: 'Run an AST-shape pattern over the project. Patterns are declarative JSON. Optional rewrite mode: --rewrite <recipe-json> previews; --apply writes the change to disk.',
+    usage: 'shrk search-structural (--pattern <json> | --pattern-file <path>) [--limit N] [--rewrite <recipe-json>] [--rewrite-file <path>] [--apply] [--dry-run] [--plan-out <path>] [--plan-in <path>] [--sign] [--verify-signature] [--secret-env <VAR>] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        // `shrk search-structural registry ...` — pattern registry subverbs.
+        // Dispatch before any pattern parsing so a missing pattern file
+        // doesn't reject a registry-only call.
+        if (args.positional[0] === 'registry') {
+            return runRegistry({ ...args, positional: args.positional.slice(1) });
+        }
+        const planInPath = flagString(args, 'plan-in');
+        if (planInPath) {
+            return runFromSavedPlan(cwd, planInPath, args, wantJson);
+        }
+        const inline = flagString(args, 'pattern');
+        const patternFile = flagString(args, 'pattern-file');
+        if (!inline && !patternFile) {
+            process.stderr.write(this.usage + '\n');
+            return 2;
+        }
+        let pattern;
+        try {
+            pattern = parseJson(inline, patternFile, cwd);
+        }
+        catch (e) {
+            process.stderr.write(`Pattern parse error: ${e.message}\n`);
+            return 2;
+        }
+        const limit = Number(flagString(args, 'limit') ?? '200');
+        // Rewrite path?
+        const recipeInline = flagString(args, 'rewrite');
+        const recipeFile = flagString(args, 'rewrite-file');
+        if (recipeInline || recipeFile) {
+            let recipe;
+            try {
+                recipe = parseJson(recipeInline, recipeFile, cwd);
+            }
+            catch (e) {
+                process.stderr.write(`Recipe parse error: ${e.message}\n`);
+                return 2;
+            }
+            return runRewrite(cwd, pattern, recipe, args, wantJson);
+        }
+        // Plain match path.
+        const result = runSearch({ projectRoot: cwd, pattern, limit });
+        if (wantJson) {
+            process.stdout.write(asJson(result) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Structural search: ${result.pattern.summary}`));
+        process.stdout.write(kv('files scanned', String(result.filesScanned)) + '\n');
+        process.stdout.write(kv('matches', String(result.matchCount)) + '\n');
+        if (result.truncated)
+            process.stdout.write(kv('truncated', 'yes') + '\n');
+        for (const m of result.matches.slice(0, 50)) {
+            process.stdout.write(`  ${m.file}:${m.line}:${m.column}  ${m.nodeKind}  ${m.excerpt}\n`);
+        }
+        for (const d of result.diagnostics.slice(0, 10)) {
+            process.stdout.write(`! ${d}\n`);
+        }
+        return 0;
+    },
+};
+async function runRewrite(cwd, pattern, recipe, args, wantJson) {
+    const apply = flagBool(args, 'apply');
+    const dryRun = flagBool(args, 'dry-run');
+    const planOut = flagString(args, 'plan-out');
+    const wantSign = flagBool(args, 'sign');
+    const secretEnv = flagString(args, 'secret-env') ?? 'SHRKCRFT_REWRITE_SECRET';
+    const plan = planRewrite({ projectRoot: cwd, pattern, recipe });
+    if (planOut) {
+        const abs = nodePath.isAbsolute(planOut) ? planOut : nodePath.resolve(cwd, planOut);
+        const { writeFileSync, mkdirSync } = await import('node:fs');
+        mkdirSync(nodePath.dirname(abs), { recursive: true });
+        const payload = wantSign
+            ? signPlanOrFail(plan, secretEnv)
+            : plan;
+        if (!payload)
+            return 2;
+        writeFileSync(abs, JSON.stringify(payload, null, 2), 'utf8');
+    }
+    if (!apply) {
+        // Preview only.
+        if (wantJson) {
+            process.stdout.write(asJson(plan) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Rewrite plan (preview): ${recipe.kind}`));
+        process.stdout.write(kv('files scanned', String(plan.filesScanned)) + '\n');
+        process.stdout.write(kv('files to change', String(plan.files.length)) + '\n');
+        process.stdout.write(kv('total edits', String(plan.totalEdits)) + '\n');
+        if (planOut)
+            process.stdout.write(kv('plan written to', planOut) + '\n');
+        for (const f of plan.files.slice(0, 20)) {
+            process.stdout.write(`\n  ${f.path}:\n`);
+            for (const e of f.edits.slice(0, 5)) {
+                process.stdout.write(`    L${e.line}  ${truncate(e.before)}  →  ${truncate(e.replacement)}\n`);
+            }
+            if (f.edits.length > 5)
+                process.stdout.write(`    … (${f.edits.length - 5} more edits)\n`);
+        }
+        if (plan.files.length > 20) {
+            process.stdout.write(`\n  … (${plan.files.length - 20} more files)\n`);
+        }
+        for (const d of plan.diagnostics.slice(0, 10))
+            process.stdout.write(`! ${d}\n`);
+        process.stdout.write(`\nTo write these changes: rerun with --apply.\n`);
+        return 0;
+    }
+    // Apply path.
+    const result = applyRewritePlan(plan, { projectRoot: cwd, dryRun });
+    if (wantJson) {
+        process.stdout.write(asJson({ plan, result, dryRun }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Rewrite ${dryRun ? '(dry-run)' : '(applied)'}: ${recipe.kind}`));
+    process.stdout.write(kv('files attempted', String(result.filesAttempted)) + '\n');
+    process.stdout.write(kv('files changed', String(result.filesChanged)) + '\n');
+    process.stdout.write(kv('bytes written', String(result.bytesWritten)) + '\n');
+    if (result.conflicts.length > 0) {
+        process.stdout.write(kv('conflicts (skipped)', String(result.conflicts.length)) + '\n');
+        for (const c of result.conflicts.slice(0, 10))
+            process.stdout.write(`  • ${c}\n`);
+    }
+    for (const d of result.diagnostics.slice(0, 10))
+        process.stdout.write(`! ${d}\n`);
+    return result.conflicts.length > 0 ? 1 : 0;
+}
+async function runFromSavedPlan(cwd, planPath, args, wantJson) {
+    const abs = nodePath.isAbsolute(planPath) ? planPath : nodePath.resolve(cwd, planPath);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(abs, 'utf8'));
+    }
+    catch (e) {
+        process.stderr.write(`Plan file read error: ${e.message}\n`);
+        return 2;
+    }
+    const apply = flagBool(args, 'apply');
+    const dryRun = flagBool(args, 'dry-run');
+    const verify = flagBool(args, 'verify-signature');
+    const secretEnv = flagString(args, 'secret-env') ?? 'SHRKCRFT_REWRITE_SECRET';
+    if (!apply) {
+        process.stderr.write('Replaying a saved plan requires --apply (or --apply --dry-run).\n');
+        return 2;
+    }
+    const wrapper = raw;
+    const isSigned = wrapper.schema === 'sharkcraft.structural-rewrite-plan-signed/v1';
+    if (verify) {
+        if (!isSigned) {
+            process.stderr.write('--verify-signature passed but plan is not signed.\n');
+            return 1;
+        }
+        const secret = process.env[secretEnv];
+        if (!secret) {
+            process.stderr.write(`Missing secret: env var ${secretEnv} not set.\n`);
+            return 1;
+        }
+        const v = verifySignedRewritePlan(raw, { secret });
+        if (!v.ok) {
+            process.stderr.write(`Signature verification failed (${v.reason}): ${v.message ?? ''}\n`);
+            return 1;
+        }
+    }
+    const plan = isSigned ? raw.plan : raw;
+    const result = applyRewritePlan(plan, { projectRoot: cwd, dryRun });
+    if (wantJson) {
+        process.stdout.write(asJson({ result, dryRun, verified: verify }) + '\n');
+        return result.conflicts.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header(`Rewrite ${dryRun ? '(dry-run)' : '(applied)'} from saved plan`));
+    if (verify)
+        process.stdout.write(kv('signature', 'verified') + '\n');
+    process.stdout.write(kv('files changed', String(result.filesChanged)) + '\n');
+    process.stdout.write(kv('conflicts (skipped)', String(result.conflicts.length)) + '\n');
+    return result.conflicts.length > 0 ? 1 : 0;
+}
+function signPlanOrFail(plan, secretEnv) {
+    const secret = process.env[secretEnv];
+    if (!secret) {
+        process.stderr.write(`Missing secret: env var ${secretEnv} not set (required for --sign).\n`);
+        return undefined;
+    }
+    return signRewritePlan(plan, { secret });
+}
+function parseJson(inline, fileFlag, cwd) {
+    if (inline)
+        return JSON.parse(inline);
+    const abs = nodePath.isAbsolute(fileFlag)
+        ? fileFlag
+        : nodePath.resolve(cwd, fileFlag);
+    return JSON.parse(readFileSync(abs, 'utf8'));
+}
+function truncate(s) {
+    const oneLine = s.replace(/\s+/g, ' ').trim();
+    return oneLine.length > 60 ? oneLine.slice(0, 57) + '…' : oneLine;
+}
+async function runRegistry(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const sub = args.positional[0] ?? 'list';
+    const store = new PatternRegistryStore(cwd);
+    if (sub === 'list') {
+        const reg = store.read();
+        if (wantJson) {
+            process.stdout.write(asJson({ path: store.absPath, registry: reg }) + '\n');
+            return 0;
+        }
+        if (reg.patterns.length === 0) {
+            process.stdout.write('No patterns registered.\n');
+            process.stdout.write(`(file: ${store.absPath})\n`);
+            return 0;
+        }
+        process.stdout.write(header(`Pattern registry (${reg.patterns.length})`));
+        process.stdout.write(kv('path', store.absPath) + '\n');
+        for (const p of reg.patterns) {
+            const err = p.lastValidationError ? ` ✗ ${p.lastValidationError}` : '';
+            const validated = p.lastValidatedAt ? ` [validated ${p.lastValidatedAt}]` : '';
+            process.stdout.write(`  • ${p.id} (${p.pattern.kind})${validated}${err}\n`);
+            if (p.title)
+                process.stdout.write(`    ${p.title}\n`);
+        }
+        return 0;
+    }
+    if (sub === 'add') {
+        const id = flagString(args, 'id');
+        const inline = flagString(args, 'pattern');
+        const patternFile = flagString(args, 'pattern-file');
+        const title = flagString(args, 'title');
+        const description = flagString(args, 'description');
+        if (!id) {
+            process.stderr.write('Usage: shrk search-structural registry add --id <id> (--pattern <json> | --pattern-file <path>) [--title "..."] [--description "..."]\n');
+            return 2;
+        }
+        if (!inline && !patternFile) {
+            process.stderr.write('Missing pattern body (--pattern or --pattern-file).\n');
+            return 2;
+        }
+        let pattern;
+        try {
+            pattern = parseJson(inline, patternFile, cwd);
+        }
+        catch (e) {
+            process.stderr.write(`Pattern parse error: ${e.message}\n`);
+            return 2;
+        }
+        const envelope = {
+            schema: 'sharkcraft.structural-pattern/v1',
+            id,
+            ...(title ? { title } : {}),
+            ...(description ? { description } : {}),
+            pattern,
+        };
+        const { result, entry } = store.add(envelope);
+        if (!result.ok) {
+            if (wantJson) {
+                process.stdout.write(asJson({ ok: false, error: result.error }) + '\n');
+            }
+            else {
+                process.stderr.write(`Pattern rejected: ${result.error}\n`);
+            }
+            return 2;
+        }
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: true, entry, path: store.absPath }) + '\n');
+            return 0;
+        }
+        process.stdout.write(`Pattern registered: ${entry?.id} (${entry?.pattern.kind})\n`);
+        process.stdout.write(`  → ${store.absPath}\n`);
+        return 0;
+    }
+    if (sub === 'remove') {
+        const id = args.positional[1] ?? flagString(args, 'id');
+        if (!id) {
+            process.stderr.write('Usage: shrk search-structural registry remove <id>\n');
+            return 2;
+        }
+        const removed = store.remove(id);
+        if (wantJson) {
+            process.stdout.write(asJson({ removed, id }) + '\n');
+            return removed ? 0 : 1;
+        }
+        process.stdout.write(removed ? `Removed pattern "${id}".\n` : `No pattern with id "${id}".\n`);
+        return removed ? 0 : 1;
+    }
+    if (sub === 'validate') {
+        const result = store.validateAll();
+        if (wantJson) {
+            process.stdout.write(asJson(result) + '\n');
+            return result.failed === 0 ? 0 : 1;
+        }
+        process.stdout.write(header('Pattern registry validation'));
+        process.stdout.write(kv('total', String(result.total)) + '\n');
+        process.stdout.write(kv('failed', String(result.failed)) + '\n');
+        if (result.failed > 0) {
+            process.stdout.write('\nFailures:\n');
+            for (const e of result.errors) {
+                process.stdout.write(`  ✗ ${e.id} — ${e.error}\n`);
+            }
+            return 1;
+        }
+        process.stdout.write('\nAll patterns valid.\n');
+        return 0;
+    }
+    if (sub === 'clear') {
+        const cleared = store.clear();
+        if (wantJson) {
+            process.stdout.write(asJson({ cleared, path: store.absPath }) + '\n');
+            return 0;
+        }
+        process.stdout.write(cleared ? `Cleared ${store.absPath}\n` : 'No registry file to clear.\n');
+        return 0;
+    }
+    if (sub === 'seed') {
+        const force = flagBool(args, 'force');
+        const existing = store.read();
+        if (existing.patterns.length > 0 && !force) {
+            const msg = `Registry already has ${existing.patterns.length} pattern(s). Use --force to merge / overwrite seed entries.\n`;
+            if (wantJson) {
+                process.stdout.write(asJson({ ok: false, error: 'non-empty' }) + '\n');
+                return 1;
+            }
+            process.stderr.write(msg);
+            return 1;
+        }
+        const added = [];
+        const failed = [];
+        for (const envelope of STARTER_PATTERNS) {
+            const { result, entry } = store.add(envelope);
+            if (result.ok && entry) {
+                added.push(entry.id);
+            }
+            else {
+                failed.push({ id: envelope.id ?? '?', error: result.error ?? 'unknown' });
+            }
+        }
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: failed.length === 0, added, failed, path: store.absPath }) + '\n');
+            return failed.length === 0 ? 0 : 1;
+        }
+        process.stdout.write(`Seeded ${added.length} starter pattern(s) → ${store.absPath}\n`);
+        for (const id of added)
+            process.stdout.write(`  + ${id}\n`);
+        if (failed.length > 0) {
+            process.stdout.write('\nFailures:\n');
+            for (const f of failed)
+                process.stdout.write(`  ✗ ${f.id} — ${f.error}\n`);
+        }
+        return failed.length === 0 ? 0 : 1;
+    }
+    process.stderr.write('Usage: shrk search-structural registry <list|add|remove|validate|clear|seed> [--json]\n');
+    return 2;
+}

package/dist/commands/search.command.js

@@ -27,7 +27,7 @@ function parseSources(args) {
 }
 export const searchCommand = {
     name: 'search',
-    description: 'Universal search across commands, MCP tools, knowledge, rules, paths, conventions, templates, helpers, playbooks, constructs, policies, decisions, scaffold patterns, contract templates, migration profiles, plugin lifecycle profiles, feedback rules, task routing hints, docs, recent reports. Default emits the 7-section unified output; pass --legacy for the flat output.',
+    description: 'Universal search across commands, MCP tools, knowledge, rules, paths, conventions, templates, helpers, playbooks, constructs, policies, decisions, scaffold patterns, contract templates, migration profiles, feedback rules, task routing hints, docs, recent reports. Default emits the 7-section unified output; pass --legacy for the flat output.',
     usage: 'shrk search <query> [--kind <kind>] [--source local|pack|...] [--limit N] [--explain] [--commands-only] [--actions-only] [--format text|markdown|json] [--legacy]',
     async run(args) {
         // Sub-dispatch for `shrk search tuning [list|doctor]`.