@entelligentsia/forgecli 1.0.25 → 1.0.36

package/dist/extensions/forgecli/init-context.js

@@ -0,0 +1,178 @@
+// init-context.ts — project-name discovery, project-context.json construction,
+// and calibration baseline computation for /forge:init.
+//
+// Per INIT_PARITY_SPEC.md §9 and PLAN.md Phase C.
+// Iron Law 6: no shell-string interpolation.
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ── Project name discovery ─────────────────────────────────────────────────
+/**
+ * Discover project name from package.json:name, falling back to cwd basename.
+ *
+ * Tries to read <cwd>/package.json and parse the `name` field. If the file is
+ * absent, malformed, or missing the name field, returns `path.basename(cwd)`.
+ */
+export function discoverProjectName(cwd) {
+    const pkgPath = path.join(cwd, "package.json");
+    try {
+        const raw = fs.readFileSync(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        if (pkg &&
+            typeof pkg === "object" &&
+            "name" in pkg &&
+            typeof pkg.name === "string") {
+            const name = pkg.name;
+            if (name.trim())
+                return name.trim();
+        }
+    }
+    catch {
+        // ENOENT or JSON parse error — fall through to basename
+    }
+    return path.basename(cwd);
+}
+/**
+ * Build a ProjectContext from discovery results and forge config.
+ *
+ * Merges discoveryResults with config data. Config project.name/prefix take
+ * precedence over discovery if both are present (config was set interactively).
+ */
+export function buildProjectContext(discoveryResults, config) {
+    const name = config.project?.name ?? discoveryResults.projectName ?? "";
+    const prefix = config.project?.prefix ?? discoveryResults.prefix ?? "";
+    const ctx = {
+        project: {
+            name,
+            prefix,
+        },
+    };
+    if (discoveryResults.description) {
+        ctx.project.description = discoveryResults.description;
+    }
+    if (discoveryResults.stack && discoveryResults.stack.length > 0) {
+        ctx.project.stack = discoveryResults.stack;
+    }
+    const testCmd = discoveryResults.testCommand ?? "";
+    const buildCmd = discoveryResults.buildCommand ?? "";
+    const lintCmd = discoveryResults.lintCommand ?? "";
+    if (testCmd || buildCmd) {
+        ctx.project.commands = {
+            ...(testCmd ? { test: testCmd } : {}),
+            ...(buildCmd ? { build: buildCmd } : {}),
+        };
+    }
+    const hasArch = discoveryResults.backendFramework ??
+        discoveryResults.frontendFramework ??
+        discoveryResults.database ??
+        discoveryResults.deployment ??
+        discoveryResults.dataAccess;
+    if (hasArch) {
+        ctx.architecture = {};
+        const frameworks = {};
+        if (discoveryResults.backendFramework)
+            frameworks.backend = discoveryResults.backendFramework;
+        if (discoveryResults.frontendFramework)
+            frameworks.frontend = discoveryResults.frontendFramework;
+        if (discoveryResults.database)
+            frameworks.database = discoveryResults.database;
+        if (Object.keys(frameworks).length > 0)
+            ctx.architecture.frameworks = frameworks;
+        if (discoveryResults.dataAccess)
+            ctx.architecture.dataAccess = discoveryResults.dataAccess;
+        if (discoveryResults.deployment)
+            ctx.architecture.deployment = discoveryResults.deployment;
+    }
+    const hasWorkflow = testCmd || lintCmd || buildCmd;
+    if (hasWorkflow) {
+        ctx.workflow = {
+            ...(testCmd ? { testCommand: testCmd } : {}),
+            ...(lintCmd ? { lintCommand: lintCmd } : {}),
+            ...(buildCmd ? { buildCommand: buildCmd } : {}),
+        };
+    }
+    const kbPath = discoveryResults.kbPath ?? config.paths?.engineering ?? "engineering";
+    ctx.knowledgeBase = {
+        path: kbPath,
+        indexFile: `${kbPath}/MASTER_INDEX.md`,
+    };
+    return ctx;
+}
+/**
+ * Validate a ProjectContext object structurally. Throws with a descriptive
+ * error if required fields are missing.
+ */
+export function validateProjectContext(ctx) {
+    if (!ctx || typeof ctx !== "object") {
+        throw new Error("project-context validation failed: not an object");
+    }
+    const record = ctx;
+    if (!record.project || typeof record.project !== "object") {
+        throw new Error("project-context validation failed: missing required field 'project'");
+    }
+    const project = record.project;
+    if (typeof project.name !== "string" || !project.name.trim()) {
+        throw new Error("project-context validation failed: project.name is missing or empty");
+    }
+    if (typeof project.prefix !== "string" || !project.prefix.trim()) {
+        throw new Error("project-context validation failed: project.prefix is missing or empty");
+    }
+}
+/**
+ * Write project-context.json to <cwd>/.forge/project-context.json
+ */
+export function writeProjectContext(cwd, ctx) {
+    const filePath = path.join(cwd, ".forge", "project-context.json");
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(ctx, null, 2) + "\n", "utf8");
+}
+/**
+ * Compute a calibration baseline snapshot for /forge:init Phase 2.
+ *
+ * @param cwd - project working directory
+ * @param kbPath - relative path to the knowledge base directory (e.g. "engineering")
+ * @param bundledPluginVersion - version string from package.json forge.bundledVersion
+ */
+export function computeCalibrationBaseline(cwd, kbPath, bundledPluginVersion) {
+    const baseline = {
+        lastCalibrated: new Date().toISOString(),
+        version: bundledPluginVersion,
+        masterIndexHash: null,
+        sprintsCovered: [],
+    };
+    // Compute SHA-256 of MASTER_INDEX.md if it exists
+    const masterIndexPath = path.join(cwd, kbPath, "MASTER_INDEX.md");
+    try {
+        const content = fs.readFileSync(masterIndexPath, "utf8");
+        baseline.masterIndexHash = crypto.createHash("sha256").update(content, "utf8").digest("hex");
+    }
+    catch {
+        // File not yet present — leave as null (init just started Phase 2)
+    }
+    // Collect completed sprint IDs from .forge/store/sprints/
+    // Matches the algorithm used by /forge:calibrate Step 2 auto-init branch.
+    const storeSprintsDir = path.join(cwd, ".forge", "store", "sprints");
+    try {
+        const files = fs.readdirSync(storeSprintsDir).filter((f) => f.endsWith(".json"));
+        const completedIds = [];
+        for (const f of files) {
+            try {
+                const raw = fs.readFileSync(path.join(storeSprintsDir, f), "utf8");
+                const sprint = JSON.parse(raw);
+                if (typeof sprint.sprintId === "string" &&
+                    (sprint.status === "done" || sprint.status === "retrospective-done")) {
+                    completedIds.push(sprint.sprintId);
+                }
+            }
+            catch {
+                // Skip malformed sprint file
+            }
+        }
+        baseline.sprintsCovered = completedIds.sort();
+    }
+    catch {
+        // Store sprints dir not yet created — leave as []
+    }
+    return baseline;
+}
+//# sourceMappingURL=init-context.js.map

package/dist/extensions/forgecli/init-context.js.map

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

package/dist/extensions/forgecli/init-progress.d.ts

@@ -0,0 +1,39 @@
+/** Canonical progress record written to .forge/init-progress.json */
+export interface InitProgress {
+    lastPhase: 1 | 2 | 3 | 4;
+    timestamp: string;
+}
+export type ReadProgressResult = {
+    kind: "none";
+} | {
+    kind: "stale";
+    reason: string;
+} | {
+    kind: "malformed";
+} | {
+    kind: "valid";
+    progress: InitProgress;
+};
+/**
+ * Read the init-progress checkpoint file.
+ *
+ * Returns:
+ *   - `{ kind: "none" }` — file does not exist
+ *   - `{ kind: "malformed" }` — file exists but JSON parse failed
+ *   - `{ kind: "stale", reason }` — file is a legacy 12-phase checkpoint
+ *   - `{ kind: "valid", progress }` — clean 4-phase checkpoint
+ */
+export declare function readInitProgress(cwd: string): ReadProgressResult;
+/**
+ * Write a progress checkpoint. Called at the end of each completed phase.
+ *
+ * @param cwd - project working directory
+ * @param lastPhase - completed phase number (1, 2, or 3; 4 is written then deleted)
+ * @param timestamp - ISO 8601 timestamp; defaults to now
+ */
+export declare function writeInitProgress(cwd: string, lastPhase: 1 | 2 | 3 | 4, timestamp?: string): void;
+/**
+ * Delete the init-progress checkpoint. Called at the end of Phase 4
+ * to signal successful completion.
+ */
+export declare function deleteInitProgress(cwd: string): void;

package/dist/extensions/forgecli/init-progress.js

@@ -0,0 +1,117 @@
+// init-progress.ts — read/write/delete .forge/init-progress.json
+//
+// Tracks the last completed phase of /forge:init so the command can resume
+// after an interrupted run. Implements stale-checkpoint detection to handle
+// legacy 12-phase checkpoint files from old forge plugin versions.
+//
+// Per INIT_PARITY_SPEC.md §4 and PLAN.md Phase B.
+import * as fs from "node:fs";
+import * as path from "node:path";
+const PROGRESS_FILENAME = ".forge/init-progress.json";
+function progressPath(cwd) {
+    return path.join(cwd, PROGRESS_FILENAME);
+}
+/**
+ * Read the init-progress checkpoint file.
+ *
+ * Returns:
+ *   - `{ kind: "none" }` — file does not exist
+ *   - `{ kind: "malformed" }` — file exists but JSON parse failed
+ *   - `{ kind: "stale", reason }` — file is a legacy 12-phase checkpoint
+ *   - `{ kind: "valid", progress }` — clean 4-phase checkpoint
+ */
+export function readInitProgress(cwd) {
+    const filePath = progressPath(cwd);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT")
+            return { kind: "none" };
+        // Unreadable — treat as missing
+        return { kind: "none" };
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+    if (!obj || typeof obj !== "object") {
+        return { kind: "malformed" };
+    }
+    const record = obj;
+    // Stale detection per spec §4:
+    // - lastPhase > 4 → old 12-phase run
+    // - contains "mode" key → old format
+    // - contains "phase-7-substep-map" key → old format
+    // - missing "timestamp" → corrupt / incomplete write
+    if ("mode" in record) {
+        return { kind: "stale", reason: 'contains "mode" field (legacy 12-phase format)' };
+    }
+    if ("phase-7-substep-map" in record) {
+        return { kind: "stale", reason: 'contains "phase-7-substep-map" field (legacy 12-phase format)' };
+    }
+    if (!("timestamp" in record)) {
+        return { kind: "stale", reason: 'missing "timestamp" field' };
+    }
+    const lastPhase = record.lastPhase;
+    if (typeof lastPhase !== "number" || !Number.isInteger(lastPhase)) {
+        return { kind: "malformed" };
+    }
+    if (lastPhase > 4) {
+        return { kind: "stale", reason: `lastPhase=${lastPhase} > 4 (legacy 12-phase run)` };
+    }
+    if (lastPhase < 1) {
+        return { kind: "malformed" };
+    }
+    const timestamp = record.timestamp;
+    if (typeof timestamp !== "string") {
+        return { kind: "malformed" };
+    }
+    return {
+        kind: "valid",
+        progress: {
+            lastPhase: lastPhase,
+            timestamp,
+        },
+    };
+}
+/**
+ * Write a progress checkpoint. Called at the end of each completed phase.
+ *
+ * @param cwd - project working directory
+ * @param lastPhase - completed phase number (1, 2, or 3; 4 is written then deleted)
+ * @param timestamp - ISO 8601 timestamp; defaults to now
+ */
+export function writeInitProgress(cwd, lastPhase, timestamp) {
+    const record = {
+        lastPhase,
+        timestamp: timestamp ?? new Date().toISOString(),
+    };
+    const filePath = progressPath(cwd);
+    // Ensure .forge/ dir exists before writing
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(record, null, 2) + "\n", "utf8");
+}
+/**
+ * Delete the init-progress checkpoint. Called at the end of Phase 4
+ * to signal successful completion.
+ */
+export function deleteInitProgress(cwd) {
+    const filePath = progressPath(cwd);
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch (err) {
+        const e = err;
+        // ENOENT is fine — file may not exist if phase was aborted before first write
+        if (e.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=init-progress.js.map

package/dist/extensions/forgecli/init-progress.js.map

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

package/dist/extensions/forgecli/input-router.d.ts

@@ -0,0 +1,33 @@
+export type RouterResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+export type RouterListener = (data: string) => RouterResult;
+export interface RegisterOptions {
+    /** Stable name for debugging and unsubscription tracking. */
+    name: string;
+    /** When true, this listener is bypassed while any overlay is active.
+     *  Use for keys that "activate" a widget (e.g. ↓ to open a strip) — the
+     *  overlay needs the same key for navigation. Default: false. */
+    skipWhenOverlayActive?: boolean;
+}
+export declare class ForgeInputRouter {
+    private listeners;
+    private overlayDepth;
+    register(listener: RouterListener, opts: RegisterOptions): () => void;
+    pushOverlay(): void;
+    popOverlay(): void;
+    isOverlayActive(): boolean;
+    /**
+     * Mirrors pi's listener-chain semantics (tui.ts:544-560):
+     * - Each listener may return { consume: true } to stop dispatch.
+     * - Each listener may return { data: rewritten } to alter the value the
+     *   next listener (and ultimately the focused overlay) sees.
+     * - Listeners flagged skipWhenOverlayActive=true are silently bypassed
+     *   whenever overlayDepth > 0.
+     */
+    dispatch(data: string): RouterResult;
+}
+export declare function getInputRouter(): ForgeInputRouter;
+/** Test helper — replace the singleton with a fresh router. */
+export declare function __resetInputRouterForTesting(): void;

package/dist/extensions/forgecli/input-router.js

@@ -0,0 +1,136 @@
+// Centralised onTerminalInput dispatch for forge-cli.
+//
+// Plan 16 Slice 4c. Pi-mono's `ctx.ui.onTerminalInput` lets any extension hook
+// raw stdin, with the first consumer winning. Pi runs listeners BEFORE
+// routing to the focused overlay (pi-mono/packages/tui/src/tui.ts:544-560).
+// That made forge-cli's two existing arrow-activator listeners
+// (thread-switcher, whats-new-widget) silently eat ↑/↓ when the config TUI was
+// mounted as an overlay.
+//
+// This router gives forge-cli a single pi listener whose dispatch is
+// overlay-aware: listeners flagged `skipWhenOverlayActive: true` are bypassed
+// whenever an overlay has been registered via `pushOverlay()`. Other listeners
+// (critical hotkeys, theme switchers, etc.) still run.
+//
+// Wiring:
+//   1. index.ts session_start: `ctx.ui.onTerminalInput((d) => router.dispatch(d))`.
+//   2. Each consumer: `router.register(listener, { name, skipWhenOverlayActive })`.
+//   3. Each overlay mounter: `router.pushOverlay()` before ctx.ui.custom,
+//      `popOverlay()` in a finally.
+//
+// Debug logging (when FORGE_DEBUG_INPUT=1):
+//   Each dispatch + push/pop is logged with timestamp + listener name +
+//   overlay depth + raw byte sequence (hex-escaped). Default target:
+//   /tmp/forge-input-router.log. Override with FORGE_DEBUG_INPUT_LOG=<path>.
+//   Logging goes through fs.appendFileSync — synchronous so events are
+//   captured even when the process crashes mid-render.
+import * as fs from "node:fs";
+function debugEnabled() {
+    return process.env.FORGE_DEBUG_INPUT === "1";
+}
+function debugLogPath() {
+    return process.env.FORGE_DEBUG_INPUT_LOG ?? "/tmp/forge-input-router.log";
+}
+function hexEscape(s) {
+    // Render printable ASCII as-is, escape everything else as \xNN. Helps spot
+    // arrow sequences (\x1b[A etc.) and Kitty-protocol variants at a glance.
+    return [...s]
+        .map((c) => {
+        const cp = c.codePointAt(0);
+        if (cp >= 0x20 && cp <= 0x7e)
+            return c;
+        return `\\x${cp.toString(16).padStart(2, "0")}`;
+    })
+        .join("");
+}
+function logEvent(line) {
+    if (!debugEnabled())
+        return;
+    try {
+        const ts = new Date().toISOString();
+        fs.appendFileSync(debugLogPath(), `${ts} ${line}\n`);
+    }
+    catch {
+        // Logging must never crash the host; failure to write is silently ignored.
+    }
+}
+export class ForgeInputRouter {
+    listeners = [];
+    overlayDepth = 0;
+    register(listener, opts) {
+        const entry = { fn: listener, opts };
+        this.listeners.push(entry);
+        logEvent(`register name=${opts.name} skipWhenOverlayActive=${!!opts.skipWhenOverlayActive} total=${this.listeners.length}`);
+        return () => {
+            const i = this.listeners.indexOf(entry);
+            if (i >= 0) {
+                this.listeners.splice(i, 1);
+                logEvent(`unregister name=${opts.name} remaining=${this.listeners.length}`);
+            }
+        };
+    }
+    pushOverlay() {
+        this.overlayDepth++;
+        logEvent(`pushOverlay depth=${this.overlayDepth}`);
+    }
+    popOverlay() {
+        if (this.overlayDepth > 0)
+            this.overlayDepth--;
+        logEvent(`popOverlay depth=${this.overlayDepth}`);
+    }
+    isOverlayActive() {
+        return this.overlayDepth > 0;
+    }
+    /**
+     * Mirrors pi's listener-chain semantics (tui.ts:544-560):
+     * - Each listener may return { consume: true } to stop dispatch.
+     * - Each listener may return { data: rewritten } to alter the value the
+     *   next listener (and ultimately the focused overlay) sees.
+     * - Listeners flagged skipWhenOverlayActive=true are silently bypassed
+     *   whenever overlayDepth > 0.
+     */
+    dispatch(data) {
+        if (debugEnabled()) {
+            logEvent(`dispatch IN data="${hexEscape(data)}" overlayDepth=${this.overlayDepth} listeners=${this.listeners.length}`);
+        }
+        let current = data;
+        for (const entry of this.listeners) {
+            if (this.overlayDepth > 0 && entry.opts.skipWhenOverlayActive) {
+                logEvent(`  skip name=${entry.opts.name} (overlay active)`);
+                continue;
+            }
+            const result = entry.fn(current);
+            if (debugEnabled()) {
+                const r = result === undefined
+                    ? "passthrough"
+                    : `${result.consume ? "consume" : ""}${result.data !== undefined ? ` data="${hexEscape(result.data)}"` : ""}`.trim() ||
+                        "noop";
+                logEvent(`  call name=${entry.opts.name} → ${r}`);
+            }
+            if (result?.consume) {
+                logEvent(`dispatch OUT consumed-by=${entry.opts.name}`);
+                return { consume: true };
+            }
+            if (result?.data !== undefined)
+                current = result.data;
+        }
+        if (current !== data) {
+            logEvent(`dispatch OUT rewritten data="${hexEscape(current)}"`);
+            return { data: current };
+        }
+        logEvent(`dispatch OUT passthrough (focused overlay should receive)`);
+        return undefined;
+    }
+}
+// ── Module-level singleton ───────────────────────────────────────────────────
+let singleton = null;
+export function getInputRouter() {
+    if (!singleton)
+        singleton = new ForgeInputRouter();
+    return singleton;
+}
+/** Test helper — replace the singleton with a fresh router. */
+export function __resetInputRouterForTesting() {
+    singleton = null;
+}
+//# sourceMappingURL=input-router.js.map

package/dist/extensions/forgecli/input-router.js.map

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

package/dist/extensions/forgecli/lib/halt-advisor.d.ts

@@ -0,0 +1,59 @@
+import type { MergedConfig, PersonaModel } from "../config-layer.js";
+export interface UiLike {
+    notify(message: string, level?: string): void;
+}
+export interface CtxLike {
+    ui: UiLike;
+}
+export interface GateFailure {
+    phase: string;
+    reasonCode: string;
+    detail: string;
+    remediation: string;
+}
+export interface RunHaltAdvisorOptions {
+    /** Structured failure parsed from preflight-gate.cjs stdout. */
+    gateFailure: GateFailure;
+    /** Resolved advisor model (from resolveAdvisorModel). If undefined, advisor is skipped. */
+    advisorModel: PersonaModel | undefined;
+    /** Task or bug id for context. */
+    taskId: string;
+    /** Working directory. */
+    cwd: string;
+    /** Extension command context (ui + modelRegistry). */
+    ctx: CtxLike;
+    /** Optional forge root path — forwarded to runForgeSubagent. */
+    forgeRoot?: string;
+}
+/**
+ * Resolve the advisor model for halt-recovery.
+ *
+ * Priority:
+ *   1. Explicit `advisorModel` config slot from forge-cli layered config.
+ * Contract (rev. 2026-06-04): the advisor model is the HEAVY model the runtime
+ * resolves point-in-time. There is NO dedicated advisorModel config entry —
+ * "heavy" is the approve/architect slot resolved through the existing routing
+ * cascade (L4 phase override → L3/L2 project → L1 user/global → default),
+ * exactly as the approve phase itself would resolve. When the cascade bottoms
+ * out at inherit, the session's current model (pi default) is used. In the
+ * Claude Code plugin route the equivalent is the opus-class session model.
+ *
+ * Returns undefined (advisor skipped, non-fatal) only when nothing is routed
+ * AND no current model is available.
+ *
+ * (History: the original FORGE-S26-T18 implementation used a dedicated
+ * advisorModel config slot with a blind registry fallback that produced
+ * "anthropic/undefined" on the CART-S03-T01 halt — both retired.)
+ */
+export declare function resolveAdvisorModel(merged: MergedConfig, currentModel?: {
+    provider?: string;
+    model?: string;
+    id?: string;
+}, pipelineName?: string): PersonaModel | undefined;
+/**
+ * Spawn a read-only advisor subagent to explain the gate failure and guide recovery.
+ *
+ * Best-effort: errors are notified via ctx.ui but do NOT propagate. The
+ * primary halt status is the caller's responsibility to surface separately.
+ */
+export declare function runHaltAdvisor(opts: RunHaltAdvisorOptions): Promise<void>;