@shrkcrft/inspector 0.1.0-alpha.2

package/dist/healing-plan.js

@@ -0,0 +1,346 @@
+/**
+ * Self-healing plans.
+ *
+ * Given a stderr blob, failed report/plan, or command exit-code, produce a
+ * deterministic recovery plan. Never auto-fixes; never writes source.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { buildDiagnosticByCode, listDiagnostics, } from "./failure-diagnostics.js";
+import { suggestDiagnostic } from "./diagnostics-suggest.js";
+export const HEALING_PLAN_SCHEMA = 'sharkcraft.healing-plan/v1';
+export var HealingInputKind;
+(function (HealingInputKind) {
+    HealingInputKind["Error"] = "error";
+    HealingInputKind["File"] = "file";
+    HealingInputKind["Report"] = "report";
+    HealingInputKind["Command"] = "command";
+})(HealingInputKind || (HealingInputKind = {}));
+const GENERIC_NEXT = 'shrk diagnostics suggest "<paste error text here>"';
+function inferFromKeywords(text) {
+    const causes = [];
+    const recover = [];
+    const cmds = [];
+    const constructs = [];
+    const docs = [];
+    let humanApproval = false;
+    let sourceWrite = false;
+    const lower = text.toLowerCase();
+    // Plan conflicts.
+    if (lower.includes('conflict') || lower.includes('anchor not found')) {
+        causes.push('Saved plan has a conflict: file already exists, anchor missing, or replace mismatch.');
+        recover.push('Review the saved plan and inspect anchors / target files.');
+        cmds.push('shrk plan review <plan.json>');
+        cmds.push('shrk plan simulate <plan.json> --include-boundaries --include-impact');
+        cmds.push('shrk plan simulate <plan.json> --format markdown --output /tmp/plan-sim.md');
+        constructs.push('plan v2 operations: append / insert-after / insert-before / replace / export');
+        docs.push('docs/plan-simulation.md');
+    }
+    // Missing barrel / anchor.
+    if (lower.includes('barrel') || lower.includes('export *') || lower.includes('missing anchor')) {
+        causes.push('Missing barrel or anchor in the target file.');
+        recover.push('Open the barrel/index file referenced by the plan and confirm the anchor exists exactly once.');
+        cmds.push('grep -n "<anchor text>" <barrel file>');
+    }
+    // Pack signing missing secret.
+    if (lower.includes('signing') ||
+        lower.includes('hmac') ||
+        lower.includes('signature') ||
+        lower.includes('packs sign') ||
+        lower.includes('signed.json')) {
+        causes.push('Pack signing failed: secret missing or signature mismatch.');
+        recover.push('Provide the signing secret via the CLI (do not commit it).');
+        cmds.push('shrk packs sign <packPath> --secret-env SHARKCRAFT_PACK_SIGNING_KEY');
+        cmds.push('shrk packs verify');
+        humanApproval = true;
+        docs.push('docs/security.md');
+    }
+    // Migration readiness.
+    if (lower.includes('migration') && (lower.includes('readiness') || lower.includes('blocker'))) {
+        causes.push('Migration readiness gate reported a blocker.');
+        recover.push('Resolve each blocker before re-running the gate.');
+        cmds.push('shrk migration readiness --profile <id>');
+        cmds.push('shrk migration profiles');
+        docs.push('docs/migration-readiness.md');
+    }
+    // Unknown command.
+    if (lower.includes('unknown command') || lower.includes('command not found') || lower.includes('not a known')) {
+        causes.push('Unknown shrk command (alias / typo / removed command).');
+        recover.push('List supported commands; do not invent commands.');
+        cmds.push('shrk --help');
+        cmds.push('shrk commands');
+    }
+    // Module not found.
+    if (lower.includes('cannot find module') || lower.includes('module_not_found')) {
+        causes.push('Dependency missing — node_modules not installed or alias unresolved.');
+        recover.push('Install dependencies; do not patch package.json blindly.');
+        cmds.push('bun install');
+        cmds.push('shrk doctor');
+        humanApproval = false;
+    }
+    // Verification failed.
+    if (lower.includes('verification failed') || lower.includes('tests failed') || lower.includes('typecheck failed')) {
+        causes.push('A verification command failed.');
+        recover.push('Re-run the failing command locally and read its output.');
+        cmds.push('bun x tsc -p tsconfig.base.json --noEmit');
+        cmds.push('bun test');
+    }
+    // Release readiness.
+    if (lower.includes('release readiness') || lower.includes('preflight')) {
+        causes.push('Release readiness reported a blocker.');
+        recover.push('Resolve each blocker; do NOT publish to bypass the gate.');
+        cmds.push('shrk release readiness --strict');
+        cmds.push('bun run release:preflight');
+        humanApproval = true;
+    }
+    // polyglot Java
+    if (lower.includes('cannot find symbol')) {
+        causes.push('Java compiler reports "cannot find symbol" — missing import or dependency.');
+        recover.push('Add the missing import / dependency; run `mvn dependency:tree` to verify.');
+        cmds.push('mvn -U test');
+        docs.push('docs/healing-plans.md');
+    }
+    if (lower.includes('package does not exist')) {
+        causes.push('Java dependency is not on the classpath.');
+        recover.push('Declare the dependency in pom.xml / build.gradle and refresh.');
+        cmds.push('mvn -U test');
+        cmds.push('./gradlew --refresh-dependencies test');
+    }
+    // polyglot C#
+    if (lower.includes('cs0246')) {
+        causes.push('CS0246 — type or namespace not found.');
+        recover.push('Add the missing `using` directive or restore the NuGet package.');
+        cmds.push('dotnet restore');
+        cmds.push('dotnet build');
+    }
+    if (lower.includes('nu1101')) {
+        causes.push('NU1101 — NuGet package not found.');
+        recover.push('Verify the package id and feed; then re-restore.');
+        cmds.push('dotnet nuget list source');
+        cmds.push('dotnet restore --force-evaluate');
+    }
+    // polyglot Python
+    if (lower.includes('modulenotfounderror') || lower.includes('no module named')) {
+        causes.push('Python ModuleNotFoundError — dependency not installed in active env.');
+        recover.push('Install the dependency; do NOT add bare paths to sys.path as a workaround.');
+        cmds.push('python -m pip install -r requirements.txt');
+        cmds.push('uv sync');
+        cmds.push('poetry install');
+    }
+    if (lower.includes('pytest') && (lower.includes('collected 0 items') || lower.includes('errors during collection'))) {
+        causes.push('pytest collection error — a test file fails to import or a fixture is missing.');
+        recover.push('Narrow down with `pytest --collect-only`; fix the failing import first.');
+        cmds.push('python -m pytest --collect-only');
+    }
+    // polyglot Go
+    if (lower.includes('no required module provides package') || lower.includes('cannot find module')) {
+        causes.push('Go module missing — go.mod is out of date.');
+        recover.push('Run `go mod tidy` to bring go.mod in sync.');
+        cmds.push('go mod tidy');
+        cmds.push('go test ./...');
+    }
+    if (lower.includes('import cycle')) {
+        causes.push('Go import cycle — two packages import each other.');
+        recover.push('Refactor: extract shared types into a new neutral package.');
+        cmds.push('go list -deps ./...');
+    }
+    // polyglot Rust
+    if (lower.includes('e0432') || lower.includes('unresolved import')) {
+        causes.push('Rust E0432 — unresolved import. Crate or mod declaration missing.');
+        recover.push('Add the dependency to Cargo.toml or declare the `mod` line.');
+        cmds.push('cargo build');
+    }
+    if (lower.includes('e0308') || lower.includes('mismatched types')) {
+        causes.push('Rust E0308 — mismatched types or lifetime/borrow conflict.');
+        recover.push('Inspect the offending expression with `cargo check --message-format=short`.');
+        cmds.push('cargo check --message-format=short');
+    }
+    return { causes, recover, cmds, constructs, docs, humanApproval, sourceWrite };
+}
+function summarize(text, max = 240) {
+    const cleaned = text.replace(/\s+/g, ' ').trim();
+    return cleaned.length > max ? cleaned.slice(0, max) + '…' : cleaned;
+}
+function buildPlan(ctx) {
+    const suggest = suggestDiagnostic(ctx.text);
+    const codes = new Set();
+    for (const c of suggest.candidates)
+        codes.add(c.code);
+    // Add command-exit-driven codes.
+    if (ctx.exitCode !== undefined && ctx.exitCode !== 0 && ctx.command) {
+        codes.add('failed-verification');
+    }
+    const detectedDiagnostics = [];
+    for (const code of codes) {
+        detectedDiagnostics.push(buildDiagnosticByCode(code, {
+            command: ctx.command ?? '',
+            exitCode: ctx.exitCode ?? -1,
+        }));
+    }
+    const inferred = inferFromKeywords(ctx.text);
+    // Confidence.
+    const top = suggest.topSuggestion?.confidence ?? (detectedDiagnostics.length > 0 ? 'medium' : 'low');
+    const confidence = top;
+    // Recommended commands.
+    const recommendedCommands = [];
+    for (const d of detectedDiagnostics) {
+        if (d.nextCommand)
+            recommendedCommands.push(d.nextCommand);
+    }
+    for (const c of inferred.cmds)
+        recommendedCommands.push(c);
+    if (recommendedCommands.length === 0)
+        recommendedCommands.push(GENERIC_NEXT);
+    // Likely causes.
+    const likelyCauses = [];
+    for (const d of detectedDiagnostics)
+        likelyCauses.push(d.likelyCause ?? d.problem);
+    for (const c of inferred.causes)
+        likelyCauses.push(c);
+    if (likelyCauses.length === 0)
+        likelyCauses.push('Unable to classify automatically — run generic triage.');
+    // Safe recovery steps.
+    const safeRecoverySteps = [
+        'Re-read the failing command output carefully (do not skip).',
+        'Reproduce the failure locally before changing code.',
+        'If unsure, run `shrk doctor` and `shrk diagnostics suggest`.',
+    ];
+    for (const r of inferred.recover)
+        safeRecoverySteps.push(r);
+    const forbiddenQuickFixes = [
+        'Do NOT bypass safety hooks (--no-verify).',
+        'Do NOT silence the failing test/check — fix the root cause.',
+        'Do NOT commit secrets or signing keys to recover.',
+        'Do NOT delete .sharkcraft/sessions or .sharkcraft/plans to clear state.',
+    ];
+    const relatedDocs = [...new Set(inferred.docs)];
+    const relatedConstructs = [...new Set(inferred.constructs)];
+    const humanApprovalRequired = inferred.humanApproval || detectedDiagnostics.some((d) => d.code === 'release-readiness-blocker' || d.code === 'plan-signature-mismatch');
+    const sourceWritesInvolved = inferred.sourceWrite;
+    const nextSafestCommand = recommendedCommands[0] ?? GENERIC_NEXT;
+    return {
+        schema: HEALING_PLAN_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        inputKind: ctx.inputKind,
+        inputSummary: summarize(ctx.inputSummary || ctx.text),
+        detectedDiagnostics,
+        confidence,
+        likelyCauses: [...new Set(likelyCauses)],
+        safeRecoverySteps: [...new Set(safeRecoverySteps)],
+        forbiddenQuickFixes,
+        recommendedCommands: [...new Set(recommendedCommands)],
+        relatedConstructs,
+        relatedDocs,
+        humanApprovalRequired,
+        sourceWritesInvolved,
+        nextSafestCommand,
+        notes: [
+            'Heal output is advisory only. No automatic fixes. No source writes.',
+            'CLI is the only write path; MCP stays read-only.',
+        ],
+    };
+}
+export function buildHealingPlanFromError(errorText) {
+    return buildPlan({
+        inputKind: HealingInputKind.Error,
+        inputSummary: summarize(errorText, 120),
+        text: errorText,
+    });
+}
+export function buildHealingPlanFromFile(filePath) {
+    if (!existsSync(filePath)) {
+        return buildPlan({
+            inputKind: HealingInputKind.File,
+            inputSummary: `(missing file) ${filePath}`,
+            text: '',
+        });
+    }
+    const text = readFileSync(filePath, 'utf8');
+    return buildPlan({
+        inputKind: HealingInputKind.File,
+        inputSummary: filePath,
+        text,
+    });
+}
+export function buildHealingPlanFromReport(reportPath) {
+    if (!existsSync(reportPath)) {
+        return buildPlan({
+            inputKind: HealingInputKind.Report,
+            inputSummary: `(missing report) ${reportPath}`,
+            text: '',
+        });
+    }
+    let text = readFileSync(reportPath, 'utf8');
+    // Flatten the report so keyword scanning works.
+    try {
+        const j = JSON.parse(text);
+        text = JSON.stringify(j);
+    }
+    catch {
+        /* not JSON */
+    }
+    return buildPlan({
+        inputKind: HealingInputKind.Report,
+        inputSummary: reportPath,
+        text,
+    });
+}
+export function buildHealingPlanFromCommand(command, exitCode, stderrText) {
+    return buildPlan({
+        inputKind: HealingInputKind.Command,
+        inputSummary: `${command} (exit ${exitCode})`,
+        text: stderrText,
+        command,
+        exitCode,
+    });
+}
+void listDiagnostics;
+export function renderHealingPlanText(p) {
+    let out = `=== Healing plan ===\n`;
+    out += `  input            ${p.inputKind} — ${p.inputSummary}\n`;
+    out += `  confidence       ${p.confidence}\n`;
+    out += `  human approval   ${p.humanApprovalRequired ? 'REQUIRED' : 'not required'}\n`;
+    out += `  source writes    ${p.sourceWritesInvolved ? 'YES' : 'no'}\n\n`;
+    out += `Likely causes:\n`;
+    for (const c of p.likelyCauses)
+        out += `  • ${c}\n`;
+    out += `\nSafe recovery steps:\n`;
+    for (const s of p.safeRecoverySteps)
+        out += `  • ${s}\n`;
+    out += `\nForbidden quick fixes:\n`;
+    for (const f of p.forbiddenQuickFixes)
+        out += `  • ${f}\n`;
+    out += `\nRecommended commands:\n`;
+    for (const c of p.recommendedCommands)
+        out += `  $ ${c}\n`;
+    if (p.detectedDiagnostics.length > 0) {
+        out += `\nDetected diagnostics:\n`;
+        for (const d of p.detectedDiagnostics)
+            out += `  • [${d.code}] ${d.problem}\n`;
+    }
+    if (p.relatedDocs.length)
+        out += `\nRelated docs: ${p.relatedDocs.join(', ')}\n`;
+    if (p.relatedConstructs.length)
+        out += `Related constructs: ${p.relatedConstructs.join(', ')}\n`;
+    out += `\nNext safest command:\n  $ ${p.nextSafestCommand}\n`;
+    return out;
+}
+export function renderHealingPlanMarkdown(p) {
+    let out = `# Healing plan\n\n`;
+    out += `- **input**: ${p.inputKind} — ${p.inputSummary}\n`;
+    out += `- **confidence**: ${p.confidence}\n`;
+    out += `- **human approval**: ${p.humanApprovalRequired ? 'REQUIRED' : 'not required'}\n`;
+    out += `- **source writes**: ${p.sourceWritesInvolved ? 'YES' : 'no'}\n\n`;
+    out += `## Likely causes\n` + p.likelyCauses.map((c) => `- ${c}`).join('\n') + '\n\n';
+    out += `## Safe recovery steps\n` + p.safeRecoverySteps.map((s) => `- ${s}`).join('\n') + '\n\n';
+    out += `## Forbidden quick fixes\n` + p.forbiddenQuickFixes.map((f) => `- ${f}`).join('\n') + '\n\n';
+    out += `## Recommended commands\n` + p.recommendedCommands.map((c) => `- \`${c}\``).join('\n') + '\n\n';
+    if (p.detectedDiagnostics.length) {
+        out += `## Detected diagnostics\n` + p.detectedDiagnostics.map((d) => `- **${d.code}** — ${d.problem}`).join('\n') + '\n\n';
+    }
+    if (p.relatedDocs.length)
+        out += `**Related docs**: ${p.relatedDocs.join(', ')}\n\n`;
+    if (p.relatedConstructs.length)
+        out += `**Related constructs**: ${p.relatedConstructs.join(', ')}\n\n`;
+    out += `\n**Next safest command**: \`${p.nextSafestCommand}\`\n`;
+    return out;
+}

package/dist/helper-registry.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Helper plan generators (profile-driven for project-specific paths).
+ *
+ * Helpers are one-shot plan-v2 producers for small, well-bounded edits.
+ * They are dry-run by default and idempotent where the plan engine supports it.
+ *
+ * No helper writes source directly. The output is a structured `IHelperPlan`
+ * containing planned ops (using the existing plan-v2 operation set) and a
+ * list of advisory conflicts when an expected anchor cannot be resolved.
+ *
+ * Helpers must accept an IPluginLifecycleProfile instead of hardcoded paths,
+ * so the engine knows where the key-table / plugin roots live.
+ * Project-specific helpers contributed by packs travel in pack-contributed
+ * playbooks/scaffolds; the engine just provides the generic shapes.
+ */
+import { type IPluginLifecycleProfile } from '@shrkcrft/plugin-api';
+export declare enum HelperId {
+    AddPluginKey = "core.add-plugin-key",
+    RemovePluginKey = "core.remove-plugin-key",
+    RenamePluginKey = "core.rename-plugin-key",
+    AddBarrelExport = "core.add-barrel-export",
+    RemoveBarrelExport = "core.remove-barrel-export",
+    AddEventEntry = "core.add-event-entry",
+    RemoveEventEntry = "core.remove-event-entry",
+    AddDefaultRegistration = "core.add-default-registration",
+    RemoveDefaultRegistration = "core.remove-default-registration",
+    AddComposerEntry = "core.add-composer-entry",
+    RemoveComposerEntry = "core.remove-composer-entry",
+    RenamePluginFolder = "core.rename-plugin-folder",
+    RemoveUserPluginEntry = "core.remove-user-plugin-entry"
+}
+export interface IHelperDefinition {
+    id: HelperId;
+    description: string;
+    destructive: boolean;
+    requiresHumanReview: boolean;
+    requiresProfile?: boolean;
+    variables: ReadonlyArray<{
+        name: string;
+        required: boolean;
+        description: string;
+    }>;
+}
+export declare const HELPERS: ReadonlyArray<IHelperDefinition>;
+export interface IHelperPlanOp {
+    targetPath: string;
+    operation: Record<string, unknown>;
+}
+export interface IHelperPlan {
+    schema: 'sharkcraft.helper-plan/v1';
+    helperId: HelperId;
+    variables: Record<string, string>;
+    ops: ReadonlyArray<IHelperPlanOp>;
+    manualSteps: ReadonlyArray<string>;
+    conflicts: ReadonlyArray<string>;
+    destructive: boolean;
+    humanReviewRequired: boolean;
+}
+/**
+ * Convert a helper plan into a saved plan (synthetic templateId) so
+ * it flows through `shrk apply`. Helper ops are persisted as v2 operation
+ * intents; the apply path evaluates them against the live file system.
+ * Unsigned by default; call `signPlan` separately when desired.
+ */
+export declare const HELPER_SYNTHETIC_TEMPLATE = "__helper__";
+export declare function helperPlanToSavedPlan(plan: IHelperPlan, projectRoot: string): {
+    schema: 'sharkcraft.plan/v2';
+    templateId: string;
+    variables: Record<string, string>;
+    projectRoot: string;
+    createdAt: string;
+    expectedChanges: {
+        type: string;
+        relativePath: string;
+        sizeBytes: number;
+        operation: Record<string, unknown>;
+    }[];
+    note?: string;
+};
+interface IHelperBuildInput {
+    helperId: HelperId;
+    projectRoot: string;
+    vars: Record<string, string>;
+    /** Required for helpers marked requiresProfile in HELPERS. */
+    profile?: IPluginLifecycleProfile;
+}
+export declare function buildHelperPlan(input: IHelperBuildInput): IHelperPlan;
+export declare function renderHelperPlanText(plan: IHelperPlan): string;
+export {};
+//# sourceMappingURL=helper-registry.d.ts.map

package/dist/helper-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-registry.d.ts","sourceRoot":"","sources":["../src/helper-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAE9B,oBAAY,QAAQ;IAClB,YAAY,wBAAwB;IACpC,eAAe,2BAA2B;IAC1C,eAAe,2BAA2B;IAC1C,eAAe,2BAA2B;IAC1C,kBAAkB,8BAA8B;IAChD,aAAa,yBAAyB;IACtC,gBAAgB,4BAA4B;IAC5C,sBAAsB,kCAAkC;IACxD,yBAAyB,qCAAqC;IAC9D,gBAAgB,4BAA4B;IAC5C,mBAAmB,+BAA+B;IAClD,kBAAkB,8BAA8B;IAChD,qBAAqB,kCAAkC;CACxD;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,QAAQ,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpF;AAED,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAqInD,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,2BAA2B,CAAC;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,GAAG,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAClC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,MAAM,GAClB;IACD,MAAM,EAAE,oBAAoB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE;QACf,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,EAAE,CAAC;IACJ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CA4CA;AAwCD,UAAU,iBAAiB;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,uBAAuB,CAAC;CACnC;AAWD,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,WAAW,CAiQrE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAuB9D"}