@anthropologies/claudestory 0.1.3 → 0.1.4

package/dist/index.js

@@ -1441,6 +1441,234 @@ async function initProject(root, options) {
   };
 }
 
+// src/core/snapshot.ts
+import { readdir as readdir3, readFile as readFile3, mkdir as mkdir2, unlink as unlink2 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { join as join5, resolve as resolve4 } from "path";
+import { z as z6 } from "zod";
+var LoadWarningSchema = z6.object({
+  type: z6.string(),
+  file: z6.string(),
+  message: z6.string()
+});
+var SnapshotV1Schema = z6.object({
+  version: z6.literal(1),
+  createdAt: z6.string().datetime({ offset: true }),
+  project: z6.string(),
+  config: ConfigSchema,
+  roadmap: RoadmapSchema,
+  tickets: z6.array(TicketSchema),
+  issues: z6.array(IssueSchema),
+  warnings: z6.array(LoadWarningSchema).optional()
+});
+var MAX_SNAPSHOTS = 20;
+async function saveSnapshot(root, loadResult) {
+  const absRoot = resolve4(root);
+  const snapshotsDir = join5(absRoot, ".story", "snapshots");
+  await mkdir2(snapshotsDir, { recursive: true });
+  const { state, warnings } = loadResult;
+  const now = /* @__PURE__ */ new Date();
+  const filename = formatSnapshotFilename(now);
+  const snapshot = {
+    version: 1,
+    createdAt: now.toISOString(),
+    project: state.config.project,
+    config: state.config,
+    roadmap: state.roadmap,
+    tickets: [...state.tickets],
+    issues: [...state.issues],
+    ...warnings.length > 0 ? {
+      warnings: warnings.map((w) => ({
+        type: w.type,
+        file: w.file,
+        message: w.message
+      }))
+    } : {}
+  };
+  const json = JSON.stringify(snapshot, null, 2) + "\n";
+  const targetPath = join5(snapshotsDir, filename);
+  const wrapDir = join5(absRoot, ".story");
+  await guardPath(targetPath, wrapDir);
+  await atomicWrite(targetPath, json);
+  const pruned = await pruneSnapshots(snapshotsDir);
+  const entries = await listSnapshotFiles(snapshotsDir);
+  return { filename, retained: entries.length, pruned };
+}
+async function loadLatestSnapshot(root) {
+  const snapshotsDir = join5(resolve4(root), ".story", "snapshots");
+  if (!existsSync4(snapshotsDir)) return null;
+  const files = await listSnapshotFiles(snapshotsDir);
+  if (files.length === 0) return null;
+  for (const filename of files) {
+    try {
+      const content = await readFile3(join5(snapshotsDir, filename), "utf-8");
+      const parsed = JSON.parse(content);
+      const snapshot = SnapshotV1Schema.parse(parsed);
+      return { snapshot, filename };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function diffStates(snapshotState, currentState) {
+  const snapTickets = new Map(snapshotState.tickets.map((t) => [t.id, t]));
+  const curTickets = new Map(currentState.tickets.map((t) => [t.id, t]));
+  const ticketsAdded = [];
+  const ticketsRemoved = [];
+  const ticketsStatusChanged = [];
+  for (const [id, cur] of curTickets) {
+    const snap = snapTickets.get(id);
+    if (!snap) {
+      ticketsAdded.push({ id, title: cur.title });
+    } else if (snap.status !== cur.status) {
+      ticketsStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+    }
+  }
+  for (const [id, snap] of snapTickets) {
+    if (!curTickets.has(id)) {
+      ticketsRemoved.push({ id, title: snap.title });
+    }
+  }
+  const snapIssues = new Map(snapshotState.issues.map((i) => [i.id, i]));
+  const curIssues = new Map(currentState.issues.map((i) => [i.id, i]));
+  const issuesAdded = [];
+  const issuesResolved = [];
+  const issuesStatusChanged = [];
+  for (const [id, cur] of curIssues) {
+    const snap = snapIssues.get(id);
+    if (!snap) {
+      issuesAdded.push({ id, title: cur.title });
+    } else if (snap.status !== cur.status) {
+      if (cur.status === "resolved") {
+        issuesResolved.push({ id, title: cur.title });
+      } else {
+        issuesStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+      }
+    }
+  }
+  const snapBlockers = new Map(
+    snapshotState.roadmap.blockers.map((b) => [b.name, b])
+  );
+  const curBlockers = new Map(
+    currentState.roadmap.blockers.map((b) => [b.name, b])
+  );
+  const blockersAdded = [];
+  const blockersCleared = [];
+  for (const [name, cur] of curBlockers) {
+    const snap = snapBlockers.get(name);
+    if (!snap) {
+      blockersAdded.push(name);
+    } else if (!isBlockerCleared(snap) && isBlockerCleared(cur)) {
+      blockersCleared.push(name);
+    }
+  }
+  const snapPhases = snapshotState.roadmap.phases;
+  const curPhases = currentState.roadmap.phases;
+  const snapPhaseMap = new Map(snapPhases.map((p) => [p.id, p]));
+  const curPhaseMap = new Map(curPhases.map((p) => [p.id, p]));
+  const phasesAdded = [];
+  const phasesRemoved = [];
+  const phasesStatusChanged = [];
+  for (const [id, curPhase] of curPhaseMap) {
+    const snapPhase = snapPhaseMap.get(id);
+    if (!snapPhase) {
+      phasesAdded.push({ id, name: curPhase.name });
+    } else {
+      const snapStatus = snapshotState.phaseStatus(id);
+      const curStatus = currentState.phaseStatus(id);
+      if (snapStatus !== curStatus) {
+        phasesStatusChanged.push({
+          id,
+          name: curPhase.name,
+          from: snapStatus,
+          to: curStatus
+        });
+      }
+    }
+  }
+  for (const [id, snapPhase] of snapPhaseMap) {
+    if (!curPhaseMap.has(id)) {
+      phasesRemoved.push({ id, name: snapPhase.name });
+    }
+  }
+  return {
+    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged },
+    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged },
+    blockers: { added: blockersAdded, cleared: blockersCleared },
+    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged }
+  };
+}
+function buildRecap(currentState, snapshotInfo) {
+  const next = nextTicket(currentState);
+  const nextTicketAction = next.kind === "found" ? { id: next.ticket.id, title: next.ticket.title, phase: next.ticket.phase } : null;
+  const highSeverityIssues = currentState.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "critical" || i.severity === "high")
+  ).map((i) => ({ id: i.id, title: i.title, severity: i.severity }));
+  if (!snapshotInfo) {
+    return {
+      snapshot: null,
+      changes: null,
+      suggestedActions: {
+        nextTicket: nextTicketAction,
+        highSeverityIssues,
+        recentlyClearedBlockers: []
+      },
+      partial: false
+    };
+  }
+  const { snapshot, filename } = snapshotInfo;
+  const snapshotState = new ProjectState({
+    tickets: snapshot.tickets,
+    issues: snapshot.issues,
+    roadmap: snapshot.roadmap,
+    config: snapshot.config,
+    handoverFilenames: []
+  });
+  const changes = diffStates(snapshotState, currentState);
+  const recentlyClearedBlockers = changes.blockers.cleared;
+  return {
+    snapshot: { filename, createdAt: snapshot.createdAt },
+    changes,
+    suggestedActions: {
+      nextTicket: nextTicketAction,
+      highSeverityIssues,
+      recentlyClearedBlockers
+    },
+    partial: (snapshot.warnings ?? []).length > 0
+  };
+}
+function formatSnapshotFilename(date) {
+  const y = date.getUTCFullYear();
+  const mo = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  const h = String(date.getUTCHours()).padStart(2, "0");
+  const mi = String(date.getUTCMinutes()).padStart(2, "0");
+  const s = String(date.getUTCSeconds()).padStart(2, "0");
+  const ms = String(date.getUTCMilliseconds()).padStart(3, "0");
+  return `${y}-${mo}-${d}T${h}-${mi}-${s}-${ms}.json`;
+}
+async function listSnapshotFiles(dir) {
+  try {
+    const entries = await readdir3(dir);
+    return entries.filter((f) => f.endsWith(".json") && !f.startsWith(".")).sort().reverse();
+  } catch {
+    return [];
+  }
+}
+async function pruneSnapshots(dir) {
+  const files = await listSnapshotFiles(dir);
+  if (files.length <= MAX_SNAPSHOTS) return 0;
+  const toRemove = files.slice(MAX_SNAPSHOTS);
+  for (const f of toRemove) {
+    try {
+      await unlink2(join5(dir, f));
+    } catch {
+    }
+  }
+  return toRemove.length;
+}
+
 // src/core/output-formatter.ts
 var ExitCode = {
   OK: 0,
@@ -1746,6 +1974,278 @@ function formatHandoverContent(filename, content, format) {
   }
   return content;
 }
+function formatSnapshotResult(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  let line = `Snapshot saved: ${result.filename} (${result.retained} retained`;
+  if (result.pruned > 0) line += `, ${result.pruned} pruned`;
+  line += ")";
+  return line;
+}
+function formatRecap(recap, state, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(recap), null, 2);
+  }
+  const lines = [];
+  if (!recap.snapshot) {
+    lines.push(`# ${escapeMarkdownInline(state.config.project)} \u2014 Recap`);
+    lines.push("");
+    lines.push("No snapshot found. Run `claudestory snapshot` to enable session diffs.");
+    lines.push("");
+    lines.push(`Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete, ${state.blockedCount} blocked`);
+    lines.push(`Issues: ${state.openIssueCount} open`);
+  } else {
+    lines.push(`# ${escapeMarkdownInline(state.config.project)} \u2014 Recap`);
+    lines.push("");
+    lines.push(`Since snapshot: ${recap.snapshot.createdAt}`);
+    if (recap.partial) {
+      lines.push("**Note:** Snapshot was taken from a project with integrity warnings. Diff may be incomplete.");
+    }
+    const changes = recap.changes;
+    const hasChanges = hasAnyChanges(changes);
+    if (!hasChanges) {
+      lines.push("");
+      lines.push("No changes since last snapshot.");
+    } else {
+      if (changes.phases.statusChanged.length > 0) {
+        lines.push("");
+        lines.push("## Phase Transitions");
+        for (const p of changes.phases.statusChanged) {
+          lines.push(`- **${escapeMarkdownInline(p.name)}** (${p.id}): ${p.from} \u2192 ${p.to}`);
+        }
+      }
+      const ticketChanges = changes.tickets;
+      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0) {
+        lines.push("");
+        lines.push("## Tickets");
+        for (const t of ticketChanges.statusChanged) {
+          lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 ${t.from} \u2192 ${t.to}`);
+        }
+        for (const t of ticketChanges.added) {
+          lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 **new**`);
+        }
+        for (const t of ticketChanges.removed) {
+          lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 **removed**`);
+        }
+      }
+      const issueChanges = changes.issues;
+      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0) {
+        lines.push("");
+        lines.push("## Issues");
+        for (const i of issueChanges.resolved) {
+          lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 **resolved**`);
+        }
+        for (const i of issueChanges.statusChanged) {
+          lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 ${i.from} \u2192 ${i.to}`);
+        }
+        for (const i of issueChanges.added) {
+          lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 **new**`);
+        }
+      }
+      if (changes.blockers.added.length > 0 || changes.blockers.cleared.length > 0) {
+        lines.push("");
+        lines.push("## Blockers");
+        for (const name of changes.blockers.cleared) {
+          lines.push(`- ${escapeMarkdownInline(name)} \u2014 **cleared**`);
+        }
+        for (const name of changes.blockers.added) {
+          lines.push(`- ${escapeMarkdownInline(name)} \u2014 **new**`);
+        }
+      }
+    }
+  }
+  const actions = recap.suggestedActions;
+  lines.push("");
+  lines.push("## Suggested Actions");
+  if (actions.nextTicket) {
+    lines.push(`- **Next:** ${actions.nextTicket.id} \u2014 ${escapeMarkdownInline(actions.nextTicket.title)}${actions.nextTicket.phase ? ` (${actions.nextTicket.phase})` : ""}`);
+  }
+  if (actions.highSeverityIssues.length > 0) {
+    for (const i of actions.highSeverityIssues) {
+      lines.push(`- **${i.severity} issue:** ${i.id} \u2014 ${escapeMarkdownInline(i.title)}`);
+    }
+  }
+  if (actions.recentlyClearedBlockers.length > 0) {
+    lines.push(`- **Recently cleared:** ${actions.recentlyClearedBlockers.map(escapeMarkdownInline).join(", ")}`);
+  }
+  if (!actions.nextTicket && actions.highSeverityIssues.length === 0 && actions.recentlyClearedBlockers.length === 0) {
+    lines.push("- No urgent actions.");
+  }
+  return lines.join("\n");
+}
+function formatExport(state, mode, phaseId, format) {
+  if (mode === "phase" && phaseId) {
+    return formatPhaseExport(state, phaseId, format);
+  }
+  return formatFullExport(state, format);
+}
+function formatPhaseExport(state, phaseId, format) {
+  const phase = state.roadmap.phases.find((p) => p.id === phaseId);
+  if (!phase) {
+    return formatError("not_found", `Phase "${phaseId}" not found`, format);
+  }
+  const phaseStatus = state.phaseStatus(phaseId);
+  const leaves = state.phaseTickets(phaseId);
+  const umbrellaAncestors = /* @__PURE__ */ new Map();
+  for (const leaf of leaves) {
+    if (leaf.parentTicket) {
+      const parent = state.ticketByID(leaf.parentTicket);
+      if (parent && !umbrellaAncestors.has(parent.id)) {
+        umbrellaAncestors.set(parent.id, parent);
+      }
+    }
+  }
+  const crossPhaseDeps = /* @__PURE__ */ new Map();
+  for (const leaf of leaves) {
+    for (const blockerId of leaf.blockedBy) {
+      const blocker = state.ticketByID(blockerId);
+      if (blocker && blocker.phase !== phaseId && !crossPhaseDeps.has(blocker.id)) {
+        crossPhaseDeps.set(blocker.id, blocker);
+      }
+    }
+  }
+  const relatedIssues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.phase === phaseId || i.relatedTickets.some((tid) => {
+      const t = state.ticketByID(tid);
+      return t && t.phase === phaseId;
+    }))
+  );
+  const activeBlockers = state.roadmap.blockers.filter(
+    (b) => !isBlockerCleared(b)
+  );
+  if (format === "json") {
+    return JSON.stringify(
+      successEnvelope({
+        phase: { id: phase.id, name: phase.name, description: phase.description, status: phaseStatus },
+        tickets: leaves.map((t) => ({ id: t.id, title: t.title, status: t.status, type: t.type, order: t.order })),
+        umbrellaAncestors: [...umbrellaAncestors.values()].map((t) => ({ id: t.id, title: t.title })),
+        crossPhaseDependencies: [...crossPhaseDeps.values()].map((t) => ({ id: t.id, title: t.title, status: t.status, phase: t.phase })),
+        issues: relatedIssues.map((i) => ({ id: i.id, title: i.title, severity: i.severity, status: i.status })),
+        blockers: activeBlockers.map((b) => ({ name: b.name, note: b.note ?? null }))
+      }),
+      null,
+      2
+    );
+  }
+  const lines = [];
+  lines.push(`# ${escapeMarkdownInline(phase.name)} (${phase.id})`);
+  lines.push("");
+  lines.push(`Status: ${phaseStatus}`);
+  if (phase.description) {
+    lines.push(`Description: ${escapeMarkdownInline(phase.description)}`);
+  }
+  if (leaves.length > 0) {
+    lines.push("");
+    lines.push("## Tickets");
+    for (const t of leaves) {
+      const indicator = t.status === "complete" ? "[x]" : t.status === "inprogress" ? "[~]" : "[ ]";
+      const parentNote = t.parentTicket && umbrellaAncestors.has(t.parentTicket) ? ` (under ${t.parentTicket})` : "";
+      lines.push(`${indicator} ${t.id}: ${escapeMarkdownInline(t.title)}${parentNote}`);
+    }
+  }
+  if (crossPhaseDeps.size > 0) {
+    lines.push("");
+    lines.push("## Cross-Phase Dependencies");
+    for (const [, dep] of crossPhaseDeps) {
+      lines.push(`- ${dep.id}: ${escapeMarkdownInline(dep.title)} [${dep.status}] (${dep.phase ?? "unphased"})`);
+    }
+  }
+  if (relatedIssues.length > 0) {
+    lines.push("");
+    lines.push("## Open Issues");
+    for (const i of relatedIssues) {
+      lines.push(`- ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}`);
+    }
+  }
+  if (activeBlockers.length > 0) {
+    lines.push("");
+    lines.push("## Active Blockers");
+    for (const b of activeBlockers) {
+      lines.push(`- ${escapeMarkdownInline(b.name)}${b.note ? ` \u2014 ${escapeMarkdownInline(b.note)}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatFullExport(state, format) {
+  const phases = phasesWithStatus(state);
+  if (format === "json") {
+    return JSON.stringify(
+      successEnvelope({
+        project: state.config.project,
+        phases: phases.map((p) => ({
+          id: p.phase.id,
+          name: p.phase.name,
+          description: p.phase.description,
+          status: p.status,
+          tickets: state.phaseTickets(p.phase.id).map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            type: t.type
+          }))
+        })),
+        issues: state.issues.map((i) => ({
+          id: i.id,
+          title: i.title,
+          severity: i.severity,
+          status: i.status
+        })),
+        blockers: state.roadmap.blockers.map((b) => ({
+          name: b.name,
+          cleared: isBlockerCleared(b),
+          note: b.note ?? null
+        }))
+      }),
+      null,
+      2
+    );
+  }
+  const lines = [];
+  lines.push(`# ${escapeMarkdownInline(state.config.project)} \u2014 Full Export`);
+  lines.push("");
+  lines.push(`Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete`);
+  lines.push(`Issues: ${state.openIssueCount} open`);
+  lines.push("");
+  lines.push("## Phases");
+  for (const p of phases) {
+    const indicator = p.status === "complete" ? "[x]" : p.status === "inprogress" ? "[~]" : "[ ]";
+    lines.push("");
+    lines.push(`### ${indicator} ${escapeMarkdownInline(p.phase.name)} (${p.phase.id})`);
+    if (p.phase.description) {
+      lines.push(escapeMarkdownInline(p.phase.description));
+    }
+    const tickets = state.phaseTickets(p.phase.id);
+    if (tickets.length > 0) {
+      lines.push("");
+      for (const t of tickets) {
+        const ti = t.status === "complete" ? "[x]" : t.status === "inprogress" ? "[~]" : "[ ]";
+        lines.push(`${ti} ${t.id}: ${escapeMarkdownInline(t.title)}`);
+      }
+    }
+  }
+  if (state.issues.length > 0) {
+    lines.push("");
+    lines.push("## Issues");
+    for (const i of state.issues) {
+      const resolved = i.status === "resolved" ? " \u2713" : "";
+      lines.push(`- ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}${resolved}`);
+    }
+  }
+  const blockers = state.roadmap.blockers;
+  if (blockers.length > 0) {
+    lines.push("");
+    lines.push("## Blockers");
+    for (const b of blockers) {
+      const cleared = isBlockerCleared(b) ? "[x]" : "[ ]";
+      lines.push(`${cleared} ${escapeMarkdownInline(b.name)}${b.note ? ` \u2014 ${escapeMarkdownInline(b.note)}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function hasAnyChanges(diff) {
+  return diff.tickets.added.length > 0 || diff.tickets.removed.length > 0 || diff.tickets.statusChanged.length > 0 || diff.issues.added.length > 0 || diff.issues.resolved.length > 0 || diff.issues.statusChanged.length > 0 || diff.blockers.added.length > 0 || diff.blockers.cleared.length > 0 || diff.phases.added.length > 0 || diff.phases.removed.length > 0 || diff.phases.statusChanged.length > 0;
+}
 function truncate(text, maxLen) {
   if (text.length <= maxLen) return text;
   return text.slice(0, maxLen - 3) + "...";
@@ -1775,15 +2275,19 @@ export {
   ProjectLoaderError,
   ProjectState,
   RoadmapSchema,
+  SnapshotV1Schema,
   TICKET_ID_REGEX,
   TICKET_STATUSES,
   TICKET_TYPES,
   TicketIdSchema,
   TicketSchema,
+  atomicWrite,
   blockedTickets,
+  buildRecap,
   currentPhase,
   deleteIssue,
   deleteTicket,
+  diffStates,
   discoverProjectRoot,
   errorEnvelope,
   escapeMarkdownInline,
@@ -1792,6 +2296,7 @@ export {
   formatBlockedTickets,
   formatBlockerList,
   formatError,
+  formatExport,
   formatHandoverContent,
   formatHandoverList,
   formatInitResult,
@@ -1800,13 +2305,17 @@ export {
   formatNextTicketOutcome,
   formatPhaseList,
   formatPhaseTickets,
+  formatRecap,
+  formatSnapshotResult,
   formatStatus,
   formatTicket,
   formatTicketList,
   formatValidation,
+  guardPath,
   initProject,
   isBlockerCleared,
   listHandovers,
+  loadLatestSnapshot,
   loadProject,
   mergeValidation,
   nextIssueID,
@@ -1818,6 +2327,7 @@ export {
   readHandover,
   runTransaction,
   runTransactionUnlocked,
+  saveSnapshot,
   serializeJSON,
   sortKeysDeep,
   successEnvelope,