@entelligentsia/forgecli 1.0.20 → 1.0.21

package/dist/extensions/forgecli/orchestrators/migrate.js

@@ -0,0 +1,260 @@
+// migrate.ts — native handler for /forge:migrate (FORGE-S23-T09)
+//
+// Two-branch handler:
+//   Structural branch: --structural flag OR .forge/structure-versions.json absent
+//     → runForgeSubagent(architect persona + migrate_structural.md workflow)
+//   Schema branch: deterministic store migration
+//     → runMigrations() from migration-engine.ts (T01)
+//
+// Post-migration health check runs in both branches via runHealthCheck().
+//
+// Iron Laws:
+//   IL6 — no shell-string interpolation (argv-array throughout)
+//   IL10 — structural branch uses runForgeSubagent (in-process pi SDK), not sendKickoff
+//   FORGE-BUG-001 — ctx.modelRegistry passed to runForgeSubagent
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getBundledPayloadRoot } from "../forge-init/forge-init.js";
+import { loadForgePersona, runForgeSubagent } from "../forge-subagent.js";
+import { getSubagentTools } from "../forge-tools.js";
+import { runHealthCheck } from "../health-check.js";
+import { runMigrations } from "../update/migration-engine.js";
+// ── Argument parser ─────────────────────────────────────────────────────────
+/**
+ * Parse /forge:migrate arguments.
+ *
+ * Also checks filesystem for .forge/structure-versions.json to determine
+ * structural vs schema branch (absence → structural).
+ */
+export function parseMigrateArgs(args, cwd) {
+    const parts = args.trim().split(/\s+/).filter(Boolean);
+    const hasStructuralFlag = parts.includes("--structural");
+    const hasDryRun = parts.includes("--dry-run");
+    // Structural if --structural flag OR structure-versions.json absent
+    const structureVersionsPath = path.join(cwd, ".forge", "structure-versions.json");
+    const structural = hasStructuralFlag || !fs.existsSync(structureVersionsPath);
+    return { structural, dryRun: hasDryRun };
+}
+// ── Ledger reader ───────────────────────────────────────────────────────────
+function readAppliedMigrationsFromVersion(cwd) {
+    const ledgerPath = path.join(cwd, ".forge", "applied-migrations.json");
+    try {
+        const raw = fs.readFileSync(ledgerPath, "utf8");
+        const ledger = JSON.parse(raw);
+        const versions = ledger.appliedVersions ?? [];
+        return versions.at(-1) ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+// ── Bundle version reader ───────────────────────────────────────────────────
+function readBundledForgeVersion(bundleRoot) {
+    try {
+        const pluginJson = path.join(bundleRoot, ".claude-plugin", "plugin.json");
+        const raw = fs.readFileSync(pluginJson, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version)
+            return parsed.version;
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0";
+}
+export function registerMigrate(pi, opts = {}) {
+    pi.registerCommand("forge:migrate", {
+        description: "Migrate an existing project store to Forge format. " +
+            "Structural branch (--structural or pre-T05 install): delegates to architect persona. " +
+            "Schema branch: applies deterministic store migrations from bundled migrations.json.",
+        async handler(args, ctx) {
+            const cwd = process.cwd();
+            const parsed = parseMigrateArgs(args, cwd);
+            // Config guard (Step 1 from plugin source)
+            const configPath = path.join(cwd, ".forge", "config.json");
+            if (!fs.existsSync(configPath)) {
+                ctx.ui.notify("× forge:migrate — no .forge/config.json found. " +
+                    "Run /forge:init first, then come back to /forge:migrate.", "error");
+                return;
+            }
+            // Resolve forge root (for subagent and health check)
+            let forgeRoot;
+            let bundleRoot;
+            if (opts._testBundleRoot) {
+                bundleRoot = opts._testBundleRoot;
+            }
+            else {
+                try {
+                    bundleRoot = getBundledPayloadRoot();
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    ctx.ui.notify(`× forge:migrate — could not resolve bundle root: ${msg}`, "error");
+                    return;
+                }
+            }
+            try {
+                const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+                const paths = cfg.paths;
+                if (paths && typeof paths.forgeRoot === "string")
+                    forgeRoot = paths.forgeRoot;
+            }
+            catch {
+                // non-fatal — forgeRoot remains undefined; health check degrades gracefully
+            }
+            if (parsed.structural) {
+                // ── Structural branch ────────────────────────────────────────────────
+                await runStructuralMigration(cwd, forgeRoot, bundleRoot, ctx, opts.forgeToolDefs);
+            }
+            else {
+                // ── Schema branch ────────────────────────────────────────────────────
+                await runSchemaMigration(cwd, forgeRoot, bundleRoot, parsed.dryRun, ctx);
+            }
+        },
+    });
+}
+// ── Structural branch ────────────────────────────────────────────────────────
+/**
+ * Structural migration: load migrate_structural.md (materialized workflow),
+ * run marker check, spawn architect subagent, then health check.
+ *
+ * Marker check rationale: migrate_structural.md does NOT contain
+ * Store-Write Verification or forge_store markers (it is a prose-heavy
+ * migration guide, not a store-writing kickoff). The handler checks only
+ * for `Iron Laws` as the minimum safeguard. This is a documented deviation
+ * from the full pack-06 marker set (pack-06 markers are designed for
+ * store-writing kickoff shims; structural migration is a different workflow
+ * class). Filed for follow-up: add Store-Write Verification to meta-migrate.md.
+ */
+async function runStructuralMigration(cwd, forgeRoot, bundleRoot, ctx, forgeToolDefs) {
+    ctx.ui.setStatus?.("forge:migrate", "Structural migration — loading workflow…");
+    // Read the materialized structural migration workflow
+    const workflowPath = path.join(cwd, ".forge", "workflows", "migrate_structural.md");
+    let workflowContent;
+    try {
+        workflowContent = fs.readFileSync(workflowPath, "utf8");
+    }
+    catch {
+        ctx.ui.notify(`× forge:migrate — migrate_structural.md not found at ${workflowPath}. ` +
+            "Run /forge:materialize first to fill missing workflows.", "error");
+        ctx.ui.setStatus?.("forge:migrate", undefined);
+        return;
+    }
+    // Materialization marker check (partial — Iron Laws only for structural workflow class)
+    if (!workflowContent.includes("Iron Laws")) {
+        ctx.ui.notify(`× forge:migrate — workflow regression: 'Iron Laws' not found in ${workflowPath}. ` +
+            "Run /forge:materialize to refresh.", "error");
+        ctx.ui.setStatus?.("forge:migrate", undefined);
+        return;
+    }
+    // Load architect persona
+    let persona;
+    try {
+        persona = loadForgePersona("architect", cwd);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`× forge:migrate — could not load architect persona: ${msg}`, "error");
+        ctx.ui.setStatus?.("forge:migrate", undefined);
+        return;
+    }
+    ctx.ui.setStatus?.("forge:migrate", "Structural migration — architect running…");
+    // Spawn isolated subagent (IL10)
+    const result = await runForgeSubagent({
+        persona,
+        task: workflowContent,
+        cwd,
+        signal: ctx.signal,
+        forgeRoot,
+        modelRegistry: ctx.modelRegistry, // FORGE-BUG-001 followup
+        customTools: forgeToolDefs ? getSubagentTools(forgeToolDefs) : undefined,
+    });
+    if (result.exitCode !== 0) {
+        ctx.ui.notify(`× forge:migrate — structural migration subagent failed (exit ${result.exitCode})`, "error");
+        ctx.ui.setStatus?.("forge:migrate", undefined);
+        return;
+    }
+    ctx.ui.notify("〇 forge:migrate — structural migration complete", "info");
+    await runPostMigrationHealthCheck(cwd, bundleRoot, forgeRoot, ctx);
+    ctx.ui.setStatus?.("forge:migrate", undefined);
+}
+// ── Schema branch ─────────────────────────────────────────────────────────────
+async function runSchemaMigration(cwd, forgeRoot, bundleRoot, dryRun, ctx) {
+    ctx.ui.setStatus?.("forge:migrate", "Schema migration — detecting versions…");
+    const fromVersion = readAppliedMigrationsFromVersion(cwd);
+    const toVersion = readBundledForgeVersion(bundleRoot);
+    if (!toVersion || toVersion === "0.0.0") {
+        ctx.ui.notify("× forge:migrate — could not determine bundled forge version. " +
+            "The bundle may be incomplete. Try reinstalling forge-cli.", "error");
+        ctx.ui.setStatus?.("forge:migrate", undefined);
+        return;
+    }
+    if (fromVersion === toVersion) {
+        ctx.ui.notify(`〇 forge:migrate — store is already at v${toVersion}; no schema migration needed. ` +
+            'Run `node "$FORGE_ROOT/tools/validate-store.cjs"` to confirm.', "info");
+        await runPostMigrationHealthCheck(cwd, bundleRoot, forgeRoot, ctx);
+        ctx.ui.setStatus?.("forge:migrate", undefined);
+        return;
+    }
+    ctx.ui.notify(`forge:migrate — applying migrations from v${fromVersion} → v${toVersion}${dryRun ? " (dry-run)" : ""}`, "info");
+    ctx.ui.setStatus?.("forge:migrate", `Applying migrations v${fromVersion} → v${toVersion}…`);
+    let migResult;
+    try {
+        migResult = await runMigrations({
+            bundleRoot,
+            projectRoot: cwd,
+            fromVersion,
+            toVersion,
+            dryRun,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`× forge:migrate — migration engine error: ${msg}`, "error");
+        ctx.ui.setStatus?.("forge:migrate", undefined);
+        return;
+    }
+    // Surface results
+    if (migResult.applied.length > 0) {
+        const versions = migResult.applied.map((a) => `v${a.toVersion}`).join(", ");
+        ctx.ui.notify(`〇 forge:migrate — applied ${migResult.applied.length} migration(s): ${versions}`, "info");
+    }
+    else {
+        ctx.ui.notify(`〇 forge:migrate — no new migrations to apply from v${fromVersion} to v${toVersion}`, "info");
+    }
+    if (migResult.skippedBreaking.length > 0) {
+        for (const skipped of migResult.skippedBreaking) {
+            ctx.ui.notify(`△ forge:migrate — skipped breaking migration to v${skipped.toVersion}: ${skipped.reason}`, "warning");
+        }
+    }
+    if (migResult.manualSteps.length > 0) {
+        ctx.ui.notify("△ forge:migrate — manual steps required after migration:", "warning");
+        for (const ms of migResult.manualSteps) {
+            for (const step of ms.steps) {
+                ctx.ui.notify(`  · v${ms.toVersion}: ${step}`, "info");
+            }
+        }
+    }
+    await runPostMigrationHealthCheck(cwd, bundleRoot, forgeRoot, ctx);
+    ctx.ui.setStatus?.("forge:migrate", undefined);
+}
+// ── Shared post-migration health check ─────────────────────────────────────────
+async function runPostMigrationHealthCheck(cwd, bundleRoot, forgeRoot, ctx) {
+    try {
+        const healthResult = await runHealthCheck(cwd, bundleRoot, forgeRoot);
+        if (healthResult.clean) {
+            ctx.ui.notify("〇 /forge:health: clean.", "info");
+        }
+        else {
+            ctx.ui.notify(`△ /forge:health: ${healthResult.gaps.length} gap(s) detected after migration`, "warning");
+            for (const gap of healthResult.gaps) {
+                ctx.ui.notify(`  · ${gap.check}: ${gap.message}`, "info");
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`△ forge:migrate — health check failed (non-fatal): ${msg}`, "warning");
+    }
+}
+//# sourceMappingURL=migrate.js.map

package/dist/extensions/forgecli/orchestrators/migrate.js.map

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

package/dist/extensions/forgecli/orchestrators/orchestrator-preflight.d.ts

@@ -0,0 +1,46 @@
+import type { MergedConfig } from "../config/config-layer.js";
+import type { OrchestratorResult } from "../lib/orchestrator-types.js";
+/** Minimal context interface — only the bits preflight needs. */
+export interface PreflightContext {
+    ui: {
+        notify(message: string, type?: "error" | "info" | "warning"): void;
+    };
+}
+export interface RunOrchestratorPreflightOptions {
+    /** "task" runs validateModelConfig; "ceremony" skips it. */
+    mode: "task" | "ceremony";
+    /** Minimal context for notifications. */
+    ctx: PreflightContext;
+    /** Prefix for notify messages, e.g. "forge:run-task" or "forge:fix-bug". */
+    notifyPrefix: string;
+    /** Persona name catalogue from readPersonaDir. */
+    personaCatalogue: string[];
+    /** Pipeline name catalogue from readPipelineNames; null if no config found. */
+    pipelineCatalogue: string[] | null;
+    /** Merged model-routing config from loadLayeredConfig. */
+    modelRoutingConfig: MergedConfig;
+    /** Available models from ctx.modelRegistry.getAvailable(). */
+    availableModels: Array<{
+        provider: string;
+        id: string;
+    }>;
+}
+/** Discriminated union: proceed=true → continue; proceed=false → return result early. */
+export type OrchestratorPreflightResult = {
+    proceed: true;
+} | {
+    proceed: false;
+    result: OrchestratorResult;
+};
+/**
+ * Run the orchestrator pre-flight check.
+ *
+ * In mode="task": calls validateModelConfig and surfaces warnings/errors via
+ * ctx.ui.notify. Returns `{ proceed: false, result }` with status="failed" if
+ * there are errors; returns `{ proceed: true }` otherwise.
+ *
+ * In mode="ceremony": returns `{ proceed: true }` immediately without calling
+ * validateModelConfig. This matches the existing behaviour of ceremony dispatch
+ * which uses lookupPersonaModel rather than the full validator.
+ */
+export declare function runOrchestratorPreflight(opts: RunOrchestratorPreflightOptions): OrchestratorPreflightResult;

package/dist/extensions/forgecli/orchestrators/orchestrator-preflight.js

@@ -0,0 +1,64 @@
+// orchestrator-preflight.ts — FORGE-S25-T17 (H-13, N-H-D)
+//
+// Single shared preflight helper for orchestrator pipelines. Replaces the
+// duplicate pre-flight validation blocks in run-task.ts and fix-bug.ts.
+//
+// Design: a `mode` parameter selects behaviour:
+//
+//   mode="task"     — full model-config validation via validateModelConfig.
+//                     Used by runTaskPipeline and runBugPipeline.
+//   mode="ceremony" — skips validateModelConfig entirely.
+//                     Aligns with dispatchSprintCeremony which uses
+//                     lookupPersonaModel (not the full validator). The
+//                     run-sprint.ts ceremony call does NOT use this helper
+//                     directly; it was already skip-validation by design
+//                     (N-H-D). This mode is available for future callers
+//                     that need a ceremony-style preflight.
+//
+// Why run-sprint.ts is NOT migrated to this helper:
+//   run-sprint.ts contains a separate sprint-entry validation block
+//   (lines 470–498) that validates sprint-level config, not task/phase-level.
+//   That block is architecturally distinct and is explicitly out of scope
+//   per the plan-review finding (N-H-D resolved, reviewer-approved).
+import { validateModelConfig } from "../config/model-validator.js";
+// ---------------------------------------------------------------------------
+// runOrchestratorPreflight
+// ---------------------------------------------------------------------------
+/**
+ * Run the orchestrator pre-flight check.
+ *
+ * In mode="task": calls validateModelConfig and surfaces warnings/errors via
+ * ctx.ui.notify. Returns `{ proceed: false, result }` with status="failed" if
+ * there are errors; returns `{ proceed: true }` otherwise.
+ *
+ * In mode="ceremony": returns `{ proceed: true }` immediately without calling
+ * validateModelConfig. This matches the existing behaviour of ceremony dispatch
+ * which uses lookupPersonaModel rather than the full validator.
+ */
+export function runOrchestratorPreflight(opts) {
+    if (opts.mode === "ceremony") {
+        return { proceed: true };
+    }
+    // mode="task" — full validation
+    const strict = process.env.FORGE_STRICT_MODELS === "1";
+    const { errors, warnings } = validateModelConfig(opts.personaCatalogue, opts.pipelineCatalogue, opts.modelRoutingConfig, opts.availableModels, strict);
+    for (const w of warnings) {
+        opts.ctx.ui.notify(`⚠ ${opts.notifyPrefix} — model routing: ${w.message}`, "warning");
+    }
+    if (errors.length > 0) {
+        for (const e of errors) {
+            opts.ctx.ui.notify(`× ${opts.notifyPrefix} — model routing: ${e.message}`, "error");
+        }
+        return {
+            proceed: false,
+            result: {
+                status: "failed",
+                lastPhaseIndex: 0,
+                iterationCounts: {},
+                lastError: `model config validation failed: ${errors.map((e) => e.code).join(", ")}`,
+            },
+        };
+    }
+    return { proceed: true };
+}
+//# sourceMappingURL=orchestrator-preflight.js.map

package/dist/extensions/forgecli/orchestrators/orchestrator-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-preflight.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/orchestrators/orchestrator-preflight.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,EAAE;AACF,gDAAgD;AAChD,EAAE;AACF,4EAA4E;AAC5E,kEAAkE;AAClE,0DAA0D;AAC1D,oEAAoE;AACpE,uEAAuE;AACvE,2EAA2E;AAC3E,yEAAyE;AACzE,yEAAyE;AACzE,4DAA4D;AAC5D,EAAE;AACF,oDAAoD;AACpD,oEAAoE;AACpE,8EAA8E;AAC9E,0EAA0E;AAC1E,qEAAqE;AAGrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAkCnE,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAqC;IAC7E,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC9B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,gCAAgC;IAChC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,GAAG,CAAC;IACvD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAC/C,IAAI,CAAC,gBAAgB,EACrB,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,kBAAkB,EACvB,IAAI,CAAC,eAAe,EACpB,MAAM,CACN,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,YAAY,qBAAqB,CAAC,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACvF,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACxB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,YAAY,qBAAqB,CAAC,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;QACrF,CAAC;QACD,OAAO;YACN,OAAO,EAAE,KAAK;YACd,MAAM,EAAE;gBACP,MAAM,EAAE,QAAQ;gBAChB,cAAc,EAAE,CAAC;gBACjB,eAAe,EAAE,EAAE;gBACnB,SAAS,EAAE,mCAAmC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;aACpF;SACD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/extensions/forgecli/orchestrators/run-sprint.d.ts

@@ -0,0 +1,27 @@
+import type { StreamFn } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { type ForgeToolDefs } from "../forge-tools.js";
+/**
+ * Test-only seam (forge-cli#17). Resolves a StreamFn for a given dispatch
+ * context — ceremony or per-phase. Production callers leave this undefined.
+ */
+export type SprintStreamFnFactory = (ctx: {
+    kind: "task-phase" | "ceremony";
+    persona: string;
+    phase?: string;
+    taskId?: string;
+}) => StreamFn | undefined;
+export interface RegisterRunSprintOptions {
+    cwd?: string;
+    /**
+     * Test-only seam (forge-cli#17). When set, each `runForgeSubagent` call
+     * spawned by the sprint handler (ceremony) and by the per-task pipeline
+     * (each phase) is dispatched with `streamFn = factory({...})`. Production
+     * callers leave this undefined.
+     */
+    streamFnFactory?: SprintStreamFnFactory;
+    forgeToolDefs?: ForgeToolDefs;
+    /** Extension factories forwarded to each task's subagent sessions (see RunTaskPipelineOptions). */
+    extensionFactories?: ExtensionFactory[];
+}
+export declare function registerRunSprint(pi: ExtensionAPI, options?: RegisterRunSprintOptions): void;