feat: team-edition collaboration surfaces + workspace-context seam

apps/daemon/src/cli.ts

@@ -195,6 +195,8 @@ const CONFIG_STRING_FLAGS = new Set(['daemon-url', 'value', 'value-json']);
 const CONFIG_BOOLEAN_FLAGS = new Set(['help', 'h', 'json']);
 const AMR_STRING_FLAGS = new Set(['daemon-url']);
 const AMR_BOOLEAN_FLAGS = new Set(['help', 'h', 'json', 'refresh']);
+const COLLAB_STRING_FLAGS = new Set(['daemon-url', 'project', 'member', 'name', 'role', 'design-system']);
+const COLLAB_BOOLEAN_FLAGS = new Set(['help', 'h', 'json']);
 const PROJECT_STRING_FLAGS = new Set([
   'daemon-url', 'name', 'skill', 'design-system', 'plugin', 'metadata-json',
   'pending-prompt', 'project', 'conversation', 'message', 'prompt',
@@ -311,6 +313,7 @@ const SUBCOMMAND_MAP = {
   media: runMedia,
   mcp: runMcp,
   amr: runAmr,
+  collab: runCollab,
   research: runResearch,
   plugin: runPlugin,
   ui: runUi,
@@ -687,6 +690,242 @@ Options:
   }
 }
 
+// ---------------------------------------------------------------------------
+// Subcommand: od collab …  (team-edition collaboration)
+// ---------------------------------------------------------------------------
+
+function printCollabHelp() {
+  console.log(`Usage:
+  od collab status <projectId> [--json]
+  od collab presence <projectId> [--json]
+  od collab heartbeat <projectId> --member <id> [--name <name>] [--role owner|admin|member] [--json]
+  od collab leave <projectId> --member <id> [--json]
+  od collab changed <projectId> [--json]
+  od collab publish <projectId> [--json]
+  od collab share <projectId> [--json]
+  od collab pull <projectId> [--json]
+  od collab share-resource <design-systems|plugins|skills> <id> [--json]
+  od collab team-resources <design-systems|plugins|skills> [--json]
+  od collab share-design-system <designSystemId> [--json]
+  od collab team-design-systems [--json]
+
+Team-edition collaboration: presence overlay + sync trigger. The
+client is authoritative about whether it is in a shared context, so it drives
+the trigger; the daemon coalesces author edits and flushes at a run boundary,
+advancing the published head version members poll to learn when to pull.
+\`share\` is the team-share intent: it requests the project be published so
+members can pull it, and reports the sync state (local_only / pending_upload /
+synced / sync_failed). \`share-resource <kind> <id>\` promotes a personal design
+system, plugin, or skill into the team scope through the resource hub, and
+\`team-resources <kind>\` lists the ones already shared (the \`*-design-system\`
+forms are kept as aliases).
+
+Options:
+  --project <id>          Project id (alternative to the positional argument).
+  --design-system <id>    Design system id for share-design-system.
+  --member <id>           Member id for the presence heartbeat / leave.
+  --name <name>           Display name attached to a heartbeat.
+  --role <role>           owner | admin | member.
+  --json                  Emit raw JSON.
+  --daemon-url <url>      Override daemon URL.
+
+Examples:
+  od collab presence p1 --json
+  od collab heartbeat p1 --member m-42 --name "Ma Shu" --role member
+  od collab publish p1
+  od collab share-resource plugins my-plugin --json
+  od collab team-resources skills --json
+  od collab share-design-system user:palette-x --json
+  od collab status p1 --json`);
+}
+
+async function runCollab(args) {
+  const sub = args[0];
+  if (!sub || sub === 'help' || args.includes('--help') || args.includes('-h')) {
+    printCollabHelp();
+    process.exit(!sub ? 2 : 0);
+  }
+  const rest = args.slice(1);
+  let flags;
+  try {
+    flags = parseFlags(rest, { string: COLLAB_STRING_FLAGS, boolean: COLLAB_BOOLEAN_FLAGS });
+  } catch (err) {
+    console.error(err.message);
+    process.exit(2);
+  }
+  // Team resource sharing (design systems / plugins / skills) is workspace-scoped
+  // — it takes a resource id, not a project id — so it runs before the project-id
+  // requirement below. `share-resource <kind> <id>` / `team-resources <kind>` are
+  // the generic forms; the design-system aliases are kept for compatibility.
+  const RESOURCE_BASE_PATHS = new Set(['design-systems', 'plugins', 'skills']);
+  if (
+    sub === 'share-resource' ||
+    sub === 'team-resources' ||
+    sub === 'share-design-system' ||
+    sub === 'team-design-systems'
+  ) {
+    const base = await cliDaemonBaseUrl(flags);
+    const emit = (payload, plain) =>
+      flags.json ? process.stdout.write(JSON.stringify(payload, null, 2) + '\n') : plain();
+    const wsRequest = async (method, path, body) => {
+      let resp;
+      try {
+        resp = await fetch(`${base}${path}`, {
+          method,
+          ...(body !== undefined
+            ? { headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }
+            : {}),
+        });
+      } catch (err) {
+        surfaceFetchError(err, base);
+        process.exit(3);
+      }
+      if (!resp.ok) return structuredHttpFailure(resp);
+      return resp.json();
+    };
+
+    // Resolve the resource kind (URL base path), whether this lists or shares,
+    // and the target id — from either the aliases or the generic <kind> <id>.
+    const positionals = positionalArgs(rest, COLLAB_STRING_FLAGS);
+    let basePath;
+    let isList;
+    let resourceId;
+    if (sub === 'team-design-systems') {
+      basePath = 'design-systems';
+      isList = true;
+    } else if (sub === 'share-design-system') {
+      basePath = 'design-systems';
+      isList = false;
+      resourceId = flags['design-system'] || positionals[0];
+    } else {
+      basePath = positionals[0];
+      if (!RESOURCE_BASE_PATHS.has(basePath)) {
+        console.error('kind must be one of: design-systems | plugins | skills');
+        process.exit(2);
+      }
+      isList = sub === 'team-resources';
+      resourceId = positionals[1];
+    }
+
+    if (isList) {
+      const body = await wsRequest('GET', `/api/workspace/${basePath}/team`);
+      return emit(body, () => {
+        const ids = Array.isArray(body?.ids) ? body.ids : [];
+        if (ids.length === 0) return console.log(`no shared ${basePath}`);
+        for (const id of ids) console.log(id);
+      });
+    }
+    if (!resourceId) {
+      console.error('missing <id>');
+      process.exit(2);
+    }
+    const body = await wsRequest(
+      'POST',
+      `/api/workspace/${basePath}/${encodeURIComponent(resourceId)}/share`,
+    );
+    return emit(body, () =>
+      console.log(`shared=${body?.shared ?? false}\tversion=${body?.version ?? '-'}`),
+    );
+  }
+
+  const projectId =
+    flags.project || positionalArgs(rest, COLLAB_STRING_FLAGS)[0] || process.env.OD_PROJECT_ID;
+  if (!projectId) {
+    console.error('missing <projectId> (positional, --project, or OD_PROJECT_ID)');
+    process.exit(2);
+  }
+  const base = await cliDaemonBaseUrl(flags);
+  const encoded = encodeURIComponent(projectId);
+
+  const request = async (method, path, body) => {
+    let resp;
+    try {
+      resp = await fetch(`${base}/api/projects/${encoded}${path}`, {
+        method,
+        ...(body !== undefined
+          ? { headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }
+          : {}),
+      });
+    } catch (err) {
+      surfaceFetchError(err, base);
+      process.exit(3);
+    }
+    if (!resp.ok) return structuredHttpFailure(resp);
+    return resp.json();
+  };
+
+  const emit = (payload, plain) => {
+    if (flags.json) return process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    return plain();
+  };
+
+  switch (sub) {
+    case 'status': {
+      const body = await request('GET', '/collab/status');
+      return emit(body, () => {
+        console.log(`publishedVersion\t${body?.publishedVersion ?? '-'}`);
+        console.log(`syncState\t${body?.syncState ?? '-'}`);
+      });
+    }
+    case 'share': {
+      // Team-share intent: request the project be published so members can pull.
+      const body = await request('POST', '/collab/sync-intent', {
+        event: 'project_team_share_requested',
+        projectId,
+      });
+      return emit(body, () => console.log(`ok\tsyncState=${body?.syncState ?? '-'}`));
+    }
+    case 'pull': {
+      // Member pull: fetch the published head (E extracts the bytes behind C's trigger).
+      const body = await request('POST', '/collab/pull');
+      return emit(body, () => console.log(`pulled\tversion=${body?.version ?? '-'}`));
+    }
+    case 'presence': {
+      const body = await request('GET', '/presence');
+      return emit(body, () => {
+        const present = Array.isArray(body?.present) ? body.present : [];
+        if (present.length === 0) return console.log('no members present');
+        for (const m of present) console.log(`${m.memberId}\t${m.name ?? '-'}\t${m.role ?? '-'}`);
+      });
+    }
+    case 'heartbeat': {
+      if (!flags.member) {
+        console.error('missing --member <id>');
+        process.exit(2);
+      }
+      const memberBody = {
+        memberId: flags.member,
+        ...(flags.name ? { name: flags.name } : {}),
+        ...(flags.role ? { role: flags.role } : {}),
+      };
+      const body = await request('POST', '/presence/heartbeat', memberBody);
+      return emit(body, () => {
+        const present = Array.isArray(body?.present) ? body.present : [];
+        console.log(`ok\t${present.length} present`);
+      });
+    }
+    case 'leave': {
+      if (!flags.member) {
+        console.error('missing --member <id>');
+        process.exit(2);
+      }
+      const body = await request('POST', '/presence/leave', { memberId: flags.member });
+      return emit(body, () => console.log('left'));
+    }
+    case 'changed': {
+      const body = await request('POST', '/collab/changed');
+      return emit(body, () => console.log('change queued'));
+    }
+    case 'publish': {
+      const body = await request('POST', '/collab/publish');
+      return emit(body, () => console.log('publish requested'));
+    }
+    default:
+      console.error(`unknown subcommand: od collab ${sub}`);
+      process.exit(2);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Subcommand: od research …
 // ---------------------------------------------------------------------------

apps/daemon/src/collab/presence-tracker.ts

@@ -0,0 +1,92 @@
+// Team collaboration presence — the "presence" overlay: who is currently viewing a
+// shared project. Decoupled from the resource/sync layer: it is a
+// lightweight, poll-friendly heartbeat set, not a realtime-cursor engine (live
+// cursors were cut; content is polled).
+//
+// Pure and timer-free by design. `present()` computes the live set on demand and
+// sweeps anyone whose heartbeat has aged past the TTL, so the orchestrator's
+// existing poll loop surfaces departures without a background timer. Explicit
+// join/leave fire `onChange` immediately so an active viewer's arrival/exit can
+// be broadcast without waiting for the next poll.
+
+import type { CollabPresenceMember } from '@open-design/contracts';
+
+// The presence identity shape is the shared contract DTO; keep the local name
+// for existing daemon-side imports.
+export type PresenceMember = CollabPresenceMember;
+
+export interface CollabPresenceTrackerOptions {
+  /** A member is considered gone this long after their last heartbeat. */
+  ttlMs?: number;
+  now?: () => number;
+  /** Fired when a project's present set changes via an explicit join or leave. */
+  onChange?: (result: { projectId: string; present: PresenceMember[] }) => void;
+}
+
+interface Entry {
+  member: PresenceMember;
+  lastSeen: number;
+}
+
+const DEFAULT_TTL_MS = 30_000;
+
+export class CollabPresenceTracker {
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+  private readonly onChange?: CollabPresenceTrackerOptions['onChange'];
+  private readonly projects = new Map<string, Map<string, Entry>>();
+
+  constructor(options: CollabPresenceTrackerOptions = {}) {
+    this.ttlMs = Math.max(0, options.ttlMs ?? DEFAULT_TTL_MS);
+    this.now = options.now ?? Date.now;
+    this.onChange = options.onChange;
+  }
+
+  /** Mark a member present in a project (call on view + on each poll). */
+  heartbeat(projectId: string, member: PresenceMember): void {
+    const entries = this.ensure(projectId);
+    const isNew = !entries.has(member.memberId);
+    entries.set(member.memberId, { member, lastSeen: this.now() });
+    if (isNew) this.emit(projectId);
+  }
+
+  /** Explicit departure (tab closed / left the project). */
+  leave(projectId: string, memberId: string): void {
+    const entries = this.projects.get(projectId);
+    if (!entries || !entries.delete(memberId)) return;
+    if (entries.size === 0) this.projects.delete(projectId);
+    this.emit(projectId);
+  }
+
+  /** Members present now — sweeps any whose heartbeat aged past the TTL. */
+  present(projectId: string): PresenceMember[] {
+    const entries = this.projects.get(projectId);
+    if (!entries) return [];
+    const cutoff = this.now() - this.ttlMs;
+    for (const [memberId, entry] of entries) {
+      if (entry.lastSeen < cutoff) entries.delete(memberId);
+    }
+    if (entries.size === 0) {
+      this.projects.delete(projectId);
+      return [];
+    }
+    return Array.from(entries.values(), (entry) => entry.member);
+  }
+
+  dispose(): void {
+    this.projects.clear();
+  }
+
+  private emit(projectId: string): void {
+    if (this.onChange) this.onChange({ projectId, present: this.present(projectId) });
+  }
+
+  private ensure(projectId: string): Map<string, Entry> {
+    let entries = this.projects.get(projectId);
+    if (!entries) {
+      entries = new Map();
+      this.projects.set(projectId, entries);
+    }
+    return entries;
+  }
+}