@entelligentsia/forgecli 1.1.0 → 1.1.3

package/dist/extensions/forgecli/orchestrators/init/init-steps.js

@@ -0,0 +1,125 @@
+// init-steps.ts — the /forge:init step machine (FORGE-S35-T02, Slice 1).
+//
+// Replaces the coarse four-phase `INIT_PHASES` walk with a flat table of
+// `Step` descriptors. Each Step declares:
+//   - `dependsOn`     — ordering edges (the only serialization constraint);
+//   - `precondition`  — a deterministic input-readiness/ordering gate checked
+//                       BEFORE any run/dispatch (halts pre-dispatch on failure);
+//   - `run`           — a discriminated union: a deterministic thunk (local
+//                       tool/fs work, spawns NO subagent) OR a scoped subagent
+//                       descriptor dispatched through the existing
+//                       runForgeSubagent path (IL10 unchanged);
+//   - `requiredOutput`— a deterministic postcondition; on failure the step is
+//                       rerun up to `retryPolicy.maxReruns`, then the pipeline
+//                       halts;
+//   - `retryPolicy`   — `{ maxReruns }` (0 = hard-halt on first failure).
+//
+// `topoSortWaves` groups steps with no unresolved dependency into the same wave
+// (Kahn layering); `runWave` dispatches a wave's steps concurrently via
+// `Promise.all` (no new npm dependency — built-ins only). Steps sharing a wave
+// are independent and overlap; cross-reference edges are the sole ordering
+// constraint.
+//
+// This module holds ONLY the reusable machine + the `Step` contract. The
+// concrete `INIT_STEPS` table (which closes over pipeline runtime state and the
+// forge-init deterministic helpers) is assembled by the orchestrator in
+// run-init-pipeline.ts. Keeping the primitives free of forge-init imports keeps
+// them independently unit-testable (init-steps.test.ts).
+//
+// Layering: type-only imports from sibling subagent modules; no runtime deps.
+// ── runStep ───────────────────────────────────────────────────────────────────
+/**
+ * Drive one step: check precondition (halt pre-dispatch on failure) → run
+ * (deterministic thunk OR subagent) → check requiredOutput → on failure rerun
+ * up to `retryPolicy.maxReruns`, else halt.
+ *
+ * A precondition failure returns `{ ok:false, dispatched:false }` with ZERO
+ * dispatches — the gate is always checked before any subagent is spawned.
+ */
+export async function runStep(step, deps) {
+    const { ctx, dispatchSubagent } = deps;
+    const startMs = Date.now();
+    if (step.precondition) {
+        const pc = await step.precondition(ctx);
+        if (!pc.ok) {
+            return {
+                ok: false,
+                reason: pc.reason ?? `precondition failed for step "${step.id}"`,
+                dispatched: false,
+                attempts: 0,
+                startMs,
+                endMs: Date.now(),
+            };
+        }
+    }
+    const isSubagent = step.run.kind === "subagent";
+    const maxAttempts = 1 + Math.max(0, step.retryPolicy?.maxReruns ?? 0);
+    let attempts = 0;
+    let lastResult;
+    let lastReason;
+    while (attempts < maxAttempts) {
+        attempts++;
+        if (step.run.kind === "deterministic") {
+            await step.run.thunk(ctx);
+        }
+        else {
+            lastResult = await dispatchSubagent(step.run, ctx);
+        }
+        if (!step.requiredOutput) {
+            return { ok: true, dispatched: isSubagent, attempts, result: lastResult, startMs, endMs: Date.now() };
+        }
+        const ro = await step.requiredOutput(ctx, lastResult);
+        if (ro.ok) {
+            return { ok: true, dispatched: isSubagent, attempts, result: lastResult, startMs, endMs: Date.now() };
+        }
+        lastReason = ro.reason;
+        // otherwise loop and rerun while attempts remain
+    }
+    return {
+        ok: false,
+        reason: lastReason ?? `requiredOutput failed for step "${step.id}"`,
+        dispatched: isSubagent,
+        attempts,
+        result: lastResult,
+        startMs,
+        endMs: Date.now(),
+    };
+}
+// ── runWave ─────────────────────────────────────────────────────────────────
+/**
+ * Dispatch every step in a wave concurrently via `Promise.all`. Steps sharing a
+ * wave are independent (no unresolved dependency), so they overlap. Returns the
+ * outcomes in the wave's step order. Concurrency is bounded by wave width
+ * (≤ 10 for the kb-doc wave), so no explicit limiter is needed this slice.
+ */
+export async function runWave(steps, run) {
+    return Promise.all(steps.map((step) => run(step)));
+}
+// ── topoSortWaves ─────────────────────────────────────────────────────────────
+/**
+ * Group steps into topo-sorted waves (Kahn layering): every step whose
+ * dependencies are all satisfied by earlier waves lands in the next wave.
+ * Declaration order is preserved within a wave. Throws on a dependency cycle.
+ * Edges to unknown step ids are ignored (treated as already-satisfied).
+ */
+export function topoSortWaves(steps) {
+    const known = new Set(steps.map((s) => s.id));
+    const deps = new Map();
+    for (const s of steps) {
+        deps.set(s.id, (s.dependsOn ?? []).filter((d) => known.has(d)));
+    }
+    const waves = [];
+    const placed = new Set();
+    while (placed.size < steps.length) {
+        const layer = steps.filter((s) => !placed.has(s.id) && (deps.get(s.id) ?? []).every((d) => placed.has(d)));
+        if (layer.length === 0) {
+            const stuck = steps.filter((s) => !placed.has(s.id)).map((s) => s.id);
+            throw new Error(`init-steps: cyclic or unsatisfiable dependency among [${stuck.join(", ")}]`);
+        }
+        waves.push(layer);
+        for (const s of layer)
+            placed.add(s.id);
+    }
+    return waves;
+}
+//# sourceMappingURL=init-steps.js.map

package/dist/extensions/forgecli/orchestrators/init/init-steps.js.map

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