@shrkcrft/cli 0.1.0-alpha.2

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

@@ -0,0 +1,6 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const pathsListCommand: ICommandHandler;
+export declare const pathsGetCommand: ICommandHandler;
+export declare const pathsSearchCommand: ICommandHandler;
+export declare const pathsBestCommand: ICommandHandler;
+//# sourceMappingURL=paths.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.command.d.ts","sourceRoot":"","sources":["../../src/commands/paths.command.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,gBAAgB,EAAE,eAmB9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAsBhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eA0B9B,CAAC"}

package/dist/commands/paths.command.js

@@ -0,0 +1,97 @@
+import { inspectSharkcraft } from '@shrkcrft/inspector';
+import { formatEntryCompact, formatEntryFull } from '@shrkcrft/knowledge';
+import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+export const pathsListCommand = {
+    name: 'list',
+    description: 'List path conventions.',
+    usage: 'shrk paths list [--json]',
+    async run(args) {
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const paths = inspection.pathService.list();
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(paths) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Path conventions (${paths.length})`));
+        for (const p of paths) {
+            const target = p.metadata?.path ?? '(unknown)';
+            process.stdout.write(`  ${p.id.padEnd(30)} → ${target}\n`);
+            process.stdout.write(`     ${p.title} (priority=${p.priority})\n`);
+        }
+        return 0;
+    },
+};
+export const pathsGetCommand = {
+    name: 'get',
+    description: 'Get one path convention.',
+    usage: 'shrk paths get <id> [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk paths get <id>\n');
+            return 2;
+        }
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const path = inspection.pathService.get(id);
+        if (!path) {
+            process.stderr.write(`No path convention with id "${id}".\n`);
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(path) + '\n');
+            return 0;
+        }
+        process.stdout.write(formatEntryFull(path) + '\n');
+        return 0;
+    },
+};
+export const pathsSearchCommand = {
+    name: 'search',
+    description: 'Search path conventions.',
+    usage: 'shrk paths search <query> [--scope x,y] [--limit 10]',
+    async run(args) {
+        const query = args.positional.join(' ').trim();
+        const scope = flagList(args, 'scope');
+        const limit = flagNumber(args, 'limit') ?? 10;
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const results = inspection.pathService.search({
+            query: query.length ? query : undefined,
+            scope: scope.length ? scope : undefined,
+            limit,
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(results) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Path conventions (${results.length})`));
+        for (const r of results)
+            process.stdout.write(formatEntryCompact(r) + '\n');
+        return 0;
+    },
+};
+export const pathsBestCommand = {
+    name: 'best',
+    description: 'Pick the best path for a task.',
+    usage: 'shrk paths best --task "<task>"',
+    async run(args) {
+        const task = flagString(args, 'task');
+        if (!task) {
+            process.stderr.write('Missing --task\n');
+            return 2;
+        }
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const selection = inspection.pathService.findBestForTask(task);
+        if (!selection) {
+            process.stdout.write('No matching path convention.\n');
+            return 0;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(selection) + '\n');
+            return 0;
+        }
+        process.stdout.write(`Best: ${selection.convention.id} → ${selection.convention.metadata?.path}\n`);
+        process.stdout.write(`Reason: ${selection.reason} (score=${selection.score})\n`);
+        return 0;
+    },
+};

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

@@ -0,0 +1,9 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const pipelinesListCommand: ICommandHandler;
+export declare const pipelinesGetCommand: ICommandHandler;
+export declare const pipelinesContextCommand: ICommandHandler;
+export declare const pipelinesPlanCommand: ICommandHandler;
+export declare const pipelinesScriptCommand: ICommandHandler;
+export declare const pipelinesNextCommand: ICommandHandler;
+export declare const pipelinesVarsCommand: ICommandHandler;
+//# sourceMappingURL=pipelines.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipelines.command.d.ts","sourceRoot":"","sources":["../../src/commands/pipelines.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAOL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,oBAAoB,EAAE,eA2BlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAsDrC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA+DlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoCpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA6ClC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiElC,CAAC"}

package/dist/commands/pipelines.command.js

@@ -0,0 +1,308 @@
+import { inspectSharkcraft, buildProjectOverview, renderOverviewText } from '@shrkcrft/inspector';
+import { buildContext } from '@shrkcrft/context';
+import { findNextStep, formatPipelineCompact, formatPipelineFull, interpolatePipeline, renderPipelineScript, } from '@shrkcrft/pipelines';
+import { flagBool, flagNumber, flagString, flagList, flagVars, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+export const pipelinesListCommand = {
+    name: 'list',
+    description: 'List available pipelines.',
+    usage: 'shrk pipelines list [--json]',
+    async run(args) {
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const list = inspection.pipelineRegistry.list();
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(list.map((p) => ({
+                id: p.id,
+                title: p.title,
+                description: p.description,
+                tags: p.tags ?? [],
+                scope: p.scope ?? [],
+                appliesWhen: p.appliesWhen ?? [],
+                stepCount: p.steps.length,
+            }))) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Pipelines (${list.length})`));
+        for (const p of list)
+            process.stdout.write(formatPipelineCompact(p) + '\n');
+        return 0;
+    },
+};
+export const pipelinesGetCommand = {
+    name: 'get',
+    description: 'Show one pipeline by id.',
+    usage: 'shrk pipelines get <id> [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk pipelines get <id>\n');
+            return 2;
+        }
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const pipeline = inspection.pipelineRegistry.get(id);
+        if (!pipeline) {
+            process.stderr.write(`No pipeline with id "${id}".\n`);
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(pipeline) + '\n');
+            return 0;
+        }
+        process.stdout.write(formatPipelineFull(pipeline) + '\n');
+        return 0;
+    },
+};
+export const pipelinesContextCommand = {
+    name: 'context',
+    description: 'Combine a pipeline with a task-specific context. Returns the pipeline + relevant rules/paths/templates for the task.',
+    usage: 'shrk pipelines context <id> --task "<task>" [--max-tokens 3000] [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk pipelines context <id> --task "<task>"\n');
+            return 2;
+        }
+        const task = flagString(args, 'task');
+        if (!task) {
+            process.stderr.write('Missing --task\n');
+            return 2;
+        }
+        const maxTokens = flagNumber(args, 'max-tokens') ?? flagNumber(args, 'maxTokens') ?? 3000;
+        const scope = flagList(args, 'scope');
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const pipeline = inspection.pipelineRegistry.get(id);
+        if (!pipeline) {
+            process.stderr.write(`No pipeline with id "${id}".\n`);
+            return 1;
+        }
+        const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+        const ctxResult = buildContext(inspection.knowledgeEntries, {
+            task,
+            scope,
+            maxTokens,
+            projectOverview: renderOverviewText(overview),
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                pipeline,
+                context: ctxResult,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Pipeline + context: ${pipeline.id}`));
+        process.stdout.write(formatPipelineFull(pipeline) + '\n');
+        process.stdout.write('\n');
+        process.stdout.write(header(`Task context: ${task}`));
+        process.stdout.write(`tokens ≈ ${ctxResult.totalTokens} / ${ctxResult.maxTokens}, sections: ${ctxResult.sections.length}\n\n`);
+        process.stdout.write(ctxResult.body + '\n');
+        return 0;
+    },
+};
+export const pipelinesPlanCommand = {
+    name: 'plan',
+    description: 'Describe what running the pipeline would do for the given task. Does not execute anything.',
+    usage: 'shrk pipelines plan <id> --task "<task>" [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk pipelines plan <id> --task "<task>"\n');
+            return 2;
+        }
+        const task = flagString(args, 'task') ?? '<task>';
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const pipeline = inspection.pipelineRegistry.get(id);
+        if (!pipeline) {
+            process.stderr.write(`No pipeline with id "${id}".\n`);
+            return 1;
+        }
+        const interpolated = pipeline.steps.map((step) => ({
+            id: step.id,
+            type: step.type,
+            description: step.description,
+            required: step.required !== false,
+            humanReview: step.humanReview === true,
+            enabledWhen: step.enabledWhen,
+            instruction: step.instruction
+                ? step.instruction.replace(/<task>/g, task)
+                : undefined,
+            mcpTools: step.mcpTools ?? [],
+            cliCommands: (step.cliCommands ?? []).map((c) => c.replace(/<task>/g, task)),
+            references: step.references ?? [],
+        }));
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                pipeline: { id: pipeline.id, title: pipeline.title, description: pipeline.description },
+                task,
+                steps: interpolated,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Plan: ${pipeline.title} (task: ${task})`));
+        for (let i = 0; i < interpolated.length; i += 1) {
+            const step = interpolated[i];
+            const req = step.required ? '' : ' (optional)';
+            const review = step.humanReview ? ' — human review' : '';
+            const when = step.enabledWhen ? ` — when ${step.enabledWhen}` : '';
+            process.stdout.write(`\n${i + 1}. [${step.type}] ${step.id}${req}${review}${when}\n`);
+            if (step.description)
+                process.stdout.write(`     ${step.description}\n`);
+            if (step.instruction)
+                process.stdout.write(`     instruction: ${step.instruction}\n`);
+            if (step.mcpTools.length)
+                process.stdout.write(`     mcpTools: ${step.mcpTools.join(', ')}\n`);
+            for (const c of step.cliCommands)
+                process.stdout.write(`     $ ${c}\n`);
+            if (step.references.length) {
+                process.stdout.write(`     references: ${step.references.join(', ')}\n`);
+            }
+        }
+        process.stdout.write('\n');
+        return 0;
+    },
+};
+export const pipelinesScriptCommand = {
+    name: 'script',
+    description: 'Render a copy-pasteable shell script for the pipeline. apply/write steps include a manual-confirm prompt.',
+    usage: 'shrk pipelines script <id> --task "<task>" [--var key=value ...] [--include-optional <stepId>] [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk pipelines script <id> --task "<task>"\n');
+            return 2;
+        }
+        const task = flagString(args, 'task') ?? '<task>';
+        const inputs = flagVars(args);
+        const includeOptionalList = flagList(args, 'include-optional');
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const pipeline = inspection.pipelineRegistry.get(id);
+        if (!pipeline) {
+            process.stderr.write(`No pipeline with id "${id}".\n`);
+            return 1;
+        }
+        const interp = interpolatePipeline(pipeline, {
+            task,
+            projectRoot: inspection.projectRoot,
+            inputs,
+            includeOptional: includeOptionalList,
+        });
+        const script = renderPipelineScript(interp);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ pipelineId: pipeline.id, task, script }) + '\n');
+            return 0;
+        }
+        process.stdout.write(script + '\n');
+        return 0;
+    },
+};
+export const pipelinesNextCommand = {
+    name: 'next',
+    description: 'Return the next non-skipped step in the pipeline. Useful for "what should I do now?".',
+    usage: 'shrk pipelines next <id> --task "<task>" [--var key=value ...] [--include-optional <stepId>] [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk pipelines next <id> --task "<task>"\n');
+            return 2;
+        }
+        const task = flagString(args, 'task') ?? '<task>';
+        const inputs = flagVars(args);
+        const includeOptionalList = flagList(args, 'include-optional');
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const pipeline = inspection.pipelineRegistry.get(id);
+        if (!pipeline) {
+            process.stderr.write(`No pipeline with id "${id}".\n`);
+            return 1;
+        }
+        const interp = interpolatePipeline(pipeline, {
+            task,
+            projectRoot: inspection.projectRoot,
+            inputs,
+            includeOptional: includeOptionalList,
+        });
+        const next = findNextStep(interp);
+        if (!next) {
+            if (flagBool(args, 'json'))
+                process.stdout.write('null\n');
+            else
+                process.stdout.write('(no remaining steps)\n');
+            return 0;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(next) + '\n');
+            return 0;
+        }
+        process.stdout.write(`Next step: [${next.type}] ${next.id}${next.humanReview ? ' — HUMAN REVIEW' : ''}\n`);
+        if (next.description)
+            process.stdout.write(`  ${next.description}\n`);
+        if (next.instruction)
+            process.stdout.write(`  instruction: ${next.instruction}\n`);
+        if (next.mcpTools.length)
+            process.stdout.write(`  mcpTools: ${next.mcpTools.join(', ')}\n`);
+        for (const c of next.cliCommands)
+            process.stdout.write(`  $ ${c}\n`);
+        return 0;
+    },
+};
+export const pipelinesVarsCommand = {
+    name: 'vars',
+    description: 'Show the inputs a pipeline accepts (required/optional/defaults) plus optional steps.',
+    usage: 'shrk [--cwd <dir>] pipelines vars <pipelineId> [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk pipelines vars <pipelineId>\n');
+            return 2;
+        }
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const pipeline = inspection.pipelineRegistry.get(id);
+        if (!pipeline) {
+            process.stderr.write(`No pipeline with id "${id}".\n`);
+            return 1;
+        }
+        const optionalSteps = (pipeline.steps ?? []).filter((s) => s.required === false);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                id: pipeline.id,
+                title: pipeline.title,
+                inputs: pipeline.inputs?.map((v) => ({
+                    name: v.name,
+                    required: v.required ?? false,
+                    description: v.description ?? '',
+                    default: v.default,
+                    choices: v.choices ?? [],
+                })) ?? [],
+                optionalSteps: optionalSteps.map((s) => ({ id: s.id, description: s.description })),
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Pipeline inputs: ${pipeline.id}`));
+        process.stdout.write(kv('title', pipeline.title) + '\n');
+        process.stdout.write(kv('description', pipeline.description ?? '') + '\n\n');
+        const inputs = pipeline.inputs ?? [];
+        if (inputs.length === 0) {
+            process.stdout.write('(no inputs)\n');
+        }
+        for (const v of inputs) {
+            const tag = v.required ? '*required' : ' optional';
+            process.stdout.write(`  ${tag}  ${v.name}\n`);
+            if (v.description)
+                process.stdout.write(`             ${v.description}\n`);
+            if (v.default)
+                process.stdout.write(`             default: ${v.default}\n`);
+            if (v.choices?.length) {
+                process.stdout.write(`             choices: ${v.choices.join(', ')}\n`);
+            }
+        }
+        if (optionalSteps.length) {
+            process.stdout.write('\nOptional steps (include with --include-optional):\n');
+            for (const s of optionalSteps) {
+                process.stdout.write(`  ${s.id}\n`);
+                if (s.description)
+                    process.stdout.write(`    ${s.description}\n`);
+            }
+        }
+        const sampleVars = inputs.map((v) => `--var ${v.name}=${v.default ?? '<value>'}`).join(' ');
+        process.stdout.write(`\nExample:\n  $ shrk pipelines script ${pipeline.id} --task "<task>" ${sampleVars}\n`);
+        return 0;
+    },
+};

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

@@ -0,0 +1,27 @@
+/**
+ * `shrk plan check <path>` — validate ANY external plan/spec file
+ * against the live workspace. Read-only; never modifies the input
+ * file.
+ *
+ * Two built-in extractors:
+ *   - `sharkcraft.spec/v1`       (spec.md format)
+ *   - `markdown-frontmatter-loose` (any YAML frontmatter; --field-map remaps)
+ */
+import { type ISpecValidationIssue } from '@shrkcrft/generator';
+import { type ICommandHandler } from '../command-registry.js';
+export declare const PLAN_CHECK_SCHEMA = "sharkcraft.plan-check/v1";
+export interface IPlanCheckReport {
+    readonly schema: typeof PLAN_CHECK_SCHEMA;
+    readonly source: string;
+    readonly extractorId: string;
+    readonly verdict: 'pass' | 'warn' | 'fail';
+    readonly errors: readonly ISpecValidationIssue[];
+    readonly warnings: readonly ISpecValidationIssue[];
+    readonly nx?: {
+        readonly enabled: boolean;
+        readonly affectedProjects?: readonly string[];
+        readonly note?: string;
+    };
+}
+export declare const planCheckCommand: ICommandHandler;
+//# sourceMappingURL=plan-check.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/plan-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,EAAE,CAAC,EAAE;QACZ,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,eAAO,MAAM,gBAAgB,EAAE,eAyE9B,CAAC"}

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

@@ -0,0 +1,150 @@
+/**
+ * `shrk plan check <path>` — validate ANY external plan/spec file
+ * against the live workspace. Read-only; never modifies the input
+ * file.
+ *
+ * Two built-in extractors:
+ *   - `sharkcraft.spec/v1`       (spec.md format)
+ *   - `markdown-frontmatter-loose` (any YAML frontmatter; --field-map remaps)
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { getExtractorById, pickExtractor, } from '@shrkcrft/generator';
+import { inspectSharkcraft, loadNxProjects, mapFilesToProjects, validateExtractedPlan, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+export const PLAN_CHECK_SCHEMA = 'sharkcraft.plan-check/v1';
+export const planCheckCommand = {
+    name: 'check',
+    description: 'Validate an external plan/spec file against the live workspace. Read-only — the input file is never modified. Supports two built-in extractors and an optional --field-map.',
+    usage: 'shrk plan check <path> [--extractor sharkcraft.spec/v1|markdown-frontmatter-loose] [--field-map <json>] [--json] [--strict]',
+    async run(args) {
+        const path = args.positional[0];
+        if (!path) {
+            process.stderr.write('Usage: shrk plan check <path> [--extractor <id>] [--field-map <json>]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const absPath = nodePath.isAbsolute(path) ? path : nodePath.resolve(cwd, path);
+        if (!existsSync(absPath)) {
+            process.stderr.write(`Plan file not found: ${absPath}\n`);
+            return 1;
+        }
+        const extractor = pickExtractorFromFlag(args, absPath);
+        if (!extractor) {
+            process.stderr.write(`Refusing: no extractor accepts "${path}". Pass --extractor sharkcraft.spec/v1 | markdown-frontmatter-loose.\n`);
+            return 1;
+        }
+        const fieldMap = parseFieldMap(flagString(args, 'field-map'));
+        if (fieldMap === 'invalid') {
+            process.stderr.write('Refusing: --field-map must be valid JSON of shape {"externalKey":"canonicalKey",...}.\n');
+            return 1;
+        }
+        const raw = readFileSync(absPath, 'utf8');
+        const extracted = extractor.extract(raw, {
+            source: nodePath.relative(cwd, absPath) || absPath,
+            ...(fieldMap ? { fieldMap } : {}),
+        });
+        if (!extracted.ok) {
+            process.stderr.write(`Extractor "${extractor.id}" refused: ${extracted.error.message}\n`);
+            return 1;
+        }
+        const inspection = await inspectSharkcraft({ cwd });
+        const validation = validateExtractedPlan(extracted.value, inspection);
+        const verdict = validation.errors.length > 0
+            ? 'fail'
+            : validation.warnings.length > 0
+                ? 'warn'
+                : 'pass';
+        const nxReport = buildNxReport(cwd, extracted.value);
+        const report = {
+            schema: PLAN_CHECK_SCHEMA,
+            source: extracted.value.source,
+            extractorId: extractor.id,
+            verdict,
+            errors: validation.errors,
+            warnings: validation.warnings,
+            ...(nxReport ? { nx: nxReport } : {}),
+        };
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(report) + '\n');
+        }
+        else {
+            renderHuman(report);
+        }
+        if (verdict === 'fail')
+            return 1;
+        if (verdict === 'warn' && flagBool(args, 'strict'))
+            return 1;
+        return 0;
+    },
+};
+function pickExtractorFromFlag(args, absPath) {
+    const explicit = flagString(args, 'extractor');
+    if (explicit)
+        return getExtractorById(explicit);
+    return pickExtractor(absPath);
+}
+function parseFieldMap(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return 'invalid';
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v !== 'string')
+                return 'invalid';
+            out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return 'invalid';
+    }
+}
+function buildNxReport(cwd, extracted) {
+    const graph = loadNxProjects(cwd);
+    if (!graph)
+        return undefined;
+    const files = extracted.affectedFiles ?? [];
+    if (files.length === 0) {
+        return { enabled: true, note: 'no affectedFiles declared — skipping project mapping' };
+    }
+    const projects = mapFilesToProjects(files, graph);
+    return {
+        enabled: true,
+        affectedProjects: projects,
+        ...(projects.length > 1
+            ? { note: `plan touches ${projects.length} projects: ${projects.join(', ')}` }
+            : {}),
+    };
+}
+function renderHuman(report) {
+    process.stdout.write(header(`Plan check: ${report.source}`));
+    process.stdout.write(`  extractor: ${report.extractorId}\n`);
+    process.stdout.write(`  verdict:   ${report.verdict.toUpperCase()}\n`);
+    process.stdout.write(`  errors:    ${report.errors.length}\n`);
+    process.stdout.write(`  warnings:  ${report.warnings.length}\n`);
+    if (report.nx) {
+        if (report.nx.affectedProjects) {
+            process.stdout.write(`  nx projects: ${report.nx.affectedProjects.join(', ') || '(none)'}\n`);
+        }
+        else if (report.nx.note) {
+            process.stdout.write(`  nx: ${report.nx.note}\n`);
+        }
+    }
+    if (report.errors.length > 0) {
+        process.stdout.write('\nErrors:\n');
+        for (const e of report.errors) {
+            process.stdout.write(`  [${e.code}] ${e.field}: ${e.message}\n`);
+        }
+    }
+    if (report.warnings.length > 0) {
+        process.stdout.write('\nWarnings:\n');
+        for (const w of report.warnings) {
+            process.stdout.write(`  [${w.code}] ${w.field}: ${w.message}\n`);
+        }
+    }
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-simulate.command.d.ts","sourceRoot":"","sources":["../../src/commands/plan-simulate.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,mBAAmB,EAAE,eAsDjC,CAAC"}