@entelligentsia/forgecli 0.2.0 → 0.3.0

package/dist/extensions/forgecli/transition-guard.js

@@ -0,0 +1,125 @@
+// Status-transition guard — FORGE-S18-T03
+//
+// Encodes the legal status-transition table for each entity (task, sprint, bug)
+// and checks whether a proposed transition is allowed.
+//
+// The guard reads the current status from disk via `store-cli read` (spawnSync).
+// Fail-open: if the current-status lookup fails for any reason, the guard returns
+// { allowed: true } and sets reason="lookup-failed". The caller (hook-dispatcher)
+// logs this as "lookup-failed" under FORGE_HOOK_AUDIT=1 but never blocks the
+// operation — a lookup failure must not block a valid operation.
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+// ── Legal transition tables ───────────────────────────────────────────────────
+//
+// Derived from task.schema.json, sprint.schema.json, bug.schema.json status enums.
+// Each entry: fromStatus → Set<toStatus>
+const TASK_TRANSITIONS = {
+    draft: new Set(["planned", "blocked", "escalated", "abandoned"]),
+    planned: new Set(["plan-approved", "plan-revision-required", "blocked", "escalated", "abandoned"]),
+    "plan-approved": new Set(["implementing", "blocked", "escalated", "abandoned"]),
+    implementing: new Set(["implemented", "code-revision-required", "blocked", "escalated", "abandoned"]),
+    implemented: new Set(["review-approved", "blocked", "escalated", "abandoned"]),
+    "review-approved": new Set(["approved", "blocked", "escalated", "abandoned"]),
+    approved: new Set(["committed", "blocked", "escalated", "abandoned"]),
+    "plan-revision-required": new Set(["planned", "blocked", "escalated", "abandoned"]),
+    "code-revision-required": new Set(["implementing", "blocked", "escalated", "abandoned"]),
+    // Terminal / sink states — can only be re-opened by --force.
+    blocked: new Set(["blocked", "escalated", "abandoned"]),
+    escalated: new Set(["blocked", "escalated", "abandoned"]),
+    abandoned: new Set(["blocked", "escalated", "abandoned"]),
+    committed: new Set(["blocked", "escalated", "abandoned"]),
+};
+const SPRINT_TRANSITIONS = {
+    planning: new Set(["active", "abandoned"]),
+    active: new Set(["completed", "partially-completed", "blocked", "abandoned"]),
+    completed: new Set(["retrospective-done"]),
+    "partially-completed": new Set(["retrospective-done"]),
+    "retrospective-done": new Set([]),
+    blocked: new Set(["active", "abandoned"]),
+    abandoned: new Set([]),
+};
+const BUG_TRANSITIONS = {
+    reported: new Set(["triaged", "abandoned"]),
+    triaged: new Set(["in-progress", "abandoned"]),
+    "in-progress": new Set(["fixed", "abandoned"]),
+    fixed: new Set(["verified"]),
+    verified: new Set([]),
+    abandoned: new Set([]),
+};
+const ENTITY_TABLES = {
+    task: TASK_TRANSITIONS,
+    sprint: SPRINT_TRANSITIONS,
+    bug: BUG_TRANSITIONS,
+};
+function legalNextStates(entity, fromStatus) {
+    const table = ENTITY_TABLES[entity];
+    if (!table)
+        return [];
+    const allowed = table[fromStatus];
+    return allowed ? [...allowed] : [];
+}
+// ── Current-status lookup (fail-open) ────────────────────────────────────────
+/**
+ * Read the current status of an entity from the store via `store-cli read`.
+ * Returns the status string on success, or null on any failure (fail-open).
+ */
+function readCurrentStatus(entity, entityId, forgeRoot) {
+    const storeCliPath = path.join(forgeRoot, "tools", "store-cli.cjs");
+    try {
+        const result = spawnSync(process.execPath, [storeCliPath, "read", entity, entityId], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        if (result.status !== 0 || result.error)
+            return null;
+        const stdout = result.stdout?.trim();
+        if (!stdout)
+            return null;
+        // store-cli read emits JSON; parse and extract the status field.
+        const record = JSON.parse(stdout);
+        const status = record.status;
+        return typeof status === "string" ? status : null;
+    }
+    catch {
+        // Any parse error or subprocess error → fail-open.
+        return null;
+    }
+}
+/**
+ * Check whether a status transition is legal.
+ *
+ * Fail-open: if the current status cannot be read, returns
+ * `{ allowed: true, reason: "lookup-failed" }`. The caller
+ * should audit-log this outcome but MUST NOT block the operation.
+ *
+ * @param input     Entity, entity ID, and target status.
+ * @param forgeRoot Absolute path to the Forge plugin root.
+ */
+export function checkTransition(input, forgeRoot) {
+    const { entity, entityId, toStatus } = input;
+    // Lookup current status — fail-open on any error.
+    const fromStatus = readCurrentStatus(entity, entityId, forgeRoot);
+    if (fromStatus === null) {
+        return {
+            allowed: true,
+            reason: "lookup-failed",
+        };
+    }
+    const table = ENTITY_TABLES[entity];
+    if (!table) {
+        // Unknown entity type — allow through (future-proofing).
+        return { allowed: true, reason: "" };
+    }
+    const allowed = table[fromStatus]?.has(toStatus) ?? false;
+    if (allowed) {
+        return { allowed: true, reason: "" };
+    }
+    const legal = legalNextStates(entity, fromStatus);
+    const legalStr = legal.length > 0 ? legal.join(", ") : "(none)";
+    return {
+        allowed: false,
+        reason: `${fromStatus} → ${toStatus} is not a legal transition for ${entity}. Legal next states from ${fromStatus}: ${legalStr}.`,
+    };
+}
+//# sourceMappingURL=transition-guard.js.map

package/dist/extensions/forgecli/transition-guard.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@entelligentsia/forgecli",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Forge SDLC ported onto @earendil-works/pi-coding-agent — production launcher with three bin aliases (forge/forgecli/4ge).",
 	"license": "MIT",
 	"author": "Entelligentsia",