@venturewild/workspace 0.4.2 → 0.5.1

package/server/src/workspace-registry.mjs

@@ -1,295 +1,295 @@
-// Workspace registry — the per-install list of LOCAL workspaces (lobby M1).
-//
-// One install can hold many workspaces; this is the list the lobby shows and
-// switches between. Stored in the GLOBAL dir (~/.wild-workspace/workspaces.json),
-// NEVER inside a synced workspace folder (core principle #1: the user's repo
-// folder is sacred — no system state in it).
-//
-// Each entry points at a folder on THIS host. The server re-roots to the chosen
-// workspace per request via the X-Workspace-Id seam (see index.mjs `workspaceFor`).
-// Creating/opening a workspace is a HOST action (the folder lives here); a remote
-// browser only ENTERS existing ones — enforced at the route, not here.
-//
-// A workspace is `kind:'local'` until the owner explicitly SHARES it (sharing
-// slice / design §4 decision 7): `markShared` promotes the entry to `kind:'shared'`
-// and records a `shared:{slug,ownerEmail,role,sharedAt}` block — the slug is the
-// workspace's first-class identity on the bmo-sync rails (membership/canvas), minted
-// by `POST /api/workspaces/create`. The folder stays exactly where it is; promoting
-// is a metadata flip on the LIST, never a move. `removeWorkspace` drops a folder
-// from the LIST only — it never deletes files.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import crypto from 'node:crypto';
-import { globalDir } from './logpaths.mjs';
-
-const FILE = 'workspaces.json';
-
-function registryPath(env = process.env) {
-  return path.join(globalDir(env), FILE);
-}
-
-// Where "New workspace" (name-only, no path) creates folders — a visible home so
-// the user always knows where their data lives (design §8.1). Overridable for tests.
-function workspacesHome(env = process.env) {
-  return env.WILD_WORKSPACE_HOME || path.join(os.homedir(), 'Workspaces');
-}
-
-// A stable id derived from the absolute dir, so re-adding the same folder is
-// idempotent and the id survives a display-name rename. Case-folded on win/mac
-// (case-insensitive filesystems) so one folder maps to exactly one id. Exported
-// so the server can compute the boot/default workspace's id WITHOUT writing the
-// registry file (keeps startup side-effect-free + test-pollution-free).
-export function workspaceIdForDir(dir) {
-  const abs = path.resolve(dir);
-  const key = process.platform === 'linux' ? abs : abs.toLowerCase();
-  return 'ws_' + crypto.createHash('sha256').update(key).digest('hex').slice(0, 12);
-}
-const idForDir = workspaceIdForDir;
-
-function nameForDir(dir) {
-  return path.basename(path.resolve(dir)) || 'workspace';
-}
-
-// folder-name-safe slug of a display name (for the New-workspace folder).
-function folderSlug(name) {
-  const s = String(name || '')
-    .trim()
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}]+/gu, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 60);
-  return s || 'workspace';
-}
-
-function readRaw(env) {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(registryPath(env), 'utf8'));
-    if (Array.isArray(parsed?.workspaces)) {
-      return parsed.workspaces.map(sanitize).filter(Boolean);
-    }
-  } catch {
-    /* missing / unreadable / malformed → empty */
-  }
-  return [];
-}
-
-// A shared workspace carries a `shared` block (the rails identity + the local
-// member's role). Only kept when the entry is actually `kind:'shared'` AND the
-// block has a slug; anything else collapses back to a plain local entry so a
-// half-written record can't masquerade as shared.
-function sanitizeShared(s) {
-  if (!s || typeof s !== 'object' || typeof s.slug !== 'string' || !s.slug.trim()) return null;
-  const out = {
-    slug: s.slug.trim().toLowerCase(),
-    ownerEmail: typeof s.ownerEmail === 'string' ? s.ownerEmail : '',
-    role: s.role === 'owner' ? 'owner' : 'member',
-    sharedAt: Number(s.sharedAt) || 0,
-  };
-  // Slice 3: the file-sync project this workspace replicates through, recorded
-  // once the daemon is paired ("going live"). Absent until file-sync starts.
-  if (typeof s.projectCode === 'string' && s.projectCode.trim()) {
-    out.projectCode = s.projectCode.trim();
-  }
-  return out;
-}
-
-function sanitize(e) {
-  if (!e || typeof e !== 'object' || typeof e.dir !== 'string' || !e.dir) return null;
-  const dir = path.resolve(e.dir);
-  const shared = sanitizeShared(e.shared);
-  const out = {
-    id: typeof e.id === 'string' && e.id ? e.id : idForDir(dir),
-    name: typeof e.name === 'string' && e.name.trim() ? e.name.trim() : nameForDir(dir),
-    dir,
-    kind: e.kind === 'shared' && shared ? 'shared' : 'local',
-    createdAt: Number(e.createdAt) || nowMs(),
-    lastOpenedAt: Number(e.lastOpenedAt) || 0,
-  };
-  if (out.kind === 'shared') out.shared = shared;
-  return out;
-}
-
-function writeRaw(list, env) {
-  const dir = globalDir(env);
-  fs.mkdirSync(dir, { recursive: true });
-  const tmp = `${registryPath(env)}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify({ workspaces: list }, null, 2), { mode: 0o600 });
-  fs.renameSync(tmp, registryPath(env)); // atomic-ish replace
-}
-
-function nowMs() {
-  return Date.now();
-}
-
-// Recency ordering (listWorkspaces) needs strictly-increasing open stamps. Two
-// opens in the same millisecond — easy on a fast machine or CI — would otherwise
-// tie on lastOpenedAt and fall back to the createdAt tiebreak, which does NOT
-// reflect open-order, so the just-touched workspace could fail to sort to the
-// front. Clamp every new open stamp strictly above every existing stamp so the
-// order is deterministic regardless of clock resolution.
-function nextOpenStamp(list) {
-  let max = 0;
-  for (const w of list) {
-    if (w.lastOpenedAt > max) max = w.lastOpenedAt;
-    if (w.createdAt > max) max = w.createdAt;
-  }
-  return Math.max(nowMs(), max + 1);
-}
-
-// --- public API ------------------------------------------------------------
-
-/** All workspaces, most-recently-opened first (then newest-created). */
-export function listWorkspaces(env = process.env) {
-  return readRaw(env).sort(
-    (a, b) => b.lastOpenedAt - a.lastOpenedAt || b.createdAt - a.createdAt,
-  );
-}
-
-/** One workspace by id, or null. */
-export function getWorkspace(id, env = process.env) {
-  return readRaw(env).find((w) => w.id === id) || null;
-}
-
-/** Find a registered workspace by its directory (idempotency helper), or null. */
-export function findByDir(dir, env = process.env) {
-  const want = idForDir(dir);
-  return readRaw(env).find((w) => w.id === want) || null;
-}
-
-/**
- * Ensure `dir` exists in the registry (idempotent) — used at startup to seed the
- * boot/default workspace so the lobby is never blank for an existing install.
- * Does NOT touch lastOpenedAt. Returns the entry.
- */
-export function seedDefault({ dir, name } = {}, env = process.env) {
-  if (!dir) return null;
-  const list = readRaw(env);
-  const existing = list.find((w) => w.id === idForDir(dir));
-  if (existing) return existing;
-  const entry = sanitize({
-    dir,
-    name: name || nameForDir(dir),
-    createdAt: nowMs(),
-    lastOpenedAt: nowMs(), // the boot workspace is "the one you were just in"
-  });
-  list.push(entry);
-  writeRaw(list, env);
-  return entry;
-}
-
-/**
- * Create a NEW local workspace. With `dir` → register that existing folder
- * ("Open an existing folder"). With only `name` → make a fresh folder under the
- * Workspaces home ("New workspace"); collisions get a -2/-3 suffix. Idempotent on
- * an already-registered dir (returns it, touched). HOST-only is enforced at the route.
- */
-export function createWorkspace({ name, dir } = {}, env = process.env) {
-  let targetDir;
-  let isNew = false;
-
-  if (dir) {
-    targetDir = path.resolve(dir);
-    if (!fs.existsSync(targetDir)) {
-      throw new Error(`folder does not exist: ${targetDir}`);
-    }
-    if (!fs.statSync(targetDir).isDirectory()) {
-      throw new Error(`not a folder: ${targetDir}`);
-    }
-  } else {
-    const home = workspacesHome(env);
-    fs.mkdirSync(home, { recursive: true });
-    const base = folderSlug(name);
-    let candidate = path.join(home, base);
-    let n = 2;
-    while (fs.existsSync(candidate)) {
-      candidate = path.join(home, `${base}-${n}`);
-      n += 1;
-    }
-    fs.mkdirSync(candidate, { recursive: true });
-    targetDir = candidate;
-    isNew = true;
-  }
-
-  const list = readRaw(env);
-  const id = idForDir(targetDir);
-  const existing = list.find((w) => w.id === id);
-  if (existing) {
-    existing.lastOpenedAt = nextOpenStamp(list);
-    if (name && isNew) existing.name = name;
-    writeRaw(list, env);
-    return existing;
-  }
-  const entry = sanitize({
-    dir: targetDir,
-    name: name || nameForDir(targetDir),
-    createdAt: nowMs(),
-    lastOpenedAt: nextOpenStamp(list),
-  });
-  list.push(entry);
-  writeRaw(list, env);
-  return entry;
-}
-
-/** Mark a workspace opened now (drives the recency sort + pre-select-last). */
-export function touchWorkspace(id, env = process.env) {
-  const list = readRaw(env);
-  const w = list.find((x) => x.id === id);
-  if (!w) return null;
-  w.lastOpenedAt = nextOpenStamp(list);
-  writeRaw(list, env);
-  return w;
-}
-
-/**
- * Promote a registered workspace to SHARED (sharing slice / design §4 decision 7).
- * The workspace must already be in the registry (the boot/default workspace is
- * seeded first by the caller). Records the rails identity (`slug`) + the local
- * member's role; the folder is untouched. Idempotent: re-sharing updates the block.
- * Returns the updated entry, or null if the id is unknown.
- */
-export function markShared(id, { slug, ownerEmail = '', role = 'owner' } = {}, env = process.env) {
-  if (!slug || typeof slug !== 'string') throw new Error('markShared requires a slug');
-  const list = readRaw(env);
-  const w = list.find((x) => x.id === id);
-  if (!w) return null;
-  w.kind = 'shared';
-  w.shared = sanitizeShared({
-    slug,
-    ownerEmail,
-    role,
-    sharedAt: w.shared?.sharedAt || nowMs(),
-    // Preserve a file-sync link already recorded (re-share/re-mark must not drop it).
-    projectCode: w.shared?.projectCode,
-  });
-  writeRaw(list, env);
-  return w;
-}
-
-/**
- * Record the file-sync project a shared workspace replicates through, once the
- * daemon has paired the folder (Slice 3 "going live"). The entry must already be
- * `kind:'shared'`. Idempotent. Returns the updated entry, or null if the id is
- * unknown / not shared.
- */
-export function setSyncProject(id, projectCode, env = process.env) {
-  if (!projectCode || typeof projectCode !== 'string') {
-    throw new Error('setSyncProject requires a projectCode');
-  }
-  const list = readRaw(env);
-  const w = list.find((x) => x.id === id);
-  if (!w || w.kind !== 'shared' || !w.shared) return null;
-  w.shared = sanitizeShared({ ...w.shared, projectCode });
-  writeRaw(list, env);
-  return w;
-}
-
-/** Remove a workspace from the LIST only. NEVER deletes the folder or its files. */
-export function removeWorkspace(id, env = process.env) {
-  const list = readRaw(env);
-  const next = list.filter((w) => w.id !== id);
-  if (next.length === list.length) return false;
-  writeRaw(next, env);
-  return true;
-}
+// Workspace registry — the per-install list of LOCAL workspaces (lobby M1).
+//
+// One install can hold many workspaces; this is the list the lobby shows and
+// switches between. Stored in the GLOBAL dir (~/.wild-workspace/workspaces.json),
+// NEVER inside a synced workspace folder (core principle #1: the user's repo
+// folder is sacred — no system state in it).
+//
+// Each entry points at a folder on THIS host. The server re-roots to the chosen
+// workspace per request via the X-Workspace-Id seam (see index.mjs `workspaceFor`).
+// Creating/opening a workspace is a HOST action (the folder lives here); a remote
+// browser only ENTERS existing ones — enforced at the route, not here.
+//
+// A workspace is `kind:'local'` until the owner explicitly SHARES it (sharing
+// slice / design §4 decision 7): `markShared` promotes the entry to `kind:'shared'`
+// and records a `shared:{slug,ownerEmail,role,sharedAt}` block — the slug is the
+// workspace's first-class identity on the bmo-sync rails (membership/canvas), minted
+// by `POST /api/workspaces/create`. The folder stays exactly where it is; promoting
+// is a metadata flip on the LIST, never a move. `removeWorkspace` drops a folder
+// from the LIST only — it never deletes files.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { globalDir } from './logpaths.mjs';
+
+const FILE = 'workspaces.json';
+
+function registryPath(env = process.env) {
+  return path.join(globalDir(env), FILE);
+}
+
+// Where "New workspace" (name-only, no path) creates folders — a visible home so
+// the user always knows where their data lives (design §8.1). Overridable for tests.
+function workspacesHome(env = process.env) {
+  return env.WILD_WORKSPACE_HOME || path.join(os.homedir(), 'Workspaces');
+}
+
+// A stable id derived from the absolute dir, so re-adding the same folder is
+// idempotent and the id survives a display-name rename. Case-folded on win/mac
+// (case-insensitive filesystems) so one folder maps to exactly one id. Exported
+// so the server can compute the boot/default workspace's id WITHOUT writing the
+// registry file (keeps startup side-effect-free + test-pollution-free).
+export function workspaceIdForDir(dir) {
+  const abs = path.resolve(dir);
+  const key = process.platform === 'linux' ? abs : abs.toLowerCase();
+  return 'ws_' + crypto.createHash('sha256').update(key).digest('hex').slice(0, 12);
+}
+const idForDir = workspaceIdForDir;
+
+function nameForDir(dir) {
+  return path.basename(path.resolve(dir)) || 'workspace';
+}
+
+// folder-name-safe slug of a display name (for the New-workspace folder).
+function folderSlug(name) {
+  const s = String(name || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+  return s || 'workspace';
+}
+
+function readRaw(env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(registryPath(env), 'utf8'));
+    if (Array.isArray(parsed?.workspaces)) {
+      return parsed.workspaces.map(sanitize).filter(Boolean);
+    }
+  } catch {
+    /* missing / unreadable / malformed → empty */
+  }
+  return [];
+}
+
+// A shared workspace carries a `shared` block (the rails identity + the local
+// member's role). Only kept when the entry is actually `kind:'shared'` AND the
+// block has a slug; anything else collapses back to a plain local entry so a
+// half-written record can't masquerade as shared.
+function sanitizeShared(s) {
+  if (!s || typeof s !== 'object' || typeof s.slug !== 'string' || !s.slug.trim()) return null;
+  const out = {
+    slug: s.slug.trim().toLowerCase(),
+    ownerEmail: typeof s.ownerEmail === 'string' ? s.ownerEmail : '',
+    role: s.role === 'owner' ? 'owner' : 'member',
+    sharedAt: Number(s.sharedAt) || 0,
+  };
+  // Slice 3: the file-sync project this workspace replicates through, recorded
+  // once the daemon is paired ("going live"). Absent until file-sync starts.
+  if (typeof s.projectCode === 'string' && s.projectCode.trim()) {
+    out.projectCode = s.projectCode.trim();
+  }
+  return out;
+}
+
+function sanitize(e) {
+  if (!e || typeof e !== 'object' || typeof e.dir !== 'string' || !e.dir) return null;
+  const dir = path.resolve(e.dir);
+  const shared = sanitizeShared(e.shared);
+  const out = {
+    id: typeof e.id === 'string' && e.id ? e.id : idForDir(dir),
+    name: typeof e.name === 'string' && e.name.trim() ? e.name.trim() : nameForDir(dir),
+    dir,
+    kind: e.kind === 'shared' && shared ? 'shared' : 'local',
+    createdAt: Number(e.createdAt) || nowMs(),
+    lastOpenedAt: Number(e.lastOpenedAt) || 0,
+  };
+  if (out.kind === 'shared') out.shared = shared;
+  return out;
+}
+
+function writeRaw(list, env) {
+  const dir = globalDir(env);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${registryPath(env)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ workspaces: list }, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, registryPath(env)); // atomic-ish replace
+}
+
+function nowMs() {
+  return Date.now();
+}
+
+// Recency ordering (listWorkspaces) needs strictly-increasing open stamps. Two
+// opens in the same millisecond — easy on a fast machine or CI — would otherwise
+// tie on lastOpenedAt and fall back to the createdAt tiebreak, which does NOT
+// reflect open-order, so the just-touched workspace could fail to sort to the
+// front. Clamp every new open stamp strictly above every existing stamp so the
+// order is deterministic regardless of clock resolution.
+function nextOpenStamp(list) {
+  let max = 0;
+  for (const w of list) {
+    if (w.lastOpenedAt > max) max = w.lastOpenedAt;
+    if (w.createdAt > max) max = w.createdAt;
+  }
+  return Math.max(nowMs(), max + 1);
+}
+
+// --- public API ------------------------------------------------------------
+
+/** All workspaces, most-recently-opened first (then newest-created). */
+export function listWorkspaces(env = process.env) {
+  return readRaw(env).sort(
+    (a, b) => b.lastOpenedAt - a.lastOpenedAt || b.createdAt - a.createdAt,
+  );
+}
+
+/** One workspace by id, or null. */
+export function getWorkspace(id, env = process.env) {
+  return readRaw(env).find((w) => w.id === id) || null;
+}
+
+/** Find a registered workspace by its directory (idempotency helper), or null. */
+export function findByDir(dir, env = process.env) {
+  const want = idForDir(dir);
+  return readRaw(env).find((w) => w.id === want) || null;
+}
+
+/**
+ * Ensure `dir` exists in the registry (idempotent) — used at startup to seed the
+ * boot/default workspace so the lobby is never blank for an existing install.
+ * Does NOT touch lastOpenedAt. Returns the entry.
+ */
+export function seedDefault({ dir, name } = {}, env = process.env) {
+  if (!dir) return null;
+  const list = readRaw(env);
+  const existing = list.find((w) => w.id === idForDir(dir));
+  if (existing) return existing;
+  const entry = sanitize({
+    dir,
+    name: name || nameForDir(dir),
+    createdAt: nowMs(),
+    lastOpenedAt: nowMs(), // the boot workspace is "the one you were just in"
+  });
+  list.push(entry);
+  writeRaw(list, env);
+  return entry;
+}
+
+/**
+ * Create a NEW local workspace. With `dir` → register that existing folder
+ * ("Open an existing folder"). With only `name` → make a fresh folder under the
+ * Workspaces home ("New workspace"); collisions get a -2/-3 suffix. Idempotent on
+ * an already-registered dir (returns it, touched). HOST-only is enforced at the route.
+ */
+export function createWorkspace({ name, dir } = {}, env = process.env) {
+  let targetDir;
+  let isNew = false;
+
+  if (dir) {
+    targetDir = path.resolve(dir);
+    if (!fs.existsSync(targetDir)) {
+      throw new Error(`folder does not exist: ${targetDir}`);
+    }
+    if (!fs.statSync(targetDir).isDirectory()) {
+      throw new Error(`not a folder: ${targetDir}`);
+    }
+  } else {
+    const home = workspacesHome(env);
+    fs.mkdirSync(home, { recursive: true });
+    const base = folderSlug(name);
+    let candidate = path.join(home, base);
+    let n = 2;
+    while (fs.existsSync(candidate)) {
+      candidate = path.join(home, `${base}-${n}`);
+      n += 1;
+    }
+    fs.mkdirSync(candidate, { recursive: true });
+    targetDir = candidate;
+    isNew = true;
+  }
+
+  const list = readRaw(env);
+  const id = idForDir(targetDir);
+  const existing = list.find((w) => w.id === id);
+  if (existing) {
+    existing.lastOpenedAt = nextOpenStamp(list);
+    if (name && isNew) existing.name = name;
+    writeRaw(list, env);
+    return existing;
+  }
+  const entry = sanitize({
+    dir: targetDir,
+    name: name || nameForDir(targetDir),
+    createdAt: nowMs(),
+    lastOpenedAt: nextOpenStamp(list),
+  });
+  list.push(entry);
+  writeRaw(list, env);
+  return entry;
+}
+
+/** Mark a workspace opened now (drives the recency sort + pre-select-last). */
+export function touchWorkspace(id, env = process.env) {
+  const list = readRaw(env);
+  const w = list.find((x) => x.id === id);
+  if (!w) return null;
+  w.lastOpenedAt = nextOpenStamp(list);
+  writeRaw(list, env);
+  return w;
+}
+
+/**
+ * Promote a registered workspace to SHARED (sharing slice / design §4 decision 7).
+ * The workspace must already be in the registry (the boot/default workspace is
+ * seeded first by the caller). Records the rails identity (`slug`) + the local
+ * member's role; the folder is untouched. Idempotent: re-sharing updates the block.
+ * Returns the updated entry, or null if the id is unknown.
+ */
+export function markShared(id, { slug, ownerEmail = '', role = 'owner' } = {}, env = process.env) {
+  if (!slug || typeof slug !== 'string') throw new Error('markShared requires a slug');
+  const list = readRaw(env);
+  const w = list.find((x) => x.id === id);
+  if (!w) return null;
+  w.kind = 'shared';
+  w.shared = sanitizeShared({
+    slug,
+    ownerEmail,
+    role,
+    sharedAt: w.shared?.sharedAt || nowMs(),
+    // Preserve a file-sync link already recorded (re-share/re-mark must not drop it).
+    projectCode: w.shared?.projectCode,
+  });
+  writeRaw(list, env);
+  return w;
+}
+
+/**
+ * Record the file-sync project a shared workspace replicates through, once the
+ * daemon has paired the folder (Slice 3 "going live"). The entry must already be
+ * `kind:'shared'`. Idempotent. Returns the updated entry, or null if the id is
+ * unknown / not shared.
+ */
+export function setSyncProject(id, projectCode, env = process.env) {
+  if (!projectCode || typeof projectCode !== 'string') {
+    throw new Error('setSyncProject requires a projectCode');
+  }
+  const list = readRaw(env);
+  const w = list.find((x) => x.id === id);
+  if (!w || w.kind !== 'shared' || !w.shared) return null;
+  w.shared = sanitizeShared({ ...w.shared, projectCode });
+  writeRaw(list, env);
+  return w;
+}
+
+/** Remove a workspace from the LIST only. NEVER deletes the folder or its files. */
+export function removeWorkspace(id, env = process.env) {
+  const list = readRaw(env);
+  const next = list.filter((w) => w.id !== id);
+  if (next.length === list.length) return false;
+  writeRaw(next, env);
+  return true;
+}