@shrkcrft/inspector 0.1.0-alpha.2

package/dist/upgrade-advisor.d.ts

@@ -0,0 +1,22 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const UPGRADE_ADVISOR_SCHEMA = "sharkcraft.upgrade-advisor/v1";
+export interface IUpgradeFinding {
+    id: string;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    suggestedAction: string;
+}
+export interface IUpgradeAdviceReport {
+    schema: typeof UPGRADE_ADVISOR_SCHEMA;
+    generatedAt: string;
+    fromVersion: string;
+    toVersion: string;
+    detectedSchemas: Record<string, string>;
+    findings: readonly IUpgradeFinding[];
+    recommendedSteps: readonly string[];
+}
+export declare function buildUpgradeAdvice(inspection: ISharkcraftInspection, options?: {
+    from?: string;
+    to?: string;
+}): IUpgradeAdviceReport;
+//# sourceMappingURL=upgrade-advisor.d.ts.map

package/dist/upgrade-advisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-advisor.d.ts","sourceRoot":"","sources":["../src/upgrade-advisor.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAiDD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3C,oBAAoB,CAwDtB"}

package/dist/upgrade-advisor.js

@@ -0,0 +1,109 @@
+/**
+ * SharkCraft upgrade advisor.
+ *
+ * Read-only advisor that detects schema versions across the repo and
+ * suggests safe manual upgrade steps. Never auto-migrates.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const UPGRADE_ADVISOR_SCHEMA = 'sharkcraft.upgrade-advisor/v1';
+function detectSchemaVersion(text) {
+    const m = /"schema"\s*:\s*"([^"]+)"/.exec(text);
+    return m ? (m[1] ?? null) : null;
+}
+function scanFile(file) {
+    try {
+        const t = readFileSync(file, 'utf8');
+        return detectSchemaVersion(t);
+    }
+    catch {
+        return null;
+    }
+}
+function walkSchemas(dir, max) {
+    const out = {};
+    const stack = [dir];
+    let count = 0;
+    while (stack.length && count < max) {
+        const cur = stack.pop();
+        let entries = [];
+        try {
+            entries = readdirSync(cur);
+        }
+        catch {
+            continue;
+        }
+        for (const f of entries) {
+            const full = nodePath.join(cur, f);
+            try {
+                const stat = statSync(full);
+                if (stat.isDirectory())
+                    stack.push(full);
+                else if (f.endsWith('.json')) {
+                    const v = scanFile(full);
+                    if (v)
+                        out[v] = (out[v] ?? '') + (full + '\n');
+                    count++;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    // Return only the *schema names → first file* pairing.
+    const compact = {};
+    for (const [k, v] of Object.entries(out))
+        compact[k] = v.split('\n')[0] ?? '';
+    return compact;
+}
+export function buildUpgradeAdvice(inspection, options = {}) {
+    const findings = [];
+    const detected = walkSchemas(nodePath.join(inspection.projectRoot, '.sharkcraft'), 600);
+    const fromVersion = options.from ?? '0.1.0-alpha.2';
+    const toVersion = options.to ?? 'current';
+    // Heuristics: surface known evolving schemas.
+    if (detected['sharkcraft.repository-map/v1']) {
+        findings.push({
+            id: 'repository-map-v1-present',
+            severity: 'info',
+            message: 'sharkcraft.repository-map/v1 artefacts found. sharkcraft.repository-intelligence/v1 ships alongside it.',
+            suggestedAction: 'No action required; run `shrk intelligence graph` for the new surface.',
+        });
+    }
+    if (detected['sharkcraft.feature-bundle/v1']) {
+        findings.push({
+            id: 'feature-bundle-v1',
+            severity: 'info',
+            message: 'Feature bundle v1 schema detected.',
+            suggestedAction: 'No migration needed — schema is stable across 0.1.x.',
+        });
+    }
+    // Adoption checkpoints can become stale across SharkCraft versions.
+    const checkpointDir = nodePath.join(inspection.projectRoot, '.sharkcraft', 'adoption-checkpoints');
+    if (existsSync(checkpointDir)) {
+        findings.push({
+            id: 'adoption-checkpoint-rehash',
+            severity: 'info',
+            message: 'Adoption checkpoints found. Upgrading SharkCraft may rewrite diff formatting.',
+            suggestedAction: 'After upgrade, re-run adoption with `--record-checkpoint` if hashes diverge.',
+        });
+    }
+    const recommendedSteps = [
+        'shrk doctor',
+        'shrk commands doctor',
+        'shrk safety audit',
+        'shrk release readiness',
+        'bun x tsc -p tsconfig.base.json --noEmit',
+        'bun test',
+    ];
+    return {
+        schema: UPGRADE_ADVISOR_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        fromVersion,
+        toVersion,
+        detectedSchemas: detected,
+        findings,
+        recommendedSteps,
+    };
+}

package/dist/why-file.d.ts

@@ -0,0 +1,75 @@
+/**
+ * DX/feedback3 — `shrk why <file>`.
+ *
+ * Closes a dangling promise: `ide.command.ts:112` already suggests
+ * `shrk why "<path>"` to the user, but the verb didn't exist until
+ * now. This helper answers: "for THIS file, which registries apply
+ * and why?" Pure composition over the existing inspection — no new
+ * asset kinds, no LLM, no shell.
+ *
+ * Symbol queries (`shrk why <symbol>`) are intentionally out of scope
+ * for the first cut. They require AST analysis that this verb
+ * shouldn't grow on its own. The verb gracefully accepts a non-path
+ * argument and routes to `shrk knowledge search` via the suggestion
+ * block.
+ */
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const WHY_FILE_SCHEMA = "sharkcraft.why/v1";
+export type WhyTargetKind = 'file' | 'directory' | 'missing';
+export interface IWhyTarget {
+    readonly inputPath: string;
+    readonly resolvedPath: string;
+    readonly relativePath: string;
+    readonly kind: WhyTargetKind;
+}
+export interface IWhyPathConvention {
+    readonly id: string;
+    readonly title: string;
+    readonly canonicalPath: string;
+    readonly source?: string;
+}
+export interface IWhyRule {
+    readonly id: string;
+    readonly title: string;
+    readonly priority: string;
+    readonly scope: readonly string[];
+    readonly tags: readonly string[];
+    readonly appliesWhen: readonly string[];
+    readonly source?: string;
+    readonly reason: string;
+}
+export interface IWhyBoundaryRule {
+    readonly id: string;
+    readonly title: string;
+    readonly severity?: string;
+    readonly from: readonly string[];
+    readonly forbiddenImports?: readonly string[];
+    readonly allowedImports?: readonly string[];
+    readonly source?: string;
+}
+export interface IWhyKnowledge {
+    readonly id: string;
+    readonly title: string;
+    readonly type: string;
+    readonly source?: string;
+    readonly reason: string;
+}
+export interface IWhyReport {
+    readonly schema: typeof WHY_FILE_SCHEMA;
+    readonly target: IWhyTarget;
+    readonly inferredPackage?: string;
+    readonly inferredLayer?: string;
+    readonly pathConventions: readonly IWhyPathConvention[];
+    readonly rules: readonly IWhyRule[];
+    readonly boundaries: readonly IWhyBoundaryRule[];
+    readonly knowledge: readonly IWhyKnowledge[];
+    readonly suggestedNext: readonly string[];
+}
+export interface IBuildWhyReportInput {
+    readonly inspection: ISharkcraftInspection;
+    readonly projectRoot: string;
+    readonly target: string;
+    readonly limit?: number;
+}
+export declare function buildWhyReport(input: IBuildWhyReportInput): IWhyReport;
+//# sourceMappingURL=why-file.d.ts.map

package/dist/why-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"why-file.d.ts","sourceRoot":"","sources":["../src/why-file.ts"],"names":[],"mappings":"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"}

package/dist/why-file.js

@@ -0,0 +1,202 @@
+/**
+ * DX/feedback3 — `shrk why <file>`.
+ *
+ * Closes a dangling promise: `ide.command.ts:112` already suggests
+ * `shrk why "<path>"` to the user, but the verb didn't exist until
+ * now. This helper answers: "for THIS file, which registries apply
+ * and why?" Pure composition over the existing inspection — no new
+ * asset kinds, no LLM, no shell.
+ *
+ * Symbol queries (`shrk why <symbol>`) are intentionally out of scope
+ * for the first cut. They require AST analysis that this verb
+ * shouldn't grow on its own. The verb gracefully accepts a non-path
+ * argument and routes to `shrk knowledge search` via the suggestion
+ * block.
+ */
+import { existsSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { matchesAny } from '@shrkcrft/boundaries';
+export const WHY_FILE_SCHEMA = 'sharkcraft.why/v1';
+export function buildWhyReport(input) {
+    const limit = input.limit ?? 10;
+    const target = resolveTarget(input.projectRoot, input.target);
+    const inferredPackage = inferPackage(target.relativePath);
+    const inferredLayer = inferLayer(target.relativePath);
+    const pathConventions = matchPathConventions(input.inspection, target);
+    const rules = matchRules(input.inspection, target, limit);
+    const boundaries = matchBoundaries(input.inspection, target);
+    const knowledge = matchKnowledge(input.inspection, target, limit);
+    const suggestedNext = buildSuggestions(target, rules, knowledge);
+    return {
+        schema: WHY_FILE_SCHEMA,
+        target,
+        ...(inferredPackage !== undefined ? { inferredPackage } : {}),
+        ...(inferredLayer !== undefined ? { inferredLayer } : {}),
+        pathConventions,
+        rules,
+        boundaries,
+        knowledge,
+        suggestedNext,
+    };
+}
+function resolveTarget(projectRoot, raw) {
+    const resolved = nodePath.isAbsolute(raw) ? raw : nodePath.resolve(projectRoot, raw);
+    const relativePath = nodePath.relative(projectRoot, resolved) || '.';
+    let kind = 'missing';
+    if (existsSync(resolved)) {
+        try {
+            kind = statSync(resolved).isDirectory() ? 'directory' : 'file';
+        }
+        catch {
+            kind = 'missing';
+        }
+    }
+    return { inputPath: raw, resolvedPath: resolved, relativePath, kind };
+}
+function inferPackage(relPath) {
+    if (!relPath || relPath === '.')
+        return undefined;
+    const segments = relPath.split(/[/\\]/).filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return undefined;
+    if (segments[0] === 'packages' && segments.length >= 2)
+        return `packages/${segments[1]}`;
+    if (segments[0] === 'apps' && segments.length >= 2)
+        return `apps/${segments[1]}`;
+    if (segments[0] === 'libs' && segments.length >= 2)
+        return `libs/${segments[1]}`;
+    if (segments[0] === 'tools' && segments.length >= 2)
+        return `tools/${segments[1]}`;
+    return segments[0];
+}
+function inferLayer(relPath) {
+    // Engine-specific heuristic: under `packages/<layer>/...` the layer is
+    // the package name (cli, inspector, generator, …). Empty otherwise so
+    // the field is omitted rather than guessed.
+    const segments = relPath.split(/[/\\]/).filter((s) => s.length > 0);
+    if (segments[0] === 'packages' && segments.length >= 2)
+        return segments[1];
+    return undefined;
+}
+function matchPathConventions(inspection, target) {
+    const out = [];
+    for (const p of inspection.pathService.list()) {
+        const canonical = p.metadata?.path ?? '';
+        if (!canonical)
+            continue;
+        const normalized = canonical.replace(/^\.\//, '');
+        if (target.relativePath === normalized || target.relativePath.startsWith(normalized.endsWith('/') ? normalized : `${normalized}/`)) {
+            out.push({
+                id: p.id,
+                title: p.title,
+                canonicalPath: canonical,
+                ...sourceField(inspection, p.id),
+            });
+        }
+    }
+    return out;
+}
+function matchRules(inspection, target, limit) {
+    const tokens = pathTokens(target.relativePath);
+    const out = [];
+    for (const rule of inspection.ruleService.list()) {
+        const r = rule;
+        const scope = r.scope ?? [];
+        const tags = r.tags ?? [];
+        const appliesWhen = r.appliesWhen ?? [];
+        const allTokens = new Set([...scope, ...tags, ...appliesWhen].map((t) => t.toLowerCase()));
+        const hits = tokens.filter((t) => allTokens.has(t.toLowerCase()));
+        if (hits.length === 0)
+            continue;
+        out.push({
+            id: r.id,
+            title: r.title,
+            priority: r.priority ?? 'medium',
+            scope,
+            tags,
+            appliesWhen,
+            reason: `Matches on: ${hits.join(', ')}`,
+            ...sourceField(inspection, r.id),
+        });
+    }
+    // Sort by priority weight desc, then by hit count desc.
+    const weight = { critical: 4, high: 3, medium: 2, low: 1 };
+    out.sort((a, b) => (weight[b.priority] ?? 2) - (weight[a.priority] ?? 2));
+    return out.slice(0, limit);
+}
+function matchBoundaries(inspection, target) {
+    const out = [];
+    for (const rule of inspection.boundaryRegistry.list()) {
+        if (rule.from.length === 0)
+            continue;
+        if (!matchesAny(target.relativePath, rule.from))
+            continue;
+        const entry = {
+            id: rule.id,
+            title: rule.title,
+            ...(rule.severity !== undefined ? { severity: rule.severity } : {}),
+            from: rule.from,
+            ...(rule.forbiddenImports !== undefined ? { forbiddenImports: rule.forbiddenImports } : {}),
+            ...(rule.allowedImports !== undefined ? { allowedImports: rule.allowedImports } : {}),
+            ...sourceField(inspection.boundarySources, rule.id),
+        };
+        out.push(entry);
+    }
+    return out;
+}
+function matchKnowledge(inspection, target, limit) {
+    const basename = nodePath.basename(target.relativePath).toLowerCase();
+    const rel = target.relativePath.toLowerCase();
+    const out = [];
+    for (const k of inspection.knowledgeEntries) {
+        const refs = (k.references ?? []).map((r) => r.path ?? '');
+        const refMatch = refs.some((p) => p.toLowerCase() === rel || p.toLowerCase().endsWith(`/${basename}`));
+        const contentMatch = ((k.content ?? '') + ' ' + (k.title ?? '')).toLowerCase().includes(basename);
+        if (!refMatch && !contentMatch)
+            continue;
+        out.push({
+            id: k.id,
+            title: k.title,
+            type: String(k.type),
+            reason: refMatch ? `references the file` : `mentions ${basename}`,
+            ...sourceField(inspection, k.id),
+        });
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+function buildSuggestions(target, rules, knowledge) {
+    const out = [];
+    if (target.kind === 'missing') {
+        out.push(`shrk knowledge search "${target.inputPath}"`);
+        out.push(`shrk search "${target.inputPath}"`);
+        return out;
+    }
+    if (rules.length > 0) {
+        out.push(`shrk rules get ${rules[0].id}`);
+    }
+    if (knowledge.length > 0) {
+        out.push(`shrk knowledge get ${knowledge[0].id}`);
+    }
+    out.push(`shrk check boundaries --since origin/main`);
+    out.push(`shrk impact "${target.relativePath}"`);
+    return out;
+}
+function pathTokens(relPath) {
+    return relPath
+        .replace(/\.[^./]+$/, '') // drop extension
+        .split(/[/\\.\-_]/)
+        .filter((t) => t.length > 0);
+}
+function sourceField(inspection, id) {
+    let map;
+    if (inspection && 'entrySources' in inspection) {
+        map = inspection.entrySources;
+    }
+    else if (inspection instanceof Map) {
+        map = inspection;
+    }
+    const source = map?.get(id)?.file;
+    return source !== undefined ? { source } : {};
+}

package/dist/workflow-simulation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Safe workflow simulation.
+ *
+ * Predicts what a workflow would do without executing it. Builds on the
+ * orchestration plan + (optionally) a playbook/pipeline to surface:
+ * phases, commands that would be suggested, files that might be touched,
+ * policies likely to be checked, validations that would run, human-
+ * review points, and a risk summary.
+ *
+ * Read-only. No commands executed. No files written except --output by
+ * the caller.
+ */
+import { OrchestrationMode, type IAgentOrchestrationPlan } from './agent-orchestration.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const WORKFLOW_SIMULATION_SCHEMA = "sharkcraft.workflow-simulation/v1";
+export interface IWorkflowSimulationStep {
+    phaseId: string;
+    command: string;
+    expectedSafetyLevel: 'read-only' | 'writes-drafts' | 'writes-session' | 'writes-source' | 'runs-shell';
+    mayWriteFiles: boolean;
+}
+export interface IWorkflowSimulation {
+    schema: typeof WORKFLOW_SIMULATION_SCHEMA;
+    generatedAt: string;
+    task: string;
+    plan: IAgentOrchestrationPlan;
+    playbookId?: string;
+    pipelineId?: string;
+    predictedSteps: readonly IWorkflowSimulationStep[];
+    predictedFiles: readonly string[];
+    predictedPolicies: readonly string[];
+    predictedValidations: readonly string[];
+    humanReviewPoints: readonly string[];
+    predictedArtifacts: readonly string[];
+    riskSummary: readonly string[];
+    notes: readonly string[];
+}
+export interface IWorkflowSimulationOptions {
+    playbookId?: string;
+    pipelineId?: string;
+    bundle?: boolean;
+    mode?: OrchestrationMode;
+}
+export declare function simulateWorkflow(task: string, inspection: ISharkcraftInspection, options?: IWorkflowSimulationOptions): Promise<IWorkflowSimulation>;
+export declare function renderWorkflowSimulationText(sim: IWorkflowSimulation): string;
+//# sourceMappingURL=workflow-simulation.d.ts.map

package/dist/workflow-simulation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-simulation.d.ts","sourceRoot":"","sources":["../src/workflow-simulation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,iBAAiB,EAA+B,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,WAAW,GAAG,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,YAAY,CAAC;IACvG,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,uBAAuB,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACnD,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAeD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,mBAAmB,CAAC,CAiG9B;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAsB7E"}

package/dist/workflow-simulation.js

@@ -0,0 +1,154 @@
+/**
+ * Safe workflow simulation.
+ *
+ * Predicts what a workflow would do without executing it. Builds on the
+ * orchestration plan + (optionally) a playbook/pipeline to surface:
+ * phases, commands that would be suggested, files that might be touched,
+ * policies likely to be checked, validations that would run, human-
+ * review points, and a risk summary.
+ *
+ * Read-only. No commands executed. No files written except --output by
+ * the caller.
+ */
+import { OrchestrationMode, buildAgentOrchestrationPlan } from "./agent-orchestration.js";
+import { listPlaybooks, loadPlaybooks } from "./playbook-registry.js";
+export const WORKFLOW_SIMULATION_SCHEMA = 'sharkcraft.workflow-simulation/v1';
+const COMMAND_SAFETY_HINTS = new Map([
+    [/^shrk (gen|init|apply|import|presets apply --write|packs (sign|new))/i, 'writes-source'],
+    [/^shrk (onboard|brief|dev start|handoff|export|report site|impact|review packet|ci scaffold)/i, 'writes-drafts'],
+    [/^shrk (session|dev report|dev open)/i, 'writes-session'],
+    [/^bun |^npm |^node |^git /i, 'runs-shell'],
+    [/^shrk /i, 'read-only'],
+]);
+function classifyCommand(c) {
+    for (const [re, level] of COMMAND_SAFETY_HINTS)
+        if (re.test(c))
+            return level;
+    return 'read-only';
+}
+export async function simulateWorkflow(task, inspection, options = {}) {
+    await loadPlaybooks(inspection);
+    void inspection;
+    const plan = await buildAgentOrchestrationPlan(task, inspection, {
+        mode: options.mode ?? OrchestrationMode.Balanced,
+    });
+    const steps = [];
+    for (const phase of plan.phases) {
+        for (const c of phase.recommendedCommands) {
+            const safety = classifyCommand(c);
+            steps.push({
+                phaseId: phase.id,
+                command: c,
+                expectedSafetyLevel: safety,
+                mayWriteFiles: safety === 'writes-source' || safety === 'writes-drafts',
+            });
+        }
+    }
+    let playbookId;
+    let pipelineId;
+    const notes = [];
+    if (options.playbookId) {
+        const pb = listPlaybooks(inspection).find((p) => p.id === options.playbookId);
+        if (pb) {
+            playbookId = pb.id;
+            for (const s of pb.steps ?? []) {
+                for (const c of s.commands ?? []) {
+                    const safety = classifyCommand(c);
+                    steps.push({
+                        phaseId: `playbook:${pb.id}`,
+                        command: c,
+                        expectedSafetyLevel: safety,
+                        mayWriteFiles: safety === 'writes-source' || safety === 'writes-drafts',
+                    });
+                }
+            }
+        }
+        else {
+            notes.push(`Playbook "${options.playbookId}" not found.`);
+        }
+    }
+    if (options.pipelineId) {
+        const pl = inspection.pipelines.find((p) => p.id === options.pipelineId);
+        if (pl) {
+            pipelineId = pl.id;
+            for (const s of pl.steps ?? []) {
+                const c = s.command ?? '';
+                if (!c)
+                    continue;
+                const safety = classifyCommand(c);
+                steps.push({
+                    phaseId: `pipeline:${pl.id}`,
+                    command: c,
+                    expectedSafetyLevel: safety,
+                    mayWriteFiles: safety === 'writes-source' || safety === 'writes-drafts',
+                });
+            }
+        }
+        else {
+            notes.push(`Pipeline "${options.pipelineId}" not found.`);
+        }
+    }
+    const predictedFiles = [];
+    if (plan.intent.likelyTemplates.length > 0) {
+        for (const t of plan.intent.likelyTemplates)
+            predictedFiles.push(`(template:${t}) target file would be rendered to a location per templates.ts targetPath`);
+    }
+    const predictedPolicies = plan.intent.kind === 'policy' || plan.intent.kind === 'release'
+        ? ['policy:run', 'safety:audit', 'readiness:strict']
+        : ['safety:audit'];
+    const humanReviewPoints = plan.phases.filter((p) => p.humanApprovalRequired).map((p) => p.title);
+    const predictedArtifacts = [];
+    for (const p of plan.phases)
+        for (const a of p.expectedArtifacts)
+            predictedArtifacts.push(`${p.id}/${a}`);
+    const risks = [];
+    if (plan.intent.requiredHumanReview)
+        risks.push('Task requires explicit human review before apply.');
+    if (steps.some((s) => s.expectedSafetyLevel === 'writes-source'))
+        risks.push('Plan contains write-source steps (apply / init / gen --write / presets apply --write).');
+    if (steps.some((s) => s.expectedSafetyLevel === 'runs-shell'))
+        risks.push('Plan suggests shell-out commands (bun/npm/node/git).');
+    return {
+        schema: WORKFLOW_SIMULATION_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        task,
+        plan,
+        ...(playbookId ? { playbookId } : {}),
+        ...(pipelineId ? { pipelineId } : {}),
+        predictedSteps: steps,
+        predictedFiles,
+        predictedPolicies,
+        predictedValidations: plan.validationCommands,
+        humanReviewPoints,
+        predictedArtifacts,
+        riskSummary: risks,
+        notes,
+    };
+}
+export function renderWorkflowSimulationText(sim) {
+    const lines = [];
+    lines.push('=== Workflow simulation ===');
+    lines.push(`  task     ${sim.task}`);
+    lines.push(`  intent   ${sim.plan.intent.kind} / ${sim.plan.intent.confidence}`);
+    if (sim.playbookId)
+        lines.push(`  playbook ${sim.playbookId}`);
+    if (sim.pipelineId)
+        lines.push(`  pipeline ${sim.pipelineId}`);
+    lines.push(`  steps    ${sim.predictedSteps.length}`);
+    lines.push(`  human review points ${sim.humanReviewPoints.length}`);
+    if (sim.riskSummary.length > 0) {
+        lines.push('Risks:');
+        for (const r of sim.riskSummary)
+            lines.push(`  • ${r}`);
+    }
+    lines.push('Predicted steps:');
+    for (const s of sim.predictedSteps.slice(0, 30)) {
+        lines.push(`  [${s.expectedSafetyLevel.padEnd(14)}] (${s.phaseId}) ${s.command}`);
+    }
+    if (sim.notes.length > 0) {
+        lines.push('Notes:');
+        for (const n of sim.notes)
+            lines.push(`  • ${n}`);
+    }
+    return lines.join('\n') + '\n';
+}