supipowers 1.5.2 → 2.0.0

package/src/ultraplan/authoring/storage.ts

@@ -0,0 +1,594 @@
+/**
+ * Storage helpers for the multi-stage authoring pipeline.
+ *
+ * Authoring artifacts live under `<session>/authoring/` and never touch the runtime tracker
+ * or the canonical `authored.json` until the APPROVE stage promotes them. This module is a
+ * thin wrapper over `node:fs` that:
+ *  - validates each artifact against its TypeBox schema before writing,
+ *  - writes JSON atomically (temp + rename),
+ *  - appends to `pipeline-log.jsonl` line-by-line (no rewriting the whole file),
+ *  - exposes load helpers that distinguish "missing" from "invalid" cleanly.
+ *
+ * Filesystem failures are returned as structured `UltraPlanStorageResult` values so callers
+ * never need to wrap calls in try/catch. The shape mirrors `src/ultraplan/storage.ts` and the
+ * runtime `tracker-storage.ts` deliberately so the consumer ergonomics are identical.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { PlatformPaths } from "../../platform/types.js";
+import type {
+  UltraPlanAuthoringFindingsArtifact,
+  UltraPlanAuthoringPipelineEvent,
+  UltraPlanAuthoringState,
+  UltraPlanStackId,
+  UltraPlanStorageError,
+  UltraPlanStorageResult,
+} from "../../types.js";
+import {
+  validateUltraPlanAuthoringFindingsArtifact,
+  validateUltraPlanAuthoringPipelineEvent,
+  validateUltraPlanAuthoringState,
+} from "../contracts.js";
+import {
+  getUltraplanAuthoringDecisionsPath,
+  getUltraplanAuthoringDeferredIdeasPath,
+  getUltraplanAuthoringDir,
+  getUltraplanAuthoringDiscussPath,
+  getUltraplanAuthoringDraftAuthoredJsonPath,
+  getUltraplanAuthoringDraftAuthoredMarkdownPath,
+  getUltraplanAuthoringDraftFindingsPath,
+  getUltraplanAuthoringDraftIterationDir,
+  getUltraplanAuthoringDraftPlannerJsonPath,
+  getUltraplanAuthoringIntakePath,
+  getUltraplanAuthoringPipelineLogPath,
+  getUltraplanAuthoringResearchStackPath,
+  getUltraplanAuthoringResearchSummaryPath,
+  getUltraplanAuthoringScoutPath,
+} from "../project-paths.js";
+import { loadUltraPlanManifest, saveUltraPlanManifest } from "../storage.js";
+
+// ---------------------------------------------------------------------------
+// Result helpers (kept private; matches the shape used elsewhere in storage.ts).
+// ---------------------------------------------------------------------------
+
+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 ensureDirExists(dirPath: string): void {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * Atomic JSON write: serialize → write to a per-process temp file → rename. The rename is
+ * atomic on the same filesystem, so concurrent readers either see the previous file or the
+ * full new file, never a half-written one.
+ */
+function writeJsonAtomic(filePath: string, payload: unknown): UltraPlanStorageResult<string> {
+  try {
+    ensureDir(filePath);
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(payload, null, 2)}\n`);
+    fs.renameSync(tmpPath, filePath);
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to write ${filePath}`,
+    );
+  }
+}
+
+/**
+ * Atomic text write (markdown, decisions, deferred ideas). Same temp+rename strategy.
+ */
+function writeTextAtomic(filePath: string, content: string): UltraPlanStorageResult<string> {
+  try {
+    ensureDir(filePath);
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, content.endsWith("\n") ? content : `${content}\n`);
+    fs.renameSync(tmpPath, filePath);
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to write ${filePath}`,
+    );
+  }
+}
+
+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 readTextFile(filePath: string): UltraPlanStorageResult<string> {
+  if (!fs.existsSync(filePath)) {
+    return failure(filePath, "missing", `Artifact not found: ${filePath}`);
+  }
+  try {
+    return success(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to read ${filePath}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Authoring state (the manifest's `authoring` block).
+//
+// The state lives inside the manifest, not in a sibling file: the manifest is already the
+// canonical truth for "what session is this and what state is it in," and the authoring
+// block is just an extension of that. We expose load/save helpers that go through the
+// manifest so callers don't need to know the embedding.
+// ---------------------------------------------------------------------------
+
+/**
+ * Load just the authoring block from the manifest. Returns `null` (wrapped in success) when
+ * the manifest exists but has no authoring block — this is the common case for legacy
+ * single-shot sessions and for sessions that have been promoted to `state: "ready"`.
+ */
+export function loadAuthoringState(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanAuthoringState | null> {
+  const manifestResult = loadUltraPlanManifest(paths, cwd, sessionId);
+  if (!manifestResult.ok) return manifestResult;
+  return success(manifestResult.value.authoring ?? null);
+}
+
+/**
+ * Persist the authoring state by overwriting the manifest's `authoring` field. The full
+ * manifest is round-tripped through schema validation before being written, so this also
+ * implicitly validates the authoring block against `UltraPlanAuthoringStateSchema`.
+ *
+ * Pre-validates the authoring block independently for a clearer error path — callers see
+ * the authoring-specific errors instead of a manifest-shaped error message.
+ */
+export function saveAuthoringState(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  authoring: UltraPlanAuthoringState,
+): UltraPlanStorageResult<string> {
+  const validation = validateUltraPlanAuthoringState(authoring);
+  if (!validation.ok) {
+    return failure(
+      "authoring-state",
+      "validation-error",
+      "Authoring state failed schema validation",
+      validation.errors,
+    );
+  }
+
+  const manifestResult = loadUltraPlanManifest(paths, cwd, sessionId);
+  if (!manifestResult.ok) return manifestResult;
+
+  const next = { ...manifestResult.value, authoring: validation.value, updatedAt: new Date().toISOString() };
+  const saved = saveUltraPlanManifest(paths, cwd, sessionId, next);
+  return saved;
+}
+
+/**
+ * Clear the authoring block. Used by the APPROVE stage after the canonical artifacts are
+ * promoted. Equivalent to `saveAuthoringState` with `undefined`, but the underlying manifest
+ * schema makes the field optional so we explicitly drop it.
+ */
+export function clearAuthoringState(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<string> {
+  const manifestResult = loadUltraPlanManifest(paths, cwd, sessionId);
+  if (!manifestResult.ok) return manifestResult;
+  const { authoring: _drop, ...rest } = manifestResult.value;
+  void _drop;
+  const next = { ...rest, updatedAt: new Date().toISOString() };
+  return saveUltraPlanManifest(paths, cwd, sessionId, next);
+}
+
+// ---------------------------------------------------------------------------
+// Stage artifacts (intake, scout, discuss, deferred-ideas, research/<stack>.md, drafts).
+// JSON artifacts go through schema validation; markdown artifacts are stored as opaque text.
+// ---------------------------------------------------------------------------
+
+export function saveIntakeArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  artifact: unknown,
+): UltraPlanStorageResult<string> {
+  // The intake schema is owned by the intake stage runner (Phase 3) — at the substrate level
+  // we accept any JSON that round-trips, so legacy callers and tests can drop any object.
+  return writeJsonAtomic(getUltraplanAuthoringIntakePath(paths, cwd, sessionId), artifact);
+}
+
+export function loadIntakeArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<unknown> {
+  return readJsonFile(getUltraplanAuthoringIntakePath(paths, cwd, sessionId));
+}
+
+export function saveScoutArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  artifact: unknown,
+): UltraPlanStorageResult<string> {
+  return writeJsonAtomic(getUltraplanAuthoringScoutPath(paths, cwd, sessionId), artifact);
+}
+
+export function loadScoutArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<unknown> {
+  return readJsonFile(getUltraplanAuthoringScoutPath(paths, cwd, sessionId));
+}
+
+export function saveDiscussArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(getUltraplanAuthoringDiscussPath(paths, cwd, sessionId), markdown);
+}
+
+export function loadDiscussArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<string> {
+  return readTextFile(getUltraplanAuthoringDiscussPath(paths, cwd, sessionId));
+}
+
+export function saveDeferredIdeas(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(getUltraplanAuthoringDeferredIdeasPath(paths, cwd, sessionId), markdown);
+}
+
+export function loadDeferredIdeas(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<string> {
+  return readTextFile(getUltraplanAuthoringDeferredIdeasPath(paths, cwd, sessionId));
+}
+
+/** Append a single decision JSONL line. Caller is responsible for the schema/shape. */
+export function appendDecisionRecord(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  decision: Record<string, unknown>,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanAuthoringDecisionsPath(paths, cwd, sessionId);
+  try {
+    ensureDir(filePath);
+    fs.appendFileSync(filePath, `${JSON.stringify(decision)}\n`);
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to append decision to ${filePath}`,
+    );
+  }
+}
+
+export function saveResearchStackArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(getUltraplanAuthoringResearchStackPath(paths, cwd, sessionId, stack), markdown);
+}
+
+export function loadResearchStackArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+): UltraPlanStorageResult<string> {
+  return readTextFile(getUltraplanAuthoringResearchStackPath(paths, cwd, sessionId, stack));
+}
+
+/**
+ * Remove a per-stack research artifact. Used when a stack flips from `applicable` to
+ * `not-applicable` mid-pipeline (the skip-stack invariant in Phase 5). Missing files are a
+ * no-op, not an error.
+ */
+export function deleteResearchStackArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanAuthoringResearchStackPath(paths, cwd, sessionId, stack);
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to delete ${filePath}`,
+    );
+  }
+}
+
+export function saveResearchSummary(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(getUltraplanAuthoringResearchSummaryPath(paths, cwd, sessionId), markdown);
+}
+
+export function loadResearchSummary(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<string> {
+  return readTextFile(getUltraplanAuthoringResearchSummaryPath(paths, cwd, sessionId));
+}
+
+// ---------------------------------------------------------------------------
+// Drafts: per-iteration directories under `drafts/iteration-N/`.
+// ---------------------------------------------------------------------------
+
+export function ensureDraftIterationDir(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): string {
+  const dir = getUltraplanAuthoringDraftIterationDir(paths, cwd, sessionId, iteration);
+  ensureDirExists(dir);
+  return dir;
+}
+
+export function saveDraftAuthoredJson(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+  artifact: unknown,
+): UltraPlanStorageResult<string> {
+  return writeJsonAtomic(
+    getUltraplanAuthoringDraftAuthoredJsonPath(paths, cwd, sessionId, iteration),
+    artifact,
+  );
+}
+
+export function loadDraftAuthoredJson(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): UltraPlanStorageResult<unknown> {
+  return readJsonFile(getUltraplanAuthoringDraftAuthoredJsonPath(paths, cwd, sessionId, iteration));
+}
+
+export function saveDraftAuthoredMarkdown(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(
+    getUltraplanAuthoringDraftAuthoredMarkdownPath(paths, cwd, sessionId, iteration),
+    markdown,
+  );
+}
+
+export function loadDraftAuthoredMarkdown(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): UltraPlanStorageResult<string> {
+  return readTextFile(getUltraplanAuthoringDraftAuthoredMarkdownPath(paths, cwd, sessionId, iteration));
+}
+
+/**
+ * Snapshot the planner's emitted draft before any user editing happens. Stored alongside the
+ * editable draft so forensics can compare what the planner wrote vs. what the user shipped.
+ */
+export function saveDraftPlannerJson(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+  artifact: unknown,
+): UltraPlanStorageResult<string> {
+  return writeJsonAtomic(
+    getUltraplanAuthoringDraftPlannerJsonPath(paths, cwd, sessionId, iteration),
+    artifact,
+  );
+}
+
+export function saveFindingsArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+  findings: UltraPlanAuthoringFindingsArtifact,
+): UltraPlanStorageResult<string> {
+  const validation = validateUltraPlanAuthoringFindingsArtifact(findings);
+  if (!validation.ok) {
+    return failure(
+      "findings-artifact",
+      "validation-error",
+      "Findings artifact failed schema validation",
+      validation.errors,
+    );
+  }
+  return writeJsonAtomic(
+    getUltraplanAuthoringDraftFindingsPath(paths, cwd, sessionId, iteration),
+    validation.value,
+  );
+}
+
+export function loadFindingsArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  iteration: number,
+): UltraPlanStorageResult<UltraPlanAuthoringFindingsArtifact> {
+  const filePath = getUltraplanAuthoringDraftFindingsPath(paths, cwd, sessionId, iteration);
+  const parsed = readJsonFile(filePath);
+  if (!parsed.ok) return parsed;
+  const validation = validateUltraPlanAuthoringFindingsArtifact(parsed.value);
+  if (!validation.ok) {
+    return failure(filePath, "validation-error", `Findings failed schema validation: ${filePath}`, validation.errors);
+  }
+  return success(validation.value);
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline log (append-only JSONL).
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a single event to `pipeline-log.jsonl`. The event is validated against
+ * `UltraPlanAuthoringPipelineEventSchema` so malformed entries never reach disk.
+ *
+ * `fs.appendFileSync` is sufficient here because line-oriented writes < PIPE_BUF are atomic
+ * on POSIX, and Windows serializes `appendFileSync` calls within a process. Concurrent
+ * authoring runs across different session IDs write to different files, so contention is
+ * not a concern.
+ */
+export function appendPipelineLog(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  event: UltraPlanAuthoringPipelineEvent,
+): UltraPlanStorageResult<string> {
+  const validation = validateUltraPlanAuthoringPipelineEvent(event);
+  if (!validation.ok) {
+    return failure(
+      "pipeline-log-event",
+      "validation-error",
+      "Pipeline event failed schema validation",
+      validation.errors,
+    );
+  }
+
+  const filePath = getUltraplanAuthoringPipelineLogPath(paths, cwd, sessionId);
+  try {
+    ensureDir(filePath);
+    fs.appendFileSync(filePath, `${JSON.stringify(validation.value)}\n`);
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to append pipeline log entry to ${filePath}`,
+    );
+  }
+}
+
+/**
+ * Read the full pipeline log into memory. Returns an empty array on missing file (this is
+ * the common state on a brand-new authoring session). Lines that fail schema validation are
+ * skipped silently — a corrupt log line should not block the picker or status presenter.
+ */
+export function readPipelineLog(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanAuthoringPipelineEvent[]> {
+  const filePath = getUltraplanAuthoringPipelineLogPath(paths, cwd, sessionId);
+  if (!fs.existsSync(filePath)) {
+    return success([]);
+  }
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to read ${filePath}`,
+    );
+  }
+  const events: UltraPlanAuthoringPipelineEvent[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const validation = validateUltraPlanAuthoringPipelineEvent(parsed);
+    if (validation.ok) {
+      events.push(validation.value);
+    }
+  }
+  return success(events);
+}
+
+/**
+ * Convenience: returns whether an authoring directory exists for the session. Cheap check
+ * used by the resume picker.
+ */
+export function hasAuthoringWorkspace(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): boolean {
+  return fs.existsSync(getUltraplanAuthoringDir(paths, cwd, sessionId));
+}