amalgm 0.1.158 → 0.1.159

package/runtime/scripts/amalgm-mcp/workspace/cards.js

@@ -0,0 +1,437 @@
+'use strict';
+
+/**
+ * The repo-card store and service: this machine's durable map of every
+ * tracked worktree.
+ *
+ * The tracked world is the workspace registry. refreshRepoCards()
+ * recomputes it — one refresh runs at a time, concurrent callers coalesce
+ * onto the next pass — writes only what changed, and bumps a card's
+ * generation exactly when its fingerprint or health moves. Absence is a
+ * state, not an erasure: a card leaves the map only when git itself
+ * settles the removal (the repo no longer registers that worktree) or
+ * the user untracks the folder that reached it — and untrack-deletes are
+ * only settled on a pass that scanned every tracked root. Everything
+ * else is health — missing, broken, inaccessible — carried on the last
+ * good observation.
+ *
+ * The service keeps the map live without anyone asking: a doorbell on
+ * each checkout's git directory rings on commits, checkouts, staging and
+ * in-flight operations, and a slow reconcile pass catches what no
+ * doorbell can see (working-tree edits, new repos in tracked folders).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { openLocalDb } = require('../state/db');
+const { insertStateEvent, publishStateEvent, subscribeStateEvents } = require('../state/events');
+const { listWorkspaces } = require('./store');
+const { buildRepoCard, cardFingerprint, discoverWorktrees } = require('./card');
+const { GitError, classifyDirectory } = require('./git');
+
+const DOORBELL_QUIET_MS = 250;
+const RECONCILE_INTERVAL_MS = 30_000;
+
+const service = {
+  started: false,
+  reconcileTimer: null,
+  workspaceTimer: null,
+  unsubscribe: null,
+  doorbells: new Map(), // replicaId → { watchers, timer }
+  counters: { refreshes: 0, doorbellRings: 0 },
+  lastRefresh: null,
+};
+
+function rowToCard(row) {
+  return {
+    ...JSON.parse(row.card_json),
+    health: row.health,
+    generation: row.generation,
+    firstSeenAt: row.first_seen_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function listRepoCards() {
+  return openLocalDb()
+    .prepare('SELECT * FROM repo_cards ORDER BY path')
+    .all()
+    .map(rowToCard);
+}
+
+function trackedRoots() {
+  return listWorkspaces()
+    .filter((workspace) => workspace.path && workspace.status === 'ready')
+    .map((workspace) => workspace.path);
+}
+
+/** The primary repo folder a git dir belongs to: '<repo>/.git',
+ * '<repo>/.git/worktrees/<name>', and '<super>/.git/modules/<name>' all
+ * answer to the folder in front of '/.git'. */
+function repoPathOfGitDir(gitDir) {
+  const marker = gitDir.lastIndexOf(`${path.sep}.git`);
+  return marker > 0 ? gitDir.slice(0, marker) : path.dirname(gitDir);
+}
+
+/**
+ * One namespace for path comparison. Card paths are realpaths (they come
+ * from live checkouts); registered roots are stored as the user gave them
+ * and may reach the same place through symlinks (`/var` vs `/private/var`).
+ * Resolve through the nearest ancestor that still exists, so a deleted
+ * path canonicalizes the same way it did while alive.
+ */
+function canonicalPath(candidate) {
+  let base = candidate;
+  const tail = [];
+  while (!fs.existsSync(base)) {
+    const parent = path.dirname(base);
+    if (parent === base) break;
+    tail.unshift(path.basename(base));
+    base = parent;
+  }
+  try {
+    base = fs.realpathSync(base);
+  } catch {
+    /* keep the unresolved form; comparison degrades to string equality */
+  }
+  return path.join(base, ...tail);
+}
+
+/**
+ * Would a registered root reach this path today? True when the path is a
+ * registered root itself, sits one level under a folder-of-repos root, or
+ * contains a registered root (a workspace inside the repo is covered by
+ * the repo that owns it). Pure string geometry over canonical paths — the
+ * paths involved may no longer exist on disk.
+ */
+function coveredByRoots(candidate, canonicalRoots) {
+  const target = canonicalPath(candidate);
+  return canonicalRoots.includes(target)
+    || canonicalRoots.includes(path.dirname(target))
+    || canonicalRoots.some((root) => root.startsWith(target + path.sep));
+}
+
+/**
+ * Is this card's checkout reachable by the registrations of today —
+ * directly, or through the primary repo that owns its git dir (how linked
+ * worktrees and submodules are discovered)? Coverage is always judged
+ * against the current registration list, never against the root recorded
+ * when the card was written: registrations change without any git
+ * activity, and a stale record must never decide an erasure. Geometry errs
+ * toward coverage; the cost of a wrong `missing` is a lingering card,
+ * the cost of a wrong delete is a broken guarantee.
+ */
+function reachableByCurrentRoots(row, canonicalRoots) {
+  return coveredByRoots(row.path, canonicalRoots)
+    || coveredByRoots(repoPathOfGitDir(row.git_dir), canonicalRoots);
+}
+
+/**
+ * What a stored card means now that its worktree did not surface.
+ * Probes are read-only: file existence plus one classification.
+ * Returns { op: 'health', health } or { op: 'delete', settledBy }.
+ */
+async function dispositionAbsent(row, canonicalRoots) {
+  const card = JSON.parse(row.card_json);
+  const stillTracked = reachableByCurrentRoots(row, canonicalRoots);
+
+  if (!fs.existsSync(row.path)) {
+    // git settles a linked worktree's (or submodule's) removal by deleting
+    // its git dir out of the owning repo. A primary's git dir dies with
+    // the folder, which settles nothing — someone deleted the repo and
+    // the card must say so for as long as the folder stays tracked.
+    if (card.kind !== 'primary' && !fs.existsSync(row.git_dir)) {
+      return { op: 'delete', settledBy: 'worktree-removed' };
+    }
+    if (stillTracked) {
+      return { op: 'health', health: 'missing' };
+    }
+    return { op: 'delete', settledBy: 'untracked' };
+  }
+
+  let classified;
+  try {
+    classified = await classifyDirectory(row.path);
+  } catch (error) {
+    if (error instanceof GitError) return { op: 'health', health: 'broken' };
+    if (error.code === 'EACCES' || error.code === 'EPERM') return { op: 'health', health: 'inaccessible' };
+    return { op: 'health', health: 'missing' };
+  }
+  if (classified.kind !== 'worktree') {
+    if (stillTracked) return { op: 'health', health: 'broken' };
+    return { op: 'delete', settledBy: 'untracked' };
+  }
+  // The path answers as a live checkout that no scanned root reaches any
+  // more (or as a different repo reusing the path): tracking ended.
+  return { op: 'delete', settledBy: 'untracked' };
+}
+
+async function runRefresh() {
+  const startedAt = Date.now();
+  service.counters.refreshes += 1;
+
+  const roots = trackedRoots();
+  const targets = new Map(); // worktree root → registry root that reached it
+  const skipped = [];
+  const rootErrors = [];
+  for (const root of roots) {
+    try {
+      const discovered = await discoverWorktrees(root);
+      for (const worktree of discovered.worktrees) {
+        if (!targets.has(worktree)) targets.set(worktree, root);
+      }
+      skipped.push(...discovered.skipped);
+    } catch (error) {
+      rootErrors.push({ root, error: error.message });
+    }
+  }
+
+  const built = [];
+  for (const [target, root] of targets) {
+    try {
+      built.push({ card: await buildRepoCard(target), root });
+    } catch (error) {
+      skipped.push({ path: target, reason: 'observation-failed', error: error.message });
+    }
+  }
+
+  const db = openLocalDb();
+  const builtReplicas = new Set(built.map((entry) => entry.card.replica));
+  const absentRows = db.prepare('SELECT * FROM repo_cards').all()
+    .filter((row) => !builtReplicas.has(row.replica_id));
+  const canonicalRoots = roots.map(canonicalPath);
+  const decisions = [];
+  for (const row of absentRows) {
+    const decision = await dispositionAbsent(row, canonicalRoots);
+    // A pass that failed to scan a root is blind, and a blind pass never
+    // settles an untrack — only git-settled removals apply.
+    if (decision.op === 'delete' && decision.settledBy === 'untracked' && rootErrors.length > 0) continue;
+    if (decision.op === 'health' && decision.health === row.health) continue;
+    decisions.push({ row, decision });
+  }
+
+  const events = [];
+  const stats = {
+    roots: roots.length,
+    discovered: targets.size,
+    changed: 0,
+    healthChanged: 0,
+    removed: 0,
+    rootErrors: rootErrors.length,
+  };
+
+  db.transaction(() => {
+    const readRow = db.prepare('SELECT * FROM repo_cards WHERE replica_id = ?');
+    const upsert = db.prepare(`
+      INSERT INTO repo_cards (
+        replica_id, path, git_dir, root, health, fingerprint,
+        generation, first_seen_at, updated_at, card_json
+      )
+      VALUES (?, ?, ?, ?, 'healthy', ?, ?, ?, ?, ?)
+      ON CONFLICT(replica_id) DO UPDATE SET
+        path = excluded.path,
+        git_dir = excluded.git_dir,
+        root = excluded.root,
+        health = excluded.health,
+        fingerprint = excluded.fingerprint,
+        generation = excluded.generation,
+        updated_at = excluded.updated_at,
+        card_json = excluded.card_json
+    `);
+
+    const repairRoot = db.prepare('UPDATE repo_cards SET root = ? WHERE replica_id = ?');
+
+    for (const { card, root } of built) {
+      const row = readRow.get(card.replica);
+      const fingerprint = cardFingerprint(card);
+      if (row && row.fingerprint === fingerprint && row.health === 'healthy') {
+        // Which registration covers a checkout can change with no git
+        // activity at all. Absence decisions no longer read this column,
+        // but it still answers "why is this card on the map" — keep it
+        // truthful. Bookkeeping only: no generation bump, no event.
+        if (row.root !== root) repairRoot.run(root, card.replica);
+        continue;
+      }
+
+      const generation = row ? row.generation + 1 : 1;
+      const firstSeenAt = row ? row.first_seen_at : card.observedAt;
+      upsert.run(
+        card.replica, card.path, card.gitDir, root, fingerprint,
+        generation, firstSeenAt, card.observedAt, JSON.stringify(card),
+      );
+      stats.changed += 1;
+      events.push(insertStateEvent(db, {
+        resource: 'repo-cards',
+        op: row ? 'update' : 'insert',
+        id: card.replica,
+        value: { ...card, health: 'healthy', generation, firstSeenAt, updatedAt: card.observedAt },
+        source: 'repo-cards:refresh',
+      }));
+    }
+
+    for (const { row, decision } of decisions) {
+      if (decision.op === 'delete') {
+        db.prepare('DELETE FROM repo_cards WHERE replica_id = ?').run(row.replica_id);
+        stats.removed += 1;
+        events.push(insertStateEvent(db, {
+          resource: 'repo-cards',
+          op: 'delete',
+          id: row.replica_id,
+          source: 'repo-cards:refresh',
+        }));
+        continue;
+      }
+      const now = new Date().toISOString();
+      const generation = row.generation + 1;
+      db.prepare('UPDATE repo_cards SET health = ?, generation = ?, updated_at = ? WHERE replica_id = ?')
+        .run(decision.health, generation, now, row.replica_id);
+      stats.healthChanged += 1;
+      events.push(insertStateEvent(db, {
+        resource: 'repo-cards',
+        op: 'update',
+        id: row.replica_id,
+        value: {
+          ...JSON.parse(row.card_json),
+          health: decision.health,
+          generation,
+          firstSeenAt: row.first_seen_at,
+          updatedAt: now,
+        },
+        source: 'repo-cards:refresh',
+      }));
+    }
+  })();
+
+  for (const event of events) publishStateEvent(event);
+
+  const cards = listRepoCards();
+  syncDoorbells(cards);
+  service.lastRefresh = { ...stats, at: new Date().toISOString(), durationMs: Date.now() - startedAt };
+  return { cards, skipped, rootErrors, stats };
+}
+
+let running = null;
+let followUp = null;
+
+/**
+ * Refresh with single-flight coherence: one pass at a time, and a call
+ * that arrives mid-pass gets the next full pass — never a stale answer,
+ * never two passes racing each other into the store.
+ */
+function refreshRepoCards() {
+  if (running) {
+    followUp ??= running.catch(() => {}).then(() => refreshRepoCards());
+    return followUp;
+  }
+  followUp = null;
+  running = runRefresh().finally(() => {
+    running = null;
+  });
+  return running;
+}
+
+// --- the live service: doorbells + reconcile ------------------------------
+
+function ringDoorbell(replicaId) {
+  const bell = service.doorbells.get(replicaId);
+  if (!bell || bell.timer) return;
+  service.counters.doorbellRings += 1;
+  bell.timer = setTimeout(() => {
+    bell.timer = null;
+    refreshRepoCards().catch((error) => console.warn('[RepoCards] doorbell refresh failed:', error.message));
+  }, DOORBELL_QUIET_MS);
+  bell.timer.unref?.();
+}
+
+function watchGitDir(card) {
+  const watchers = [];
+  const ring = () => ringDoorbell(card.replica);
+  // The git dir itself carries HEAD, index, and operation markers; logs/
+  // carries the reflog, which moves on every commit, checkout, and reset.
+  for (const dir of [card.gitDir, path.join(card.gitDir, 'logs')]) {
+    try {
+      const watcher = fs.watch(dir, ring);
+      watcher.on('error', () => watcher.close());
+      watchers.push(watcher);
+    } catch {
+      // The directory vanished between observation and watch; the next
+      // reconcile pass re-syncs the bells.
+    }
+  }
+  return watchers;
+}
+
+function dropDoorbell(replicaId) {
+  const bell = service.doorbells.get(replicaId);
+  if (!bell) return;
+  for (const watcher of bell.watchers) watcher.close();
+  if (bell.timer) clearTimeout(bell.timer);
+  service.doorbells.delete(replicaId);
+}
+
+function syncDoorbells(cards) {
+  if (!service.started) return;
+  const healthy = new Map(
+    cards.filter((card) => card.health === 'healthy').map((card) => [card.replica, card]),
+  );
+  for (const replicaId of [...service.doorbells.keys()]) {
+    if (!healthy.has(replicaId)) dropDoorbell(replicaId);
+  }
+  for (const [replicaId, card] of healthy) {
+    if (!service.doorbells.has(replicaId)) {
+      service.doorbells.set(replicaId, { watchers: watchGitDir(card), timer: null });
+    }
+  }
+}
+
+function scheduleWorkspaceRefresh() {
+  if (service.workspaceTimer) return;
+  service.workspaceTimer = setTimeout(() => {
+    service.workspaceTimer = null;
+    refreshRepoCards().catch((error) => console.warn('[RepoCards] workspace refresh failed:', error.message));
+  }, DOORBELL_QUIET_MS);
+  service.workspaceTimer.unref?.();
+}
+
+function startRepoCardService() {
+  if (service.started) return;
+  service.started = true;
+  refreshRepoCards().catch((error) => console.warn('[RepoCards] initial refresh failed:', error.message));
+  service.unsubscribe = subscribeStateEvents((event) => {
+    if (event.resource === 'workspaces') scheduleWorkspaceRefresh();
+  });
+  service.reconcileTimer = setInterval(() => {
+    refreshRepoCards().catch((error) => console.warn('[RepoCards] reconcile failed:', error.message));
+  }, RECONCILE_INTERVAL_MS);
+  service.reconcileTimer.unref?.();
+}
+
+function stopRepoCardService() {
+  if (!service.started) return;
+  service.started = false;
+  clearInterval(service.reconcileTimer);
+  service.reconcileTimer = null;
+  if (service.workspaceTimer) clearTimeout(service.workspaceTimer);
+  service.workspaceTimer = null;
+  service.unsubscribe?.();
+  service.unsubscribe = null;
+  for (const replicaId of [...service.doorbells.keys()]) dropDoorbell(replicaId);
+}
+
+function repoCardServiceStats() {
+  return {
+    started: service.started,
+    refreshes: service.counters.refreshes,
+    doorbellRings: service.counters.doorbellRings,
+    doorbells: service.doorbells.size,
+    lastRefresh: service.lastRefresh,
+  };
+}
+
+module.exports = {
+  listRepoCards,
+  refreshRepoCards,
+  repoCardServiceStats,
+  startRepoCardService,
+  stopRepoCardService,
+};