@entelligentsia/forgecli 0.15.0 → 0.19.0

package/dist/extensions/forgecli/lib/parsers.d.ts

@@ -0,0 +1,25 @@
+export type FrontmatterParseErrorCode = "invalid_frontmatter";
+export declare class FrontmatterParseError extends Error {
+    readonly code: FrontmatterParseErrorCode;
+    constructor(code: FrontmatterParseErrorCode, message: string);
+}
+export interface ParsedBlock {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export interface ParseOptions {
+    /** When true, supports nested (indented) block keys as in workflow frontmatter.
+     *  When false, only flat key: value pairs are parsed (persona/skill frontmatter). */
+    allowNesting: boolean;
+}
+/**
+ * Parse the YAML-like frontmatter block from a markdown string.
+ *
+ * Returns `{ frontmatter: {}, body: content }` if the content does not start with `---`.
+ * Throws `FrontmatterParseError("invalid_frontmatter", …)` on malformed input.
+ *
+ * @param content  Raw markdown string (may have CRLF line endings).
+ * @param opts     `allowNesting: false` → flat key:value only (persona/skill);
+ *                 `allowNesting: true`  → supports indented child blocks (workflow).
+ */
+export declare function parseFrontmatterBlock(content: string, opts: ParseOptions): ParsedBlock;

package/dist/extensions/forgecli/lib/parsers.js

@@ -0,0 +1,164 @@
+// lib/parsers.ts — Shared frontmatter block parser (FORGE-S25-T19).
+//
+// Provides a single `parseFrontmatterBlock(content, { allowNesting })` entry
+// point that supersedes the private `parseFrontmatter()` in
+// parsers/persona-skill-loader.ts and the private `parseWorkflowFrontmatter()`
+// in parsers/workflow-loader.ts.
+//
+// Design notes:
+//   - `parseFrontmatterBlock` throws `FrontmatterParseError` (module-local typed
+//     error). Callers catch it and re-throw as their own typed error to preserve
+//     existing error contracts without introducing circular dependencies.
+//   - Always returns `{ frontmatter, body }` for consistency regardless of
+//     `allowNesting`. Callers that do not need `body` (e.g. workflow-loader) may
+//     ignore it.
+//   - `parseInlineArray` and `stripQuotes` are private helpers for the nested
+//     YAML case.
+//
+// Iron Laws (forge-cli-engineer):
+//   IL6 — no shell-string interpolation; pure in-memory string processing.
+//   IL7 — no silent continuation; malformed input throws FrontmatterParseError.
+export class FrontmatterParseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "FrontmatterParseError";
+        this.code = code;
+    }
+}
+// --- Private helpers for nested parsing ---
+function parseInlineArray(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return null;
+    const inner = trimmed.slice(1, -1);
+    if (inner.trim() === "")
+        return [];
+    return inner
+        .split(",")
+        .map((s) => {
+        const t = s.trim();
+        if ((t.startsWith('"') && t.endsWith('"') && t.length >= 2) ||
+            (t.startsWith("'") && t.endsWith("'") && t.length >= 2)) {
+            return t.slice(1, -1);
+        }
+        return t;
+    })
+        .filter((s) => s.length > 0);
+}
+function stripQuotes(value) {
+    const v = value.trim();
+    if ((v.startsWith('"') && v.endsWith('"') && v.length >= 2) ||
+        (v.startsWith("'") && v.endsWith("'") && v.length >= 2)) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+// --- Core implementation ---
+/**
+ * Parse the YAML-like frontmatter block from a markdown string.
+ *
+ * Returns `{ frontmatter: {}, body: content }` if the content does not start with `---`.
+ * Throws `FrontmatterParseError("invalid_frontmatter", …)` on malformed input.
+ *
+ * @param content  Raw markdown string (may have CRLF line endings).
+ * @param opts     `allowNesting: false` → flat key:value only (persona/skill);
+ *                 `allowNesting: true`  → supports indented child blocks (workflow).
+ */
+export function parseFrontmatterBlock(content, opts) {
+    // Normalise CRLF for line-based parsing while preserving body reconstruction.
+    const lines = content.split(/\r?\n/);
+    if (lines.length === 0 || lines[0] !== "---") {
+        return { frontmatter: {}, body: content };
+    }
+    const fm = {};
+    let i = 1;
+    let closed = false;
+    if (!opts.allowNesting) {
+        // --- Flat parsing (persona-skill-loader behaviour) ---
+        for (; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === "---") {
+                closed = true;
+                i++;
+                break;
+            }
+            // Allow blank lines inside frontmatter.
+            if (line.trim() === "")
+                continue;
+            const m = /^([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line);
+            if (!m) {
+                throw new FrontmatterParseError("invalid_frontmatter", `Malformed frontmatter line ${i + 1}: ${JSON.stringify(line)}`);
+            }
+            const value = m[2].trim();
+            // Strip matching surrounding quotes if present.
+            let parsed = value;
+            if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+                (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
+                parsed = value.slice(1, -1);
+            }
+            fm[m[1]] = parsed;
+        }
+    }
+    else {
+        // --- Nested parsing (workflow-loader behaviour) ---
+        let currentBlock = null;
+        let blockChildren = {};
+        for (; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === "---") {
+                if (currentBlock !== null) {
+                    fm[currentBlock] = blockChildren;
+                    currentBlock = null;
+                    blockChildren = {};
+                }
+                closed = true;
+                i++;
+                break;
+            }
+            if (line.trim() === "")
+                continue;
+            // Indented line → child of current block.
+            if (/^\s/.test(line)) {
+                if (currentBlock === null) {
+                    throw new FrontmatterParseError("invalid_frontmatter", `Indented frontmatter line ${i + 1} with no parent block: ${JSON.stringify(line)}`);
+                }
+                const childMatch = /^\s+([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line);
+                if (!childMatch) {
+                    throw new FrontmatterParseError("invalid_frontmatter", `Malformed indented frontmatter line ${i + 1}: ${JSON.stringify(line)}`);
+                }
+                const childKey = childMatch[1];
+                const childRaw = childMatch[2].trim();
+                const arr = parseInlineArray(childRaw);
+                blockChildren[childKey] = arr !== null ? arr : stripQuotes(childRaw);
+                continue;
+            }
+            // Top-level key:value or bare block key.
+            const topMatch = /^([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line);
+            if (!topMatch) {
+                throw new FrontmatterParseError("invalid_frontmatter", `Malformed frontmatter line ${i + 1}: ${JSON.stringify(line)}`);
+            }
+            if (currentBlock !== null) {
+                fm[currentBlock] = blockChildren;
+                currentBlock = null;
+                blockChildren = {};
+            }
+            const key = topMatch[1];
+            const rawValue = topMatch[2].trim();
+            if (rawValue === "") {
+                currentBlock = key;
+                blockChildren = {};
+            }
+            else {
+                const arr = parseInlineArray(rawValue);
+                fm[key] = arr !== null ? arr : stripQuotes(rawValue);
+            }
+        }
+    }
+    if (!closed) {
+        throw new FrontmatterParseError("invalid_frontmatter", "Frontmatter block opened with `---` but never closed");
+    }
+    const body = lines.slice(i).join("\n");
+    return { frontmatter: fm, body };
+}
+//# sourceMappingURL=parsers.js.map

package/dist/extensions/forgecli/lib/parsers.js.map

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

package/dist/extensions/forgecli/lib/shared-fs-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns true when `p` exists and is a regular file.
+ * Returns false for directories, symlinks to directories, missing paths,
+ * and any other filesystem error.
+ */
+export declare function isFile(p: string): boolean;
+/**
+ * Returns true when `p` exists and is a directory.
+ * Returns false for regular files, missing paths, and any other filesystem
+ * error.
+ */
+export declare function isDirectory(p: string): boolean;

package/dist/extensions/forgecli/lib/shared-fs-utils.js

@@ -0,0 +1,37 @@
+// lib/shared-fs-utils.ts — shared filesystem predicates (C-16, S-3).
+//
+// Centralises the isFile / isDirectory helpers that were previously
+// duplicated as private functions in forge-root.ts and subagent/agents.ts
+// (and inlined in forge-tools.ts, store-resolver.ts, migration-engine.ts).
+//
+// Both helpers return `false` on any filesystem error (including ENOENT,
+// EACCES, ENOTDIR). Callers that need to distinguish error kinds must call
+// `fs.statSync` directly.
+import * as fs from "node:fs";
+/**
+ * Returns true when `p` exists and is a regular file.
+ * Returns false for directories, symlinks to directories, missing paths,
+ * and any other filesystem error.
+ */
+export function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns true when `p` exists and is a directory.
+ * Returns false for regular files, missing paths, and any other filesystem
+ * error.
+ */
+export function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=shared-fs-utils.js.map

package/dist/extensions/forgecli/lib/shared-fs-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-fs-utils.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/lib/shared-fs-utils.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,oEAAoE;AACpE,0EAA0E;AAC1E,2EAA2E;AAC3E,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,0BAA0B;AAE1B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,CAAS;IAC/B,IAAI,CAAC;QACJ,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS;IACpC,IAAI,CAAC;QACJ,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC"}

package/dist/extensions/forgecli/lib/spawn-store-cli.d.ts

@@ -0,0 +1,44 @@
+export interface SpawnEmitResult {
+    ok: boolean;
+    stderr: string;
+}
+export interface SpawnValidateResult {
+    ok: boolean;
+    reason: string;
+}
+/**
+ * Spawn `store-cli.cjs emit <sprintId> <event-json>` synchronously.
+ *
+ * Uses `STORE_CLI_EMIT_TIMEOUT_MS` (10 s). Fail-closed: returns ok=false on
+ * any non-zero exit or error signal.
+ *
+ * @param storeCli  Absolute path to store-cli.cjs.
+ * @param sprintId  Sprint ID string (e.g. "FORGE-S25").
+ * @param event     Event payload object; JSON.stringify'd before dispatch.
+ * @param cwd       Working directory for the subprocess.
+ */
+export declare function spawnStoreCliEmit(storeCli: string, sprintId: string, event: unknown, cwd: string): SpawnEmitResult;
+/**
+ * Spawn `store-cli.cjs read <entity> <entityId>` synchronously and parse stdout
+ * as JSON.
+ *
+ * Fail-open: returns null on non-zero exit, error signal, or JSON parse error.
+ * Callers that need fail-open semantics (like transition-guard) rely on this.
+ *
+ * @param storeCli  Absolute path to store-cli.cjs.
+ * @param entity    Entity type: "task" | "sprint" | "bug" | …
+ * @param entityId  Entity ID string.
+ * @param cwd       Working directory for the subprocess.
+ */
+export declare function spawnStoreCliRead(storeCli: string, entity: string, entityId: string, cwd: string): Record<string, unknown> | null;
+/**
+ * Spawn `store-cli.cjs validate <entity> <payload-json>` synchronously.
+ *
+ * Returns ok=false with a reason string on non-zero exit.
+ *
+ * @param storeCli  Absolute path to store-cli.cjs.
+ * @param entity    Entity type: "task" | "sprint" | "bug" | "event" | …
+ * @param payload   Payload object or pre-serialised JSON string.
+ * @param cwd       Working directory for the subprocess.
+ */
+export declare function spawnStoreCliValidate(storeCli: string, entity: string, payload: unknown, cwd: string): SpawnValidateResult;

package/dist/extensions/forgecli/lib/spawn-store-cli.js

@@ -0,0 +1,93 @@
+// lib/spawn-store-cli.ts — FORGE-S25-T17 (C-1, C-17, N-C-A)
+//
+// Centralised wrappers for the three store-cli.cjs spawn patterns used across
+// forge-cli. Replaces inline spawnSync calls in:
+//   - transition-guard.ts  (read)
+//   - store-validator.ts   (validate)
+//   - friction-emit.ts     (emit)
+//   - skill-retriever.ts   (emit)
+//   - skill-usage-tracker.ts (emit)
+//
+// Iron Law IL6 compliance: every external call uses argv arrays — no shell
+// string interpolation.
+//
+// Timeout discipline (N-C-A): emit calls use STORE_CLI_EMIT_TIMEOUT_MS so
+// the three previous callers that were missing timeouts now carry them.
+import { spawnSync } from "node:child_process";
+import { STORE_CLI_TIMEOUT_MS, STORE_CLI_EMIT_TIMEOUT_MS } from "./store-cli-timeouts.js";
+// ---------------------------------------------------------------------------
+// spawnStoreCliEmit
+// ---------------------------------------------------------------------------
+/**
+ * Spawn `store-cli.cjs emit <sprintId> <event-json>` synchronously.
+ *
+ * Uses `STORE_CLI_EMIT_TIMEOUT_MS` (10 s). Fail-closed: returns ok=false on
+ * any non-zero exit or error signal.
+ *
+ * @param storeCli  Absolute path to store-cli.cjs.
+ * @param sprintId  Sprint ID string (e.g. "FORGE-S25").
+ * @param event     Event payload object; JSON.stringify'd before dispatch.
+ * @param cwd       Working directory for the subprocess.
+ */
+export function spawnStoreCliEmit(storeCli, sprintId, event, cwd) {
+    const result = spawnSync(process.execPath, [storeCli, "emit", sprintId, JSON.stringify(event)], { cwd, encoding: "utf8", timeout: STORE_CLI_EMIT_TIMEOUT_MS });
+    if (result.status !== 0 || result.error) {
+        const stderr = (typeof result.stderr === "string" ? result.stderr : "") ||
+            result.error?.message ||
+            `store-cli emit exited ${String(result.status)}`;
+        return { ok: false, stderr };
+    }
+    return { ok: true, stderr: "" };
+}
+// ---------------------------------------------------------------------------
+// spawnStoreCliRead
+// ---------------------------------------------------------------------------
+/**
+ * Spawn `store-cli.cjs read <entity> <entityId>` synchronously and parse stdout
+ * as JSON.
+ *
+ * Fail-open: returns null on non-zero exit, error signal, or JSON parse error.
+ * Callers that need fail-open semantics (like transition-guard) rely on this.
+ *
+ * @param storeCli  Absolute path to store-cli.cjs.
+ * @param entity    Entity type: "task" | "sprint" | "bug" | …
+ * @param entityId  Entity ID string.
+ * @param cwd       Working directory for the subprocess.
+ */
+export function spawnStoreCliRead(storeCli, entity, entityId, cwd) {
+    try {
+        const result = spawnSync(process.execPath, [storeCli, "read", entity, entityId], { cwd, encoding: "utf8", timeout: STORE_CLI_TIMEOUT_MS });
+        if (result.status !== 0 || result.error)
+            return null;
+        const stdout = typeof result.stdout === "string" ? result.stdout : String(result.stdout);
+        return JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// spawnStoreCliValidate
+// ---------------------------------------------------------------------------
+/**
+ * Spawn `store-cli.cjs validate <entity> <payload-json>` synchronously.
+ *
+ * Returns ok=false with a reason string on non-zero exit.
+ *
+ * @param storeCli  Absolute path to store-cli.cjs.
+ * @param entity    Entity type: "task" | "sprint" | "bug" | "event" | …
+ * @param payload   Payload object or pre-serialised JSON string.
+ * @param cwd       Working directory for the subprocess.
+ */
+export function spawnStoreCliValidate(storeCli, entity, payload, cwd) {
+    const payloadStr = typeof payload === "string" ? payload : JSON.stringify(payload);
+    const result = spawnSync(process.execPath, [storeCli, "validate", entity, payloadStr], { encoding: "utf8", cwd, timeout: STORE_CLI_TIMEOUT_MS });
+    if (result.status !== 0 || result.error) {
+        const reason = result.stderr?.trim() ||
+            result.error?.message ||
+            `store-cli validate exited ${String(result.status)}`;
+        return { ok: false, reason };
+    }
+    return { ok: true, reason: "" };
+}
+//# sourceMappingURL=spawn-store-cli.js.map

package/dist/extensions/forgecli/lib/spawn-store-cli.js.map

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

package/dist/extensions/forgecli/lib/state-helpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Read a JSON state file from disk.
+ * Returns null if the file does not exist or cannot be parsed.
+ */
+export declare function readJsonState<T>(filePath: string): T | null;
+/**
+ * Write a JSON state file to disk, creating intermediate directories as needed.
+ */
+export declare function writeJsonState<T>(filePath: string, data: T): void;
+/**
+ * Returns true if a saved-at timestamp is older than maxAgeMs (default: 7 days).
+ */
+export declare function isStateStale(savedAt: string, maxAgeMs?: number): boolean;
+/** Minimal interface shared by task state. Full interface in run-task.ts. */
+export interface TaskStateBase {
+    taskId: string;
+    savedAt: string;
+}
+/**
+ * Build the canonical state file path for a run-task session.
+ * Exported so run-task.ts can use it without duplicating the path logic.
+ */
+export declare function taskStateFilePath(cwd: string, taskId: string): string;
+/** Minimal interface shared by sprint state. Full interface in run-sprint.ts. */
+export interface SprintStateBase {
+    sprintId: string;
+    savedAt: string;
+}
+/**
+ * Build the canonical state file path for a run-sprint session.
+ * Exported so run-sprint.ts can use it without duplicating the path logic.
+ */
+export declare function sprintStateFilePath(cwd: string, sprintId: string): string;

package/dist/extensions/forgecli/lib/state-helpers.js

@@ -0,0 +1,69 @@
+// lib/state-helpers.ts — FORGE-S25-T16
+//
+// Centralizes the orchestrator session-state helpers for /forge:run-task and
+// /forge:run-sprint. Addresses finding N-H-B (Pass-3): naming divergence across
+// run-task.ts (readState/writeState), run-sprint.ts (readSprintState/writeSprintState).
+//
+// Design decisions per review-plan approval (2026-05-23):
+//   - Bug-state helpers (readBugState, writeBugState, deleteBugState) remain in
+//     fix-bug.ts ONLY. Exporting them here would create a circular dep:
+//     fix-bug.ts → lib/state-helpers.ts → fix-bug.ts.
+//   - run-sprint.ts continues to import readState/writeState from run-task.ts
+//     (no import-path change needed). run-task.ts delegates to this lib internally.
+//   - lib/state-helpers.ts has no imports from handler files — clean dependency direction.
+//
+// Task state  — .forge/cache/run-task-state-{taskId}.json
+// Sprint state — .forge/cache/run-sprint-state-{sprintId}.json
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ──────────────────────────────────────────────────────────────────────────────
+// Shared utilities
+// ──────────────────────────────────────────────────────────────────────────────
+/** Seven days in milliseconds — default staleness window for state files. */
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Read a JSON state file from disk.
+ * Returns null if the file does not exist or cannot be parsed.
+ */
+export function readJsonState(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return null;
+        const raw = fs.readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a JSON state file to disk, creating intermediate directories as needed.
+ */
+export function writeJsonState(filePath, data) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf8");
+}
+/**
+ * Returns true if a saved-at timestamp is older than maxAgeMs (default: 7 days).
+ */
+export function isStateStale(savedAt, maxAgeMs = SEVEN_DAYS_MS) {
+    const savedAtMs = new Date(savedAt).getTime();
+    const ageMs = Date.now() - savedAtMs;
+    return ageMs > maxAgeMs;
+}
+/**
+ * Build the canonical state file path for a run-task session.
+ * Exported so run-task.ts can use it without duplicating the path logic.
+ */
+export function taskStateFilePath(cwd, taskId) {
+    return path.join(cwd, ".forge", "cache", `run-task-state-${taskId}.json`);
+}
+/**
+ * Build the canonical state file path for a run-sprint session.
+ * Exported so run-sprint.ts can use it without duplicating the path logic.
+ */
+export function sprintStateFilePath(cwd, sprintId) {
+    return path.join(cwd, ".forge", "cache", `run-sprint-state-${sprintId}.json`);
+}
+//# sourceMappingURL=state-helpers.js.map

package/dist/extensions/forgecli/lib/state-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-helpers.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/lib/state-helpers.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,wFAAwF;AACxF,EAAE;AACF,0DAA0D;AAC1D,gFAAgF;AAChF,wEAAwE;AACxE,sDAAsD;AACtD,8EAA8E;AAC9E,oFAAoF;AACpF,2FAA2F;AAC3F,EAAE;AACF,0DAA0D;AAC1D,+DAA+D;AAE/D,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,iFAAiF;AACjF,mBAAmB;AACnB,iFAAiF;AAEjF,6EAA6E;AAC7E,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAI,QAAgB;IAChD,IAAI,CAAC;QACJ,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAI,QAAgB,EAAE,IAAO;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AACnE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAQ,GAAG,aAAa;IACrE,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACrC,OAAO,KAAK,GAAG,QAAQ,CAAC;AACzB,CAAC;AAYD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,MAAc;IAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,MAAM,OAAO,CAAC,CAAC;AAC3E,CAAC;AAYD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,QAAgB;IAChE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,oBAAoB,QAAQ,OAAO,CAAC,CAAC;AAC/E,CAAC"}

package/dist/extensions/forgecli/lib/store-cli-timeouts.d.ts

@@ -0,0 +1,4 @@
+/** Default timeout (ms) for store-cli read / validate / update-status calls. */
+export declare const STORE_CLI_TIMEOUT_MS = 10000;
+/** Timeout (ms) for store-cli emit calls (event emission). */
+export declare const STORE_CLI_EMIT_TIMEOUT_MS = 10000;

package/dist/extensions/forgecli/lib/store-cli-timeouts.js

@@ -0,0 +1,10 @@
+// lib/store-cli-timeouts.ts — FORGE-S25-T17 (N-C-A)
+//
+// Named timeout constants for store-cli.cjs subprocess invocations.
+// Import these instead of using bare numeric literals so all callers
+// share a single source of truth and the value is visible in diffs.
+/** Default timeout (ms) for store-cli read / validate / update-status calls. */
+export const STORE_CLI_TIMEOUT_MS = 10_000;
+/** Timeout (ms) for store-cli emit calls (event emission). */
+export const STORE_CLI_EMIT_TIMEOUT_MS = 10_000;
+//# sourceMappingURL=store-cli-timeouts.js.map

package/dist/extensions/forgecli/lib/store-cli-timeouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-cli-timeouts.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/lib/store-cli-timeouts.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,oEAAoE;AAEpE,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C,8DAA8D;AAC9D,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC"}

package/dist/extensions/forgecli/lib/versions.d.ts

@@ -0,0 +1,56 @@
+/** Minimal shape of the forgecli `package.json`. */
+interface ForgePkg {
+    version?: string;
+    forge?: {
+        bundledVersion?: string;
+    };
+}
+/**
+ * Reads the forgecli `package.json` from the given package root.
+ * Returns `{ version: "unknown" }` on any error.
+ */
+export declare function readForgeCliPkg(pkgRoot: string): ForgePkg;
+/**
+ * Returns the forgecli package version string.
+ * Returns `"unknown"` when `package.json` cannot be read or is missing a
+ * `version` field.
+ */
+export declare function readForgeCliVersion(pkgRoot: string): string;
+/**
+ * Returns the bundled Forge plugin version.
+ *
+ * Primary source: `<pkgRoot>/dist/forge-payload/.claude-plugin/plugin.json`,
+ * regenerated by `scripts/build-payload.cjs` on every build — single source
+ * of truth that never drifts.
+ *
+ * Fallback: `package.json`'s `forge.bundledVersion` mirror (hand-maintained,
+ * used in dev / pre-build environments).
+ *
+ * Returns `"unknown"` when neither source is available.
+ */
+export declare function readBundledPluginVersion(pkgRoot: string): string;
+/**
+ * Asynchronously resolves the pi-coding-agent version by finding its
+ * `package.json` via `import.meta.resolve`.
+ *
+ * Returns `"unknown"` when the resolution fails (e.g. the package is not
+ * installed or bundled).
+ */
+export declare function readPiVersionAsync(): Promise<string>;
+/**
+ * Synchronously reads both the CLI and bundled plugin versions.
+ *
+ * Intended for use at module load time where async is not available (e.g.
+ * `const PKG_VERSIONS = readPkgVersionsSync(pkgRoot)` at the top level of
+ * an ES module).
+ *
+ * Returns empty strings `""` on any read failure so that callers can use
+ * falsy checks (`if (cliVersion && bundledForgeVersion)`) to gate
+ * version-dependent features. Distinct from `readForgeCliVersion` which
+ * returns `"unknown"` — the two have different sentinel conventions.
+ */
+export declare function readPkgVersionsSync(pkgRoot: string): {
+    cliVersion: string;
+    bundledForgeVersion: string;
+};
+export {};