@venturewild/workspace 0.1.2 → 0.1.3

package/server/src/sync.mjs

@@ -1,248 +1,248 @@
-// bmo-sync folder sharing — wild-workspace's control plane for the daemon.
-//
-// wild-workspace does not run the sync engine; the bmo-sync daemon does
-// (a separate local process — see bmo-sync/daemon/README.md). This module is
-// the thin HTTP client wild-workspace uses to drive it:
-//
-//   - pair / detach / list a workspace folder against the local daemon
-//     (http://127.0.0.1:8320);
-//   - mint an invite against the central server's admin API — but only when
-//     an admin key is configured. Most installs only ever *redeem* invites,
-//     and that path runs entirely through the daemon and needs no secret.
-//
-// The daemon may not be running. Read paths (health / listWorkspaces /
-// status) degrade to an "offline" result instead of throwing; explicit
-// actions (pair / detach / createInvite) throw a readable error for the UI.
-
-const DAEMON_TIMEOUT_MS = 4000;
-// Pairing and invite creation reach the central server on Fly.io, which can
-// cold-start (~1s+) when idle — give those calls a longer leash.
-const SERVER_TIMEOUT_MS = 12000;
-
-export class SyncControl {
-  /**
-   * @param {object}        opts
-   * @param {string}        opts.daemonHttpUrl     daemon HTTP origin, e.g. http://127.0.0.1:8320
-   * @param {string}        opts.bmoSyncServerUrl  central server, e.g. https://sync.venturewild.llc
-   * @param {string|null}  [opts.adminKey]         central-server X-Admin-Key; null = redeem-only
-   * @param {typeof fetch} [opts.fetchImpl]        injectable fetch (tests)
-   */
-  constructor({ daemonHttpUrl, bmoSyncServerUrl, adminKey = null, fetchImpl } = {}) {
-    this.daemonBase = trimSlash(daemonHttpUrl) || 'http://127.0.0.1:8320';
-    this.serverBase = trimSlash(bmoSyncServerUrl) || 'https://sync.venturewild.llc';
-    this.adminKey = adminKey || null;
-    this._fetch = fetchImpl || globalThis.fetch;
-  }
-
-  /** True when this install can mint invites (an admin key is configured). */
-  get canInvite() {
-    return Boolean(this.adminKey);
-  }
-
-  /** Liveness of the local daemon. Never throws. */
-  async health() {
-    try {
-      const res = await this._fetch(`${this.daemonBase}/health`, {
-        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
-      });
-      if (!res.ok) return { running: false };
-      const body = await res.json().catch(() => ({}));
-      return { running: body?.status === 'ok' };
-    } catch {
-      return { running: false };
-    }
-  }
-
-  /** Paired workspaces the daemon is syncing. [] when the daemon is down. */
-  async listWorkspaces() {
-    try {
-      const res = await this._fetch(`${this.daemonBase}/api/workspaces`, {
-        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
-      });
-      if (!res.ok) return [];
-      const body = await res.json().catch(() => ({}));
-      return Array.isArray(body?.workspaces) ? body.workspaces : [];
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Snapshot for the Sync panel: daemon liveness, paired workspaces, and
-   * whether this install can mint invites. Never throws — a missing daemon
-   * is a normal, displayable state.
-   */
-  async status() {
-    const [health, workspaces] = await Promise.all([
-      this.health(),
-      this.listWorkspaces(),
-    ]);
-    return {
-      daemon: health,
-      workspaces,
-      paired: workspaces.length > 0,
-      canInvite: this.canInvite,
-    };
-  }
-
-  /**
-   * Pair this workspace folder with a shared project by redeeming an invite.
-   * The daemon redeems against the central server, persists the pairing, and
-   * starts syncing `rootPath`. Throws a readable error on a bad invite or an
-   * unreachable daemon.
-   */
-  async pair(inviteCode, rootPath) {
-    const code = String(inviteCode || '').trim();
-    if (!code) throw new Error('An invite code is required.');
-    if (!rootPath) throw new Error('No workspace folder to pair.');
-    const res = await this._daemonFetch(`${this.daemonBase}/api/pair`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ inviteCode: code, rootPath }),
-      // Pairing redeems against the central server — allow for a cold start.
-      signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
-    });
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      throw new Error(body?.error || `Pairing failed (HTTP ${res.status}).`);
-    }
-    return body.workspace || body;
-  }
-
-  /** Stop syncing a workspace and forget the pairing. */
-  async detach(workspaceId) {
-    const id = String(workspaceId || '').trim();
-    if (!id) throw new Error('A workspace id is required.');
-    const res = await this._daemonFetch(
-      `${this.daemonBase}/api/workspaces/${encodeURIComponent(id)}`,
-      { method: 'DELETE', signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS) },
-    );
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      throw new Error(body?.error || `Disconnect failed (HTTP ${res.status}).`);
-    }
-    return { detached: Boolean(body.detached) };
-  }
-
-  /**
-   * Mint an invite code for a project on the central server. Requires an
-   * admin key; callers should check `canInvite` first and fall back to the
-   * paste-a-code flow when it is false.
-   */
-  async createInvite({ projectCode, displayName, expiresHours = 168 } = {}) {
-    if (!this.adminKey) {
-      throw new Error(
-        'Creating invites needs a bmo-sync admin key (set BMO_SYNC_ADMIN_KEY). ' +
-          'Without one, ask whoever owns the shared folder to send you a code.',
-      );
-    }
-    if (!projectCode) throw new Error('A paired project is required to invite into.');
-    let res;
-    try {
-      res = await this._fetch(`${this.serverBase}/api/admin/invites`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', 'x-admin-key': this.adminKey },
-        body: JSON.stringify({
-          project_code: projectCode,
-          display_name: displayName || 'Collaborator',
-          expires_hours: Number(expiresHours) || 168,
-        }),
-        signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
-      });
-    } catch {
-      throw new Error('Could not reach the bmo-sync server. Check your connection.');
-    }
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      throw new Error(
-        body?.message || body?.error || `Invite creation failed (HTTP ${res.status}).`,
-      );
-    }
-    return { code: body.code, projectCode: body.project_code, expiresAt: body.expires_at };
-  }
-
-  /** A daemon fetch that turns a connection failure into a readable error. */
-  async _daemonFetch(url, init) {
-    try {
-      return await this._fetch(url, init);
-    } catch {
-      throw new Error("The bmo-sync daemon isn't running. Start it, then try again.");
-    }
-  }
-
-  // ── C12-e: conflict surface ──────────────────────────────────────────
-  // The daemon emits SyncEvent::Conflict via /api/events (already piped
-  // into the wild-workspace ActivityBus by DaemonBridge); these methods
-  // are the explicit "give me / resolve" operations behind the badge
-  // and CLI.
-
-  /** All open conflicts across every paired workspace. [] when daemon down. */
-  async listConflicts() {
-    try {
-      const res = await this._fetch(`${this.daemonBase}/api/conflicts`, {
-        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
-      });
-      if (!res.ok) return [];
-      const body = await res.json().catch(() => ({}));
-      return Array.isArray(body?.conflicts) ? body.conflicts : [];
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Fetch one conflict's mine/theirs bytes (base64) plus the row. Used by
-   * the human-fallback diff panel + the `wild_conflicts_view` agent tool.
-   */
-  async viewConflict(workspaceId, path) {
-    if (!workspaceId) throw new Error('workspaceId is required');
-    if (!path) throw new Error('path is required');
-    const url =
-      `${this.daemonBase}/api/conflicts/` +
-      `${encodeURIComponent(workspaceId)}/` +
-      path.split('/').map(encodeURIComponent).join('/');
-    const res = await this._daemonFetch(url, {
-      signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
-    });
-    const body = await res.json().catch(() => ({}));
-    if (res.status === 404) return null;
-    if (!res.ok) {
-      throw new Error(body?.error || `Conflict view failed (HTTP ${res.status}).`);
-    }
-    return body;
-  }
-
-  /**
-   * Resolve a conflict. `action` is `keep_mine` or `take_theirs`. The
-   * server-mediated multi-peer broadcast is a V1.1 follow-up; for V1
-   * this is local-only.
-   */
-  async resolveConflict(workspaceId, path, action) {
-    const verb = String(action || '').trim();
-    if (!['keep_mine', 'take_theirs'].includes(verb)) {
-      throw new Error('action must be "keep_mine" or "take_theirs".');
-    }
-    // GET = view, POST = resolve on the same URL — the daemon's route was
-    // collapsed because axum 0.8 disallows a literal segment after a
-    // `{*path}` catchall.
-    const url =
-      `${this.daemonBase}/api/conflicts/` +
-      `${encodeURIComponent(workspaceId)}/` +
-      path.split('/').map(encodeURIComponent).join('/');
-    const res = await this._daemonFetch(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ action: verb }),
-      signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
-    });
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      throw new Error(body?.error || `Resolve failed (HTTP ${res.status}).`);
-    }
-    return { ok: true };
-  }
-}
-
-function trimSlash(u) {
-  return typeof u === 'string' ? u.replace(/\/+$/, '') : '';
-}
+// bmo-sync folder sharing — wild-workspace's control plane for the daemon.
+//
+// wild-workspace does not run the sync engine; the bmo-sync daemon does
+// (a separate local process — see bmo-sync/daemon/README.md). This module is
+// the thin HTTP client wild-workspace uses to drive it:
+//
+//   - pair / detach / list a workspace folder against the local daemon
+//     (http://127.0.0.1:8320);
+//   - mint an invite against the central server's admin API — but only when
+//     an admin key is configured. Most installs only ever *redeem* invites,
+//     and that path runs entirely through the daemon and needs no secret.
+//
+// The daemon may not be running. Read paths (health / listWorkspaces /
+// status) degrade to an "offline" result instead of throwing; explicit
+// actions (pair / detach / createInvite) throw a readable error for the UI.
+
+const DAEMON_TIMEOUT_MS = 4000;
+// Pairing and invite creation reach the central server on Fly.io, which can
+// cold-start (~1s+) when idle — give those calls a longer leash.
+const SERVER_TIMEOUT_MS = 12000;
+
+export class SyncControl {
+  /**
+   * @param {object}        opts
+   * @param {string}        opts.daemonHttpUrl     daemon HTTP origin, e.g. http://127.0.0.1:8320
+   * @param {string}        opts.bmoSyncServerUrl  central server, e.g. https://sync.venturewild.llc
+   * @param {string|null}  [opts.adminKey]         central-server X-Admin-Key; null = redeem-only
+   * @param {typeof fetch} [opts.fetchImpl]        injectable fetch (tests)
+   */
+  constructor({ daemonHttpUrl, bmoSyncServerUrl, adminKey = null, fetchImpl } = {}) {
+    this.daemonBase = trimSlash(daemonHttpUrl) || 'http://127.0.0.1:8320';
+    this.serverBase = trimSlash(bmoSyncServerUrl) || 'https://sync.venturewild.llc';
+    this.adminKey = adminKey || null;
+    this._fetch = fetchImpl || globalThis.fetch;
+  }
+
+  /** True when this install can mint invites (an admin key is configured). */
+  get canInvite() {
+    return Boolean(this.adminKey);
+  }
+
+  /** Liveness of the local daemon. Never throws. */
+  async health() {
+    try {
+      const res = await this._fetch(`${this.daemonBase}/health`, {
+        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+      });
+      if (!res.ok) return { running: false };
+      const body = await res.json().catch(() => ({}));
+      return { running: body?.status === 'ok' };
+    } catch {
+      return { running: false };
+    }
+  }
+
+  /** Paired workspaces the daemon is syncing. [] when the daemon is down. */
+  async listWorkspaces() {
+    try {
+      const res = await this._fetch(`${this.daemonBase}/api/workspaces`, {
+        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+      });
+      if (!res.ok) return [];
+      const body = await res.json().catch(() => ({}));
+      return Array.isArray(body?.workspaces) ? body.workspaces : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Snapshot for the Sync panel: daemon liveness, paired workspaces, and
+   * whether this install can mint invites. Never throws — a missing daemon
+   * is a normal, displayable state.
+   */
+  async status() {
+    const [health, workspaces] = await Promise.all([
+      this.health(),
+      this.listWorkspaces(),
+    ]);
+    return {
+      daemon: health,
+      workspaces,
+      paired: workspaces.length > 0,
+      canInvite: this.canInvite,
+    };
+  }
+
+  /**
+   * Pair this workspace folder with a shared project by redeeming an invite.
+   * The daemon redeems against the central server, persists the pairing, and
+   * starts syncing `rootPath`. Throws a readable error on a bad invite or an
+   * unreachable daemon.
+   */
+  async pair(inviteCode, rootPath) {
+    const code = String(inviteCode || '').trim();
+    if (!code) throw new Error('An invite code is required.');
+    if (!rootPath) throw new Error('No workspace folder to pair.');
+    const res = await this._daemonFetch(`${this.daemonBase}/api/pair`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ inviteCode: code, rootPath }),
+      // Pairing redeems against the central server — allow for a cold start.
+      signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(body?.error || `Pairing failed (HTTP ${res.status}).`);
+    }
+    return body.workspace || body;
+  }
+
+  /** Stop syncing a workspace and forget the pairing. */
+  async detach(workspaceId) {
+    const id = String(workspaceId || '').trim();
+    if (!id) throw new Error('A workspace id is required.');
+    const res = await this._daemonFetch(
+      `${this.daemonBase}/api/workspaces/${encodeURIComponent(id)}`,
+      { method: 'DELETE', signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS) },
+    );
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(body?.error || `Disconnect failed (HTTP ${res.status}).`);
+    }
+    return { detached: Boolean(body.detached) };
+  }
+
+  /**
+   * Mint an invite code for a project on the central server. Requires an
+   * admin key; callers should check `canInvite` first and fall back to the
+   * paste-a-code flow when it is false.
+   */
+  async createInvite({ projectCode, displayName, expiresHours = 168 } = {}) {
+    if (!this.adminKey) {
+      throw new Error(
+        'Creating invites needs a bmo-sync admin key (set BMO_SYNC_ADMIN_KEY). ' +
+          'Without one, ask whoever owns the shared folder to send you a code.',
+      );
+    }
+    if (!projectCode) throw new Error('A paired project is required to invite into.');
+    let res;
+    try {
+      res = await this._fetch(`${this.serverBase}/api/admin/invites`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-admin-key': this.adminKey },
+        body: JSON.stringify({
+          project_code: projectCode,
+          display_name: displayName || 'Collaborator',
+          expires_hours: Number(expiresHours) || 168,
+        }),
+        signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
+      });
+    } catch {
+      throw new Error('Could not reach the bmo-sync server. Check your connection.');
+    }
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(
+        body?.message || body?.error || `Invite creation failed (HTTP ${res.status}).`,
+      );
+    }
+    return { code: body.code, projectCode: body.project_code, expiresAt: body.expires_at };
+  }
+
+  /** A daemon fetch that turns a connection failure into a readable error. */
+  async _daemonFetch(url, init) {
+    try {
+      return await this._fetch(url, init);
+    } catch {
+      throw new Error("The bmo-sync daemon isn't running. Start it, then try again.");
+    }
+  }
+
+  // ── C12-e: conflict surface ──────────────────────────────────────────
+  // The daemon emits SyncEvent::Conflict via /api/events (already piped
+  // into the wild-workspace ActivityBus by DaemonBridge); these methods
+  // are the explicit "give me / resolve" operations behind the badge
+  // and CLI.
+
+  /** All open conflicts across every paired workspace. [] when daemon down. */
+  async listConflicts() {
+    try {
+      const res = await this._fetch(`${this.daemonBase}/api/conflicts`, {
+        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+      });
+      if (!res.ok) return [];
+      const body = await res.json().catch(() => ({}));
+      return Array.isArray(body?.conflicts) ? body.conflicts : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Fetch one conflict's mine/theirs bytes (base64) plus the row. Used by
+   * the human-fallback diff panel + the `wild_conflicts_view` agent tool.
+   */
+  async viewConflict(workspaceId, path) {
+    if (!workspaceId) throw new Error('workspaceId is required');
+    if (!path) throw new Error('path is required');
+    const url =
+      `${this.daemonBase}/api/conflicts/` +
+      `${encodeURIComponent(workspaceId)}/` +
+      path.split('/').map(encodeURIComponent).join('/');
+    const res = await this._daemonFetch(url, {
+      signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new Error(body?.error || `Conflict view failed (HTTP ${res.status}).`);
+    }
+    return body;
+  }
+
+  /**
+   * Resolve a conflict. `action` is `keep_mine` or `take_theirs`. The
+   * server-mediated multi-peer broadcast is a V1.1 follow-up; for V1
+   * this is local-only.
+   */
+  async resolveConflict(workspaceId, path, action) {
+    const verb = String(action || '').trim();
+    if (!['keep_mine', 'take_theirs'].includes(verb)) {
+      throw new Error('action must be "keep_mine" or "take_theirs".');
+    }
+    // GET = view, POST = resolve on the same URL — the daemon's route was
+    // collapsed because axum 0.8 disallows a literal segment after a
+    // `{*path}` catchall.
+    const url =
+      `${this.daemonBase}/api/conflicts/` +
+      `${encodeURIComponent(workspaceId)}/` +
+      path.split('/').map(encodeURIComponent).join('/');
+    const res = await this._daemonFetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action: verb }),
+      signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(body?.error || `Resolve failed (HTTP ${res.status}).`);
+    }
+    return { ok: true };
+  }
+}
+
+function trimSlash(u) {
+  return typeof u === 'string' ? u.replace(/\/+$/, '') : '';
+}