@venturewild/workspace 0.3.8 → 0.4.1

package/server/src/workspace-registry.mjs

@@ -0,0 +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;
+}

package/server/src/workspaces.mjs

@@ -0,0 +1,135 @@
+// WorkspaceRails — the shared-workspace membership client (multi-host step 2).
+//
+// A thin client over bmo-sync's POST /api/workspaces/{create,list,members/add,
+// members/remove} (account-token self-authed, exactly like canvas-rails.mjs).
+// The caller (owner/member) is DERIVED server-side from the account token, so a
+// caller can only act as itself.
+//
+// Unlike CanvasRails (which degrades silently to a local cache), these are
+// operator/dev affordances driven by `wild-workspace workspace …`, so the
+// methods SURFACE the rails' error code + message instead of collapsing to a
+// bare false — the human running the command needs to see "slug_taken" /
+// "not_owner" / "no_such_account". Network failures still never throw: they
+// resolve to { ok:false, status:0, code:'unreachable' }.
+//
+// This is the FOUNDATION client — there is no App.jsx / lobby UI yet (that's the
+// lobby's job). The CLI is the only consumer.
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+export class WorkspaceRails {
+  constructor({
+    bmoSyncUrl,
+    accountToken,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchImpl = (...a) => globalThis.fetch(...a),
+  } = {}) {
+    this.bmoSyncUrl = bmoSyncUrl ? bmoSyncUrl.replace(/\/$/, '') : null;
+    this.accountToken = accountToken || null;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+    // Inert without a token (can't key it) or without a server URL.
+    this.capable = Boolean(this.accountToken) && Boolean(this.bmoSyncUrl);
+  }
+
+  /**
+   * POST to a workspaces endpoint with the account token folded in.
+   * @returns {Promise<{ok:boolean, status:number, data:object|null, code?:string, message?:string}>}
+   *   ok:true  → 2xx; `data` is the parsed body.
+   *   ok:false → a 4xx/5xx (carries the rails' {code,message}) OR a transport
+   *              failure (status 0, code 'unreachable' / 'not_configured').
+   */
+  async _post(path, body) {
+    if (!this.capable) {
+      return { ok: false, status: 0, data: null, code: 'not_configured', message: 'not logged in / no rails URL' };
+    }
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      const r = await this.fetchImpl(`${this.bmoSyncUrl}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ account_token: this.accountToken, ...body }),
+        signal: ctrl.signal,
+      });
+      const data = await r.json().catch(() => null);
+      if (r.ok) return { ok: true, status: r.status, data };
+      return {
+        ok: false,
+        status: r.status,
+        data,
+        code: data?.code || `http_${r.status}`,
+        message: data?.message || `HTTP ${r.status}`,
+      };
+    } catch (e) {
+      return { ok: false, status: 0, data: null, code: 'unreachable', message: String(e?.message || e) };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Create a shared workspace. `slug` is optional (the rails auto-suggest from name). */
+  create(name, slug = null) {
+    const body = { name };
+    if (slug) body.slug = slug;
+    return this._post('/api/workspaces/create', body);
+  }
+
+  /** The shared workspaces this account belongs to. */
+  list() {
+    return this._post('/api/workspaces/list', {});
+  }
+
+  /**
+   * Add a member by email (owner-only). If the email has no account yet the
+   * rails records a PENDING invite (`data.pending === true`) instead of an
+   * active membership; the person claims it by signing in + Join.
+   */
+  addMember(slug, email) {
+    return this._post('/api/workspaces/members/add', { slug, member_email: email });
+  }
+
+  /**
+   * Claim membership at Join time. Activates a pending invite addressed to this
+   * account's own VERIFIED email; a no-op for an already-active member. Returns
+   * `{ok, data:{role, name, owner_email, claimed}}` or a 403 `not_a_member`.
+   */
+  claim(slug) {
+    return this._post('/api/workspaces/claim', { slug });
+  }
+
+  /**
+   * Mint a file-sync pass for a shared workspace this account belongs to
+   * (Slice 3). Returns `{ok, data:{project_code, invite_code, expires_at}}` — the
+   * daemon redeems `invite_code` to pair the folder and start replicating. The
+   * project is provisioned lazily server-side; the code is stable, the invite is
+   * one-shot (each call mints a fresh one). A non-member → 403 `not_a_member`.
+   */
+  syncCredential(slug) {
+    return this._post('/api/workspaces/sync-credential', { slug });
+  }
+
+  /** Remove a member by email or accountId (owner-only; the owner can't be removed). */
+  removeMember(slug, ref) {
+    const body = { slug };
+    if (ref && typeof ref === 'object') {
+      if (ref.accountId) body.account_id = ref.accountId;
+      else if (ref.email) body.member_email = ref.email;
+    } else if (typeof ref === 'string') {
+      // Heuristic: an '@' means an email, otherwise treat it as an account id.
+      if (ref.includes('@')) body.member_email = ref;
+      else body.account_id = ref;
+    }
+    return this._post('/api/workspaces/members/remove', body);
+  }
+}
+
+/** Build the client from server config + account (or an inert one when logged out). */
+export function createWorkspaceRails(config, account, fetchImpl) {
+  return new WorkspaceRails({
+    bmoSyncUrl: config?.bmoSyncServerUrl,
+    accountToken: account?.accountToken,
+    fetchImpl,
+  });
+}