@pellux/goodvibes-tui 1.20.0 → 1.21.0

package/src/work-plans/work-plan-store.ts

@@ -1,7 +1,69 @@
+// ---------------------------------------------------------------------------
+// work-plan-store.ts — per-project work plan persisted at
+//   <home>/.goodvibes/tui/work-plans/<projectId>.json
+//
+// Recovery discipline (applies to every read):
+//
+//  * CONTENT, NOT EXISTENCE, decides whether the file is usable. A plan file
+//    can exist and still be unusable — zero-byte, truncated mid-write, or
+//    otherwise torn by a crash. Every read parses defensively and validates the
+//    parsed SHAPE; an unusable file degrades to an empty plan instead of
+//    throwing out of the store's public methods (which used to brick every
+//    /work-plan operation until the user deleted the file by hand).
+//  * AN UNREADABLE FILE IS PRESERVED, NOT OVERWRITTEN. It is renamed aside to
+//    `<plan>.json.corrupt-<ms>-<rand>` so a user can still recover their list.
+//    Those quarantine copies are themselves bounded (age TTL + count cap) so
+//    the recovery path cannot become its own leak.
+//  * THE STORE IS BOUNDED. Terminal (done/cancelled) items age out and are
+//    capped by count. Items the user still has open — pending, in_progress,
+//    blocked, failed — are NEVER reclaimed by either bound: garbage collection
+//    must not delete live work.
+//  * NOTHING IS DELETED SILENTLY. Whatever a sweep reclaimed is recorded on the
+//    plan as `housekeeping` and rendered by `toMarkdown()` (which /work-plan
+//    show prints), so a reclaim is distinguishable from data loss.
+//
+// Sweeps are idempotent and safe to run from more than one process: removal is
+// computed from the file's own contents, writes go through atomicWriteFileSync
+// (rename(2)), and unlink races are treated as already-done.
+// ---------------------------------------------------------------------------
+
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { readdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
 import { atomicWriteFileSync } from '@/config/atomic-write.ts';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+
+/**
+ * Age TTL for TERMINAL (done/cancelled) items. Once a completed or cancelled
+ * item has been untouched this long it is reclaimed by the next read. Chosen to
+ * comfortably outlive "I finished that last month and want to see it" while
+ * still bounding a plan that is never manually cleared.
+ */
+export const WORK_PLAN_TERMINAL_ITEM_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+/**
+ * Count cap for TERMINAL (done/cancelled) items: the most recently completed
+ * this many are kept, older ones are reclaimed oldest-first. Live items are
+ * neither counted against this cap nor removed by it.
+ */
+export const WORK_PLAN_TERMINAL_ITEM_CAP = 200;
+
+/** Age TTL for quarantined (unreadable) plan files — the recovery copy's own bound. */
+export const WORK_PLAN_QUARANTINE_TTL_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
+
+/** Count cap for quarantined plan files kept alongside one plan; oldest go first. */
+export const WORK_PLAN_QUARANTINE_CAP = 5;
+
+/**
+ * Minimum gap between quarantine-directory scans for one store instance. The
+ * item bounds are evaluated on every read (they are a pure pass over in-memory
+ * items); the directory scan is throttled so a redrawing modal cannot turn it
+ * into a per-frame readdir. This is what makes the sweep periodic rather than
+ * startup-only: a long-lived session keeps sweeping on this cadence.
+ */
+export const WORK_PLAN_QUARANTINE_SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+/** Filename marker for a preserved copy of a plan file that could not be parsed. */
+const QUARANTINE_SUFFIX = '.corrupt-';
 
 export const WORK_PLAN_STATUSES = [
   'pending',
@@ -34,6 +96,26 @@ export interface WorkPlanItem {
   readonly completedAt?: number;
 }
 
+/**
+ * What the last recovery/bounding sweep reclaimed. Persisted with the plan and
+ * rendered by `toMarkdown()` so a removal is always disclosed — counts and
+ * paths only, never item text.
+ */
+export interface WorkPlanHousekeeping {
+  /** Unix ms of the sweep that produced these counts. */
+  readonly at: number;
+  /** Terminal items reclaimed by the age TTL. */
+  readonly expiredItems: number;
+  /** Terminal items reclaimed by the count cap. */
+  readonly cappedItems: number;
+  /** True when the plan file on disk could not be parsed and the plan was reset. */
+  readonly resetFromUnreadableFile?: boolean;
+  /** Where the unreadable file was preserved, when there was content worth keeping. */
+  readonly quarantinePath?: string;
+  /** Quarantined files removed by their own TTL / count cap. */
+  readonly quarantinesRemoved?: number;
+}
+
 export interface WorkPlan {
   readonly id: string;
   readonly projectId: string;
@@ -44,6 +126,8 @@ export interface WorkPlan {
   readonly source?: string;
   readonly createdAt: number;
   readonly updatedAt: number;
+  /** Result of the most recent sweep that actually reclaimed something. */
+  readonly housekeeping?: WorkPlanHousekeeping;
 }
 
 export interface WorkPlanStoreOptions {
@@ -147,6 +231,70 @@ function formatStatus(status: WorkPlanItemStatus): string {
   return status.replace(/_/g, ' ');
 }
 
+/**
+ * Terminal = the user is done with it. Only these two statuses are eligible for
+ * the age TTL and the count cap. `blocked` and `failed` still need attention and
+ * `pending`/`in_progress` are live, so none of them are ever auto-reclaimed.
+ */
+function isTerminalStatus(status: WorkPlanItemStatus): boolean {
+  return status === 'done' || status === 'cancelled';
+}
+
+/** The timestamp a terminal item is aged from. */
+function terminalAgeStamp(item: WorkPlanItem): number {
+  return item.completedAt ?? item.updatedAt ?? item.createdAt;
+}
+
+function normalizeHousekeeping(value: unknown): WorkPlanHousekeeping | undefined {
+  if (!isObject(value)) return undefined;
+  if (typeof value.at !== 'number') return undefined;
+  const expiredItems = typeof value.expiredItems === 'number' ? value.expiredItems : 0;
+  const cappedItems = typeof value.cappedItems === 'number' ? value.cappedItems : 0;
+  const quarantinePath = readString(value.quarantinePath);
+  const quarantinesRemoved = typeof value.quarantinesRemoved === 'number' ? value.quarantinesRemoved : undefined;
+  return {
+    at: value.at,
+    expiredItems,
+    cappedItems,
+    ...(value.resetFromUnreadableFile === true ? { resetFromUnreadableFile: true } : {}),
+    ...(quarantinePath ? { quarantinePath } : {}),
+    ...(quarantinesRemoved !== undefined ? { quarantinesRemoved } : {}),
+  };
+}
+
+/**
+ * Parse a plan file's CONTENT. Returns null for anything that is not a JSON
+ * object — empty/whitespace-only (a zero-byte file left by a crash), truncated
+ * JSON, or a valid JSON scalar/array. Never throws.
+ */
+function parsePlanDocument(raw: string): Record<string, unknown> | null {
+  if (raw.trim().length === 0) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  return isObject(parsed) ? parsed : null;
+}
+
+/** One-line, content-free disclosure of what the last sweep reclaimed. */
+function formatHousekeeping(record: WorkPlanHousekeeping): string {
+  const parts: string[] = [];
+  if (record.resetFromUnreadableFile) {
+    parts.push(record.quarantinePath
+      ? `the previous plan file could not be read and was preserved at ${record.quarantinePath}`
+      : 'the previous plan file was empty or unreadable and was reset');
+  }
+  if (record.expiredItems > 0) parts.push(`${record.expiredItems} completed item(s) aged out`);
+  if (record.cappedItems > 0) parts.push(`${record.cappedItems} completed item(s) over the retention cap removed`);
+  if (record.quarantinesRemoved && record.quarantinesRemoved > 0) {
+    parts.push(`${record.quarantinesRemoved} old quarantined plan file(s) deleted`);
+  }
+  if (parts.length === 0) parts.push('nothing reclaimed');
+  return `Housekeeping (${new Date(record.at).toISOString()}): ${parts.join('; ')}.`;
+}
+
 export function nextWorkPlanStatus(status: WorkPlanItemStatus): WorkPlanItemStatus {
   switch (status) {
     case 'pending':
@@ -165,6 +313,12 @@ export function nextWorkPlanStatus(status: WorkPlanItemStatus): WorkPlanItemStat
 export class WorkPlanStore {
   readonly filePath: string;
 
+  /**
+   * Unix ms of this instance's last quarantine-directory scan. Zero means the
+   * first read of the session sweeps — that read IS the recovery point.
+   */
+  private lastQuarantineSweepAt = 0;
+
   constructor(private readonly options: WorkPlanStoreOptions) {
     const fileName = `${safeFileId(options.projectId, options.projectRoot)}.json`;
     this.filePath = join(options.homeDirectory, '.goodvibes', 'tui', 'work-plans', fileName);
@@ -287,8 +441,11 @@ export class WorkPlanStore {
       `Project: ${plan.projectRoot}`,
       `Project ID: ${plan.projectId}`,
       `Updated: ${new Date(plan.updatedAt).toISOString()}`,
-      '',
     ];
+    // Disclosure: whatever the last sweep reclaimed is stated here, so a
+    // removal can never be mistaken for silent data loss.
+    if (plan.housekeeping) lines.push(formatHousekeeping(plan.housekeeping));
+    lines.push('');
     if (plan.items.length === 0) {
       lines.push('No work plan items recorded.');
       return lines.join('\n');
@@ -304,11 +461,49 @@ export class WorkPlanStore {
     return lines.join('\n');
   }
 
+  /**
+   * The plan as callers see it: loaded from disk (content-validated), then put
+   * through the recovery/bounding sweep. When the sweep reclaimed anything the
+   * bounded plan — carrying its housekeeping disclosure — is written back
+   * immediately, so the disclosure survives even if the caller only reads.
+   */
   private readPlan(): WorkPlan {
-    if (!existsSync(this.filePath)) return this.createEmptyPlan();
-    const raw = readFileSync(this.filePath, 'utf8');
-    const parsed = JSON.parse(raw) as unknown;
-    if (!isObject(parsed)) return this.createEmptyPlan();
+    const loaded = this.loadFromDisk();
+    const swept = this.sweep(loaded.plan, loaded.recovery);
+    if (swept.changed) this.writePlan(swept.plan);
+    return swept.plan;
+  }
+
+  /**
+   * Read and validate the plan file's CONTENT. A missing file is the ordinary
+   * empty case. A file that exists but does not parse into a plan object is
+   * moved aside (never overwritten in place) and reported as a recovery.
+   */
+  private loadFromDisk(): { plan: WorkPlan; recovery: WorkPlanHousekeeping | null } {
+    let raw: string;
+    try {
+      raw = readFileSync(this.filePath, 'utf8');
+    } catch {
+      // No file yet (the common first-run case), or it is unreadable right now.
+      // Nothing existed to preserve, so there is nothing to disclose.
+      return { plan: this.createEmptyPlan(), recovery: null };
+    }
+    const parsed = parsePlanDocument(raw);
+    if (parsed === null) {
+      // The file EXISTED but its contents are not a usable plan: zero-byte,
+      // truncated mid-write, or otherwise torn. Existence is not validity.
+      const quarantinePath = raw.trim().length > 0 ? this.quarantineUnreadableFile() : undefined;
+      return {
+        plan: this.createEmptyPlan(),
+        recovery: {
+          at: nowMs(),
+          expiredItems: 0,
+          cappedItems: 0,
+          resetFromUnreadableFile: true,
+          ...(quarantinePath ? { quarantinePath } : {}),
+        },
+      };
+    }
     const time = nowMs();
     const createdAt = typeof parsed.createdAt === 'number' ? parsed.createdAt : time;
     const updatedAt = typeof parsed.updatedAt === 'number' ? parsed.updatedAt : createdAt;
@@ -317,19 +512,142 @@ export class WorkPlanStore {
       : [];
     const activeItemId = readString(parsed.activeItemId);
     const source = readString(parsed.source);
+    const housekeeping = normalizeHousekeeping(parsed.housekeeping);
+    return {
+      plan: {
+        id: readString(parsed.id) ?? createPlanId(this.options.projectId, this.options.projectRoot),
+        projectId: readString(parsed.projectId) ?? this.options.projectId,
+        projectRoot: readString(parsed.projectRoot) ?? this.options.projectRoot,
+        title: readString(parsed.title) ?? 'Work Plan',
+        items,
+        ...(activeItemId && items.some((item) => item.id === activeItemId) ? { activeItemId } : {}),
+        ...(source ? { source } : {}),
+        createdAt,
+        updatedAt,
+        ...(housekeeping ? { housekeeping } : {}),
+      },
+      recovery: null,
+    };
+  }
+
+  /**
+   * Apply both bounds (age TTL, then count cap) over TERMINAL items only, plus
+   * the throttled quarantine-file sweep. Pure with respect to disk except for
+   * quarantine deletions; the caller persists the result when `changed`.
+   *
+   * Idempotent: re-running it on the returned plan reclaims nothing further,
+   * which is what makes it safe to run concurrently from several processes.
+   */
+  private sweep(
+    plan: WorkPlan,
+    recovery: WorkPlanHousekeeping | null,
+  ): { plan: WorkPlan; changed: boolean } {
+    const now = nowMs();
+    const expired = new Set<WorkPlanItem>();
+    for (const item of plan.items) {
+      if (!isTerminalStatus(item.status)) continue;
+      if (now - terminalAgeStamp(item) > WORK_PLAN_TERMINAL_ITEM_TTL_MS) expired.add(item);
+    }
+    const survivors = plan.items.filter((item) => !expired.has(item));
+    // Count cap applies to terminal survivors only — newest completions kept.
+    const terminalSurvivors = survivors
+      .filter((item) => isTerminalStatus(item.status))
+      .sort((a, b) => terminalAgeStamp(b) - terminalAgeStamp(a));
+    const capped = new Set<WorkPlanItem>(terminalSurvivors.slice(WORK_PLAN_TERMINAL_ITEM_CAP));
+    const kept = survivors.filter((item) => !capped.has(item));
+    const quarantinesRemoved = this.sweepQuarantines(now);
+
+    const changed = expired.size > 0 || capped.size > 0 || recovery !== null || quarantinesRemoved > 0;
+    if (!changed) return { plan, changed: false };
+
+    const housekeeping: WorkPlanHousekeeping = {
+      at: now,
+      expiredItems: expired.size,
+      cappedItems: capped.size,
+      ...(recovery?.resetFromUnreadableFile ? { resetFromUnreadableFile: true } : {}),
+      ...(recovery?.quarantinePath ? { quarantinePath: recovery.quarantinePath } : {}),
+      ...(quarantinesRemoved > 0 ? { quarantinesRemoved } : {}),
+    };
+    const activeItemId = plan.activeItemId && kept.some((item) => item.id === plan.activeItemId)
+      ? plan.activeItemId
+      : undefined;
     return {
-      id: readString(parsed.id) ?? createPlanId(this.options.projectId, this.options.projectRoot),
-      projectId: readString(parsed.projectId) ?? this.options.projectId,
-      projectRoot: readString(parsed.projectRoot) ?? this.options.projectRoot,
-      title: readString(parsed.title) ?? 'Work Plan',
-      items,
-      ...(activeItemId && items.some((item) => item.id === activeItemId) ? { activeItemId } : {}),
-      ...(source ? { source } : {}),
-      createdAt,
-      updatedAt,
+      plan: {
+        id: plan.id,
+        projectId: plan.projectId,
+        projectRoot: plan.projectRoot,
+        title: plan.title,
+        items: kept,
+        ...(activeItemId ? { activeItemId } : {}),
+        ...(plan.source ? { source: plan.source } : {}),
+        createdAt: plan.createdAt,
+        // `updatedAt` tracks the user's edits; a garbage-collection pass is not
+        // one, so it is deliberately left alone. housekeeping.at dates the sweep.
+        updatedAt: plan.updatedAt,
+        housekeeping,
+      },
+      changed: true,
     };
   }
 
+  /**
+   * Move an unparseable plan file aside so the user can still recover it.
+   * Returns the quarantine path, or undefined if the rename did not happen
+   * (already moved by a concurrent process, or the directory is not writable).
+   */
+  private quarantineUnreadableFile(): string | undefined {
+    const target = `${this.filePath}${QUARANTINE_SUFFIX}${nowMs()}-${randomUUID().slice(0, 8)}`;
+    try {
+      renameSync(this.filePath, target);
+      return target;
+    } catch {
+      // Gone already (another process quarantined it first) or unwritable —
+      // either way the plan still degrades to empty rather than throwing.
+      return undefined;
+    }
+  }
+
+  /**
+   * Bound the quarantine copies: delete any past WORK_PLAN_QUARANTINE_TTL_MS
+   * and any beyond WORK_PLAN_QUARANTINE_CAP (oldest first). Throttled to
+   * WORK_PLAN_QUARANTINE_SWEEP_INTERVAL_MS per store instance so a long-lived
+   * session keeps sweeping without scanning the directory on every read.
+   */
+  private sweepQuarantines(now: number): number {
+    if (now - this.lastQuarantineSweepAt < WORK_PLAN_QUARANTINE_SWEEP_INTERVAL_MS) return 0;
+    this.lastQuarantineSweepAt = now;
+    const directory = dirname(this.filePath);
+    const prefix = `${basename(this.filePath)}${QUARANTINE_SUFFIX}`;
+    let entries: string[];
+    try {
+      entries = readdirSync(directory);
+    } catch {
+      return 0;
+    }
+    const candidates = entries
+      .filter((entry) => entry.startsWith(prefix))
+      .map((entry) => {
+        const stamp = Number.parseInt(entry.slice(prefix.length).split('-')[0] ?? '', 10);
+        return { entry, at: Number.isFinite(stamp) ? stamp : 0 };
+      })
+      .sort((a, b) => b.at - a.at); // newest first
+    let removed = 0;
+    for (let index = 0; index < candidates.length; index += 1) {
+      const candidate = candidates[index]!;
+      const tooOld = now - candidate.at > WORK_PLAN_QUARANTINE_TTL_MS;
+      const overCap = index >= WORK_PLAN_QUARANTINE_CAP;
+      if (!tooOld && !overCap) continue;
+      try {
+        unlinkSync(join(directory, candidate.entry));
+        removed += 1;
+      } catch {
+        // Already removed by a concurrent sweep — idempotent, not an error, and
+        // not counted so the disclosed number stays truthful.
+      }
+    }
+    return removed;
+  }
+
   private createEmptyPlan(): WorkPlan {
     const time = nowMs();
     return {