slidemind 0.3.19 → 0.4.0

package/src/workspace/registry.mjs

@@ -0,0 +1,359 @@
+// The persistent deck library: `<sessionConfigDir>/workspace/registry.json`.
+//
+//   { schemaVersion: 1, cliVersion, roots: [abs...], decks: [{ id, path, name, lastSeenAt, missing, hidden, format }] }
+//
+// `cliVersion` is the CLI that last populated the library; a different one at
+// daemon start re-scans every remembered root (discovery.mjs autoDiscover).
+// `format` is deck-paths `deckFormat` — current / legacy / unknown — refreshed
+// on every registration and listing. Registration migrates a flat pre-workspace
+// deck into `.slidemind/` first (`migrateLegacyDeck`), so `legacy` only survives
+// a migration that failed, and such a deck is flagged, never opened.
+//
+// An entry's `id` is a local UUID; its `path` is the canonical realpath of the
+// deck ROOT (the deliverable dir, never `.slidemind`). Two directories that
+// carry the same portable deck ID stay two entries — the library identifies
+// working copies, not decks. Every function reads the file fresh: the daemon
+// and any CLI process share it through the short-lived registry lock, so there
+// is no in-memory copy to invalidate. The lock is never held while acquiring a
+// deck lock (lock ordering: registry inside deck, never the other way round).
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolveBundleDirForDeck } from "../bridge/bundle.mjs";
+import { sessionConfigDir } from "../bridge/config.mjs";
+import { deckFormat, deckRoot, deckSlug, isDeckDir, migrateLegacyDeck, resolveWorkspace } from "../lib/deck-paths.mjs";
+
+export const REGISTRY_SCHEMA_VERSION = 1;
+
+export function workspaceConfigDir() {
+  return path.join(sessionConfigDir(), "workspace");
+}
+
+export function registryPath() {
+  return path.join(workspaceConfigDir(), "registry.json");
+}
+
+/** Write-then-rename, so a kill mid-write never leaves half a JSON file. */
+export function writeJsonAtomic(file, data, { mode } = {}) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", mode ? { mode } : undefined);
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+export function coded(code, message, extra = {}) {
+  return Object.assign(new Error(message), { code, ...extra });
+}
+
+// ---------------------------------------------------------------------------
+// lock
+// ---------------------------------------------------------------------------
+
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 5_000;
+
+const LOCK_SLICE_MS = 25;
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const lockPath = () => path.join(workspaceConfigDir(), "registry.lock");
+const lockOwner = (lock) => {
+  try {
+    const pid = Number(fs.readFileSync(path.join(lock, "owner"), "utf8"));
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null; // a lock from before this file, or taken a microsecond ago
+  }
+};
+// A pid can be recycled and an unreadable owner cannot be judged, so this only
+// ever SHORTENS a wait — the mtime staleness stays the backstop.
+const ownerAlive = (pid) => {
+  if (pid === null) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+};
+
+/**
+ * One acquisition loop, driven two ways: it yields the milliseconds to wait
+ * before the next attempt and returns once the lock is held.
+ *
+ * The critical section is one small read-modify-write, so an honest hold is
+ * about a millisecond. The only way the wait below ever reached its 5s deadline
+ * was a lock nobody holds any more, which is why the owner's pid is written into
+ * it and a dead owner's lock is reclaimed at once instead of after the stale TTL.
+ */
+function* acquireLock(lock) {
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      fs.mkdirSync(lock);
+      try {
+        fs.writeFileSync(path.join(lock, "owner"), String(process.pid));
+      } catch {
+        // an unwritable owner file costs a faster reclaim, never correctness
+      }
+      return;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      let age = 0;
+      try {
+        age = Date.now() - fs.statSync(lock).mtimeMs;
+      } catch {
+        continue; // released between our attempt and the stat
+      }
+      if (age > LOCK_STALE_MS || !ownerAlive(lockOwner(lock))) {
+        fs.rmSync(lock, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() > deadline) throw coded("registry_busy", "deck registry is locked by another slidemind process");
+      yield LOCK_SLICE_MS;
+    }
+  }
+}
+
+/** Run `fn` under the registry lock (a mkdir'd directory; exclusive by the OS). */
+export function withRegistryLock(fn) {
+  const lock = lockPath();
+  const it = acquireLock(lock);
+  // A CLI process has nothing else to do while it waits, so it blocks its thread.
+  for (let step = it.next(); !step.done; step = it.next()) sleepSync(step.value);
+  try {
+    return fn();
+  } finally {
+    fs.rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The same lock, awaited. The daemon serves SSE streams and long polls off one
+ * event loop, so `Atomics.wait` there stalls every other request in the process
+ * — never spin on the daemon's thread, use this from its request handlers.
+ */
+export async function withRegistryLockAsync(fn) {
+  const lock = lockPath();
+  const it = acquireLock(lock);
+  for (let step = it.next(); !step.done; step = it.next()) await sleep(step.value);
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// read / write
+// ---------------------------------------------------------------------------
+
+const EMPTY = () => ({ schemaVersion: REGISTRY_SCHEMA_VERSION, roots: [], decks: [] });
+
+/** The registry as on disk; a missing file is an empty one, a malformed one throws `registry_malformed` and is retained. */
+export function readRegistry() {
+  const file = registryPath();
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return EMPTY();
+    throw err;
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    throw coded("registry_malformed", `deck registry ${file} is not valid JSON; it was left in place for recovery`, { file });
+  }
+  if (!data || data.schemaVersion !== REGISTRY_SCHEMA_VERSION || !Array.isArray(data.decks) || !Array.isArray(data.roots)) {
+    throw coded("registry_malformed", `deck registry ${file} has an unsupported shape; it was left in place for recovery`, { file });
+  }
+  return data;
+}
+
+function writeRegistry(data) {
+  return writeJsonAtomic(registryPath(), data);
+}
+
+// The critical section itself, shared by both drivers. Every registry mutator is
+// a synchronous function of the loaded registry, so only the WAIT differs.
+const mutate = (fn) => () => {
+  const reg = readRegistry();
+  const out = fn(reg);
+  writeRegistry(reg);
+  return out;
+};
+const update = (fn) => withRegistryLock(mutate(fn));
+const updateAsync = (fn) => withRegistryLockAsync(mutate(fn));
+
+// ---------------------------------------------------------------------------
+// decks
+// ---------------------------------------------------------------------------
+
+/** Canonical deck root of anything a user might point at: the root, its workspace, or a file inside. */
+export function canonicalDeckPath(p) {
+  const abs = path.resolve(p);
+  const root = deckRoot(resolveWorkspace(abs));
+  return fs.realpathSync(root);
+}
+
+/**
+ * Register a deck directory (idempotent per realpath). Throws `not_a_deck` for a
+ * directory without deck markers and `missing_path` when it does not exist.
+ */
+// The path checks and the migration happen BEFORE the lock is taken (neither
+// touches the registry), then the mutator runs under it. Split out so the async
+// twin the daemon's routes use shares every rule rather than repeating it.
+function deckEntryMutator(p, { hidden = false, name = null } = {}) {
+  let real;
+  try {
+    real = canonicalDeckPath(p);
+  } catch (err) {
+    if (err.code === "ENOENT") throw coded("missing_path", `${p} does not exist`);
+    throw err;
+  }
+  if (!fs.statSync(real).isDirectory() || !isDeckDir(real)) {
+    throw coded("not_a_deck", `${real} carries no deck markers (.slidemind/, slides/, plan.md or a plan record)`);
+  }
+  migrateBestEffort(real);
+  return (reg) => {
+    const now = new Date().toISOString();
+    let entry = reg.decks.find((d) => d.path === real);
+    const format = deckFormat(real);
+    if (entry) {
+      entry.lastSeenAt = now;
+      entry.missing = false;
+      entry.format = format;
+      if (name) entry.name = name;
+      return { ...entry, created: false };
+    }
+    entry = { id: randomUUID(), path: real, name: name ?? deckSlug(real), lastSeenAt: now, missing: false, hidden, format };
+    reg.decks.push(entry);
+    return { ...entry, created: true };
+  };
+}
+
+export const addDeck = (p, opts = {}) => update(deckEntryMutator(p, opts));
+/** `addDeck` for the daemon: the wait for the lock never blocks its event loop. */
+export const addDeckAsync = (p, opts = {}) => updateAsync(deckEntryMutator(p, opts));
+
+/** Move a flat deck into `.slidemind/`; a failure leaves it `legacy` and says why. */
+export function migrateBestEffort(root) {
+  try {
+    // The resolver is injected rather than imported by deck-paths: bundle.mjs
+    // already imports deck-paths, so the arrow would be a cycle.
+    const moved = migrateLegacyDeck(root, { bundleDirFor: resolveBundleDirForDeck });
+    if (moved) process.stderr.write(`slidemind: migrated ${deckSlug(root)} into ${path.join(root, ".slidemind")} (${moved.length} entries)\n`);
+    return moved;
+  } catch (err) {
+    process.stderr.write(`slidemind: could not migrate ${root} into .slidemind/: ${err.message}\n`);
+    return null;
+  }
+}
+
+/** Registration that never throws: warns on stderr and returns null. For command hooks. */
+export function registerDeckBestEffort(p, opts = {}) {
+  try {
+    return addDeck(p, opts);
+  } catch (err) {
+    process.stderr.write(`slidemind: workspace registry skipped ${p}: ${err.message}\n`);
+    return null;
+  }
+}
+
+export function getDeck(id) {
+  return readRegistry().decks.find((d) => d.id === id) ?? null;
+}
+
+/** Visible entries, newest-seen first, with `missing` refreshed from the filesystem. */
+export function listDecks({ q = "", hidden = false, limit = 100, offset = 0 } = {}) {
+  const needle = String(q || "").toLowerCase();
+  const all = readRegistry()
+    .decks.filter((d) => hidden || !d.hidden)
+    .filter((d) => !needle || d.name.toLowerCase().includes(needle) || d.path.toLowerCase().includes(needle))
+    .map((d) => {
+      const missing = !fs.existsSync(d.path);
+      return { ...d, missing, format: missing ? (d.format ?? "unknown") : deckFormat(d.path) };
+    })
+    .sort((a, b) => (b.lastSeenAt ?? "").localeCompare(a.lastSeenAt ?? ""));
+  return { total: all.length, decks: all.slice(offset, offset + limit) };
+}
+
+export function markMissing(id, missing = true) {
+  return update((reg) => {
+    const entry = reg.decks.find((d) => d.id === id);
+    if (!entry) throw coded("unknown_deck", `no registered deck ${id}`);
+    entry.missing = missing;
+    return { ...entry };
+  });
+}
+
+/** Point a moved entry at its new location; refuses a path another entry already owns. */
+export function locateDeck(id, newPath) {
+  const real = canonicalDeckPath(newPath);
+  if (!isDeckDir(real)) throw coded("not_a_deck", `${real} carries no deck markers`);
+  return update((reg) => {
+    const entry = reg.decks.find((d) => d.id === id);
+    if (!entry) throw coded("unknown_deck", `no registered deck ${id}`);
+    const other = reg.decks.find((d) => d.id !== id && d.path === real);
+    if (other) throw coded("path_registered", `${real} is already registered as ${other.name} (${other.id})`, { deckId: other.id });
+    entry.path = real;
+    entry.name = entry.name || deckSlug(real);
+    entry.missing = false;
+    entry.format = deckFormat(real);
+    entry.lastSeenAt = new Date().toISOString();
+    return { ...entry };
+  });
+}
+
+/** Drop the entry only. Never touches the deck's files. */
+const removeDeckMutator = (id) => (reg) => {
+  const i = reg.decks.findIndex((d) => d.id === id);
+  if (i === -1) return false;
+  reg.decks.splice(i, 1);
+  return true;
+};
+export const removeDeck = (id) => update(removeDeckMutator(id));
+/** `removeDeck` for the daemon: see `addDeckAsync`. */
+export const removeDeckAsync = (id) => updateAsync(removeDeckMutator(id));
+
+// ---------------------------------------------------------------------------
+// roots
+// ---------------------------------------------------------------------------
+
+export function addRoot(p) {
+  const real = fs.realpathSync(path.resolve(p));
+  if (!fs.statSync(real).isDirectory()) throw coded("not_a_directory", `${real} is not a directory`);
+  return update((reg) => {
+    if (!reg.roots.includes(real)) reg.roots.push(real);
+    return real;
+  });
+}
+
+export function listRoots() {
+  return readRegistry().roots.slice();
+}
+
+// ---------------------------------------------------------------------------
+// which CLI populated the library
+// ---------------------------------------------------------------------------
+
+/** The CLI version that last populated the library, or null (never / before this field). */
+export function registryVersion() {
+  return readRegistry().cliVersion ?? null;
+}
+
+export function recordRegistryVersion(version) {
+  return update((reg) => {
+    reg.cliVersion = version;
+    return version;
+  });
+}