@entelligentsia/forgecli 1.0.10 → 1.0.14

package/dist/extensions/forgecli/orchestrator-tree.js

@@ -0,0 +1,390 @@
+// orchestrator-tree.ts — Generic observable tree for orchestrator > subagent
+// visualization.
+//
+// Sibling to SessionRegistry (which drives the chip strip). The dashboard
+// overlay reads from OrchestratorTree; the chip strip reads from
+// SessionRegistry. Both are written to by the same orchestrator call-sites.
+//
+// The tree is depth-agnostic: Sprint>Tasks>Phases, Fix-bug>Phases, and
+// standalone Run-task are all fan-out trees with the same node shape. Any
+// future orchestrator (run-release, etc.) adds nodes without dashboard
+// changes.
+//
+// Node IDs are dot/colon-separated paths for readability:
+//   "FORGE-S27"                    — sprint root (orchestrator)
+//   "FORGE-S27-T01"                — task (orchestrator)
+//   "FORGE-S27-T01:plan:1"         — phase (leaf)
+//   "FORGE-S27:ceremony"           — ceremony (leaf)
+//
+// LRU-capped at MAX_NODES to bound memory across long-running processes.
+// Ring-buffer tail caps at MAX_TAIL_LINES_PER_NODE.
+import { EventEmitter } from "node:events";
+// ── Constants ──────────────────────────────────────────────────────────────
+const MAX_NODES = 50;
+const MAX_TAIL_LINES_PER_NODE = 2048;
+const MAX_TAIL_APPEND = 500; // per-append cap before trimming
+// ── OrchestratorTree ───────────────────────────────────────────────────────
+export class OrchestratorTree extends EventEmitter {
+    nodes = new Map();
+    roots = new Set();
+    // ── Mutation: lifecycle ────────────────────────────────────────────────
+    startNode(id, opts = {}) {
+        const existing = this.nodes.get(id);
+        if (existing) {
+            // Resume — refresh status and timestamps, keep events for visibility.
+            existing.status = "running";
+            existing.startedAt = Date.now();
+            existing.endedAt = undefined;
+            existing.abortController = new AbortController();
+            // Reconcile parentId: if the caller specifies a different parent,
+            // reparent the node so stale root placements self-correct.
+            const newParentId = opts.parentId ?? null;
+            const oldParentId = existing.parentId;
+            if (newParentId !== oldParentId) {
+                this.reparentNode(existing, oldParentId, newParentId);
+            }
+            // Re-apply label/kind if caller supplies them (resume may change role).
+            if (opts.label !== undefined)
+                existing.label = opts.label;
+            if (opts.kind !== undefined)
+                existing.kind = opts.kind;
+            if (opts.promptPreview !== undefined)
+                existing.promptPreview = opts.promptPreview;
+            this.emit("change", id);
+            this.emit("tree", id);
+            return existing;
+        }
+        const node = {
+            id,
+            label: opts.label ?? id,
+            kind: opts.kind ?? "leaf",
+            parentId: opts.parentId ?? null,
+            children: [],
+            status: "running",
+            startedAt: Date.now(),
+            usage: { input: 0, output: 0, cacheRead: 0 },
+            metrics: { turn: 0, toolCount: 0, errCount: 0 },
+            tailBuffer: [],
+            unreadWarnings: 0,
+            abortController: new AbortController(),
+        };
+        if (opts.promptPreview) {
+            node.promptPreview = opts.promptPreview;
+        }
+        // Link to parent.
+        if (node.parentId) {
+            const parent = this.nodes.get(node.parentId);
+            if (parent && !parent.children.includes(id)) {
+                parent.children.push(id);
+            }
+        }
+        else {
+            this.roots.add(id);
+        }
+        this.nodes.set(id, node);
+        this.evictIfNeeded();
+        this.emit("change", id);
+        this.emit("tree", id);
+        return node;
+    }
+    completeNode(id, status) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        // Idempotent for terminal states — don't clobber a success-path mark.
+        if (node.status !== "running" && node.status !== "cancelling")
+            return;
+        node.status = status;
+        node.endedAt = Date.now();
+        node.abortController = undefined;
+        this.emit("change", id);
+    }
+    // ── Mutation: telemetry ─────────────────────────────────────────────────
+    setNodeUsage(id, usage) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.usage = { input: usage.input, output: usage.output, cacheRead: usage.cacheRead };
+        this.emit("change", id);
+    }
+    setNodeModel(id, model, provider) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        // Only emit when the value actually changes — turn_end fires every
+        // turn and the model is stable across a phase.
+        if (node.provider === provider && node.model === model)
+            return;
+        node.model = model;
+        node.provider = provider;
+        this.emit("change", id);
+    }
+    setNodeCompression(id, compression) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.compression = { calls: compression.calls, tokensSaved: compression.tokensSaved };
+        this.emit("change", id);
+    }
+    bumpNodeTurn(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.metrics.turn++;
+        this.emit("change", id);
+    }
+    incrementNodeToolCount(id, delta = 1) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.metrics.toolCount += delta;
+        this.emit("change", id);
+    }
+    incrementNodeErrCount(id, delta = 1) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.metrics.errCount += delta;
+        this.emit("change", id);
+    }
+    setNodeIteration(id, iteration) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.iteration = iteration;
+        this.emit("change", id);
+    }
+    setNodeOutcome(id, preview) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.outcomePreview = preview;
+        this.emit("change", id);
+    }
+    // ── Mutation: tail buffer ───────────────────────────────────────────────
+    appendTail(id, line, opts) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.tailBuffer.push(line);
+        if (node.tailBuffer.length > MAX_TAIL_LINES_PER_NODE) {
+            node.tailBuffer.splice(0, node.tailBuffer.length - MAX_TAIL_LINES_PER_NODE);
+        }
+        if (opts?.warning)
+            node.unreadWarnings++;
+        this.emit("tail", id);
+    }
+    markTailRead(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        if (node.unreadWarnings === 0)
+            return;
+        node.unreadWarnings = 0;
+        this.emit("change", id);
+    }
+    setTurnPreview(id, preview) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        if (node.lastTurnPreview === preview)
+            return;
+        node.lastTurnPreview = preview;
+        if (node.firstTurnPreview === undefined)
+            node.firstTurnPreview = preview;
+        this.emit("preview", id);
+    }
+    // ── Mutation: cancellation ───────────────────────────────────────────────
+    requestCancel(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return false;
+        if (node.status !== "running")
+            return false;
+        node.status = "cancelling";
+        node.abortController?.abort();
+        this.emit("change", id);
+        return true;
+    }
+    getAbortSignal(id) {
+        return this.nodes.get(id)?.abortController?.signal;
+    }
+    // ── Queries ──────────────────────────────────────────────────────────────
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    getChildren(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return [];
+        return node.children
+            .map((cid) => this.nodes.get(cid))
+            .filter((n) => n !== undefined);
+    }
+    getAncestors(id) {
+        const result = [];
+        let current = this.nodes.get(id);
+        while (current?.parentId) {
+            const parent = this.nodes.get(current.parentId);
+            if (parent)
+                result.push(parent);
+            current = parent;
+        }
+        return result;
+    }
+    getRoots() {
+        return [...this.roots]
+            .map((id) => this.nodes.get(id))
+            .filter((n) => n !== undefined);
+    }
+    /** Active roots: all roots if any are running/cancelling, otherwise
+     *  only non-terminal roots. Prunes stale terminal roots that have no
+     *  running descendants — the dashboard should not show completed sprints
+     *  from prior invocations alongside the current one. */
+    getActiveRoots() {
+        const roots = this.getRoots();
+        const hasActive = roots.some((r) => r.status === "running" || r.status === "cancelling");
+        if (!hasActive)
+            return roots; // nothing in flight — show all
+        return roots.filter((r) => r.status === "running" ||
+            r.status === "cancelling" ||
+            r.status === "pending" ||
+            (r.kind === "orchestrator" && !this.isSubtreeTerminal(r.id)));
+    }
+    /** Returns true if every node in the subtree rooted at `id` has reached a
+     *  terminal state (completed, failed, cancelled, or escalated). */
+    isSubtreeTerminal(id) {
+        const stack = [id];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const node = this.nodes.get(current);
+            if (!node)
+                continue;
+            if (node.status !== "completed" &&
+                node.status !== "failed" &&
+                node.status !== "cancelled" &&
+                node.status !== "escalated") {
+                return false;
+            }
+            stack.push(...node.children);
+        }
+        return true;
+    }
+    /** Re-parent a node from its current position to a new parent (or to root
+     *  if newParentId is null). Removes from old parent's children and/or
+     *  roots, adds to new parent's children and/or roots, and updates the
+     *  node's parentId field. */
+    reparentNode(node, oldParentId, newParentId) {
+        if (oldParentId === newParentId)
+            return;
+        // Unlink from old parent (or roots).
+        if (oldParentId) {
+            const oldParent = this.nodes.get(oldParentId);
+            if (oldParent) {
+                oldParent.children = oldParent.children.filter((cid) => cid !== node.id);
+            }
+        }
+        else {
+            this.roots.delete(node.id);
+        }
+        // Link to new parent (or roots).
+        if (newParentId) {
+            const newParent = this.nodes.get(newParentId);
+            if (newParent && !newParent.children.includes(node.id)) {
+                newParent.children.push(node.id);
+            }
+        }
+        else {
+            this.roots.add(node.id);
+        }
+        node.parentId = newParentId;
+    }
+    getSubtreeUsage(id) {
+        const agg = { input: 0, output: 0, cacheRead: 0 };
+        const stack = [id];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const node = this.nodes.get(current);
+            if (!node)
+                continue;
+            agg.input += node.usage.input;
+            agg.output += node.usage.output;
+            agg.cacheRead += node.usage.cacheRead;
+            stack.push(...node.children);
+        }
+        return agg;
+    }
+    getSubtreeProgress(id) {
+        let completed = 0;
+        let total = 0;
+        const stack = [id];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const node = this.nodes.get(current);
+            if (!node)
+                continue;
+            if (node.kind === "leaf") {
+                total++;
+                if (node.status === "completed")
+                    completed++;
+            }
+            stack.push(...node.children);
+        }
+        return { completed, total };
+    }
+    /** Depth of a node (root = 0). Useful for tree indentation. */
+    getDepth(id) {
+        let depth = 0;
+        let current = this.nodes.get(id);
+        while (current?.parentId) {
+            depth++;
+            current = this.nodes.get(current.parentId);
+        }
+        return depth;
+    }
+    // ── Private ─────────────────────────────────────────────────────────────
+    evictIfNeeded() {
+        if (this.nodes.size <= MAX_NODES)
+            return;
+        // Evict the oldest completed/failed/cancelled root node.
+        const roots = this.getRoots();
+        const evictable = roots
+            .filter((r) => r.status === "completed" ||
+            r.status === "failed" ||
+            r.status === "cancelled" ||
+            r.status === "escalated")
+            .sort((a, b) => a.startedAt - b.startedAt);
+        if (evictable.length === 0)
+            return;
+        const victim = evictable[0];
+        this.removeSubtree(victim.id);
+    }
+    removeSubtree(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        // Remove all descendants first.
+        for (const childId of [...node.children]) {
+            this.removeSubtree(childId);
+        }
+        // Unlink from parent.
+        if (node.parentId) {
+            const parent = this.nodes.get(node.parentId);
+            if (parent) {
+                parent.children = parent.children.filter((cid) => cid !== id);
+            }
+        }
+        else {
+            this.roots.delete(id);
+        }
+        this.nodes.delete(id);
+    }
+}
+// ── Singleton ──────────────────────────────────────────────────────────────
+let _tree;
+export function getOrchestratorTree() {
+    if (!_tree)
+        _tree = new OrchestratorTree();
+    return _tree;
+}
+//# sourceMappingURL=orchestrator-tree.js.map

package/dist/extensions/forgecli/orchestrator-tree.js.map

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

package/dist/extensions/forgecli/project-orientation.js

@@ -25,7 +25,8 @@ function findUpConfigJson(cwd) {
 }
 export function buildProjectOrientation(cwdAbs) {
     // Resolve FORGE_ROOT from .forge/config.json so subagent bash sessions
-    // get the absolute path instead of the unresolved $FORGE_ROOT variable.
+    // can use the transition-fallback $FORGE_ROOT path for un-migrated projects.
+    // Post-FORGE-S29-T05, tools are also available at .forge/tools/ (preferred path).
     // Subagent processes do NOT inherit FORGE_ROOT from the parent environment.
     let resolvedForgeRoot = "$FORGE_ROOT";
     try {
@@ -53,19 +54,22 @@ export function buildProjectOrientation(cwdAbs) {
         "",
         "## Forge Tools (canonical shapes)",
         "",
-        `$FORGE_ROOT resolves to \`${resolvedForgeRoot}\`.`,
+        "Forge tools are available at `.forge/tools/` (preferred, project-relative) after /forge:init.",
+        "If `.forge/tools/store-cli.cjs` does not exist, run `/forge:rebuild tools` to populate it.",
+        `Backward-compat: $FORGE_ROOT resolves to \`${resolvedForgeRoot}\` (transition fallback for un-migrated projects).`,
         "",
-        `- Store read:   \`node "${resolvedForgeRoot}/tools/store-cli.cjs" read <entity> <id>\``,
-        `- Store list:   \`node "${resolvedForgeRoot}/tools/store-cli.cjs" list <entity>\``,
-        `- Store write:  \`node "${resolvedForgeRoot}/tools/store-cli.cjs" write <entity> '<json>'\`  (id INSIDE json)`,
-        `- Update status: \`node "${resolvedForgeRoot}/tools/store-cli.cjs" update-status <entity> <id> <status>\``,
-        `- Emit event:   \`node "${resolvedForgeRoot}/tools/store-cli.cjs" emit <sprintId> '<json>' [--sidecar]\``,
-        `- Help anytime: \`node "${resolvedForgeRoot}/tools/store-cli.cjs" --help\``,
+        `- Store read:   \`node ".forge/tools/store-cli.cjs" read <entity> <id>\``,
+        `- Store list:   \`node ".forge/tools/store-cli.cjs" list <entity>\``,
+        `- Store write:  \`node ".forge/tools/store-cli.cjs" write <entity> '<json>'\`  (id INSIDE json)`,
+        `- Update status: \`node ".forge/tools/store-cli.cjs" update-status <entity> <id> <status>\``,
+        `- Emit event:   \`node ".forge/tools/store-cli.cjs" emit <sprintId> '<json>' [--sidecar]\``,
+        `- Help anytime: \`node ".forge/tools/store-cli.cjs" --help\``,
         "",
         "store-cli verbs: read | list | write | emit | update-status | set-summary | describe | nlp | query | delete — there is no get/set/find.",
         "",
         "## Forge Paths",
         "",
+        "- Forge tools:        `.forge/tools/` (vendored at /forge:init, refreshed via /forge:rebuild tools)",
         "- Workflow fragments: `.forge/workflows/_fragments/` (NOT `.forge/_fragments/`)",
         "- Personas:           `.forge/personas/`",
         "- Templates:          `.forge/templates/`",

package/dist/extensions/forgecli/project-orientation.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-orientation.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/project-orientation.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,EAAE;AACF,6EAA6E;AAC7E,0EAA0E;AAC1E,wEAAwE;AACxE,0EAA0E;AAC1E,+CAA+C;AAC/C,EAAE;AACF,8DAA8D;AAE9D,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,mFAAmF;AACnF,SAAS,gBAAgB,CAAC,GAAW;IACpC,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;QAC1D,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACrD,uEAAuE;IACvE,wEAAwE;IACxE,4EAA4E;IAC5E,IAAI,iBAAiB,GAAG,aAAa,CAAC;IACtC,IAAI,CAAC;QACJ,MAAM,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,UAAU,EAAE,CAAC;YAChB,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC/B,MAAM,SAAS,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC;YAC3C,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;gBACnC,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC;YACvE,CAAC;QACF,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,4CAA4C;IAC7C,CAAC;IAED,OAAO;QACN,wBAAwB;QACxB,EAAE;QACF,0BAA0B,MAAM,kDAAkD;QAClF,EAAE;QACF,+GAA+G;QAC/G,oIAAoI;QACpI,yDAAyD;QACzD,EAAE;QACF,mCAAmC;QACnC,EAAE;QACF,6BAA6B,iBAAiB,KAAK;QACnD,EAAE;QACF,2BAA2B,iBAAiB,4CAA4C;QACxF,2BAA2B,iBAAiB,uCAAuC;QACnF,2BAA2B,iBAAiB,mEAAmE;QAC/G,4BAA4B,iBAAiB,8DAA8D;QAC3G,2BAA2B,iBAAiB,8DAA8D;QAC1G,2BAA2B,iBAAiB,gCAAgC;QAC5E,EAAE;QACF,yIAAyI;QACzI,EAAE;QACF,gBAAgB;QAChB,EAAE;QACF,iFAAiF;QACjF,0CAA0C;QAC1C,2CAA2C;QAC3C,oEAAoE;QACpE,EAAE;QACF,oBAAoB;QACpB,EAAE;QACF,qHAAqH;QACrH,EAAE;QACF,yDAAyD;QACzD,iEAAiE;QACjE,EAAE;KACF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC"}
+{"version":3,"file":"project-orientation.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/project-orientation.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,EAAE;AACF,6EAA6E;AAC7E,0EAA0E;AAC1E,wEAAwE;AACxE,0EAA0E;AAC1E,+CAA+C;AAC/C,EAAE;AACF,8DAA8D;AAE9D,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,mFAAmF;AACnF,SAAS,gBAAgB,CAAC,GAAW;IACpC,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;QAC1D,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACrD,uEAAuE;IACvE,6EAA6E;IAC7E,kFAAkF;IAClF,4EAA4E;IAC5E,IAAI,iBAAiB,GAAG,aAAa,CAAC;IACtC,IAAI,CAAC;QACJ,MAAM,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,UAAU,EAAE,CAAC;YAChB,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC/B,MAAM,SAAS,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC;YAC3C,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;gBACnC,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC;YACvE,CAAC;QACF,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,4CAA4C;IAC7C,CAAC;IAED,OAAO;QACN,wBAAwB;QACxB,EAAE;QACF,0BAA0B,MAAM,kDAAkD;QAClF,EAAE;QACF,+GAA+G;QAC/G,oIAAoI;QACpI,yDAAyD;QACzD,EAAE;QACF,mCAAmC;QACnC,EAAE;QACF,+FAA+F;QAC/F,4FAA4F;QAC5F,8CAA8C,iBAAiB,oDAAoD;QACnH,EAAE;QACF,0EAA0E;QAC1E,qEAAqE;QACrE,iGAAiG;QACjG,6FAA6F;QAC7F,4FAA4F;QAC5F,8DAA8D;QAC9D,EAAE;QACF,yIAAyI;QACzI,EAAE;QACF,gBAAgB;QAChB,EAAE;QACF,qGAAqG;QACrG,iFAAiF;QACjF,0CAA0C;QAC1C,2CAA2C;QAC3C,oEAAoE;QACpE,EAAE;QACF,oBAAoB;QACpB,EAAE;QACF,qHAAqH;QACrH,EAAE;QACF,yDAAyD;QACzD,iEAAiE;QACjE,EAAE;KACF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC"}

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

@@ -21,4 +21,20 @@ export interface ModifiedFile {
  * Pure function (no I/O beyond fs reads + manifest tool spawns).
  */
 export declare function findModifiedStructuralFiles(cwd: string, toolsRoot: string): ModifiedFile[];
+/**
+ * Copy bundled tools (*.cjs, *.js, lib/) from bundleToolsRoot into cwd/.forge/tools/.
+ *
+ * Atomic handler pattern: no LLM in the loop, errors surfaced via returned messages[],
+ * not throw. Accepts _testBundleToolsRoot for test isolation (defaults to getBundledToolsRoot()).
+ *
+ * When singleTool is provided (e.g. "store-cli"), only that file is copied (both .cjs
+ * variant checked first). Used by the `forge:rebuild tools <name>` sub-target.
+ *
+ * @param cwd            Project root directory (must contain .forge/)
+ * @param _testBundleToolsRoot  Override bundle tools root for tests; omit to use getBundledToolsRoot()
+ * @param singleTool     Optional: copy only this one tool by stem name (without extension)
+ */
+export declare function runRebuildTools(cwd: string, _testBundleToolsRoot?: string, singleTool?: string): {
+    messages: string[];
+};
 export declare function registerRegenerate(pi: ExtensionAPI): void;

package/dist/extensions/forgecli/regenerate.js

@@ -111,6 +111,104 @@ async function runTool(toolPath, argv, cwd, ctx, label, timeoutMs = 60_000) {
         });
     });
 }
+/**
+ * Copy bundled tools (*.cjs, *.js, lib/) from bundleToolsRoot into cwd/.forge/tools/.
+ *
+ * Atomic handler pattern: no LLM in the loop, errors surfaced via returned messages[],
+ * not throw. Accepts _testBundleToolsRoot for test isolation (defaults to getBundledToolsRoot()).
+ *
+ * When singleTool is provided (e.g. "store-cli"), only that file is copied (both .cjs
+ * variant checked first). Used by the `forge:rebuild tools <name>` sub-target.
+ *
+ * @param cwd            Project root directory (must contain .forge/)
+ * @param _testBundleToolsRoot  Override bundle tools root for tests; omit to use getBundledToolsRoot()
+ * @param singleTool     Optional: copy only this one tool by stem name (without extension)
+ */
+export function runRebuildTools(cwd, _testBundleToolsRoot, singleTool) {
+    const messages = [];
+    const toolsSrc = _testBundleToolsRoot ?? getBundledToolsRoot();
+    if (!fs.existsSync(toolsSrc)) {
+        messages.push(`× forge:rebuild tools — bundle tools dir not found: ${toolsSrc}`);
+        return { messages };
+    }
+    const toolsDest = path.join(cwd, ".forge", "tools");
+    try {
+        fs.mkdirSync(toolsDest, { recursive: true });
+    }
+    catch (err) {
+        messages.push(`× forge:rebuild tools — could not create .forge/tools/: ${err.message ?? String(err)}`);
+        return { messages };
+    }
+    if (singleTool) {
+        // Single-file sub-target: copy only the named tool
+        const srcCjs = path.join(toolsSrc, `${singleTool}.cjs`);
+        const srcJs = path.join(toolsSrc, `${singleTool}.js`);
+        const resolvedSrc = fs.existsSync(srcCjs) ? srcCjs : fs.existsSync(srcJs) ? srcJs : null;
+        if (resolvedSrc) {
+            const destFile = path.join(toolsDest, path.basename(resolvedSrc));
+            try {
+                fs.copyFileSync(resolvedSrc, destFile);
+                messages.push(`〇 forge:rebuild tools — copied ${path.basename(resolvedSrc)}`);
+            }
+            catch (err) {
+                messages.push(`× forge:rebuild tools — copy failed for ${singleTool}: ${err.message ?? String(err)}`);
+            }
+        }
+        else {
+            messages.push(`△ forge:rebuild tools — tool not found: ${singleTool} (neither .cjs nor .js)`);
+        }
+        return { messages };
+    }
+    // Full copy: all .cjs and .js files
+    let copiedCount = 0;
+    try {
+        const entries = fs.readdirSync(toolsSrc, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith(".cjs") && !entry.name.endsWith(".js"))
+                continue;
+            try {
+                fs.copyFileSync(path.join(toolsSrc, entry.name), path.join(toolsDest, entry.name));
+                copiedCount++;
+            }
+            catch {
+                // non-fatal per-file
+            }
+        }
+    }
+    catch (err) {
+        messages.push(`× forge:rebuild tools — could not read bundle tools dir: ${err.message ?? String(err)}`);
+        return { messages };
+    }
+    // Copy lib/ subdirectory
+    const libSrc = path.join(toolsSrc, "lib");
+    const libDest = path.join(toolsDest, "lib");
+    if (fs.existsSync(libSrc)) {
+        try {
+            fs.mkdirSync(libDest, { recursive: true });
+            const libEntries = fs.readdirSync(libSrc, { withFileTypes: true });
+            for (const entry of libEntries) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith(".cjs") && !entry.name.endsWith(".js"))
+                    continue;
+                try {
+                    fs.copyFileSync(path.join(libSrc, entry.name), path.join(libDest, entry.name));
+                    copiedCount++;
+                }
+                catch {
+                    // non-fatal per-file
+                }
+            }
+        }
+        catch {
+            // non-fatal lib copy failure
+        }
+    }
+    messages.push(`〇 forge:rebuild tools — copied ${copiedCount} tool file(s) to .forge/tools/`);
+    return { messages };
+}
 export function registerRegenerate(pi) {
     pi.registerCommand("forge:rebuild", {
         description: "Re-materialize .forge/ and .claude/commands/ from the bundled forge-payload " +
@@ -119,8 +217,20 @@ export function registerRegenerate(pi) {
         async handler(args, ctx) {
             const cwd = process.cwd();
             // FORGE-S26-T11: --enrich flag dispatches to enhance behavior (absorbed from forge:enhance).
+            // FORGE-S29-T05: `tools` sub-arg dispatches to runRebuildTools.
             const parts = (args ?? "").trim().split(/\s+/).filter(Boolean);
             const hasEnrich = parts.includes("--enrich");
+            const toolsIdx = parts.indexOf("tools");
+            if (toolsIdx !== -1) {
+                // forge:rebuild tools [<name>]
+                // Optional single tool name follows the "tools" keyword.
+                const singleTool = parts[toolsIdx + 1];
+                const result = runRebuildTools(cwd, undefined, singleTool);
+                for (const msg of result.messages) {
+                    ctx.ui.notify(msg, msg.startsWith("×") ? "error" : "info");
+                }
+                return;
+            }
             if (hasEnrich) {
                 // Strip --enrich, pass remaining args to enhance handler (Phase 2 default)
                 const enhanceArgs = parts.filter((p) => p !== "--enrich").join(" ");