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

package/dist/commands/init.command.js

@@ -6,6 +6,7 @@ import { listBuiltInSurfaceProfiles, suggestSurfaceProfile } from '@shrkcrft/ins
 import { INIT_FILES } from "../init/init-templates.js";
 import { buildDetectedBlock, renderDetectedBlockText } from "../init/detected-block.js";
 import { ensureSharkcraftGitignore, renderGitignorePatch } from "../init/gitignore.js";
+import { annotatePathsAgainstDisk } from "../init/paths-advisory.js";
 import { applySurfaceTextEdit } from "../surface/surface-config-writer.js";
 import { flagBool, flagString, resolveCwd } from "../command-registry.js";
 import { bullet, header } from "../output/format-output.js";
@@ -133,6 +134,11 @@ async function applyPresetInit(cwd, mode) {
             source: 'override',
         });
     }
+    // Workspace-shape advisory: when the preset emits path conventions
+    // that don't exist in this repo (common with generic presets in
+    // framework-specific repos), annotate paths.ts so the user knows
+    // which defaults to fix.
+    const pathsAdvisory = annotatePathsAgainstDisk(cwd, plan.sharkcraftDir);
     process.stdout.write(header('SharkCraft initialized'));
     process.stdout.write(`Preset: ${preset.id} — ${preset.title}\n`);
     process.stdout.write(`Folder: ${plan.sharkcraftDir}\n`);
@@ -169,16 +175,29 @@ async function applyPresetInit(cwd, mode) {
             process.stdout.write('\n' + renderGitignorePatch(patch, false));
         }
     }
+    if (pathsAdvisory.annotated) {
+        renderPathsAdvisory(pathsAdvisory);
+    }
     process.stdout.write('\nNext:\n');
-    for (const cmd of preset.recommendedNextCommands ?? [
-        'shrk doctor',
-        'shrk context --task "<task>"',
-    ]) {
+    process.stdout.write(bullet('$ shrk doctor                            — verify the setup (shape-aware verdict)') + '\n');
+    process.stdout.write(bullet('$ shrk brief                             — single-page brief Claude reads first') + '\n');
+    process.stdout.write(bullet('$ shrk export claude-skill --write       — inline the rules into Claude\'s prompt via .claude/skills/') + '\n');
+    for (const cmd of preset.recommendedNextCommands ?? []) {
         process.stdout.write(bullet(`$ ${cmd}`) + '\n');
     }
     process.stdout.write(bullet('Start the MCP server: `shrk mcp serve` (or run it via Claude Code)') + '\n');
     return 0;
 }
+function renderPathsAdvisory(advisory) {
+    process.stdout.write('\n');
+    process.stdout.write(header('Paths advisory'));
+    process.stdout.write('These preset-default paths do not exist in this repo:\n');
+    for (const p of advisory.missingPaths) {
+        process.stdout.write(bullet(p) + '\n');
+    }
+    process.stdout.write('\nEdit sharkcraft/paths.ts to match your real layout. ' +
+        'Run `shrk onboard --dry-run` to see what the engine infers.\n');
+}
 function applyLegacyInit(cwd, force) {
     const { root } = detectProjectRoot(cwd);
     const sharkcraftDir = nodePath.join(root, 'sharkcraft');
@@ -212,6 +231,10 @@ function applyLegacyInit(cwd, force) {
         for (const s of skipped)
             process.stdout.write(bullet(s) + '\n');
     }
+    const legacyAdvisory = annotatePathsAgainstDisk(cwd, sharkcraftDir);
+    if (legacyAdvisory.annotated) {
+        renderPathsAdvisory(legacyAdvisory);
+    }
     process.stdout.write('\nNext:\n');
     process.stdout.write(bullet('Run `shrk inspect` to see your project summary.') + '\n');
     process.stdout.write(bullet('Run `shrk knowledge list` to see what was seeded.') + '\n');
@@ -220,13 +243,23 @@ function applyLegacyInit(cwd, force) {
 }
 export const initCommand = {
     name: 'init',
-    description: 'Initialize a sharkcraft/ folder in the current repository. Pass --preset <id> to apply a built-in preset (default: generic). Use --zero-config or --preset auto to detect the workspace and pick a preset automatically. Use --legacy for the full pre-preset seed.',
-    usage: 'shrk init [--preset <id|auto>] [--zero-config] [--dry-run] [--write] [--legacy] [--force] [--merge] [--suggest-only] [--no-gitignore] [--surface-profile <id>]',
+    description: 'Initialize a sharkcraft/ folder in the current repository. Pass --preset <id> to apply a built-in preset (default: generic). Use --zero-config or --preset auto to detect the workspace and pick a preset automatically. Use --legacy for the full pre-preset seed. Pass --infer to scan the repo and populate sharkcraft/* with the real signals it finds (paths from disk, rules from tsconfig/package.json, boundaries from layer structure) — combines with --preset to add inferred entries on top of the preset baseline. Pass --with-claude-skill to also generate .claude/skills/<name>/SKILL.md so Claude Code picks up the rules automatically.',
+    usage: 'shrk init [--preset <id|auto>] [--zero-config] [--infer] [--dry-run] [--write] [--with-claude-skill] [--legacy] [--force] [--merge] [--suggest-only] [--no-gitignore] [--surface-profile <id>]',
     async run(args) {
         const force = flagBool(args, 'force');
         const merge = flagBool(args, 'merge');
         const cwd = resolveCwd(args);
+        const wantInfer = flagBool(args, 'infer');
         const skipGitignore = flagBool(args, 'no-gitignore');
+        // `--infer` mode short-circuits the preset path entirely. The
+        // inferred output IS the populated sharkcraft/*, no preset
+        // baseline to merge against. This is the cleaner contract: the
+        // user opted into "scan my repo and tell me what's there", and
+        // adding a preset's static defaults on top would muddy the
+        // confidence reporting in .inferred-report.md.
+        if (wantInfer) {
+            return runInferInit(cwd, args, force);
+        }
         if (flagBool(args, 'legacy')) {
             const code = applyLegacyInit(cwd, force);
             if (code === 0 && !skipGitignore) {
@@ -287,7 +320,7 @@ export const initCommand = {
         if (dryRun) {
             process.stdout.write(`Surface profile: ${surfaceDecision.profile} (${surfaceDecision.source}) — ${surfaceDecision.reason}\n`);
         }
-        return applyPresetInit(cwd, {
+        const presetCode = await applyPresetInit(cwd, {
             presetId,
             dryRun,
             force,
@@ -297,5 +330,139 @@ export const initCommand = {
             surfaceProfile: surfaceDecision.profile,
             surfaceProfileReason: surfaceDecision.reason,
         });
+        // `--with-claude-skill` chains the claude-skill export onto the init
+        // so a fresh user goes from `npx shrk init --with-claude-skill --write`
+        // to a working .claude/skills/<name>/SKILL.md in one step. Skipped in
+        // dry-run + when init itself didn't succeed.
+        if (presetCode === 0 &&
+            !dryRun &&
+            (flagBool(args, 'with-claude-skill') || flagBool(args, 'with-skill'))) {
+            const skillCode = await runClaudeSkillExportAfterInit(cwd, force);
+            // Init success is what we report; skill failure is logged but
+            // doesn't fail the init exit code (otherwise users would see a
+            // half-applied repo with a non-zero exit and panic).
+            if (skillCode !== 0) {
+                process.stderr.write('\n(claude-skill export failed — re-run `shrk export claude-skill --write` to retry.)\n');
+            }
+        }
+        return presetCode;
     },
 };
+/**
+ * Chain the claude-skill export onto a successful init. Loads the
+ * exporter lazily (it depends on inspectSharkcraft which has its own
+ * caching) and writes the skill file using the same `--force` semantics
+ * as init itself.
+ */
+/**
+ * `shrk init --infer` — scan the repo and populate `sharkcraft/*`
+ * with the real signals it finds, instead of writing preset defaults.
+ *
+ * Pipeline:
+ *   1. `inspectSharkcraft({ cwd })` builds the full inspection.
+ *   2. `buildOnboardingPlan(inspection)` extracts inferred paths,
+ *      rules, boundaries, pipelines, verification commands.
+ *   3. `synthesizeFromOnboarding(plan)` triages each entry by
+ *      confidence and emits populated `sharkcraft/*.ts` files plus
+ *      a companion `.inferred-report.md` + `.inferred-report.json`.
+ *   4. Writer respects `--dry-run` / `--write` / `--force` /
+ *      `--with-claude-skill` semantics consistently with the
+ *      preset-init path.
+ *
+ * Honest-by-default: every adopted entry is tagged with its source
+ * signal; medium-confidence rows get a `// TODO: review` marker; low-
+ * confidence rows are dropped from the populated files and listed in
+ * the report so the user knows exactly what was inferred vs needs
+ * authoring.
+ */
+async function runInferInit(cwd, args, force) {
+    const { inspectSharkcraft, buildOnboardingPlan, synthesizeFromOnboarding } = await import('@shrkcrft/inspector');
+    const dryRun = !flagBool(args, 'write');
+    const sharkcraftDir = nodePath.join(cwd, 'sharkcraft');
+    process.stdout.write(header('SharkCraft init — infer'));
+    process.stdout.write(`Folder: ${sharkcraftDir}\n`);
+    const inspection = await inspectSharkcraft({ cwd });
+    const plan = buildOnboardingPlan(inspection);
+    const result = synthesizeFromOnboarding(plan);
+    // Summary block — print BEFORE writing so the user can ctrl-C if the
+    // confidence triage doesn't look right.
+    process.stdout.write(`\nDetected profiles: ${plan.projectSummary.profiles.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Inference triage: ${result.report.adoptedHigh.length} adopted directly · ` +
+        `${result.report.adoptedMedium.length} marked for review · ` +
+        `${result.report.dropped.length} dropped (in report).\n\n`);
+    const written = [];
+    const skipped = [];
+    const wouldWrite = [];
+    for (const file of result.files) {
+        const fullPath = nodePath.join(sharkcraftDir, file.path);
+        if (dryRun) {
+            wouldWrite.push(file.path);
+            continue;
+        }
+        mkdirSync(nodePath.dirname(fullPath), { recursive: true });
+        if (existsSync(fullPath) && !force) {
+            skipped.push(file.path);
+            continue;
+        }
+        writeFileSync(fullPath, file.content, 'utf8');
+        written.push(file.path);
+    }
+    if (dryRun) {
+        process.stdout.write('Would write:\n');
+        for (const p of wouldWrite)
+            process.stdout.write(bullet(p) + '\n');
+        process.stdout.write('\nRe-run with --write to persist.\n');
+        return 0;
+    }
+    if (written.length) {
+        process.stdout.write('Wrote:\n');
+        for (const p of written)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    if (skipped.length) {
+        process.stdout.write('\nSkipped (already exist; use --force to overwrite):\n');
+        for (const p of skipped)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    process.stdout.write(`\nRead the confidence report: \`${nodePath.join('sharkcraft', '.inferred-report.md')}\`\n` +
+        `It lists what was adopted high-confidence, what's marked for your review, ` +
+        `and what shrk can't infer (project-specific decisions you should author by hand).\n`);
+    process.stdout.write('\nNext:\n');
+    process.stdout.write(bullet('$ shrk doctor                            — verify the setup (shape-aware verdict)') + '\n');
+    process.stdout.write(bullet('$ shrk brief                             — single-page brief Claude reads first') + '\n');
+    process.stdout.write(bullet('$ shrk export claude-skill --write       — inline the rules into Claude\'s prompt') + '\n');
+    // Chain claude-skill if requested.
+    if (flagBool(args, 'with-claude-skill') || flagBool(args, 'with-skill')) {
+        const skillCode = await runClaudeSkillExportAfterInit(cwd, force);
+        if (skillCode !== 0) {
+            process.stderr.write('\n(claude-skill export failed — re-run `shrk export claude-skill --write` to retry.)\n');
+        }
+    }
+    // Gitignore + paths advisory same as preset path.
+    const skipGitignore = flagBool(args, 'no-gitignore');
+    if (!skipGitignore) {
+        const patch = ensureSharkcraftGitignore({ cwd, dryRun: false });
+        if (patch.added.length > 0) {
+            process.stdout.write('\n' + renderGitignorePatch(patch, false));
+        }
+    }
+    return 0;
+}
+async function runClaudeSkillExportAfterInit(cwd, force) {
+    const { inspectSharkcraft } = await import('@shrkcrft/inspector');
+    const { renderExport } = await import("../export/export-formats.js");
+    const inspection = await inspectSharkcraft({ cwd });
+    const result = renderExport(inspection, { format: 'claude-skill' });
+    const outputPath = nodePath.join(cwd, result.suggestedPath);
+    mkdirSync(nodePath.dirname(outputPath), { recursive: true });
+    if (existsSync(outputPath) && !force) {
+        process.stdout.write(`\nSkipped claude-skill export — ${result.suggestedPath} already exists. Pass --force to overwrite, or run \`shrk export claude-skill --write --force\`.\n`);
+        return 0;
+    }
+    writeFileSync(outputPath, result.content, 'utf8');
+    process.stdout.write('\n');
+    process.stdout.write(header('Claude-skill exported'));
+    process.stdout.write(`Wrote ${result.suggestedPath}\n` +
+        `  → Claude Code will auto-load this skill in any session opened against this repo.\n`);
+    return 0;
+}

package/dist/commands/knowledge-author.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-author.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-author.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoBH,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0GpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoEpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA2DlC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAmB3C,CAAC"}
+{"version":3,"file":"knowledge-author.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-author.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoBH,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0GpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoEpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAsElC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAmB3C,CAAC"}

package/dist/commands/knowledge-author.command.js

@@ -300,6 +300,15 @@ export const knowledgeLintCommand = {
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
+        // Loud guard: a 0-entry scan is NOT a clean pass — it almost always means
+        // the loader found nothing (wrong cwd / no `sharkcraft/` folder / no
+        // entries), which otherwise reads as "lint passed". Surface it on stderr so
+        // it can't be mistaken for success, while keeping stdout/JSON clean.
+        if (inspection.knowledgeEntries.length === 0) {
+            process.stderr.write('WARN  knowledge lint scanned 0 entries — there is nothing to lint (this is NOT a clean pass).\n' +
+                '      Likely causes: no `sharkcraft/` folder here, not at the workspace root, or no\n' +
+                '      knowledge entries are defined. Run `shrk doctor` to confirm how many entries load.\n');
+        }
         const entryIds = flagList(args, 'id');
         const includeAdvisory = !flagBool(args, 'no-advisory');
         const stale = buildKnowledgeStaleReport(inspection);

package/dist/commands/knowledge-propose.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-propose.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-propose.command.ts"],"names":[],"mappings":"AAqBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkDhC,eAAO,MAAM,uBAAuB,EAAE,eA0ErC,CAAC"}
+{"version":3,"file":"knowledge-propose.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-propose.command.ts"],"names":[],"mappings":"AAqBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkDhC,eAAO,MAAM,uBAAuB,EAAE,eA4ErC,CAAC"}

package/dist/commands/knowledge-propose.command.js

@@ -10,7 +10,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { AssetKind, AssetProvenanceOperation, KNOWLEDGE_PROPOSE_SCHEMA, proposeKnowledge, recordProvenance, renderKnowledgeProposeMarkdown, } from '@shrkcrft/inspector';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
 import { detectAuthoringSource } from "../authoring/authoring-kit.js";
 function renderProposalAsTs(p) {
@@ -54,13 +54,14 @@ function writeDraftFiles(cwd, report) {
 export const knowledgeProposeCommand = {
     name: 'propose',
     description: 'Propose stub knowledge entries for exported top-level constructs that lack coverage. Preview-first; --write materialises drafts under .sharkcraft/authoring/proposed/.',
-    usage: 'shrk knowledge propose [--path <file>] [--symbol <name>] [--since <ref>|--all] [--json] [--write]',
+    usage: 'shrk knowledge propose [--path <file>] [--symbol <name>] [--since <ref>|--all] [--max <n>] [--json] [--write]',
     async run(args) {
         const cwd = resolveCwd(args);
         const path = flagString(args, 'path');
         const symbol = flagString(args, 'symbol');
         const sinceFlag = flagString(args, 'since');
         const all = flagBool(args, 'all');
+        const max = flagNumber(args, 'max');
         const since = path
             ? undefined
             : symbol
@@ -73,6 +74,7 @@ export const knowledgeProposeCommand = {
             ...(path ? { path } : {}),
             ...(symbol ? { symbol } : {}),
             ...(since !== undefined ? { since } : {}),
+            ...(max !== undefined && max >= 0 ? { max } : {}),
         });
         if (flagBool(args, 'json')) {
             const payload = flagBool(args, 'write')

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

@@ -1 +1 @@
-{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,oBAAoB,EAAE,eAsBlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}
+{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,oBAAoB,EAAE,eA8ClC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}

package/dist/commands/knowledge.command.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join as nodePathJoin, resolve as nodePathResolve } from 'node:path';
 import { buildAnchorUpdatePlan, buildKnowledgeStaleReport, buildRenameFilePlan, buildRenameSymbolPlan, inspectSharkcraft, ReferenceCheckOutcome, resolveChangedFiles, } from '@shrkcrft/inspector';
-import { formatEntryCompact, formatEntryFull, searchKnowledge } from '@shrkcrft/knowledge';
+import { formatEntryCompact, formatEntryFull, projectKnowledgeEntryForJson, searchKnowledge, } from '@shrkcrft/knowledge';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
@@ -54,7 +54,7 @@ ${p.ci.exitNonZero ? `<p style="color:#a40000;font-weight:bold">FAIL: ${esc(p.ci
 export const knowledgeListCommand = {
     name: 'list',
     description: 'List knowledge entries.',
-    usage: 'shrk knowledge list [--type rule] [--scope x,y] [--json]',
+    usage: 'shrk knowledge list [--type rule] [--scope x,y] [--top N] [--brief] [--json]',
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const types = flagList(args, 'type');
@@ -64,8 +64,31 @@ export const knowledgeListCommand = {
             entries = entries.filter((e) => types.includes(String(e.type)));
         if (scope.length)
             entries = entries.filter((e) => scope.some((s) => e.scope.includes(s)));
+        // --top N: a deterministic, token-bounded slice. Sort by id first so the
+        // "top N" is stable across machines (entries otherwise load in fs-scan
+        // order). Reduce at the source instead of piping through `shrk compress`.
+        const top = flagNumber(args, 'top');
+        if (top !== undefined && top > 0) {
+            entries = [...entries].sort((a, b) => a.id.localeCompare(b.id)).slice(0, top);
+        }
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(entries.map((e) => ({ ...e }))) + '\n');
+            // --brief: project to the high-signal fields, dropping content / examples
+            // / metadata (the bulk of the payload) so an agent pays far fewer tokens.
+            const payload = flagBool(args, 'brief')
+                ? entries.map((e) => ({
+                    id: e.id,
+                    type: e.type,
+                    priority: e.priority,
+                    title: e.title,
+                    scope: e.scope,
+                    tags: e.tags,
+                    appliesWhen: e.appliesWhen,
+                }))
+                : // Project the declared IKnowledgeEntry fields by direct access rather
+                    // than spreading (`{ ...e }`), which copies only own-enumerable props
+                    // and would strip pack entries whose fields are getters/non-enumerable.
+                    entries.map(projectKnowledgeEntryForJson);
+            process.stdout.write(asJson(payload) + '\n');
             return 0;
         }
         process.stdout.write(header(`Knowledge (${entries.length})`));

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

@@ -0,0 +1,13 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk migrate` — run a multi-step migration definition.
+ *
+ *   - shrk migrate plan <id>      preview what each step would do
+ *   - shrk migrate apply <id>     execute the migration (writes!)
+ *
+ * Migrations live in `sharkcraft/migrations/<id>.ts` by default; pass
+ * `--from <path>` to point at a specific file. Each migration file
+ * default-exports an `IMigration` (use `defineMigration({ ... })`).
+ */
+export declare const migrateCommand: ICommandHandler;
+//# sourceMappingURL=migrate.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.command.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,eAsI5B,CAAC"}

package/dist/commands/migrate.command.js

@@ -0,0 +1,152 @@
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { safeImport } from '@shrkcrft/core';
+import { applyMigration, planMigration, pruneMigrations, resumeMigration, } from '@shrkcrft/migrate';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk migrate` — run a multi-step migration definition.
+ *
+ *   - shrk migrate plan <id>      preview what each step would do
+ *   - shrk migrate apply <id>     execute the migration (writes!)
+ *
+ * Migrations live in `sharkcraft/migrations/<id>.ts` by default; pass
+ * `--from <path>` to point at a specific file. Each migration file
+ * default-exports an `IMigration` (use `defineMigration({ ... })`).
+ */
+export const migrateCommand = {
+    name: 'migrate',
+    description: 'Orchestrate multi-step refactors: structural rewrites + shell + checks in one named, replayable migration.',
+    usage: 'shrk migrate plan <id> [--from <path>] [--json] | shrk migrate apply <id> [--from <path>] [--dry-run] [--no-stop-on-failure] [--json] | shrk migrate resume <id> [--from <path>] [--json] | shrk migrate prune [--older-than <days>] [--include-failed] [--dry-run] [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub !== 'plan' && sub !== 'apply' && sub !== 'resume' && sub !== 'prune') {
+            process.stderr.write(this.usage + '\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        if (sub === 'prune') {
+            const olderThanRaw = flagString(args, 'older-than');
+            const olderThanDays = olderThanRaw !== undefined ? Number(olderThanRaw) : undefined;
+            if (olderThanDays !== undefined && (!Number.isFinite(olderThanDays) || olderThanDays < 0)) {
+                process.stderr.write(`Invalid --older-than: ${olderThanRaw}\n`);
+                return 2;
+            }
+            const result = pruneMigrations({
+                projectRoot: cwd,
+                ...(olderThanDays !== undefined ? { olderThanDays } : {}),
+                includeFailed: flagBool(args, 'include-failed'),
+                dryRun: flagBool(args, 'dry-run'),
+            });
+            if (wantJson) {
+                process.stdout.write(asJson(result) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(`Migrate prune (${result.dryRun ? 'dry-run' : 'applied'})`));
+            process.stdout.write(kv('scanned', String(result.scanned)) + '\n');
+            process.stdout.write(kv('eligible', String(result.eligible)) + '\n');
+            process.stdout.write(kv('removed', String(result.removed)) + '\n');
+            for (const e of result.entries.slice(0, 50)) {
+                process.stdout.write(`  ${e.id}  (${e.overall}, ${e.ageDays}d, reason=${e.reason})\n`);
+            }
+            return 0;
+        }
+        const id = args.positional[1];
+        if (!id) {
+            process.stderr.write('Usage: shrk migrate ' + sub + ' <id>\n');
+            return 2;
+        }
+        const fromFlag = flagString(args, 'from');
+        const candidate = fromFlag
+            ? (nodePath.isAbsolute(fromFlag) ? fromFlag : nodePath.resolve(cwd, fromFlag))
+            : nodePath.resolve(cwd, 'sharkcraft', 'migrations', `${id}.ts`);
+        if (!existsSync(candidate)) {
+            process.stderr.write(`Migration file not found: ${candidate}\n`);
+            return 1;
+        }
+        const result = await safeImport(candidate);
+        if (!result.ok) {
+            process.stderr.write(`Migration load failed: ${result.error.message}\n`);
+            return 1;
+        }
+        const migration = result.module.default ?? result.module.migration;
+        if (!migration) {
+            process.stderr.write(`Migration module ${candidate} does not export a default migration.\n`);
+            return 1;
+        }
+        if (migration.id !== id) {
+            process.stderr.write(`Migration id mismatch: requested "${id}", file contains "${migration.id}".\n`);
+            return 1;
+        }
+        if (sub === 'plan') {
+            const plan = planMigration(migration, cwd);
+            if (wantJson) {
+                process.stdout.write(asJson(plan) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(`Migration plan: ${plan.migration.title}`));
+            process.stdout.write(kv('id', plan.migration.id) + '\n');
+            process.stdout.write(kv('total steps', String(plan.plannedSteps.length)) + '\n');
+            process.stdout.write(kv('total edits', String(plan.totalEdits)) + '\n');
+            process.stdout.write(kv('files affected', String(plan.totalFiles)) + '\n');
+            for (const step of plan.plannedSteps) {
+                process.stdout.write(`\n  [${step.index + 1}/${plan.plannedSteps.length}] ${step.id} (${step.step.kind})\n`);
+                if (step.description)
+                    process.stdout.write(`     ${step.description}\n`);
+                if (step.rewritePlan) {
+                    process.stdout.write(`     files=${step.rewritePlan.files.length}  edits=${step.rewritePlan.totalEdits}\n`);
+                }
+                else if (step.step.kind === 'shell' || step.step.kind === 'check') {
+                    process.stdout.write(`     $ ${step.step.command}\n`);
+                }
+            }
+            return 0;
+        }
+        // apply / resume
+        const dryRun = flagBool(args, 'dry-run');
+        const noStop = flagBool(args, 'no-stop-on-failure');
+        let report;
+        let resumedFromIndex = 0;
+        const resumeDiagnostics = [];
+        if (sub === 'resume') {
+            const result = resumeMigration(migration, {
+                projectRoot: cwd,
+                dryRun,
+                stopOnFailure: !noStop,
+            });
+            report = result.report;
+            resumedFromIndex = result.resumedFromIndex;
+            for (const d of result.diagnostics)
+                resumeDiagnostics.push(d);
+        }
+        else {
+            report = applyMigration(migration, {
+                projectRoot: cwd,
+                dryRun,
+                stopOnFailure: !noStop,
+            });
+        }
+        if (wantJson) {
+            process.stdout.write(asJson({ ...report, resumedFromIndex, resumeDiagnostics }) + '\n');
+            return report.overall === 'fail' ? 1 : 0;
+        }
+        if (sub === 'resume') {
+            for (const d of resumeDiagnostics)
+                process.stdout.write(`! ${d}\n`);
+        }
+        process.stdout.write(header(`Migration ${dryRun ? '(dry-run)' : '(applied)'}: ${report.overall.toUpperCase()}`));
+        process.stdout.write(kv('id', report.migration.id) + '\n');
+        process.stdout.write(kv('total duration', `${report.totalDurationMs}ms`) + '\n');
+        for (const s of report.steps) {
+            process.stdout.write(`  [${s.status.padEnd(8)}] ${s.id} (${s.kind})  (${s.durationMs}ms)\n`);
+            process.stdout.write(`              ${s.message}\n`);
+            if (s.rewriteStats && s.rewriteStats.conflicts.length > 0) {
+                for (const c of s.rewriteStats.conflicts.slice(0, 5)) {
+                    process.stdout.write(`                conflict: ${c}\n`);
+                }
+            }
+        }
+        return report.overall === 'fail' ? 1 : 0;
+    },
+};

package/dist/commands/move-plan.command.d.ts

@@ -0,0 +1,23 @@
+import { type ICommandHandler } from '../command-registry.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 declare const movePlanCommand: ICommandHandler;
+//# sourceMappingURL=move-plan.command.d.ts.map

package/dist/commands/move-plan.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"move-plan.command.d.ts","sourceRoot":"","sources":["../../src/commands/move-plan.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAqCrG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,eA4M7B,CAAC"}