memoir-cli 3.8.1 → 3.10.0

package/src/session/state.js

@@ -9,13 +9,25 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
+import { withSessionLock } from './lock.js';
+import { SCHEMA_VERSION, migrateSessionData, emptySession } from './migrations.js';
+// NOTE: events/log.js imports getMachineId FROM this module — this is a
+// circular import, safe here because both appendEvent (used below) and
+// getMachineId (used by events/log.js) are hoisted function declarations
+// used only inside other functions' bodies, never at module-evaluation
+// time. Verified working; see test-event-log.mjs.
+import { appendEvent } from '../events/log.js';
 
 const home = os.homedir();
 const CONFIG_DIR = path.join(home, '.config', 'memoir');
 const SESSION_PATH = path.join(CONFIG_DIR, 'session.json');
 const MACHINE_ID_PATH = path.join(CONFIG_DIR, 'machine.id');
+const SESSION_LOCK_PATH = path.join(CONFIG_DIR, 'session.json.lock');
 
-export const SCHEMA_VERSION = 1;
+// Re-exported for external consumers (e.g. test-session.mjs asserts against
+// state.SCHEMA_VERSION) — the canonical constant now lives in migrations.js
+// alongside the migration ladder it governs.
+export { SCHEMA_VERSION, emptySession };
 
 // Maximum items kept in each list before oldest entries rotate into history.
 // Prevents unbounded growth of the live pinned block.
@@ -44,66 +56,107 @@ export async function getMachineId() {
   return { id, label: os.hostname() };
 }
 
-// ── Schema ───────────────────────────────────────────────────────
-
-function emptySession() {
-  return {
-    version: SCHEMA_VERSION,
-    created_at: new Date().toISOString(),
-    updated_at: new Date().toISOString(),
-    machines: {}, // { [machineId]: { label, last_seen } }
-    current: {
-      goals: [],         // { text, machine_id, set_on }
-      next_actions: [],  // { text, machine_id, added, completed? }
-      open_questions: [],// { text, machine_id, asked }
-      decisions: [],     // { text, why?, rejected?, machine_id, date }
-    },
-    history: [],         // { date, machine_id, summary, files_touched, duration_min? }
-  };
-}
-
 // ── Read / write ─────────────────────────────────────────────────
+//
+// Forward-version guard: if session.json's version is NEWER than this
+// build's SCHEMA_VERSION (the file came from a newer memoir install — e.g.
+// another machine upgraded first and this one hasn't yet), readSession()
+// backs up the original file (mirroring the corrupted-JSON quarantine
+// pattern below) and returns a safe, empty-but-valid session instead of
+// misinterpreting an unknown shape. This is centralized HERE, not in
+// individual callers, so all ~20 call sites across mcp.js (8 MCP tool
+// handlers), commands/session.js, commands/why.js, commands/auto-refresh.js,
+// commands/push.js, commands/restore.js automatically get safe behavior
+// with zero changes required at each call site — and critically, no MCP
+// tool call is ever allowed to throw/crash because of a schema mismatch.
+let warnedForwardVersion = false; // print the upgrade warning once per process, not once per call
+
+// Opportunistic cleanup so the .corrupted-<ts> / .pre-migration-<ts> backup
+// patterns don't accumulate forever on a machine that repeatedly hits
+// either quarantine path. Keeps the N most recent of EACH pattern, deletes
+// older ones. Best-effort — a cleanup failure never blocks the caller.
+const MAX_BACKUPS_PER_PATTERN = 3;
+function cleanupOldBackups(suffixPrefix) {
+  try {
+    const dir = path.dirname(SESSION_PATH);
+    const base = path.basename(SESSION_PATH); // "session.json"
+    const marker = `${base}.${suffixPrefix}-`;
+    const matches = fs.readdirSync(dir)
+      .filter((f) => f.startsWith(marker))
+      .map((f) => {
+        let mtime = 0;
+        try { mtime = fs.statSync(path.join(dir, f)).mtimeMs; } catch {}
+        return { name: f, mtime };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+    for (const f of matches.slice(MAX_BACKUPS_PER_PATTERN)) {
+      try { fs.unlinkSync(path.join(dir, f.name)); } catch {}
+    }
+  } catch {
+    // Best-effort — never block the caller.
+  }
+}
 
-// Atomic read with graceful recovery from corrupted JSON.
+// Atomic read with graceful recovery from corrupted JSON AND from a
+// too-new schema version.
 export async function readSession() {
   if (!await fs.pathExists(SESSION_PATH)) return emptySession();
 
+  let raw;
   try {
-    const raw = await fs.readFile(SESSION_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    return migrateIfNeeded(parsed);
-  } catch (err) {
+    raw = await fs.readFile(SESSION_PATH, 'utf8');
+  } catch {
+    // Unreadable (permissions, race with a concurrent delete, etc.) —
+    // degrade to a safe empty session rather than throwing.
+    return emptySession();
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
     // Corrupted — preserve it for inspection, start fresh.
     const backup = `${SESSION_PATH}.corrupted-${Date.now()}`;
     try { await fs.copy(SESSION_PATH, backup); } catch {}
+    cleanupOldBackups('corrupted');
     return emptySession();
   }
+
+  const { future, state } = migrateSessionData(parsed);
+
+  if (future) {
+    const backup = `${SESSION_PATH}.pre-migration-${Date.now()}`;
+    try { await fs.copy(SESSION_PATH, backup); } catch {}
+    cleanupOldBackups('pre-migration');
+    if (!warnedForwardVersion) {
+      warnedForwardVersion = true;
+      try {
+        process.stderr.write(
+          `memoir: session.json is from a newer version of memoir than this install understands ` +
+          `(schema v${parsed?.version} > v${SCHEMA_VERSION}). It has been backed up to ${backup}. ` +
+          `Run: npm i -g memoir-cli@latest\n`
+        );
+      } catch {}
+    }
+  }
+
+  return state;
 }
 
 // Atomic write: write to tmp, rename. Prevents torn writes on crash.
+// Unconditionally stamps version — every write lands at the CURRENT
+// SCHEMA_VERSION, since it always passed through readSession/migrateSessionData
+// (or emptySession()) to get here. Always called from within a locked
+// critical section (see the mutators below and lock.js).
 export async function writeSession(state) {
   await fs.ensureDir(CONFIG_DIR);
+  state.version = SCHEMA_VERSION;
   state.updated_at = new Date().toISOString();
   const tmp = `${SESSION_PATH}.tmp-${process.pid}`;
   await fs.writeFile(tmp, JSON.stringify(state, null, 2));
   await fs.move(tmp, SESSION_PATH, { overwrite: true });
 }
 
-function migrateIfNeeded(state) {
-  if (state && state.version === SCHEMA_VERSION) return state;
-  // Future versions: add migration steps here.
-  // For now, if version mismatch, merge defaults to fill gaps.
-  const fresh = emptySession();
-  return {
-    ...fresh,
-    ...state,
-    version: SCHEMA_VERSION,
-    current: { ...fresh.current, ...(state?.current || {}) },
-    machines: { ...fresh.machines, ...(state?.machines || {}) },
-    history: Array.isArray(state?.history) ? state.history : [],
-  };
-}
-
 // ── Machine registration ────────────────────────────────────────
 
 async function touchMachine(state) {
@@ -117,98 +170,123 @@ async function touchMachine(state) {
 
 // ── Mutators ────────────────────────────────────────────────────
 
+// Every mutator below wraps its ENTIRE read -> mutate -> write cycle in
+// withSessionLock — not just the write. Locking only the write would still
+// allow two processes to both read the same stale snapshot before either
+// writes; the read must be inside the lock too so the second process reads
+// the FIRST process's already-written change rather than a stale copy.
+
 export async function addGoal(text) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  state.current.goals.unshift({
-    text,
-    machine_id: machineId,
-    set_on: new Date().toISOString(),
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    state.current.goals.unshift({
+      text,
+      machine_id: machineId,
+      set_on: new Date().toISOString(),
+    });
+    state.current.goals = state.current.goals.slice(0, MAX_GOALS);
+    await writeSession(state);
+    await appendEvent('goal_set', {}); // no PII/content — count-and-type only
+    return state;
   });
-  state.current.goals = state.current.goals.slice(0, MAX_GOALS);
-  await writeSession(state);
-  return state;
 }
 
 export async function addNext(text) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  // Dedupe by text (case-insensitive)
-  const normalized = text.trim().toLowerCase();
-  const exists = state.current.next_actions.some(a => a.text.trim().toLowerCase() === normalized);
-  if (!exists) {
-    state.current.next_actions.push({
-      text,
-      machine_id: machineId,
-      added: new Date().toISOString(),
-    });
-    state.current.next_actions = state.current.next_actions.slice(-MAX_NEXT);
-  }
-  await writeSession(state);
-  return state;
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    // Dedupe by text (case-insensitive)
+    const normalized = text.trim().toLowerCase();
+    const exists = state.current.next_actions.some(a => a.text.trim().toLowerCase() === normalized);
+    if (!exists) {
+      state.current.next_actions.push({
+        text,
+        machine_id: machineId,
+        added: new Date().toISOString(),
+      });
+      state.current.next_actions = state.current.next_actions.slice(-MAX_NEXT);
+    }
+    await writeSession(state);
+    return state;
+  });
 }
 
 export async function completeNext(textOrIndex) {
-  const state = await readSession();
-  await touchMachine(state);
-  let idx = -1;
-  if (typeof textOrIndex === 'number') {
-    idx = textOrIndex;
-  } else {
-    const normalized = String(textOrIndex).trim().toLowerCase();
-    idx = state.current.next_actions.findIndex(a => a.text.trim().toLowerCase().includes(normalized));
-  }
-  if (idx >= 0) {
-    state.current.next_actions.splice(idx, 1);
-  }
-  await writeSession(state);
-  return state;
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    await touchMachine(state);
+    let idx = -1;
+    if (typeof textOrIndex === 'number') {
+      idx = textOrIndex;
+    } else {
+      const normalized = String(textOrIndex).trim().toLowerCase();
+      idx = state.current.next_actions.findIndex(a => a.text.trim().toLowerCase().includes(normalized));
+    }
+    const completed = idx >= 0;
+    if (completed) {
+      state.current.next_actions.splice(idx, 1);
+    }
+    await writeSession(state);
+    // Only when something was actually completed — the event should mean
+    // "something happened," not "this function was called with no match."
+    if (completed) await appendEvent('next_completed', {});
+    return state;
+  });
 }
 
 export async function addNote(text, opts = {}) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  const decision = {
-    text,
-    machine_id: machineId,
-    date: new Date().toISOString(),
-  };
-  if (opts.why) decision.why = opts.why;
-  if (opts.rejected) decision.rejected = opts.rejected;
-  state.current.decisions.unshift(decision);
-  state.current.decisions = state.current.decisions.slice(0, MAX_DECISIONS_RECENT);
-  await writeSession(state);
-  return state;
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    const decision = {
+      text,
+      machine_id: machineId,
+      date: new Date().toISOString(),
+    };
+    if (opts.why) decision.why = opts.why;
+    if (opts.rejected) decision.rejected = opts.rejected;
+    state.current.decisions.unshift(decision);
+    state.current.decisions = state.current.decisions.slice(0, MAX_DECISIONS_RECENT);
+    await writeSession(state);
+    // Count/booleans only — never the decision text itself.
+    await appendEvent('decision_captured', { has_why: !!opts.why, has_rejected: !!opts.rejected });
+    return state;
+  });
 }
 
 export async function addQuestion(text) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  state.current.open_questions.push({
-    text,
-    machine_id: machineId,
-    asked: new Date().toISOString(),
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    state.current.open_questions.push({
+      text,
+      machine_id: machineId,
+      asked: new Date().toISOString(),
+    });
+    state.current.open_questions = state.current.open_questions.slice(-MAX_QUESTIONS);
+    await writeSession(state);
+    return state;
   });
-  state.current.open_questions = state.current.open_questions.slice(-MAX_QUESTIONS);
-  await writeSession(state);
-  return state;
 }
 
 // Roll up the current state into a history entry. Use at session end / push.
 // Does not clear `current` — these are "the working set," not per-session scratch.
 export async function recordSessionEnd({ summary, filesTouched = [], durationMin = null } = {}) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  state.history.unshift({
-    date: new Date().toISOString(),
-    machine_id: machineId,
-    summary: summary || '',
-    files_touched: filesTouched.slice(0, 20),
-    duration_min: durationMin,
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    state.history.unshift({
+      date: new Date().toISOString(),
+      machine_id: machineId,
+      summary: summary || '',
+      files_touched: filesTouched.slice(0, 20),
+      duration_min: durationMin,
+    });
+    state.history = state.history.slice(0, MAX_HISTORY);
+    await writeSession(state);
+    return state;
   });
-  state.history = state.history.slice(0, MAX_HISTORY);
-  await writeSession(state);
-  return state;
 }
 
 // ── Cross-machine merge ─────────────────────────────────────────
@@ -293,4 +371,5 @@ export const paths = {
   config: CONFIG_DIR,
   session: SESSION_PATH,
   machineId: MACHINE_ID_PATH,
+  sessionLock: SESSION_LOCK_PATH,
 };