@entelligentsia/forgecli 0.10.0 → 0.11.2

package/dist/extensions/forgecli/materialize.js

@@ -0,0 +1,195 @@
+// materialize.ts — native handler for /forge:materialize (FORGE-S23-T09)
+//
+// Ports the deterministic subset of the plugin's /forge:materialize:
+//   - Full warm-up (no args or --all): runs substitute-placeholders.cjs,
+//     build-persona-pack.cjs, and build-context-pack.cjs from the bundled payload.
+//   - Single-workflow mode: deferred — notify + return (follow-up task).
+//
+// Mode-neutral invariant: never writes .forge/config.json mode field.
+// Uses spawn("node", [toolPath, ...argv]) — argv-array, no shell (IL6).
+//
+// References: regenerate.ts (substitute-placeholders.cjs argv),
+//             forge-init.ts (build-persona-pack / build-context-pack argv).
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getBundledPayloadRoot, getBundledToolsRoot } from "./forge-init.js";
+// ── Argument parser ─────────────────────────────────────────────────────────
+/**
+ * Parse /forge:materialize arguments.
+ *
+ * Recognised forms:
+ *   (empty)                  → { mode: "all" }
+ *   --all                    → { mode: "all" }
+ *   workflows <id>           → { mode: "single-workflow", workflowId: "<id>" }
+ *   workflows:<id>           → { mode: "single-workflow", workflowId: "<id>" }
+ */
+export function parseMaterializeArgs(args) {
+    const trimmed = args.trim();
+    if (!trimmed || trimmed === "--all") {
+        return { mode: "all" };
+    }
+    // "workflows plan_task" or "workflows:plan_task"
+    const workflowsMatch = trimmed.match(/^workflows[: ](.+)$/);
+    if (workflowsMatch) {
+        return { mode: "single-workflow", workflowId: workflowsMatch[1].trim() };
+    }
+    // Unrecognised flags/forms: treat as full warm-up (fail-open)
+    return { mode: "all" };
+}
+// ── Tool runner ─────────────────────────────────────────────────────────────
+/**
+ * Spawn `node <toolPath> [...argv]` and await completion.
+ * Returns `{ ok: boolean, stderr: string }`.
+ *
+ * Non-zero exit is FATAL when `fatal === true` (default), ADVISORY otherwise.
+ */
+async function runTool(toolPath, argv, cwd, label, timeoutMs = 60_000) {
+    return new Promise((resolve) => {
+        const child = spawn("node", [toolPath, ...argv], {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stderrBuf = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            resolve({ ok: false, stderr: `${label} timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+        child.stderr?.on("data", (d) => {
+            stderrBuf += d.toString();
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ ok: code === 0, stderr: stderrBuf });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ ok: false, stderr: err.message });
+        });
+    });
+}
+// ── Register ────────────────────────────────────────────────────────────────
+export function registerMaterialize(pi) {
+    pi.registerCommand("forge:materialize", {
+        description: "Fill missing or stubbed Forge scaffolding without overwriting pristine files. " +
+            "Deterministic complement to /forge:init --fast. Mode-neutral: never writes config mode.",
+        async handler(args, ctx) {
+            const cwd = process.cwd();
+            const parsed = parseMaterializeArgs(args);
+            // Single-workflow mode: deferred in forge-cli — notify and return
+            if (parsed.mode === "single-workflow") {
+                ctx.ui.notify(`〇 forge:materialize — single-workflow mode ('${parsed.workflowId ?? "?"}') is not yet supported in forge-cli. ` +
+                    "Use the Forge plugin directly or run /forge:materialize --all for a full warm-up.", "info");
+                return;
+            }
+            // Config guard
+            const configPath = path.join(cwd, ".forge", "config.json");
+            if (!fs.existsSync(configPath)) {
+                ctx.ui.notify("× forge:materialize — no .forge/config.json found. Run /forge:init first.", "error");
+                return;
+            }
+            // Resolve tool paths
+            let bundleRoot;
+            let toolsRoot;
+            try {
+                bundleRoot = getBundledPayloadRoot();
+                toolsRoot = getBundledToolsRoot();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                ctx.ui.notify(`× forge:materialize — could not resolve bundle paths: ${msg}`, "error");
+                return;
+            }
+            const substituteTool = path.join(toolsRoot, "substitute-placeholders.cjs");
+            const basePackDir = path.join(bundleRoot, ".base-pack");
+            const configJsonPath = path.join(cwd, ".forge", "config.json");
+            // Guard: tools must exist
+            if (!fs.existsSync(substituteTool)) {
+                ctx.ui.notify(`× forge:materialize — substitute-placeholders.cjs not found at ${substituteTool}`, "error");
+                return;
+            }
+            if (!fs.existsSync(basePackDir)) {
+                ctx.ui.notify(`× forge:materialize — .base-pack not found at ${basePackDir}`, "error");
+                return;
+            }
+            ctx.ui.setStatus?.("forge:materialize", "Materializing .forge/ artifacts…");
+            // Step 1: substitute-placeholders.cjs (fatal on failure)
+            // argv shape mirrors regenerate.ts usage
+            const initContextJson = path.join(cwd, ".forge", "init-context.json");
+            const subArgv = [
+                "--forge-root",
+                bundleRoot,
+                "--base-pack",
+                basePackDir,
+                "--config",
+                configJsonPath,
+                "--out",
+                cwd,
+            ];
+            if (fs.existsSync(initContextJson)) {
+                subArgv.push("--context", initContextJson);
+            }
+            const subResult = await runTool(substituteTool, subArgv, cwd, "substitute-placeholders", 60_000);
+            if (!subResult.ok) {
+                const errMsg = subResult.stderr.trim().split("\n").slice(-3).join(" | ") || "unknown error";
+                ctx.ui.notify(`× forge:materialize — substitute-placeholders.cjs failed: ${errMsg}`, "error");
+                ctx.ui.setStatus?.("forge:materialize", undefined);
+                return;
+            }
+            ctx.ui.notify("〇 forge:materialize — scaffold filled", "info");
+            // Step 2: build-persona-pack.cjs (advisory — non-fatal)
+            const buildPersonaPackTool = path.join(toolsRoot, "build-persona-pack.cjs");
+            if (fs.existsSync(buildPersonaPackTool)) {
+                fs.mkdirSync(path.join(cwd, ".forge", "cache"), { recursive: true });
+                const personaResult = await runTool(buildPersonaPackTool, ["--out", path.join(cwd, ".forge", "cache", "persona-pack.json")], cwd, "build-persona-pack", 30_000);
+                if (!personaResult.ok) {
+                    const msg = personaResult.stderr.trim().split("\n").at(-1) ?? "unknown";
+                    ctx.ui.notify(`△ forge:materialize — build-persona-pack.cjs failed (non-fatal): ${msg}`, "warning");
+                }
+            }
+            // Step 3: build-context-pack.cjs (advisory — non-fatal)
+            const buildContextPackTool = path.join(toolsRoot, "build-context-pack.cjs");
+            if (fs.existsSync(buildContextPackTool)) {
+                // Read engineering path from config
+                let kbPath = "engineering";
+                try {
+                    const raw = fs.readFileSync(configPath, "utf8");
+                    const cfg = JSON.parse(raw);
+                    const p = cfg.paths;
+                    if (p && typeof p.engineering === "string")
+                        kbPath = p.engineering;
+                }
+                catch {
+                    // use default
+                }
+                const ctxResult = await runTool(buildContextPackTool, [
+                    "--arch-dir",
+                    path.join(cwd, kbPath, "architecture"),
+                    "--out-md",
+                    path.join(cwd, ".forge", "cache", "context-pack.md"),
+                    "--out-json",
+                    path.join(cwd, ".forge", "cache", "context-pack.json"),
+                ], cwd, "build-context-pack", 30_000);
+                if (!ctxResult.ok) {
+                    const msg = ctxResult.stderr.trim().split("\n").at(-1) ?? "unknown";
+                    ctx.ui.notify(`△ forge:materialize — build-context-pack.cjs failed (non-fatal): ${msg}`, "warning");
+                }
+            }
+            // Complete
+            ctx.ui.setStatus?.("forge:materialize", undefined);
+            ctx.ui.notify("〇 forge:materialize complete — gaps filled (mode unchanged)", "info");
+            // Promotion hint (mode-neutral: only read, never write)
+            try {
+                const raw = fs.readFileSync(configPath, "utf8");
+                const cfg = JSON.parse(raw);
+                if (cfg.mode === "fast") {
+                    ctx.ui.notify("〇 To declare the project fully generated: /forge:config mode full", "info");
+                }
+            }
+            catch {
+                // non-fatal — promotion hint is cosmetic
+            }
+        },
+    });
+}
+//# sourceMappingURL=materialize.js.map

package/dist/extensions/forgecli/materialize.js.map

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

package/dist/extensions/forgecli/migrate.d.ts

@@ -0,0 +1,19 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface ParsedMigrateArgs {
+    /** True when --structural flag present OR .forge/structure-versions.json absent. */
+    structural: boolean;
+    /** True when --dry-run flag present (schema branch only). */
+    dryRun: boolean;
+}
+/**
+ * Parse /forge:migrate arguments.
+ *
+ * Also checks filesystem for .forge/structure-versions.json to determine
+ * structural vs schema branch (absence → structural).
+ */
+export declare function parseMigrateArgs(args: string, cwd: string): ParsedMigrateArgs;
+export interface RegisterMigrateOptions {
+    /** Override bundleRoot — for testing only. Production: always undefined (resolved via getBundledPayloadRoot). */
+    _testBundleRoot?: string;
+}
+export declare function registerMigrate(pi: ExtensionAPI, opts?: RegisterMigrateOptions): void;

package/dist/extensions/forgecli/migrate.js

@@ -0,0 +1,258 @@
+// 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.js";
+import { runHealthCheck } from "./health-check.js";
+import { loadForgePersona, runForgeSubagent } from "./forge-subagent.js";
+import { runMigrations } from "./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);
+            }
+            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) {
+    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
+    });
+    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/migrate.js.map

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

package/dist/extensions/forgecli/migration-engine.d.ts

@@ -0,0 +1,111 @@
+export interface MigrationEntry {
+    version: string;
+    date: string;
+    notes: string;
+    regenerate?: string[];
+    fileOps?: FileOp[];
+    breaking?: boolean;
+    manual?: string[];
+}
+export interface FileOp {
+    op: "mkdir" | "copy" | "delete" | "substitute-placeholder";
+    path: string;
+    src?: string;
+}
+export interface MigrationsJson {
+    [key: string]: MigrationEntry;
+}
+export interface MigrationResult {
+    applied: Array<{
+        fromVersion: string;
+        toVersion: string;
+        categories: string[];
+    }>;
+    skippedBreaking: Array<{
+        fromVersion: string;
+        toVersion: string;
+        reason: string;
+    }>;
+    manualSteps: Array<{
+        fromVersion: string;
+        toVersion: string;
+        steps: string[];
+    }>;
+    dryRun: boolean;
+    schemasRefreshed: string[];
+    forgeRootUpdated: boolean;
+}
+export interface RunMigrationsOptions {
+    /** Absolute path to the dist/forge-payload/ bundle root */
+    bundleRoot: string;
+    /** Absolute path to the project root (contains .forge/) */
+    projectRoot: string;
+    /** Version the user was running before the upgrade */
+    fromVersion: string;
+    /** Version the user just upgraded to */
+    toVersion: string;
+    /** When true, log actions without writing any files */
+    dryRun?: boolean;
+}
+interface EntryWithKey {
+    key: string;
+    entry: MigrationEntry;
+}
+/** Write-descriptor: source path + destination path for a file copy/write operation */
+interface WriteDescriptor {
+    src: string;
+    dest: string;
+    content?: string;
+}
+/**
+ * Compare two version strings using semver integer-component comparison.
+ * Returns: negative if a < b, 0 if a === b, positive if a > b.
+ *
+ * Unlike string comparison, this correctly handles 0.9.x vs 0.10.x boundaries.
+ * Strips leading "v" prefix (matches parseTriple() behavior in forge-update-command.ts:118).
+ * Falls back to localeCompare for invalid/non-semver inputs.
+ */
+export declare function semverCompare(a: string, b: string): number;
+/**
+ * Filter migrations.json entries using [fromVersion, toVersion) semantics on keys.
+ *
+ * - fromVersion entry IS included: it represents the transition AWAY from that version.
+ * - toVersion entry is EXCLUDED: it would be a further transition past the target.
+ * - Results are sorted ascending by semver (oldest first).
+ *
+ * No first-run special case — this same filter applies for both first-run
+ * (empty ledger) and subsequent runs. The idempotency ledger handles re-run protection.
+ */
+export declare function filterMigrationEntries(migrations: MigrationsJson, fromVersion: string, toVersion: string): EntryWithKey[];
+/**
+ * Resolve a migration category string to one or more WriteDescriptors.
+ * Pure function — does not write files; appends to the provided writes array.
+ *
+ * ENOENT trap rule: if source doesn't exist, skip silently (never throw on ENOENT).
+ * Non-ENOENT IO errors propagate.
+ *
+ * Path-traversal defense: all output paths are validated against
+ * path.join(projectRoot, '.forge') before being added to writes.
+ */
+export declare function resolveCategory(category: string, bundleRoot: string, projectRoot: string, writes: WriteDescriptor[]): void;
+/**
+ * Execute all migration entries between [fromVersion, toVersion) from the
+ * bundled migrations.json against the project's .forge/ directory.
+ *
+ * Design constraints:
+ * - No UI context (no ctx.ui calls).
+ * - No event emission (caller is responsible).
+ * - Pure deterministic engine: reads from bundleRoot, writes to projectRoot/.forge/.
+ * - Idempotent: already-applied versions (from .forge/applied-migrations.json) are skipped.
+ *
+ * Forward-compat: entries with non-empty fileOps[] use fileOps; otherwise regenerate.
+ * NOTE: 0 of 158 current entries use fileOps — the executor is dead code on day 1.
+ * Once a real fileOps entry lands, an integration test against that entry MUST be added.
+ */
+export declare function runMigrations(opts: RunMigrationsOptions): Promise<MigrationResult>;
+export declare const __test__: {
+    semverCompare: typeof semverCompare;
+    filterMigrationEntries: typeof filterMigrationEntries;
+    resolveCategory: typeof resolveCategory;
+};
+export {};