Merge pull request #5281 from nexu-io/feat/collab-daemon-resources

Team collaboration (1/3): backend — contracts, presence, comments, sync, resource sharing

Author: lefarcen

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,
@@ -689,6 +692,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/invite-continue.ts

@@ -0,0 +1,78 @@
+import type { WorkspaceCollabContext } from '@open-design/contracts';
+import { readVelaControlApiContext } from '../integrations/vela.js';
+import { mapVelaWorkspaceContext } from './vela-workspace-context.js';
+
+// Daemon half of the desktop invite hand-off ("桌面唤起和本地恢复", C's lane in
+// the B-C invite contract). The desktop app receives an
+// `opendesign://workspace/invite/continue?...&nonce=...` deeplink, parses it, and
+// forwards the nonce here. The daemon proves identity with the SAME signed-in vela
+// session (never a client-supplied one) and consumes the one-time continuation on
+// B, which finalizes the membership and returns the current workspace context so
+// the client can switch into the team workspace. Any failure degrades to a typed
+// outcome the route maps onto HTTP — it never throws into the caller.
+
+const DEFAULT_TIMEOUT_MS = 8_000;
+
+function consumePath(nonce: string): string {
+  return `/api/v1/workspace-invites/continuations/${encodeURIComponent(nonce)}/consume`;
+}
+
+export type InviteContinueOutcome =
+  | { ok: true; context: WorkspaceCollabContext | null; workspaceMemberId: string }
+  | { ok: false; status: number; error: string };
+
+export interface ConsumeInviteContinuationOptions {
+  /** Injectable for tests. */
+  fetch?: typeof fetch;
+  /** Injectable for tests; defaults to reading ~/.amr / env. */
+  readSession?: typeof readVelaControlApiContext;
+  timeoutMs?: number;
+}
+
+/**
+ * Consume an invite continuation nonce against B using the local vela session,
+ * returning the mapped workspace context on success. Errors are typed, not
+ * thrown: `no_session` (401) when the client is not signed in, `continuation_<n>`
+ * for B's 401/403/409/410 (subject mismatch / already consumed / expired), and
+ * `continuation_unreachable` (502) on a transport failure.
+ */
+export async function consumeInviteContinuation(
+  nonce: string,
+  options: ConsumeInviteContinuationOptions = {},
+): Promise<InviteContinueOutcome> {
+  const fetchImpl = options.fetch ?? fetch;
+  const readSession = options.readSession ?? readVelaControlApiContext;
+  const trimmed = nonce.trim();
+  if (!trimmed) return { ok: false, status: 400, error: 'missing_nonce' };
+
+  const session = readSession();
+  if (!session || !session.controlKey || !session.apiUrl) {
+    return { ok: false, status: 401, error: 'no_session' };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(new URL(consumePath(trimmed), session.apiUrl), {
+      method: 'POST',
+      headers: { authorization: `Bearer ${session.controlKey}` },
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return { ok: false, status: response.status, error: `continuation_${response.status}` };
+    }
+    const body = (await response.json()) as {
+      workspaceMemberId?: unknown;
+      currentWorkspaceContext?: unknown;
+    };
+    return {
+      ok: true,
+      context: mapVelaWorkspaceContext(body.currentWorkspaceContext),
+      workspaceMemberId: typeof body.workspaceMemberId === 'string' ? body.workspaceMemberId : '',
+    };
+  } catch {
+    return { ok: false, status: 502, error: 'continuation_unreachable' };
+  } finally {
+    clearTimeout(timeout);
+  }
+}