@entelligentsia/forgecli 0.10.1 → 0.11.3

package/dist/extensions/forgecli/lib/store-error-remediation.d.ts

@@ -0,0 +1,65 @@
+export interface RemediationResult {
+    /** One-line user-facing hint explaining the error and the fix. */
+    hint: string;
+    /** Optional copy-pasteable store-cli command. Empty string if N/A. */
+    command: string;
+}
+/**
+ * Infer the entity type from an entity name/ID string.
+ * Returns "task" as default if no match.
+ */
+export declare function inferEntityType(entity: string): string;
+/** Parsed breakdown of a validation error string. */
+interface ParsedError {
+    field: string;
+    errorKind: "enum" | "required" | "undeclared" | "type" | "pattern" | "datetime" | "length" | "other";
+    observed?: string;
+    enumValues?: string[];
+}
+/**
+ * Parse a single validation error line from validate.js / store-cli.
+ *
+ * Examples:
+ *   'status: value "verified" not in [reported, triaged, in-progress, fixed]'
+ *   'taskId: missing required field'
+ *   'xyz: undeclared field'
+ *   'sprintId: expected string, got number'
+ *   'title: value length 0 is below minLength 1'
+ *   'createdAt: value "today" is not a valid date-time'
+ *   'prefix: value "AB" does not match pattern ^[A-Z]+-[A-Z]$'
+ */
+export declare function parseValidationError(line: string): ParsedError;
+/**
+ * Given a single validation error line (from validate.js or store-cli),
+ * return a user-facing remediation hint and optional copy-pasteable command.
+ *
+ * @param errorLine  A single error line from validate.js / store-cli output.
+ * @param entityType  The entity type (task, sprint, bug, feature, event).
+ * @param entityId   The entity ID (e.g. "FORGE-S18-T02") — used for commands.
+ * @returns          RemediationResult with hint and command.
+ */
+export declare function remediateError(errorLine: string, entityType: string, entityId: string): RemediationResult;
+/**
+ * Parse a multi-line validation output (e.g. from store-cli validate or
+ * validate-store --dry-run) into individual error lines and return
+ * remediation for each.
+ *
+ * @param output    Raw multi-line output from validation tool.
+ * @param entityType Override entity type (inferred from output if not provided).
+ * @returns         Array of { errorLine, remediation } objects.
+ */
+export declare function remediateValidationOutput(output: string, entityType?: string): Array<{
+    errorLine: string;
+    remediation: RemediationResult;
+}>;
+/**
+ * Format a block message for a write-guard violation, appending remediation hints.
+ * Used by hook-dispatcher.ts for store-cli intercept blocks.
+ *
+ * @param rawReason  The raw reason string from validateStoreCLIPayload or checkWriteGuard.
+ * @param entityType  The entity type if known.
+ * @param entityId   The entity ID if known.
+ * @returns          Enhanced reason string with remediation hints appended.
+ */
+export declare function enhanceBlockMessage(rawReason: string, entityType?: string, entityId?: string): string;
+export {};

package/dist/extensions/forgecli/lib/store-error-remediation.js

@@ -0,0 +1,298 @@
+// Store-error remediation — forge-cli#24
+//
+// Shared remediation-hint surface for store validation errors.
+// Consumed by:
+//   - health-check.ts (per-error row in store-integrity output)
+//   - hooks/write-guard.ts (block-message body for schema violations)
+//   - hook-dispatcher.ts (store-cli intercept block messages)
+//   - store-validator.ts (structured result for hook callers)
+//
+// Error sources:
+//   1. validate.js (in-process via write-guard) — produces error strings like:
+//        "status: value "verified" not in [reported, triaged, in-progress, fixed]"
+//        "taskId: missing required field"
+//        "xyz: undeclared field"
+//   2. store-cli.cjs validate (subprocess via store-validator.ts) — same format,
+//      piped through stderr.
+//   3. validate-store.cjs --dry-run (subprocess via health-check.ts) — lines like:
+//        "ERROR  FORGE-S18-T02: status: value "verified" not in [reported, triaged, ...]"
+//        "WARN   FORGE-S18-T02: ..."
+//
+// This module parses those formats and returns a one-line user-facing hint
+// plus an optional copy-pasteable store-cli command.
+// ── Entity-type inference from entity name / ID ────────────────────────────────
+/** Map entity type to the corresponding schema's status enum values. */
+const STATUS_ENUMS = {
+    task: [
+        "draft", "planned", "plan-approved", "implementing", "implemented",
+        "review-approved", "approved", "committed", "plan-revision-required",
+        "code-revision-required", "blocked", "escalated", "abandoned",
+    ],
+    sprint: [
+        "planning", "active", "completed", "retrospective-done",
+        "partially-completed", "blocked", "abandoned",
+    ],
+    bug: ["reported", "triaged", "in-progress", "fixed"],
+    feature: ["proposed", "accepted", "in-progress", "delivered", "declined"],
+    event: [], // no status field
+};
+/** Known entity types that support write via store-cli. */
+const ENTITY_TYPES = new Set(["task", "sprint", "bug", "feature", "event"]);
+/**
+ * Infer the entity type from an entity name/ID string.
+ * Returns "task" as default if no match.
+ */
+export function inferEntityType(entity) {
+    const lower = entity.toLowerCase();
+    // Bug patterns: BUG-015, FORGE-BUG-015, bug-031
+    if (/\bbug/i.test(entity))
+        return "bug";
+    // Sprint patterns: S18 (standalone), sprint-01 — but NOT inside task IDs like FORGE-S18-T02
+    if (/^[A-Z]+-S\d+$/i.test(entity) || /\bsprint/i.test(entity))
+        return "sprint";
+    // Feature patterns: FORGE-F01
+    if (/\bf\d+\b/i.test(entity) || lower.includes("feat"))
+        return "feature";
+    // Event patterns
+    if (lower.includes("event"))
+        return "event";
+    // Task IDs: FORGE-S18-T02, PROJECT-T01
+    if (/\bt\d+\b/i.test(entity))
+        return "task";
+    // Default
+    return "task";
+}
+const STATUS_REMEDIATION = {
+    hint: "Set status to one of the legal values for this entity type.",
+    command: (entityType, entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" update-status ${entityType} ${entityId} status <legal-value>`,
+};
+const REQUIRED_FIELD_REMEDIATION = {
+    hint: "Add the missing field with a valid value. Use the template command to see the canonical shape.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+};
+const UNDECLARED_FIELD_REMEDIATION = {
+    hint: "Remove the undeclared field, or check the schema for the correct property name.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const TYPE_MISMATCH_REMEDIATION = {
+    hint: "Use the correct type for this field. Use the describe command to see the expected type.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const PATTERN_REMEDIATION = {
+    hint: "The value must match the expected pattern (e.g. a date-time or ID format).",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const DATE_TIME_REMEDIATION = {
+    hint: "Use an ISO 8601 date-time string (e.g. 2026-05-21T12:00:00Z).",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const LENGTH_REMEDIATION = {
+    hint: "Adjust the value length to satisfy the schema constraint.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+/**
+ * Parse a single validation error line from validate.js / store-cli.
+ *
+ * Examples:
+ *   'status: value "verified" not in [reported, triaged, in-progress, fixed]'
+ *   'taskId: missing required field'
+ *   'xyz: undeclared field'
+ *   'sprintId: expected string, got number'
+ *   'title: value length 0 is below minLength 1'
+ *   'createdAt: value "today" is not a valid date-time'
+ *   'prefix: value "AB" does not match pattern ^[A-Z]+-[A-Z]$'
+ */
+export function parseValidationError(line) {
+    // Enum violation: 'field: value "X" not in [a, b, c]'
+    const enumMatch = line.match(/^(\w+):\s+value\s+"([^"]+)"\s+not in \[([^\]]+)\]/);
+    if (enumMatch) {
+        return {
+            field: enumMatch[1],
+            errorKind: "enum",
+            observed: enumMatch[2],
+            enumValues: enumMatch[3].split(",").map((s) => s.trim()),
+        };
+    }
+    // Required field: 'field: missing required field'
+    if (/\bmissing required field\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "required" };
+    }
+    // Undeclared field: 'xyz: undeclared field'
+    if (/\bundeclared field\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "undeclared" };
+    }
+    // Type mismatch: 'field: expected string, got number'
+    const typeMatch = line.match(/^(\w+):\s+expected\s+\S+,?\s+got\s+\S+/);
+    if (typeMatch) {
+        return { field: typeMatch[1], errorKind: "type" };
+    }
+    // Date-time format: 'field: value "..." is not a valid date-time'
+    if (/\bis not a valid date-time\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "datetime" };
+    }
+    // Pattern mismatch: 'field: value "..." does not match pattern ...'
+    if (/\bdoes not match pattern\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "pattern" };
+    }
+    // Length violations
+    if (/\blength\b.*\b(exceeds|below)\b/.test(line) || /\b(exceeds|below)\b.*\blength\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "length" };
+    }
+    // Generic: capture leading field name if present
+    const genericMatch = line.match(/^(\w+):/);
+    return { field: genericMatch?.[1] ?? "unknown", errorKind: "other" };
+}
+// ── Public API ──────────────────────────────────────────────────────────────────
+/**
+ * Given a single validation error line (from validate.js or store-cli),
+ * return a user-facing remediation hint and optional copy-pasteable command.
+ *
+ * @param errorLine  A single error line from validate.js / store-cli output.
+ * @param entityType  The entity type (task, sprint, bug, feature, event).
+ * @param entityId   The entity ID (e.g. "FORGE-S18-T02") — used for commands.
+ * @returns          RemediationResult with hint and command.
+ */
+export function remediateError(errorLine, entityType, entityId) {
+    const parsed = parseValidationError(errorLine);
+    switch (parsed.errorKind) {
+        case "enum": {
+            const legalValues = STATUS_ENUMS[entityType] ?? parsed.enumValues ?? [];
+            const isStatusField = parsed.field === "status" || parsed.field.toLowerCase().includes("status");
+            if (isStatusField && legalValues.length > 0) {
+                return {
+                    hint: `"${parsed.observed}" is not a legal ${entityType} status. Legal values: ${legalValues.join(", ")}.`,
+                    command: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status ${entityType} ${entityId} status <${legalValues.join("|")}>`,
+                };
+            }
+            if (legalValues.length > 0) {
+                return {
+                    hint: `Invalid value for "${parsed.field}". Allowed: ${legalValues.join(", ")}.`,
+                    command: `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+                };
+            }
+            return {
+                hint: STATUS_REMEDIATION.hint,
+                command: STATUS_REMEDIATION.command(entityType, entityId),
+            };
+        }
+        case "required":
+            return {
+                hint: REQUIRED_FIELD_REMEDIATION.hint,
+                command: REQUIRED_FIELD_REMEDIATION.command(entityType, entityId),
+            };
+        case "undeclared":
+            return {
+                hint: UNDECLARED_FIELD_REMEDIATION.hint,
+                command: UNDECLARED_FIELD_REMEDIATION.command(entityType, entityId),
+            };
+        case "type":
+            return {
+                hint: TYPE_MISMATCH_REMEDIATION.hint,
+                command: TYPE_MISMATCH_REMEDIATION.command(entityType, entityId),
+            };
+        case "datetime":
+            return {
+                hint: DATE_TIME_REMEDIATION.hint,
+                command: DATE_TIME_REMEDIATION.command(entityType, entityId),
+            };
+        case "pattern":
+            return {
+                hint: PATTERN_REMEDIATION.hint,
+                command: PATTERN_REMEDIATION.command(entityType, entityId),
+            };
+        case "length":
+            return {
+                hint: LENGTH_REMEDIATION.hint,
+                command: LENGTH_REMEDIATION.command(entityType, entityId),
+            };
+        case "other":
+        default:
+            return {
+                hint: "Check the schema for the expected shape.",
+                command: `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+            };
+    }
+}
+/**
+ * Parse a multi-line validation output (e.g. from store-cli validate or
+ * validate-store --dry-run) into individual error lines and return
+ * remediation for each.
+ *
+ * @param output    Raw multi-line output from validation tool.
+ * @param entityType Override entity type (inferred from output if not provided).
+ * @returns         Array of { errorLine, remediation } objects.
+ */
+export function remediateValidationOutput(output, entityType) {
+    const lines = output
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    const results = [];
+    for (const line of lines) {
+        // Strip "ERROR" / "WARN" prefix from validate-store --dry-run output
+        const cleaned = line.replace(/^(ERROR|WARN)\s+/, "");
+        if (!cleaned)
+            continue;
+        // Extract entity ID from lines like "FORGE-S18-T02: status: ..."
+        const entityIdMatch = cleaned.match(/^([A-Z]+-S?\d+-T?\d+|[A-Z]+-BUG-\d+|[A-Z]+-F\d+):/);
+        const entityId = entityIdMatch?.[1] ?? "unknown";
+        // If entity type not overridden, try to infer
+        const inferredType = entityType ?? inferEntityType(entityId);
+        // Skip non-error lines (hint lines from validate.js, blank lines, etc.)
+        if (cleaned.startsWith("(") || cleaned.startsWith("hint:") || cleaned.startsWith("#")) {
+            continue;
+        }
+        // Skip lines that are just an entity name without an error field
+        // (the real error is on the same line after the entity prefix)
+        const errorPart = entityIdMatch ? cleaned.slice(entityIdMatch[0].length).trim() : cleaned;
+        if (!errorPart || errorPart.length < 3)
+            continue;
+        results.push({
+            errorLine: cleaned,
+            remediation: remediateError(errorPart, inferredType, entityId),
+        });
+    }
+    return results;
+}
+/**
+ * Format a block message for a write-guard violation, appending remediation hints.
+ * Used by hook-dispatcher.ts for store-cli intercept blocks.
+ *
+ * @param rawReason  The raw reason string from validateStoreCLIPayload or checkWriteGuard.
+ * @param entityType  The entity type if known.
+ * @param entityId   The entity ID if known.
+ * @returns          Enhanced reason string with remediation hints appended.
+ */
+export function enhanceBlockMessage(rawReason, entityType, entityId) {
+    // Parse the raw reason into lines and try to add remediation to each error line.
+    const lines = rawReason.split("\n");
+    const enhanced = [];
+    for (const line of lines) {
+        // Strip leading list markers and bullet points
+        const stripped = line.replace(/^\s*[-•]\s*/, "").trim();
+        // Check if this line contains a recognizable validation error pattern
+        const parsed = parseValidationError(stripped);
+        // Also match lines that contain validation error patterns not caught by parseValidationError
+        const hasKnownError = parsed.errorKind !== "other" || /\bmissing required\b|\bnot in \[|\bundeclared\b|\bexpected\b.*\bgot\b/.test(stripped);
+        if (hasKnownError) {
+            const type = entityType ?? "task";
+            const id = entityId ?? "unknown";
+            const remediation = remediateError(stripped, type, id);
+            enhanced.push(line);
+            enhanced.push(`  💡 ${remediation.hint}`);
+            if (remediation.command) {
+                enhanced.push(`  → ${remediation.command}`);
+            }
+        }
+        else {
+            enhanced.push(line);
+        }
+    }
+    return enhanced.join("\n");
+}
+//# sourceMappingURL=store-error-remediation.js.map

package/dist/extensions/forgecli/lib/store-error-remediation.js.map

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

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

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface ParsedMaterializeArgs {
+    mode: "all" | "single-workflow";
+    workflowId?: string;
+}
+/**
+ * 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 declare function parseMaterializeArgs(args: string): ParsedMaterializeArgs;
+export declare function registerMaterialize(pi: ExtensionAPI): void;

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;