@shrkcrft/inspector 0.1.0-alpha.2

package/dist/failure-diagnostics.js

@@ -0,0 +1,243 @@
+/**
+ * Failure diagnostics.
+ *
+ * Common error surfaces should not just say "X failed" — they should say
+ * "X failed, probable cause is Y, try Z next". This module is a curated set
+ * of diagnostic helpers callers can use to enrich the human-facing message
+ * without re-implementing the dispatch in every command.
+ *
+ * Pure data — no I/O, no shell calls, no writes. Safe to call from MCP.
+ */
+export const FAILURE_DIAGNOSTIC_SCHEMA = 'sharkcraft.failure-diagnostic/v1';
+function make(code, problem, likelyCause, nextCommand, docsLink, extra) {
+    return {
+        schema: FAILURE_DIAGNOSTIC_SCHEMA,
+        code,
+        problem,
+        likelyCause,
+        nextCommand,
+        ...(docsLink ? { docsLink } : {}),
+        ...(extra ? { extra } : {}),
+    };
+}
+export function diagnoseMissingSharkcraftConfig(projectRoot) {
+    return make('missing-sharkcraft-config', `No sharkcraft/ directory at ${projectRoot}.`, 'SharkCraft is not initialised here yet.', 'shrk onboard --dry-run', 'docs/onboarding.md');
+}
+export function diagnoseMissingNodeModules() {
+    return make('missing-node-modules', 'node_modules/ not found — Bun cannot resolve workspace packages.', 'Dependencies have not been installed yet.', 'bun install', 'docs/quickstart.md');
+}
+export function diagnosePackHelperMissing(symbol, packName) {
+    return make('pack-helper-missing', `Pack "${packName}" imports "${symbol}" from @shrkcrft/plugin-api which is not exported.`, 'The pack expects a newer plugin-api than the consumer has installed.', `shrk packs compat ${packName} --consumer-root <consumer-path>`, 'docs/pack-authoring.md', { symbol, packName });
+}
+export function diagnoseMcpCacheMiss(briefId) {
+    return make('mcp-cache-miss', `MCP brief cache miss for id "${briefId}".`, 'The server restarted or the brief expired.', 'Re-run start_agent_brief_chunks with the same input — briefIds are deterministic.', 'docs/brief.md', { briefId });
+}
+export function diagnoseAdoptionCheckpointStale(reason) {
+    return make('adoption-checkpoint-stale', `Adoption checkpoint is stale: ${reason}.`, 'Drafts, targets or the rendered diff changed since the checkpoint was recorded.', 'shrk onboard adopt diff --record-checkpoint', 'docs/adoption-checkpoints.md');
+}
+export function diagnoseUnknownCommand(command, suggestions) {
+    return make('unknown-command', `Unknown command "${command}".`, suggestions.length > 0
+        ? `Closest known commands: ${suggestions.slice(0, 3).join(', ')}`
+        : 'No close match in the command catalog.', 'shrk commands primary', 'docs/start-here.md', { command, suggestions });
+}
+export function diagnoseMissingTemplateVariables(templateId, missing) {
+    return make('missing-template-variables', `Template "${templateId}" is missing variables: ${missing.join(', ')}.`, 'The template expects these variables to be passed via --var key=value.', `shrk gen ${templateId} <name> ${missing.map((m) => `--var ${m}=<value>`).join(' ')}`, 'docs/templates.md', { templateId, missing });
+}
+export function diagnoseUnsafePathRefused(target) {
+    return make('unsafe-path-refused', `Path "${target}" is outside the project root or in a protected location.`, 'SharkCraft refuses to write outside the project root, into node_modules, or dist.', 'shrk doctor', 'docs/safety-model.md', { target });
+}
+export function diagnoseFailedVerification(verificationId, exitCode) {
+    return make('failed-verification', `Verification "${verificationId}" failed (exit code ${exitCode}).`, 'A configured verification command in sharkcraft.config.ts returned non-zero.', `Run the verification command manually and inspect the output, then re-apply the plan.`, 'docs/safety-model.md', { verificationId, exitCode });
+}
+export function diagnoseReleaseReadinessBlocker(blockerId, message) {
+    return make('release-readiness-blocker', `Release readiness blocker: ${blockerId}.`, message, 'shrk release readiness --json', 'docs/release-readiness.md', { blockerId });
+}
+export function diagnosePlanSignatureMismatch(planFile) {
+    return make('plan-signature-mismatch', `Plan signature did not verify for ${planFile}.`, 'The plan has been edited after it was signed, or the signing secret has changed.', `shrk plan review ${planFile}`, 'docs/security.md', { planFile });
+}
+export function diagnoseWorkflowFileNotFound(file) {
+    return make('workflow-file-not-found', `Workflow file not found: ${file}.`, 'The path may be wrong or the workflow has not been scaffolded yet.', 'shrk ci scaffold github-actions', 'docs/ci-scaffold.md', { file });
+}
+// ─── Polyglot diagnostics ────────────────────────────────────────────────────
+export function diagnoseJavaCannotFindSymbol(symbol) {
+    return make('java-cannot-find-symbol', `Java compiler reports "cannot find symbol${symbol ? `: ${symbol}` : ''}".`, 'Missing import, typo, or a dependency that is not on the classpath.', 'mvn dependency:tree | grep -i <symbol>  # then add the missing import or dependency', 'docs/healing-plans.md', { symbol });
+}
+export function diagnoseJavaPackageDoesNotExist(pkg) {
+    return make('java-package-does-not-exist', `Java reports "package ${pkg || '<name>'} does not exist".`, 'Dependency not declared in pom.xml / build.gradle, or build cache out of date.', 'mvn -U test  # or `./gradlew --refresh-dependencies test`', 'docs/healing-plans.md', { pkg });
+}
+export function diagnoseCSharpCs0246(typeName) {
+    return make('csharp-cs0246', `CS0246: the type or namespace "${typeName || '(unknown)'}" could not be found.`, 'Missing `using` directive or NuGet package not restored.', 'dotnet restore  # then check the using directives in the failing file', 'docs/healing-plans.md', { typeName });
+}
+export function diagnoseCSharpNu1101(packageName) {
+    return make('csharp-nu1101', `NU1101: package "${packageName || '(unknown)'}" not found.`, 'NuGet feed misconfigured or package id misspelled.', 'dotnet nuget list source  # verify the feed; then `dotnet restore --force-evaluate`', 'docs/healing-plans.md', { packageName });
+}
+export function diagnosePythonModuleNotFound(moduleName) {
+    return make('python-module-not-found', `ModuleNotFoundError: No module named "${moduleName || '(unknown)'}".`, 'Dependency not installed in the active env, or import path is wrong.', 'python -m pip install -r requirements.txt  # or `uv sync` / `poetry install`', 'docs/healing-plans.md', { moduleName });
+}
+export function diagnosePythonPytestCollectionError(detail) {
+    return make('python-pytest-collection-error', `pytest collection error: ${detail || '(see traceback above)'}.`, 'Test file imports something missing, or a fixture / conftest fails to import.', 'python -m pytest --collect-only  # narrow down the failing module', 'docs/healing-plans.md', { detail });
+}
+export function diagnoseGoCannotFindModule(moduleName) {
+    return make('go-cannot-find-module', `Go build reports "no required module provides package ${moduleName || '<name>'}".`, 'go.mod is out of date — module not declared or not pulled.', 'go mod tidy  # then `go test ./...`', 'docs/healing-plans.md', { moduleName });
+}
+export function diagnoseGoImportCycle(detail) {
+    return make('go-import-cycle', `Go build reports import cycle: ${detail || '(see error)'}.`, 'Two packages import each other directly or transitively.', 'go list -deps ./...  # then refactor: extract shared types into a new package', 'docs/healing-plans.md', { detail });
+}
+export function diagnoseRustE0432(detail) {
+    return make('rust-e0432', `Rust E0432: unresolved import (${detail || 'see compiler output'}).`, 'Crate not declared in Cargo.toml, or `mod` declaration missing.', 'cargo build  # then add the missing dependency to Cargo.toml or declare the mod', 'docs/healing-plans.md', { detail });
+}
+export function diagnoseRustE0308(detail) {
+    return make('rust-e0308', `Rust E0308: mismatched types (${detail || 'see compiler output'}).`, 'Borrow / move / lifetime mismatch, or the expression returns a different type than expected.', 'cargo check --message-format=short  # then inspect the offending expression', 'docs/healing-plans.md', { detail });
+}
+export function renderDiagnosticText(d) {
+    const lines = [];
+    lines.push(`⚠️  ${d.problem}`);
+    lines.push(`   Likely cause: ${d.likelyCause}`);
+    lines.push(`   Try next:    ${d.nextCommand}`);
+    if (d.docsLink)
+        lines.push(`   Docs:        ${d.docsLink}`);
+    return lines.join('\n') + '\n';
+}
+const REGISTRY = Object.freeze([
+    {
+        code: 'missing-sharkcraft-config',
+        description: 'No sharkcraft/ directory in the project root.',
+        contextKeys: ['projectRoot'],
+    },
+    {
+        code: 'missing-node-modules',
+        description: 'node_modules/ is absent — dependencies not installed yet.',
+        contextKeys: [],
+    },
+    {
+        code: 'pack-helper-missing',
+        description: 'Pack imports a plugin-api symbol the consumer does not export.',
+        contextKeys: ['symbol', 'packName'],
+    },
+    {
+        code: 'mcp-cache-miss',
+        description: 'MCP brief cache miss — the briefId is no longer cached.',
+        contextKeys: ['briefId'],
+    },
+    {
+        code: 'adoption-checkpoint-stale',
+        description: 'Adoption checkpoint is stale (drafts / targets / diff hash changed, or age > max-age-days).',
+        contextKeys: ['reason'],
+    },
+    {
+        code: 'unknown-command',
+        description: 'The user invoked a `shrk` command that is not in the catalog.',
+        contextKeys: ['command'],
+    },
+    {
+        code: 'missing-template-variables',
+        description: 'Template generation is missing one or more required variables.',
+        contextKeys: ['templateId', 'missing'],
+    },
+    {
+        code: 'unsafe-path-refused',
+        description: 'A target path resolved outside the project root or into a protected location.',
+        contextKeys: ['target'],
+    },
+    {
+        code: 'failed-verification',
+        description: 'A `sharkcraft.config` verification command returned non-zero.',
+        contextKeys: ['verificationId', 'exitCode'],
+    },
+    {
+        code: 'release-readiness-blocker',
+        description: 'Release readiness reported a blocker.',
+        contextKeys: ['blockerId', 'message'],
+    },
+    {
+        code: 'plan-signature-mismatch',
+        description: 'A signed plan did not verify (the plan was edited or the secret rotated).',
+        contextKeys: ['planFile'],
+    },
+    {
+        code: 'workflow-file-not-found',
+        description: 'A CI workflow file path was missing during audit.',
+        contextKeys: ['file'],
+    },
+    // Polyglot
+    { code: 'java-cannot-find-symbol', description: 'Java compiler "cannot find symbol".', contextKeys: ['symbol'] },
+    { code: 'java-package-does-not-exist', description: 'Java compiler "package X does not exist".', contextKeys: ['pkg'] },
+    { code: 'csharp-cs0246', description: 'CS0246 — type or namespace not found.', contextKeys: ['typeName'] },
+    { code: 'csharp-nu1101', description: 'NU1101 — NuGet package not found.', contextKeys: ['packageName'] },
+    { code: 'python-module-not-found', description: 'Python ModuleNotFoundError.', contextKeys: ['moduleName'] },
+    { code: 'python-pytest-collection-error', description: 'pytest collection error.', contextKeys: ['detail'] },
+    { code: 'go-cannot-find-module', description: 'Go "no required module provides package".', contextKeys: ['moduleName'] },
+    { code: 'go-import-cycle', description: 'Go import cycle.', contextKeys: ['detail'] },
+    { code: 'rust-e0432', description: 'Rust E0432 — unresolved import.', contextKeys: ['detail'] },
+    { code: 'rust-e0308', description: 'Rust E0308 — mismatched types.', contextKeys: ['detail'] },
+]);
+export function listDiagnostics() {
+    return REGISTRY;
+}
+export function getDiagnosticEntry(code) {
+    return REGISTRY.find((e) => e.code === code) ?? null;
+}
+/**
+ * Produce a diagnostic by code using a context bag. Missing context fields
+ * fall back to `(unknown)` so the diagnostic remains useful as documentation.
+ */
+export function buildDiagnosticByCode(code, context = {}) {
+    const s = (k, fallback = '(unknown)') => {
+        const v = context[k];
+        return typeof v === 'string' || typeof v === 'number' ? String(v) : fallback;
+    };
+    switch (code) {
+        case 'missing-sharkcraft-config':
+            return diagnoseMissingSharkcraftConfig(s('projectRoot', '(unknown)'));
+        case 'missing-node-modules':
+            return diagnoseMissingNodeModules();
+        case 'pack-helper-missing':
+            return diagnosePackHelperMissing(s('symbol'), s('packName'));
+        case 'mcp-cache-miss':
+            return diagnoseMcpCacheMiss(s('briefId'));
+        case 'adoption-checkpoint-stale':
+            return diagnoseAdoptionCheckpointStale(s('reason', 'unknown'));
+        case 'unknown-command': {
+            const suggestions = Array.isArray(context['suggestions'])
+                ? context['suggestions']
+                : [];
+            return diagnoseUnknownCommand(s('command'), suggestions);
+        }
+        case 'missing-template-variables': {
+            const missing = Array.isArray(context['missing']) ? context['missing'] : [];
+            return diagnoseMissingTemplateVariables(s('templateId'), missing);
+        }
+        case 'unsafe-path-refused':
+            return diagnoseUnsafePathRefused(s('target'));
+        case 'failed-verification':
+            return diagnoseFailedVerification(s('verificationId'), Number(context['exitCode'] ?? -1));
+        case 'release-readiness-blocker':
+            return diagnoseReleaseReadinessBlocker(s('blockerId'), s('message', 'see release readiness output'));
+        case 'plan-signature-mismatch':
+            return diagnosePlanSignatureMismatch(s('planFile'));
+        case 'workflow-file-not-found':
+            return diagnoseWorkflowFileNotFound(s('file'));
+        case 'java-cannot-find-symbol':
+            return diagnoseJavaCannotFindSymbol(s('symbol', ''));
+        case 'java-package-does-not-exist':
+            return diagnoseJavaPackageDoesNotExist(s('pkg', ''));
+        case 'csharp-cs0246':
+            return diagnoseCSharpCs0246(s('typeName', ''));
+        case 'csharp-nu1101':
+            return diagnoseCSharpNu1101(s('packageName', ''));
+        case 'python-module-not-found':
+            return diagnosePythonModuleNotFound(s('moduleName', ''));
+        case 'python-pytest-collection-error':
+            return diagnosePythonPytestCollectionError(s('detail', ''));
+        case 'go-cannot-find-module':
+            return diagnoseGoCannotFindModule(s('moduleName', ''));
+        case 'go-import-cycle':
+            return diagnoseGoImportCycle(s('detail', ''));
+        case 'rust-e0432':
+            return diagnoseRustE0432(s('detail', ''));
+        case 'rust-e0308':
+            return diagnoseRustE0308(s('detail', ''));
+        default:
+            return make(code, `Unknown diagnostic code "${code}".`, 'The code may be misspelled.', 'shrk diagnostics list', 'docs/start-here.md');
+    }
+}

package/dist/feature-bundle.d.ts

@@ -0,0 +1,111 @@
+import type { ITaskPacket } from './task-packet.js';
+import type { ITaskDecomposition } from './task-decompose.js';
+export declare const FEATURE_BUNDLE_SCHEMA = "sharkcraft.feature-bundle/v1";
+export declare enum FeatureBundleStatus {
+    Draft = "draft",
+    Planned = "planned",
+    PartiallyApplied = "partially-applied",
+    Applied = "applied",
+    Validated = "validated",
+    Failed = "failed",
+    Completed = "completed"
+}
+export declare enum BundleRiskLevel {
+    Low = "low",
+    Medium = "medium",
+    High = "high",
+    Critical = "critical"
+}
+export interface IFeatureBundlePlan {
+    /** Stable name within the bundle (basename without extension). */
+    name: string;
+    templateId: string;
+    generatedName?: string;
+    variables: Record<string, string>;
+    missingVariables: readonly string[];
+    /** Plans file under `plans/<name>.json` or `plans/<name>.intent.md`. */
+    file: string;
+    status: 'intent' | 'saved' | 'reviewed' | 'applied' | 'failed';
+    reviewReportFile?: string;
+    signed?: boolean;
+    /** Files this plan is expected to write (best-effort). */
+    expectedTargets: readonly string[];
+}
+export interface IFeatureBundlePlanGroup {
+    /** Ordering group: plans in the same group can be applied in any order. */
+    id: string;
+    planNames: readonly string[];
+    description?: string;
+}
+export interface IFeatureBundleDependency {
+    from: string;
+    to: string;
+    reason: string;
+}
+export interface IFeatureBundleValidation {
+    startedAt: string;
+    finishedAt: string;
+    passed: boolean;
+    warnings: number;
+    commandsRun: {
+        command: string;
+        passed: boolean;
+        note?: string;
+    }[];
+    boundaryViolations: number;
+    reportFile: string;
+}
+export interface IFeatureBundle {
+    schema: typeof FEATURE_BUNDLE_SCHEMA;
+    id: string;
+    task: string;
+    createdAt: string;
+    updatedAt: string;
+    projectRoot: string;
+    sessionId?: string;
+    pipelineId?: string;
+    status: FeatureBundleStatus;
+    plans: readonly IFeatureBundlePlan[];
+    planGroups: readonly IFeatureBundlePlanGroup[];
+    dependencies: readonly IFeatureBundleDependency[];
+    validations: readonly IFeatureBundleValidation[];
+    reports: readonly string[];
+    affectedFiles: readonly string[];
+    affectedAreas: readonly string[];
+    riskLevel: BundleRiskLevel;
+    nextAction: string | null;
+    commandHints: readonly string[];
+    warnings: readonly string[];
+}
+export declare function getBundlesRoot(cwd: string): string;
+export declare function getBundleDir(cwd: string, id: string): string;
+export interface ICreateFeatureBundleInput {
+    id: string;
+    task: string;
+    projectRoot: string;
+    packet: ITaskPacket;
+    decomposition?: ITaskDecomposition;
+    sessionId?: string;
+}
+export declare function createFeatureBundleState(input: ICreateFeatureBundleInput): IFeatureBundle;
+export declare function writeFeatureBundle(cwd: string, bundle: IFeatureBundle): IFeatureBundle;
+export declare function readFeatureBundle(cwd: string, id: string): IFeatureBundle | null;
+export declare function listFeatureBundles(cwd: string): IFeatureBundle[];
+export declare function upsertBundlePlan(bundle: IFeatureBundle, plan: IFeatureBundlePlan): IFeatureBundle;
+export declare function recomputeBundleStatus(bundle: IFeatureBundle): IFeatureBundle;
+export declare function setBundleNextAction(bundle: IFeatureBundle, nextAction: string | null): IFeatureBundle;
+export declare function recordBundleReport(bundle: IFeatureBundle, file: string): IFeatureBundle;
+export declare function recordBundleValidation(bundle: IFeatureBundle, v: IFeatureBundleValidation): IFeatureBundle;
+/**
+ * Mark a plan as applied (status='applied') after a human ran `shrk apply`.
+ * Returns the updated bundle without touching validations.
+ */
+export declare function markBundlePlanApplied(bundle: IFeatureBundle, planName: string, note?: string): IFeatureBundle;
+/**
+ * Persist graph-derived dependencies onto the bundle so MCP / read-only
+ * consumers can see the order without rebuilding the graph from the
+ * registries. `planGroups` are derived from the topological order: every plan
+ * whose predecessors are already in an earlier group becomes a new group.
+ */
+export declare function setBundleDependencies(bundle: IFeatureBundle, edges: readonly IFeatureBundleDependency[], order: readonly string[]): IFeatureBundle;
+//# sourceMappingURL=feature-bundle.d.ts.map

package/dist/feature-bundle.d.ts.map

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

package/dist/feature-bundle.js

@@ -0,0 +1,211 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+export const FEATURE_BUNDLE_SCHEMA = 'sharkcraft.feature-bundle/v1';
+export var FeatureBundleStatus;
+(function (FeatureBundleStatus) {
+    FeatureBundleStatus["Draft"] = "draft";
+    FeatureBundleStatus["Planned"] = "planned";
+    FeatureBundleStatus["PartiallyApplied"] = "partially-applied";
+    FeatureBundleStatus["Applied"] = "applied";
+    FeatureBundleStatus["Validated"] = "validated";
+    FeatureBundleStatus["Failed"] = "failed";
+    FeatureBundleStatus["Completed"] = "completed";
+})(FeatureBundleStatus || (FeatureBundleStatus = {}));
+export var BundleRiskLevel;
+(function (BundleRiskLevel) {
+    BundleRiskLevel["Low"] = "low";
+    BundleRiskLevel["Medium"] = "medium";
+    BundleRiskLevel["High"] = "high";
+    BundleRiskLevel["Critical"] = "critical";
+})(BundleRiskLevel || (BundleRiskLevel = {}));
+export function getBundlesRoot(cwd) {
+    return nodePath.join(cwd, '.sharkcraft', 'bundles');
+}
+export function getBundleDir(cwd, id) {
+    return nodePath.join(getBundlesRoot(cwd), id);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+export function createFeatureBundleState(input) {
+    const created = nowIso();
+    const pipelineId = input.packet.recommendedPipelines[0]?.pipelineId;
+    const commandHints = [...input.packet.recommendedCliCommands].slice(0, 6);
+    const dec = input.decomposition;
+    const initialPlans = [];
+    const out = {
+        schema: FEATURE_BUNDLE_SCHEMA,
+        id: input.id,
+        task: input.task,
+        createdAt: created,
+        updatedAt: created,
+        projectRoot: input.projectRoot,
+        status: FeatureBundleStatus.Draft,
+        plans: initialPlans,
+        planGroups: [],
+        dependencies: [],
+        validations: [],
+        reports: [],
+        affectedFiles: [],
+        affectedAreas: dec?.riskAreas ?? [],
+        riskLevel: assessRisk(input.packet, dec),
+        nextAction: `shrk bundle plan ${input.id}`,
+        commandHints,
+        warnings: [],
+    };
+    if (input.sessionId)
+        out.sessionId = input.sessionId;
+    if (pipelineId)
+        out.pipelineId = pipelineId;
+    return out;
+}
+function assessRisk(packet, dec) {
+    const subtasks = dec?.subtasks ?? [];
+    if (subtasks.some((s) => s.riskLevel === 'high'))
+        return BundleRiskLevel.High;
+    if (packet.forbiddenActions.length > 5)
+        return BundleRiskLevel.Medium;
+    if (subtasks.some((s) => s.riskLevel === 'medium'))
+        return BundleRiskLevel.Medium;
+    return BundleRiskLevel.Low;
+}
+export function writeFeatureBundle(cwd, bundle) {
+    const dir = getBundleDir(cwd, bundle.id);
+    mkdirSync(dir, { recursive: true });
+    mkdirSync(nodePath.join(dir, 'plans'), { recursive: true });
+    mkdirSync(nodePath.join(dir, 'reviews'), { recursive: true });
+    mkdirSync(nodePath.join(dir, 'reports'), { recursive: true });
+    const next = { ...bundle, updatedAt: nowIso() };
+    writeFileSync(nodePath.join(dir, 'bundle.json'), JSON.stringify(next, null, 2) + '\n', 'utf8');
+    return next;
+}
+export function readFeatureBundle(cwd, id) {
+    const file = nodePath.join(getBundleDir(cwd, id), 'bundle.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function listFeatureBundles(cwd) {
+    const root = getBundlesRoot(cwd);
+    if (!existsSync(root))
+        return [];
+    const ids = [];
+    try {
+        for (const e of readdirSync(root)) {
+            try {
+                if (statSync(nodePath.join(root, e)).isDirectory())
+                    ids.push(e);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    catch {
+        return [];
+    }
+    ids.sort();
+    const out = [];
+    for (const id of ids) {
+        const b = readFeatureBundle(cwd, id);
+        if (b)
+            out.push(b);
+    }
+    return out;
+}
+export function upsertBundlePlan(bundle, plan) {
+    const plans = bundle.plans.filter((p) => p.name !== plan.name);
+    return { ...bundle, plans: [...plans, plan] };
+}
+export function recomputeBundleStatus(bundle) {
+    if (bundle.plans.length === 0)
+        return { ...bundle, status: FeatureBundleStatus.Draft };
+    const allApplied = bundle.plans.every((p) => p.status === 'applied');
+    const someApplied = bundle.plans.some((p) => p.status === 'applied');
+    const allReviewed = bundle.plans.every((p) => p.status === 'reviewed' || p.status === 'applied' || p.status === 'intent');
+    const validatedOk = bundle.validations.length > 0 && bundle.validations.every((v) => v.passed);
+    let status = FeatureBundleStatus.Draft;
+    if (allReviewed && !someApplied)
+        status = FeatureBundleStatus.Planned;
+    if (someApplied && !allApplied)
+        status = FeatureBundleStatus.PartiallyApplied;
+    if (allApplied)
+        status = FeatureBundleStatus.Applied;
+    if (allApplied && validatedOk)
+        status = FeatureBundleStatus.Validated;
+    if (bundle.validations.some((v) => !v.passed))
+        status = FeatureBundleStatus.Failed;
+    return { ...bundle, status };
+}
+export function setBundleNextAction(bundle, nextAction) {
+    return { ...bundle, nextAction };
+}
+export function recordBundleReport(bundle, file) {
+    if (bundle.reports.includes(file))
+        return bundle;
+    return { ...bundle, reports: [...bundle.reports, file] };
+}
+export function recordBundleValidation(bundle, v) {
+    return { ...bundle, validations: [...bundle.validations, v] };
+}
+/**
+ * Mark a plan as applied (status='applied') after a human ran `shrk apply`.
+ * Returns the updated bundle without touching validations.
+ */
+export function markBundlePlanApplied(bundle, planName, note) {
+    const plans = bundle.plans.map((p) => p.name === planName ? { ...p, status: 'applied', ...(note ? { note } : {}) } : p);
+    return { ...bundle, plans };
+}
+/**
+ * Persist graph-derived dependencies onto the bundle so MCP / read-only
+ * consumers can see the order without rebuilding the graph from the
+ * registries. `planGroups` are derived from the topological order: every plan
+ * whose predecessors are already in an earlier group becomes a new group.
+ */
+export function setBundleDependencies(bundle, edges, order) {
+    const incoming = new Map();
+    for (const e of edges) {
+        const s = incoming.get(e.to) ?? new Set();
+        s.add(e.from);
+        incoming.set(e.to, s);
+    }
+    const placed = new Set();
+    const groups = [];
+    let remaining = [...order];
+    let idx = 0;
+    while (remaining.length > 0) {
+        const wave = remaining.filter((n) => {
+            const deps = incoming.get(n) ?? new Set();
+            for (const d of deps)
+                if (!placed.has(d))
+                    return false;
+            return true;
+        });
+        if (wave.length === 0) {
+            // Cycle remnant — pack everything left into a final group so the
+            // bundle stays writable.
+            groups.push({
+                id: `group-${idx + 1}`,
+                planNames: remaining,
+                description: 'unresolved dependency cycle',
+            });
+            for (const n of remaining)
+                placed.add(n);
+            break;
+        }
+        groups.push({
+            id: `group-${idx + 1}`,
+            planNames: wave,
+        });
+        for (const n of wave)
+            placed.add(n);
+        remaining = remaining.filter((n) => !placed.has(n));
+        idx += 1;
+    }
+    return { ...bundle, dependencies: edges, planGroups: groups };
+}

package/dist/feedback-actions-v2.d.ts

@@ -0,0 +1,65 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const FEEDBACK_ACTIONS_V2_SCHEMA = "sharkcraft.feedback-actions/v2";
+export declare enum FeedbackActionCategory {
+    Good = "good",
+    Bad = "bad",
+    Missing = "missing",
+    Confusion = "confusion",
+    Friction = "friction",
+    Bug = "bug",
+    Feature = "feature",
+    Docs = "docs",
+    Safety = "safety"
+}
+/**
+ * Improvement classification: where the fix should land. The spec
+ * asks for an explicit 4-bucket split, distinct from category (type of
+ * feedback) and origin (where the feedback came from).
+ */
+export type FeedbackImprovementKind = 'engine' | 'pack' | 'local-config' | 'docs' | 'unknown';
+export interface IFeedbackAction {
+    readonly id: string;
+    readonly originalExcerpt: string;
+    readonly paraphrase?: string;
+    readonly category: FeedbackActionCategory;
+    readonly targetArea: string;
+    readonly origin: 'engine-generic' | 'pack-specific' | 'project-specific' | 'unknown';
+    /** Where the resulting fix should land. */
+    readonly improvementKind: FeedbackImprovementKind;
+    readonly severity: 'info' | 'minor' | 'major' | 'blocker';
+    readonly priority: 'p0' | 'p1' | 'p2' | 'p3';
+    readonly confidence: 'high' | 'medium' | 'low';
+    readonly recommendedCommands: readonly string[];
+    readonly suggestedImplementationCategory: string;
+    readonly suggestedTests: readonly string[];
+    readonly alreadyCoveredBy?: string;
+    readonly suggestedPromptSection?: string;
+}
+export interface IFeedbackActionsReport {
+    readonly schema: typeof FEEDBACK_ACTIONS_V2_SCHEMA;
+    readonly generatedAt: string;
+    readonly sourceFile: string;
+    readonly actions: readonly IFeedbackAction[];
+}
+export interface IFeedbackBacklogReport {
+    readonly schema: 'sharkcraft.feedback-backlog/v1';
+    readonly generatedAt: string;
+    readonly grouped: Readonly<Record<string, readonly IFeedbackAction[]>>;
+    readonly markdown: string;
+}
+export interface IFeedbackPromptReport {
+    readonly schema: 'sharkcraft.feedback-prompt/v1';
+    readonly generatedAt: string;
+    readonly markdown: string;
+}
+export interface IFeedbackPlanReport {
+    readonly schema: 'sharkcraft.feedback-plan/v1';
+    readonly generatedAt: string;
+    readonly orderedActions: readonly IFeedbackAction[];
+    readonly validationGates: readonly string[];
+}
+export declare function buildFeedbackActionsReport(inspection: ISharkcraftInspection, sourceFile: string): IFeedbackActionsReport;
+export declare function buildFeedbackBacklogReport(inspection: ISharkcraftInspection, sourceFile: string): IFeedbackBacklogReport;
+export declare function buildFeedbackPromptReport(inspection: ISharkcraftInspection, sourceFile: string): IFeedbackPromptReport;
+export declare function buildFeedbackPlanReport(inspection: ISharkcraftInspection, sourceFile: string): IFeedbackPlanReport;
+//# sourceMappingURL=feedback-actions-v2.d.ts.map

package/dist/feedback-actions-v2.d.ts.map

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