feat(engine): add resolvePlanOverallStatus plan DAG helper

packages/gittensory-engine/README.md

@@ -538,6 +538,7 @@ dashboard progress summaries:
 - `hasPlanCompletedSteps(plan)` — any step is `completed`
 - `isPlanBlocked(plan)` — pending steps remain but none are runnable (deadlock; mirrors `planProgress`'s `blocked` status)
 - `isPlanProgressComplete(plan)` — every step is `completed` or `skipped` (empty plans are not complete; mirrors `planProgress`'s `completed` status)
+- `resolvePlanOverallStatus(plan)` — coarse status (`pending` | `running` | `completed` | `failed` | `blocked`); mirrors `planProgress`'s `status`
 
 ## Opportunity competition
 

packages/gittensory-engine/src/index.ts

@@ -148,6 +148,7 @@ export { hasPlanSkippedSteps } from "./plan-skipped.js";
 export { hasPlanCompletedSteps } from "./plan-completed.js";
 export { isPlanBlocked } from "./plan-blocked.js";
 export { isPlanProgressComplete } from "./plan-progress-complete.js";
+export { resolvePlanOverallStatus, type PlanOverallStatus } from "./plan-overall-status.js";
 export * from "./plan-templates.js";
 export * from "./portfolio/queue.js";
 export {

packages/gittensory-engine/src/plan-overall-status.ts

@@ -0,0 +1,30 @@
+import type { PlanDag, PlanStep, PlanStepStatus } from "./plan-export.js";
+
+export type PlanOverallStatus = "pending" | "running" | "completed" | "failed" | "blocked";
+
+const isDone = (status: PlanStepStatus): boolean => status === "completed" || status === "skipped";
+
+function nextReadySteps(plan: PlanDag): PlanStep[] {
+  const statusById = new Map(plan.steps.map((step) => [step.id, step.status]));
+  return plan.steps.filter(
+    (step) => step.status === "pending" && step.dependsOn.every((dep) => isDone(statusById.get(dep) ?? "pending")),
+  );
+}
+
+/**
+ * Resolve the coarse plan status matching hosted `planProgress`'s `status` field. Pure — reads the plan DAG only.
+ */
+export function resolvePlanOverallStatus(plan: PlanDag): PlanOverallStatus {
+  const total = plan.steps.length;
+  const completed = plan.steps.filter((step) => step.status === "completed").length;
+  const skipped = plan.steps.filter((step) => step.status === "skipped").length;
+  const failed = plan.steps.filter((step) => step.status === "failed").length;
+  const running = plan.steps.filter((step) => step.status === "running").length;
+  const pending = plan.steps.filter((step) => step.status === "pending").length;
+
+  if (total > 0 && completed + skipped === total) return "completed";
+  if (failed > 0) return "failed";
+  if (running > 0) return "running";
+  if (pending > 0 && nextReadySteps(plan).length === 0) return "blocked";
+  return "pending";
+}

test/unit/plan-overall-status.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import { resolvePlanOverallStatus } from "../../packages/gittensory-engine/src/plan-overall-status";
+import type { PlanStep } from "../../packages/gittensory-engine/src/plan-export";
+
+function step(over: Partial<PlanStep> & { id: string; title: string }): PlanStep {
+  return {
+    actionClass: undefined,
+    dependsOn: [],
+    status: "pending",
+    attempts: 0,
+    maxAttempts: 3,
+    lastError: null,
+    ...over,
+  };
+}
+
+describe("resolvePlanOverallStatus", () => {
+  it("returns pending for an empty plan", () => {
+    expect(resolvePlanOverallStatus({ steps: [] })).toBe("pending");
+  });
+
+  it("returns completed when every step is completed or skipped", () => {
+    expect(
+      resolvePlanOverallStatus({
+        steps: [
+          step({ id: "a", title: "Build", status: "completed" }),
+          step({ id: "b", title: "Deploy", status: "skipped" }),
+        ],
+      }),
+    ).toBe("completed");
+  });
+
+  it("returns failed when any step failed", () => {
+    expect(
+      resolvePlanOverallStatus({
+        steps: [
+          step({ id: "a", title: "Build", status: "running" }),
+          step({ id: "b", title: "Deploy", status: "failed" }),
+        ],
+      }),
+    ).toBe("failed");
+  });
+
+  it("returns running when a step is in flight and none failed", () => {
+    expect(
+      resolvePlanOverallStatus({
+        steps: [
+          step({ id: "a", title: "Build", status: "running" }),
+          step({ id: "b", title: "Test", status: "pending" }),
+        ],
+      }),
+    ).toBe("running");
+  });
+
+  it("returns blocked for a cyclic deadlock with no ready steps", () => {
+    expect(
+      resolvePlanOverallStatus({
+        steps: [
+          step({ id: "a", title: "A", dependsOn: ["b"] }),
+          step({ id: "b", title: "B", dependsOn: ["a"] }),
+        ],
+      }),
+    ).toBe("blocked");
+  });
+
+  it("returns blocked when a pending step depends on a missing step id", () => {
+    expect(
+      resolvePlanOverallStatus({
+        steps: [step({ id: "a", title: "A", dependsOn: ["ghost"] })],
+      }),
+    ).toBe("blocked");
+  });
+
+  it("returns pending when runnable steps remain", () => {
+    expect(
+      resolvePlanOverallStatus({
+        steps: [
+          step({ id: "a", title: "Build", status: "pending" }),
+          step({ id: "b", title: "Test", status: "pending", dependsOn: ["a"] }),
+        ],
+      }),
+    ).toBe("pending");
+  });
+
+  it("is exported from the package barrel", async () => {
+    const barrel = await import("../../packages/gittensory-engine/src/index");
+    expect(typeof barrel.resolvePlanOverallStatus).toBe("function");
+    expect(
+      barrel.resolvePlanOverallStatus({
+        steps: [step({ id: "a", title: "A", status: "completed" })],
+      }),
+    ).toBe("completed");
+  });
+});