supipowers 1.5.3 → 2.0.1

package/src/ultraplan/batch/planner.ts

@@ -0,0 +1,150 @@
+import type { UltraPlanBatchNode, UltraPlanBatchRun } from "../../types.js";
+
+function buildSessionNodeMap(run: UltraPlanBatchRun): Map<string, UltraPlanBatchNode> {
+  return new Map(run.nodes.map((node) => [node.sessionId, node]));
+}
+
+export function getUltraPlanBatchGraphErrors(run: UltraPlanBatchRun): string[] {
+  const errors: string[] = [];
+  const seenNodeIds = new Set<string>();
+  const seenSessionIds = new Set<string>();
+  const nodesBySessionId = new Map<string, UltraPlanBatchNode>();
+
+  for (const node of run.nodes) {
+    if (seenNodeIds.has(node.nodeId)) {
+      errors.push(`duplicate batch nodeId ${node.nodeId}`);
+    }
+    seenNodeIds.add(node.nodeId);
+
+    if (seenSessionIds.has(node.sessionId)) {
+      errors.push(`duplicate batch sessionId ${node.sessionId}`);
+    }
+    seenSessionIds.add(node.sessionId);
+    nodesBySessionId.set(node.sessionId, node);
+  }
+
+  const wavesByIndex = new Map<number, Set<string>>();
+  const sessionsInWaves = new Set<string>();
+  for (const wave of run.waves) {
+    if (wavesByIndex.has(wave.waveIndex)) {
+      errors.push(`duplicate batch waveIndex ${wave.waveIndex}`);
+      continue;
+    }
+    const sessions = new Set<string>();
+    for (const sessionId of wave.sessionIds) {
+      if (sessions.has(sessionId)) {
+        errors.push(`batch wave ${wave.waveIndex} lists ${sessionId} more than once`);
+      }
+      if (sessionsInWaves.has(sessionId)) {
+        errors.push(`batch session ${sessionId} appears in more than one wave`);
+      }
+      sessions.add(sessionId);
+      sessionsInWaves.add(sessionId);
+    }
+    wavesByIndex.set(wave.waveIndex, sessions);
+  }
+
+  for (const node of run.nodes) {
+    const waveMembers = wavesByIndex.get(node.waveIndex);
+    if (!waveMembers) {
+      errors.push(`batch node ${node.sessionId} references missing wave ${node.waveIndex}`);
+      continue;
+    }
+    if (!waveMembers.has(node.sessionId)) {
+      errors.push(`batch node ${node.sessionId} is missing from wave ${node.waveIndex}`);
+    }
+  }
+
+  for (const wave of run.waves) {
+    for (const sessionId of wave.sessionIds) {
+      const node = nodesBySessionId.get(sessionId);
+      if (!node) {
+        errors.push(`batch wave ${wave.waveIndex} references unknown session ${sessionId}`);
+        continue;
+      }
+      if (node.waveIndex !== wave.waveIndex) {
+        errors.push(`batch wave ${wave.waveIndex} includes ${sessionId}, but the node is assigned to wave ${node.waveIndex}`);
+      }
+    }
+  }
+
+  for (const node of run.nodes) {
+    for (const dependencySessionId of node.dependencies) {
+      const dependencyNode = nodesBySessionId.get(dependencySessionId);
+      if (!dependencyNode) {
+        errors.push(`batch node ${node.sessionId} depends on unknown session ${dependencySessionId}`);
+        continue;
+      }
+      if (dependencyNode.waveIndex > node.waveIndex) {
+        errors.push(
+          `batch node ${node.sessionId} depends on ${dependencySessionId} from a later wave (${dependencyNode.waveIndex} > ${node.waveIndex})`,
+        );
+      }
+    }
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+
+  function visit(sessionId: string): void {
+    if (visiting.has(sessionId)) {
+      errors.push(`dependency cycle detected at session ${sessionId}`);
+      return;
+    }
+    if (visited.has(sessionId)) {
+      return;
+    }
+
+    visiting.add(sessionId);
+    const node = nodesBySessionId.get(sessionId);
+    if (node) {
+      for (const dependencySessionId of node.dependencies) {
+        if (nodesBySessionId.has(dependencySessionId)) {
+          visit(dependencySessionId);
+        }
+      }
+    }
+    visiting.delete(sessionId);
+    visited.add(sessionId);
+  }
+
+  for (const node of run.nodes) {
+    visit(node.sessionId);
+  }
+
+  return [...new Set(errors)];
+}
+
+export function buildUltraPlanBatchRunGraph(run: UltraPlanBatchRun): UltraPlanBatchRun {
+  const errors = getUltraPlanBatchGraphErrors(run);
+  if (errors.length > 0) {
+    throw new Error(errors.join("; "));
+  }
+
+  return run;
+}
+
+function dependenciesAreMerged(node: UltraPlanBatchNode, nodesBySessionId: Map<string, UltraPlanBatchNode>): boolean {
+  return node.dependencies.every((dependencySessionId) => nodesBySessionId.get(dependencySessionId)?.state === "merged");
+}
+
+function isDependencyBlocked(node: UltraPlanBatchNode): boolean {
+  return node.state === "blocked" && node.blockerKind === "dependency";
+}
+
+export function computeUltraPlanBatchEligibleFrontier(run: UltraPlanBatchRun): UltraPlanBatchNode[] {
+  const validatedRun = buildUltraPlanBatchRunGraph(run);
+  const nodesBySessionId = buildSessionNodeMap(validatedRun);
+
+  return validatedRun.nodes.filter((node) => {
+    if (node.state === "pending") {
+      return dependenciesAreMerged(node, nodesBySessionId);
+    }
+
+    if (isDependencyBlocked(node)) {
+      return dependenciesAreMerged(node, nodesBySessionId);
+    }
+
+    return false;
+  });
+}

package/src/ultraplan/batch/presenter.ts

@@ -0,0 +1,97 @@
+import type {
+  UltraPlanBatchJournalEvent,
+  UltraPlanBatchNode,
+  UltraPlanBatchRun,
+} from "../../types.js";
+import { computeUltraPlanBatchEligibleFrontier } from "./planner.js";
+
+function findDependencyNames(node: UltraPlanBatchNode): string {
+  return node.dependencies.join(", ");
+}
+
+function findCleanupWarning(
+  node: UltraPlanBatchNode,
+  journal: UltraPlanBatchJournalEvent[],
+): string | null {
+  const match = journal.find((event) => event.sessionId === node.sessionId && event.type === "cleanup-warning");
+  return match?.summary ?? null;
+}
+
+export function renderUltraPlanBatchNodeSummary(
+  node: UltraPlanBatchNode,
+  _run: UltraPlanBatchRun,
+  journal: UltraPlanBatchJournalEvent[] = [],
+): string {
+  if (node.state === "merged") {
+    const cleanupWarning = findCleanupWarning(node, journal);
+    if (cleanupWarning) {
+      return `${node.sessionId} merged with cleanup warning: ${cleanupWarning}`;
+    }
+    return `${node.sessionId} merged`;
+  }
+
+  if (node.state === "blocked" && node.blockerKind === "dependency") {
+    return `${node.sessionId} is waiting for dependencies: ${findDependencyNames(node)}`;
+  }
+
+  if (node.state === "running") {
+    return `${node.sessionId} is running`;
+  }
+
+  return `${node.sessionId} is ${node.state}`;
+}
+
+export function renderUltraPlanBatchSummary(
+  run: UltraPlanBatchRun,
+  journal: UltraPlanBatchJournalEvent[] = [],
+): string {
+  const lines: string[] = [];
+  if (run.state === "blocked" && run.batchBlockerCode) {
+    lines.push(`Batch blocked: ${run.batchBlockerCode}`);
+    if (run.batchBlockerSummary) {
+      lines.push(run.batchBlockerSummary);
+    }
+  } else {
+    lines.push(`Batch state: ${run.state}`);
+  }
+
+  const activeWave = run.nodes
+    .filter((node) => node.state !== "merged" && node.state !== "abandoned")
+    .map((node) => node.waveIndex)
+    .sort((left, right) => left - right)[0];
+  if (activeWave !== undefined) {
+    lines.push(`Active wave: ${activeWave}`);
+  }
+
+  const frontier = computeUltraPlanBatchEligibleFrontier(run).map((node) => node.sessionId);
+  if (frontier.length > 0) {
+    lines.push(`Frontier: ${frontier.join(", ")}`);
+  }
+
+  const runningWorkers = run.nodes.filter((node) => node.state === "running").map((node) => node.sessionId);
+  if (runningWorkers.length > 0) {
+    lines.push(`Running workers: ${runningWorkers.join(", ")}`);
+  }
+
+  const keptWorktrees = run.nodes
+    .filter((node) => node.worktreePath !== null)
+    .map((node) => node.worktreePath as string);
+  if (keptWorktrees.length > 0) {
+    lines.push(`Kept worktrees: ${keptWorktrees.join(", ")}`);
+  }
+
+  for (const node of run.nodes) {
+    if (node.state === "blocked" && node.blockerKind === "dependency") {
+      lines.push(renderUltraPlanBatchNodeSummary(node, run, journal));
+      continue;
+    }
+
+    if (node.waveIndex > activeWave!
+      && node.state === "pending"
+      && node.dependencies.length > 0) {
+      lines.push(`Later wave queued: ${node.sessionId} becomes eligible after ${findDependencyNames(node)} merges.`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/ultraplan/batch/storage.ts

@@ -0,0 +1,420 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { PlatformPaths } from "../../platform/types.js";
+import type {
+  UltraPlanBatchActiveRunLease,
+  UltraPlanBatchJournalEvent,
+  UltraPlanBatchRun,
+  UltraPlanStorageError,
+  UltraPlanStorageResult,
+} from "../../types.js";
+import {
+  getUltraPlanSchemaErrors,
+  UltraPlanBatchJournalEventSchema,
+  validateUltraPlanBatchActiveRunLease,
+  validateUltraPlanBatchRun,
+} from "../contracts.js";
+import {
+  getUltraplanActiveBatchRunPath,
+  getUltraplanBatchJournalPath,
+  getUltraplanBatchRunPath,
+} from "../project-paths.js";
+
+function success<T>(value: T): UltraPlanStorageResult<T> {
+  return { ok: true, value };
+}
+
+function failure(
+  pathname: string,
+  kind: UltraPlanStorageError["kind"],
+  message: string,
+  details?: string[],
+): UltraPlanStorageResult<never> {
+  return {
+    ok: false,
+    error: {
+      kind,
+      path: pathname,
+      message,
+      ...(details ? { details } : {}),
+    },
+  };
+}
+
+function ensureDir(filePath: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readJsonFile(filePath: string): UltraPlanStorageResult<unknown> {
+  if (!fs.existsSync(filePath)) {
+    return failure(filePath, "missing", `Artifact not found: ${filePath}`);
+  }
+
+  try {
+    return success(JSON.parse(fs.readFileSync(filePath, "utf8")));
+  } catch (error) {
+    return failure(
+      filePath,
+      "invalid-json",
+      error instanceof Error ? error.message : `Invalid JSON in ${filePath}`,
+    );
+  }
+}
+
+function writeJsonFile(filePath: string, payload: unknown): UltraPlanStorageResult<string> {
+  try {
+    ensureDir(filePath);
+    fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to write ${filePath}`,
+    );
+  }
+}
+
+
+function validateBatchRunForStorage(
+  filePath: string,
+  value: unknown,
+): UltraPlanStorageResult<UltraPlanBatchRun> {
+  const validation = validateUltraPlanBatchRun(value);
+  if (!validation.ok) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, validation.errors);
+  }
+
+
+  return success(validation.value);
+}
+
+function validateBatchLeaseForStorage(
+  filePath: string,
+  value: unknown,
+ ): UltraPlanStorageResult<UltraPlanBatchActiveRunLease> {
+  const validation = validateUltraPlanBatchActiveRunLease(value);
+  if (!validation.ok) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, validation.errors);
+  }
+
+
+  return success(validation.value);
+}
+
+function parseLeaseTimestamp(
+  filePath: string,
+  fieldName: string,
+  value: string | null,
+ ): UltraPlanStorageResult<number | null> {
+  if (value === null) {
+    return success(null);
+  }
+
+  const millis = Date.parse(value);
+  if (Number.isNaN(millis)) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      `${fieldName} must be a valid ISO timestamp`,
+    ]);
+  }
+
+  return success(millis);
+}
+
+
+export function loadUltraPlanBatchRun(
+  paths: PlatformPaths,
+  cwd: string,
+  runId: string,
+): UltraPlanStorageResult<UltraPlanBatchRun> {
+  const filePath = getUltraplanBatchRunPath(paths, cwd, runId);
+  const parsed = readJsonFile(filePath);
+  if (!parsed.ok) {
+    return parsed;
+  }
+
+  return validateBatchRunForStorage(filePath, parsed.value);
+}
+
+export function saveUltraPlanBatchRun(
+  paths: PlatformPaths,
+  cwd: string,
+  run: UltraPlanBatchRun,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanBatchRunPath(paths, cwd, run.runId);
+  const validation = validateBatchRunForStorage(filePath, run);
+  if (!validation.ok) {
+    return validation;
+  }
+
+  return writeJsonFile(filePath, validation.value);
+}
+
+export function loadUltraPlanBatchJournal(
+  paths: PlatformPaths,
+  cwd: string,
+  runId: string,
+): UltraPlanStorageResult<UltraPlanBatchJournalEvent[]> {
+  const filePath = getUltraplanBatchJournalPath(paths, cwd, runId);
+  if (!fs.existsSync(filePath)) {
+    return success([]);
+  }
+
+  try {
+    const entries: UltraPlanBatchJournalEvent[] = [];
+    const lines = fs.readFileSync(filePath, "utf8").split(/\r?\n/).filter((line) => line.trim().length > 0);
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index]!;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch (error) {
+        return failure(
+          filePath,
+          "invalid-json",
+          error instanceof Error ? error.message : `Invalid JSON in ${filePath}`,
+          [`journal line ${index + 1} is not valid JSON`],
+        );
+      }
+
+      const errors = getUltraPlanSchemaErrors(UltraPlanBatchJournalEventSchema, parsed);
+      if (errors.length > 0) {
+        return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, errors);
+      }
+      entries.push(parsed as UltraPlanBatchJournalEvent);
+    }
+
+    return success(entries);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to read ${filePath}`,
+    );
+  }
+}
+
+export function appendUltraPlanBatchJournalEvent(
+  paths: PlatformPaths,
+  cwd: string,
+  runId: string,
+  event: UltraPlanBatchJournalEvent,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanBatchJournalPath(paths, cwd, runId);
+  const errors = getUltraPlanSchemaErrors(UltraPlanBatchJournalEventSchema, event);
+  if (errors.length > 0) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, errors);
+  }
+
+  try {
+    ensureDir(filePath);
+    fs.appendFileSync(filePath, `${JSON.stringify(event)}\n`, "utf8");
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to append ${filePath}`,
+    );
+  }
+}
+
+export function loadUltraPlanBatchActiveRunLease(
+  paths: PlatformPaths,
+  cwd: string,
+): UltraPlanStorageResult<UltraPlanBatchActiveRunLease | null> {
+  const filePath = getUltraplanActiveBatchRunPath(paths, cwd);
+  if (!fs.existsSync(filePath)) {
+    return success(null);
+  }
+
+  const parsed = readJsonFile(filePath);
+  if (!parsed.ok) {
+    return parsed;
+  }
+
+  return validateBatchLeaseForStorage(filePath, parsed.value);
+}
+
+export function saveUltraPlanBatchActiveRunLease(
+  paths: PlatformPaths,
+  cwd: string,
+  lease: UltraPlanBatchActiveRunLease,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanActiveBatchRunPath(paths, cwd);
+  const validation = validateBatchLeaseForStorage(filePath, lease);
+  if (!validation.ok) {
+    return validation;
+  }
+
+  return writeJsonFile(filePath, validation.value);
+}
+
+export function clearUltraPlanBatchActiveRunLease(
+  paths: PlatformPaths,
+  cwd: string,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanActiveBatchRunPath(paths, cwd);
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.rmSync(filePath);
+    }
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to remove ${filePath}`,
+    );
+  }
+}
+
+export function loadUltraPlanActiveBatchRun(
+  paths: PlatformPaths,
+  cwd: string,
+): UltraPlanStorageResult<UltraPlanBatchRun | null> {
+  const lease = loadUltraPlanBatchActiveRunLease(paths, cwd);
+  if (!lease.ok) {
+    return lease;
+  }
+  if (lease.value === null) {
+    return success(null);
+  }
+
+  return loadUltraPlanBatchRun(paths, cwd, lease.value.runId);
+}
+
+export function acquireUltraPlanBatchActiveRunLease(
+  paths: PlatformPaths,
+  cwd: string,
+  lease: UltraPlanBatchActiveRunLease,
+  options?: { nowIso?: string },
+): UltraPlanStorageResult<UltraPlanBatchActiveRunLease> {
+  const filePath = getUltraplanActiveBatchRunPath(paths, cwd);
+  const validation = validateBatchLeaseForStorage(filePath, lease);
+  if (!validation.ok) {
+    return validation;
+  }
+  if (
+    validation.value.ownerSessionId === null
+    || validation.value.leaseAcquiredAt === null
+    || validation.value.leaseExpiresAt === null
+  ) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      "acquired lease must include ownerSessionId, leaseAcquiredAt, and leaseExpiresAt",
+    ]);
+  }
+
+  const trustedNow = parseLeaseTimestamp(filePath, "nowIso", options?.nowIso ?? new Date().toISOString());
+  if (!trustedNow.ok) {
+    return trustedNow;
+  }
+  const requestedAcquiredAt = parseLeaseTimestamp(filePath, "leaseAcquiredAt", validation.value.leaseAcquiredAt);
+  if (!requestedAcquiredAt.ok) {
+    return requestedAcquiredAt;
+  }
+  const requestedExpiresAt = parseLeaseTimestamp(filePath, "leaseExpiresAt", validation.value.leaseExpiresAt);
+  if (!requestedExpiresAt.ok) {
+    return requestedExpiresAt;
+  }
+  if ((requestedAcquiredAt.value ?? 0) > (trustedNow.value ?? 0)) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      "leaseAcquiredAt cannot be in the future relative to nowIso",
+    ]);
+  }
+  if ((requestedExpiresAt.value ?? 0) <= (trustedNow.value ?? 0)) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      "leaseExpiresAt must be in the future relative to nowIso",
+    ]);
+  }
+
+  const current = loadUltraPlanBatchActiveRunLease(paths, cwd);
+  if (!current.ok) {
+    return current;
+  }
+
+  const currentLease = current.value;
+  if (currentLease !== null) {
+    const currentIsHeld = currentLease.ownerSessionId !== null
+      && currentLease.leaseAcquiredAt !== null
+      && currentLease.leaseExpiresAt !== null;
+    const sameOwner = currentLease.runId === validation.value.runId
+      && currentLease.ownerSessionId === validation.value.ownerSessionId;
+    if (currentIsHeld && !sameOwner) {
+      const existingExpiry = parseLeaseTimestamp(filePath, "leaseExpiresAt", currentLease.leaseExpiresAt);
+      if (!existingExpiry.ok) {
+        return existingExpiry;
+      }
+      if ((existingExpiry.value ?? 0) > (trustedNow.value ?? 0)) {
+        return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+          `active-run lease already held by ${currentLease.ownerSessionId}`,
+        ]);
+      }
+    }
+  }
+
+  const saved = saveUltraPlanBatchActiveRunLease(paths, cwd, validation.value);
+  if (!saved.ok) {
+    return saved;
+  }
+  return success(validation.value);
+}
+
+export function releaseUltraPlanBatchActiveRunLease(
+  paths: PlatformPaths,
+  cwd: string,
+  leaseOwner: Pick<UltraPlanBatchActiveRunLease, "runId" | "ownerSessionId">,
+  nextState: UltraPlanBatchRun["state"],
+  releasedAt: string,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanActiveBatchRunPath(paths, cwd);
+  if (!leaseOwner.ownerSessionId) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      "release requires the persisted ownerSessionId",
+    ]);
+  }
+
+  const current = loadUltraPlanBatchActiveRunLease(paths, cwd);
+  if (!current.ok) {
+    return current;
+  }
+  if (current.value === null) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      "active-run lease is missing",
+    ]);
+  }
+  if (current.value.runId !== leaseOwner.runId) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      `active-run lease points at ${current.value.runId}, not ${leaseOwner.runId}`,
+    ]);
+  }
+  if (current.value.ownerSessionId !== leaseOwner.ownerSessionId) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      `active-run lease is owned by ${current.value.ownerSessionId}, not ${leaseOwner.ownerSessionId}`,
+    ]);
+  }
+  if (current.value.leaseAcquiredAt === null || current.value.leaseExpiresAt === null) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      "active-run lease is not currently held",
+    ]);
+  }
+
+  if (nextState === "complete" || nextState === "abandoned") {
+    return clearUltraPlanBatchActiveRunLease(paths, cwd);
+  }
+
+  if (nextState !== "paused" && nextState !== "blocked") {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, [
+      `cannot release active-run lease for state ${nextState}`,
+    ]);
+  }
+
+  const releasedLease: UltraPlanBatchActiveRunLease = {
+    runId: leaseOwner.runId,
+    ownerSessionId: null,
+    leaseAcquiredAt: null,
+    leaseExpiresAt: null,
+    updatedAt: releasedAt,
+  };
+  return saveUltraPlanBatchActiveRunLease(paths, cwd, releasedLease);
+}