Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

28.3 KB
Raw Blame
#!/usr/bin/env npx tsx

/**
 * gRPC contract reference generator (cua.env.v1 and cua.daemon.v1).
 *
 * Source: `buf build libs/cua/proto -o -#format=json`, a FileDescriptorSet as
 * proto3 JSON that keeps SourceCodeInfo, so every leading comment (mandatory
 * under the module's `COMMENTS` lint) reaches the page. The gRPC-Web
 * fallbacks, metadata keys and protocol revision come from
 * `libs/cua/crates/cua-proto/src/lib.rs`.
 *
 * Usage:
 *   pnpm --dir docs docs:generate:cua-proto
 *   pnpm --dir docs docs:check:cua-proto     # drift gate (CI)
 *
 * Set BUF=/path/to/buf to pick the binary (CI pins buf 1.73.0).
 */

import { execFileSync } from 'child_process';
import * as fs from 'fs';
import * as path from 'path';
import {
  DOCS_CONTENT,
  REPO_ROOT,
  codeCell,
  escapeMdxText,
  escapeTableCell,
  finish,
  isCheckMode,
  metaJson,
  readHeader,
  renderPage,
  slug,
  syncFiles,
  wordCount,
} from './lib/mdx';

// ============================================================================
// Descriptor types (the subset of descriptor.proto the renderer reads)
// ============================================================================

export interface FieldDescriptor {
  name: string;
  number: number;
  label?: string;
  type?: string;
  typeName?: string;
  oneofIndex?: number;
  proto3Optional?: boolean;
  options?: { deprecated?: boolean };
}

export interface MessageDescriptor {
  name: string;
  field?: FieldDescriptor[];
  nestedType?: MessageDescriptor[];
  enumType?: EnumDescriptor[];
  oneofDecl?: Array<{ name: string }>;
  options?: { mapEntry?: boolean; deprecated?: boolean };
}

export interface EnumDescriptor {
  name: string;
  value?: Array<{ name: string; number: number; options?: { deprecated?: boolean } }>;
  options?: { deprecated?: boolean };
}

export interface MethodDescriptor {
  name: string;
  inputType: string;
  outputType: string;
  clientStreaming?: boolean;
  serverStreaming?: boolean;
  options?: { deprecated?: boolean };
}

export interface ServiceDescriptor {
  name: string;
  method?: MethodDescriptor[];
  options?: { deprecated?: boolean };
}

export interface FileDescriptor {
  name: string;
  package?: string;
  messageType?: MessageDescriptor[];
  enumType?: EnumDescriptor[];
  service?: ServiceDescriptor[];
  sourceCodeInfo?: { location?: Array<{ path?: number[]; leadingComments?: string }> };
}

export interface FileDescriptorSet {
  file: FileDescriptor[];
}

/** Facts from cua-proto's lib.rs that the descriptors do not carry. */
export interface ContractFacts {
  /** `/pkg.Service/Method` of a client stream -> its unary gRPC-Web fallback. */
  fallbacks: Array<[string, string]>;
  /** Metadata keys and HTTP paths: constant name -> [value, doc]. */
  metadata: Array<{ name: string; value: string; doc: string }>;
  protocolVersion: string;
  protocolRevision: string;
}

// ============================================================================
// Page layout
// ============================================================================

export interface PageSpec {
  slug: string;
  title: string;
  description: string;
  intro: string;
  files: string[];
}

const ROUTE = '/cua-sdk/reference/protocol';
const OUTPUT_DIR = path.join(DOCS_CONTENT, 'cua-sdk', 'reference', 'protocol');
const GENERATOR = 'pnpm --dir docs docs:generate:cua-proto';
/** One page per service family, within the docs page budget (docs/scripts/page-budget.test.ts). */
export const MAX_WORDS = 12_000;
export const MAX_BYTES = 100_000;
const PROTO_DIR = path.join(REPO_ROOT, 'libs', 'cua', 'proto');
const LIB_RS = path.join(REPO_ROOT, 'libs', 'cua', 'crates', 'cua-proto', 'src', 'lib.rs');
const VERSION_FILE = path.join(REPO_ROOT, 'libs', 'cua', 'VERSION');

/**
 * Every contract file belongs to exactly one page. A new .proto file fails
 * generation until it is placed here, so the nav never silently grows.
 */
export const PAGES: PageSpec[] = [
  {
    slug: 'env-system',
    title: 'System, diagnostics and shared types',
    description:
      'cua.env.v1 SystemService, the image self-test report, and the types every spacesd service shares: ErrorInfo, principals and geometry.',
    intro:
      'The handshake (`GetCapabilities`), session init, health, shutdown, viewer tickets and joining a relay (`AttachRelay`); the report of the image self-test (`SystemService.Diagnose` / `DiagnoseOnce`); and the shared types: errors (`google.rpc.Status` carrying `ErrorInfo`), principals and geometry.',
    files: ['cua/env/v1/system.proto', 'cua/env/v1/diagnose.proto', 'cua/env/v1/common.proto'],
  },
  {
    slug: 'env-process',
    title: 'Processes and files',
    description:
      'cua.env.v1 ProcessService and FilesystemService: guest processes, and stat, list, watch, read, chunked upload and signed URLs.',
    intro:
      'Detached, reattachable guest processes with PTY support and bounded scrollback; file and directory operations, watchers, chunked transfers and signed HTTP URLs.',
    files: ['cua/env/v1/process.proto', 'cua/env/v1/filesystem.proto'],
  },
  {
    slug: 'env-computer',
    title: 'Computer, windows and accessibility',
    description:
      'cua.env.v1 ComputerService, DriverService, WindowsService and AccessibilityService: screenshots, input, clipboard, displays, Cua Driver tools, windows and the accessibility tree.',
    intro:
      'Desktop control. These services need the desktop provider; input goes through Cua Driver, which `DriverService` also exposes tool by tool.',
    files: ['cua/env/v1/computer.proto', 'cua/env/v1/driver.proto', 'cua/env/v1/windows.proto', 'cua/env/v1/accessibility.proto'],
  },
  {
    slug: 'env-stream',
    title: 'Streams, teleport and tunnels',
    description:
      'cua.env.v1 StreamService, PresenceService, TeleportService, TunnelService and VolumeService.',
    intro:
      'Media sessions (video and audio over the media wire, see `libs/cua/proto/MEDIA.md`) and presence; the receiving side of teleport (sending lives in the cua SDK), TCP port forwards, the reverse-SOCKS hotspot and the guest mount of Cua Volume. Host Spaces are on [Host Spaces](/cua-sdk/reference/protocol/env-host-spaces).',
    files: [
      'cua/env/v1/stream.proto',
      'cua/env/v1/presence.proto',
      'cua/env/v1/teleport.proto',
      'cua/env/v1/tunnel.proto',
      'cua/env/v1/volume.proto',
    ],
  },
  {
    slug: 'env-host-spaces',
    title: 'Host Spaces',
    description:
      'cua.env.v1 HostSpacesService: Spaces a host creates for its owner\'s devices through the relay.',
    intro:
      'Spaces a machine set up with `cua host setup --share both` creates for its owner\'s enrolled devices: settings, capacity, create and delete. The host\'s cua-spacesd forwards each call to its cua daemon. What a host reports for placement is on [Host capacity](/cua-sdk/reference/protocol/env-host-capacity).',
    files: ['cua/env/v1/host.proto'],
  },
  {
    slug: 'env-host-capacity',
    title: 'Host capacity',
    description:
      'cua.env.v1 HostNodeStatus and HostMeasured: what a host reports for placement (capacity, load, measured memory).',
    intro:
      'What a host reports to whoever places Spaces and jobs on it: `HostNodeStatus` (kinds, runtimes, CPU and memory, jobs) and, in `HostNodeStatus.measured`, what it measures rather than reserves: available memory, memory pressure, and how many more VMs fit when VMs share snapshot memory.',
    files: ['cua/env/v1/capacity.proto'],
  },
  {
    slug: 'env-host-warm',
    title: 'Host prewarms',
    description:
      'cua.env.v1 SetHostWarm: the warm pool a host keeps for a prewarm, so the next creates of a shape start at once.',
    intro:
      'A prewarm\'s warm pool on a host (`HostSpacesService.SetHostWarm`): Spaces of one shape kept ready, claimed by the next creates of that shape, ended at the TTL or when the count is 0.',
    files: ['cua/env/v1/warm.proto'],
  },
  {
    slug: 'env-host-snapshots',
    title: 'Host snapshots',
    description:
      'cua.env.v1 HostSnapshotsService: the checkpoints a host holds, and copying them between your machines.',
    intro:
      'Checkpoints a host holds and copying them to your other machines: a manifest of files by SHA-256, read grants, resumable LAN copies with verification, and a fallback copy in S3 or a shared folder. The host\'s cua-spacesd forwards each call to its cua daemon.',
    files: ['cua/env/v1/snapshots.proto'],
  },
  {
    slug: 'daemon-resize',
    title: 'Daemon: resize',
    description: 'cua.daemon.v1 ResizeSandbox: give a local VM another shape.',
    intro:
      'The messages of `SandboxService.ResizeSandbox`: a local VM stops and boots again from its own disk with new vCPUs, memory and a larger disk.',
    files: ['cua/daemon/v1/resize.proto'],
  },
  {
    slug: 'daemon-fork-batch',
    title: 'Daemon: batched forks',
    description:
      'cua.daemon.v1 batched forks: many sandboxes from checkpoints at once, on this machine or across your machines.',
    intro:
      'Requests and events of `SandboxService.ForkSandboxBatch`: groups of forks of one checkpoint placed together on one machine, checkpoints spread over the least-loaded machines, each fork streamed as it is ready.',
    files: ['cua/daemon/v1/fork_batch.proto'],
  },
  {
    slug: 'daemon-shares',
    title: 'Daemon: shares',
    description:
      'cua.daemon.v1 ShareService: links to a port, a Space port, a file or a folder that open on your other signed-in devices.',
    intro:
      'Shares are links the `cua daemon` owns and serves (`cua share`): created, listed, stopped and checked through `ShareService`.',
    files: ['cua/daemon/v1/shares.proto'],
  },
  {
    slug: 'daemon-builds',
    title: 'Daemon: builds',
    description: 'cua.daemon.v1 builds: the messages of SpaceService.BuildSpace, ListBuilds and DeleteBuild.',
    intro: 'Building an image from a Dockerfile or steps into pinned checkpoints, its progress, result and listing.',
    files: ['cua/daemon/v1/builds.proto'],
  },
  {
    slug: 'daemon-egress',
    title: 'Egress policies',
    description: 'EgressPolicy: which destinations a Space may open connections to, enforced by the host outside the guest.',
    intro: 'The egress policy `CreateSpaceRequest.egress` and `SpaceService.SetSpaceEgress` take and `Space.egress` returns, and its host form for `HostSpacesService.SetHostSpaceEgress`.',
    files: ['cua/daemon/v1/egress.proto', 'cua/env/v1/host_egress.proto'],
  },
  {
    slug: 'daemon',
    title: 'Cua daemon: sandboxes and runtimes',
    description:
      'cua.daemon.v1 SandboxService and RuntimeService: sandbox lifecycle across locations, checkpoints and forks, local pools, and the local runtimes and images.',
    intro:
      'The local `cua daemon` API (a Unix socket on the host, not cua-spacesd): sandbox lifecycle across locations; checkpoints of local sandboxes that new sandboxes fork from (`ForkSandbox`); local pools of ready sandboxes (`ApplyPool`, `ListPools`, `DeletePool`, claimed by a create that names one in `local_pool`); and the local runtimes (gVisor, runc, QEMU, Lume, Firecracker) and images it orchestrates. Spaces and the daemon\'s identity are on [Daemon: Spaces and service](/cua-sdk/reference/protocol/daemon-spaces).',
    files: ['cua/daemon/v1/sandboxes.proto', 'cua/daemon/v1/checkpoints.proto', 'cua/daemon/v1/pools.proto', 'cua/daemon/v1/runtime.proto'],
  },
  {
    slug: 'daemon-spaces',
    title: 'Daemon: Spaces and service',
    description:
      'cua.daemon.v1 SpaceService and DaemonService: Spaces and the computers that provide them, the daemon\'s identity and the media bridge.',
    intro:
      'Spaces through the local `cua daemon` (create, list, power, delete, and the computers that provide Spaces), batch runs on your computers (`PoolRequest`), the daemon identity (`GetInfo`) and the loopback media bridge for webviews.',
    files: ['cua/daemon/v1/spaces.proto', 'cua/daemon/v1/daemon.proto'],
  },
  {
    slug: 'daemon-resources',
    title: 'Daemon: resources',
    description: 'cua.daemon.v1 resource messages: processor, memory and disk of this Mac, its extra Spaces and your other computers.',
    intro: 'What `SpaceService.GetResources` and `WatchResources` return: one snapshot, then updates and the low-disk warning. Numbers only.',
    files: ['cua/daemon/v1/resources.proto'],
  },
];

// ============================================================================
// Inputs
// ============================================================================

export function buildDescriptorSet(buf = process.env.BUF || 'buf'): FileDescriptorSet {
  const json = execFileSync(buf, ['build', PROTO_DIR, '-o', '-#format=json'], {
    cwd: REPO_ROOT,
    encoding: 'utf-8',
    maxBuffer: 256 * 1024 * 1024,
  });
  return JSON.parse(json) as FileDescriptorSet;
}

/** Reads fallbacks, metadata keys and the protocol revision from lib.rs. */
export function parseContractFacts(libRs: string): ContractFacts {
  const fallbackBlock = libRs.match(/CLIENT_STREAM_FALLBACKS[^=]*=\s*&\[([\s\S]*?)\];/);
  const fallbacks: Array<[string, string]> = [];
  if (fallbackBlock) {
    for (const m of fallbackBlock[1].matchAll(/\(\s*"([^"]+)",\s*"([^"]+)",?\s*\)/g)) {
      fallbacks.push([m[1], m[2]]);
    }
  }
  const metadata: ContractFacts['metadata'] = [];
  const metaBlock = libRs.match(/pub mod metadata \{([\s\S]*?)\n\}/);
  if (metaBlock) {
    let doc: string[] = [];
    for (const line of metaBlock[1].split('\n')) {
      const d = line.match(/^\s*\/\/\/\s?(.*)$/);
      if (d) {
        doc.push(d[1]);
        continue;
      }
      const c = line.match(/pub const (\w+): &str = "([^"]*)";/);
      if (c) metadata.push({ name: c[1], value: c[2], doc: doc.join(' ').trim() });
      doc = [];
    }
  }
  const num = (name: string) => libRs.match(new RegExp(`${name}: u32 = (\\d+);`))?.[1] ?? '';
  return {
    fallbacks,
    metadata,
    protocolVersion: num('ENV_PROTOCOL_VERSION'),
    protocolRevision: num('ENV_PROTOCOL_REVISION'),
  };
}

// ============================================================================
// Rendering
// ============================================================================

interface TypeRef {
  page: string;
  anchor: string;
  display: string;
}

/** Leading comments by source path (`4,0,2,1`). */
function commentIndex(file: FileDescriptor): Map<string, string> {
  const out = new Map<string, string>();
  for (const loc of file.sourceCodeInfo?.location ?? []) {
    if (loc.path && loc.leadingComments) out.set(loc.path.join(','), loc.leadingComments);
  }
  return out;
}

/** A proto comment as Markdown: one leading space stripped, MDX escaped. */
export function commentMarkdown(raw: string | undefined): string {
  if (!raw) return '';
  return raw
    .replace(/\n$/, '')
    .split('\n')
    .map((line) => line.replace(/^ /, ''))
    .map((line) => (/^\s*#/.test(line) ? line.replace('#', '\\#') : line))
    .map((line) => escapeMdxText(line))
    .join('\n')
    .trim();
}

/** A comment flattened for a table cell. */
function commentCell(raw: string | undefined): string {
  if (!raw) return '';
  return escapeTableCell(
    raw
      .split('\n')
      .map((l) => l.trim())
      .join(' ')
      .replace(/\s+/g, ' ')
  );
}

const SCALARS: Record<string, string> = {
  TYPE_DOUBLE: 'double',
  TYPE_FLOAT: 'float',
  TYPE_INT64: 'int64',
  TYPE_UINT64: 'uint64',
  TYPE_INT32: 'int32',
  TYPE_FIXED64: 'fixed64',
  TYPE_FIXED32: 'fixed32',
  TYPE_BOOL: 'bool',
  TYPE_STRING: 'string',
  TYPE_BYTES: 'bytes',
  TYPE_UINT32: 'uint32',
  TYPE_SFIXED32: 'sfixed32',
  TYPE_SFIXED64: 'sfixed64',
  TYPE_SINT32: 'sint32',
  TYPE_SINT64: 'sint64',
};

class Renderer {
  /** Fully qualified name (`.cua.env.v1.Foo`) -> where it is documented. */
  private readonly types = new Map<string, TypeRef>();
  /** Map-entry messages, rendered inline as `map<K, V>`. */
  private readonly mapEntries = new Map<string, MessageDescriptor>();

  constructor(
    private readonly set: FileDescriptorSet,
    private readonly pages: PageSpec[],
    private readonly facts: ContractFacts
  ) {
    const owner = new Map<string, string>();
    for (const page of pages) for (const f of page.files) owner.set(f, page.slug);
    for (const file of this.contractFiles()) {
      const page = owner.get(file.name);
      if (!page) {
        throw new Error(
          `${file.name} is not assigned to a reference page; add it to PAGES in scripts/docs-generators/proto.ts`
        );
      }
      const pkg = `.${file.package}`;
      const visitMessage = (m: MessageDescriptor, prefix: string) => {
        const display = prefix ? `${prefix}.${m.name}` : m.name;
        const fq = `${pkg}.${display}`;
        if (m.options?.mapEntry) this.mapEntries.set(fq, m);
        else this.types.set(fq, { page, anchor: slug(display), display });
        for (const e of m.enumType ?? []) {
          const ed = `${display}.${e.name}`;
          this.types.set(`${pkg}.${ed}`, { page, anchor: slug(ed), display: ed });
        }
        for (const n of m.nestedType ?? []) visitMessage(n, display);
      };
      for (const m of file.messageType ?? []) visitMessage(m, '');
      for (const e of file.enumType ?? []) {
        this.types.set(`${pkg}.${e.name}`, { page, anchor: slug(e.name), display: e.name });
      }
    }
    for (const page of pages) {
      for (const f of page.files) {
        if (!this.set.file.some((file) => file.name === f)) {
          throw new Error(`${f} is listed in PAGES but buf did not build it`);
        }
      }
    }
  }

  contractFiles(): FileDescriptor[] {
    return this.set.file
      .filter((f) => f.package?.startsWith('cua.'))
      .sort((a, b) => a.name.localeCompare(b.name));
  }

  private file(name: string): FileDescriptor {
    return this.set.file.find((f) => f.name === name)!;
  }

  /** A type reference as a (linked) inline code span. */
  private typeLink(fq: string, fromPage: string): string {
    const ref = this.types.get(fq);
    if (!ref) {
      // Well-known and external types: name without the leading dot.
      return codeCell(fq.replace(/^\./, ''));
    }
    const href = ref.page === fromPage ? `#${ref.anchor}` : `${ROUTE}/${ref.page}#${ref.anchor}`;
    return `[${codeCell(ref.display)}](${href})`;
  }

  private fieldType(f: FieldDescriptor, page: string, oneofs: string[]): string {
    let base: string;
    const entry = f.typeName ? this.mapEntries.get(f.typeName) : undefined;
    if (entry) {
      const [k, v] = entry.field ?? [];
      return `map of ${this.fieldType(k, page, [])} to ${this.fieldType(v, page, [])}`;
    }
    if (f.type === 'TYPE_MESSAGE' || f.type === 'TYPE_ENUM')
      base = this.typeLink(f.typeName ?? '', page);
    else
      base = codeCell(SCALARS[f.type ?? ''] ?? (f.type ?? '').replace(/^TYPE_/, '').toLowerCase());
    if (f.label === 'LABEL_REPEATED') return `repeated ${base}`;
    if (f.proto3Optional) return `optional ${base}`;
    if (f.oneofIndex !== undefined && oneofs[f.oneofIndex])
      return `${base} (oneof ${codeCell(oneofs[f.oneofIndex])})`;
    return base;
  }

  private renderMessage(
    m: MessageDescriptor,
    prefix: string,
    pathPrefix: number[],
    comments: Map<string, string>,
    page: string,
    pkg: string
  ): string[] {
    if (m.options?.mapEntry) return [];
    const display = prefix ? `${prefix}.${m.name}` : m.name;
    const out: string[] = [`### ${display}`, ''];
    const doc = commentMarkdown(comments.get(pathPrefix.join(',')));
    if (m.options?.deprecated) out.push('**Deprecated.**', '');
    if (doc) out.push(doc, '');
    const fields = m.field ?? [];
    // Synthetic oneofs (proto3 `optional`) are not user-visible groups.
    const oneofs = (m.oneofDecl ?? []).map((o, i) =>
      fields.some((f) => f.oneofIndex === i && f.proto3Optional) ? '' : o.name
    );
    if (fields.length) {
      out.push('| Field | # | Type | Description |', '| --- | --- | --- | --- |');
      fields.forEach((f, i) => {
        let desc = commentCell(comments.get([...pathPrefix, 2, i].join(',')));
        if (f.options?.deprecated) desc = `Deprecated. ${desc}`.trim();
        out.push(
          `| ${codeCell(f.name)} | ${f.number} | ${this.fieldType(f, page, oneofs)} | ${desc} |`
        );
      });
      out.push('');
    } else {
      out.push('No fields.', '');
    }
    (m.enumType ?? []).forEach((e, i) => {
      out.push(...this.renderEnum(e, display, [...pathPrefix, 4, i], comments));
    });
    (m.nestedType ?? []).forEach((n, i) => {
      out.push(...this.renderMessage(n, display, [...pathPrefix, 3, i], comments, page, pkg));
    });
    return out;
  }

  private renderEnum(
    e: EnumDescriptor,
    prefix: string,
    pathPrefix: number[],
    comments: Map<string, string>
  ): string[] {
    const display = prefix ? `${prefix}.${e.name}` : e.name;
    const out: string[] = [`### ${display}`, ''];
    const doc = commentMarkdown(comments.get(pathPrefix.join(',')));
    if (e.options?.deprecated) out.push('**Deprecated.**', '');
    if (doc) out.push(doc, '');
    out.push('| Value | # | Description |', '| --- | --- | --- |');
    (e.value ?? []).forEach((v, i) => {
      let desc = commentCell(comments.get([...pathPrefix, 2, i].join(',')));
      if (v.options?.deprecated) desc = `Deprecated. ${desc}`.trim();
      out.push(`| ${codeCell(v.name)} | ${v.number} | ${desc} |`);
    });
    out.push('');
    return out;
  }

  private rpcKind(m: MethodDescriptor): string {
    if (m.clientStreaming && m.serverStreaming) return 'bidi stream';
    if (m.clientStreaming) return 'client stream';
    if (m.serverStreaming) return 'server stream';
    return 'unary';
  }

  private renderService(
    s: ServiceDescriptor,
    index: number,
    file: FileDescriptor,
    comments: Map<string, string>,
    page: string
  ): string[] {
    const fqService = `${file.package}.${s.name}`;
    const out: string[] = [`## ${s.name}`, '', `${codeCell(fqService)}`, ''];
    const doc = commentMarkdown(comments.get(`6,${index}`));
    if (s.options?.deprecated) out.push('**Deprecated.**', '');
    if (doc) out.push(doc, '');
    const methods = s.method ?? [];
    out.push('| RPC | Request | Response | Kind |', '| --- | --- | --- | --- |');
    for (const m of methods) {
      const anchor = slug(`${s.name}.${m.name}`);
      out.push(
        `| [${codeCell(m.name)}](#${anchor}) | ${this.typeLink(m.inputType, page)} | ${this.typeLink(m.outputType, page)} | ${this.rpcKind(m)} |`
      );
    }
    out.push('');
    methods.forEach((m, i) => {
      out.push(`### ${s.name}.${m.name}`, '');
      out.push(
        `${codeCell(`/${fqService}/${m.name}`)}, ${this.rpcKind(m)}: ${this.typeLink(m.inputType, page)} to ${this.typeLink(m.outputType, page)}.`,
        ''
      );
      if (m.options?.deprecated) out.push('**Deprecated.**', '');
      const mdoc = commentMarkdown(comments.get(`6,${index},2,${i}`));
      if (mdoc) out.push(mdoc, '');
      const fallback = this.facts.fallbacks.find(
        ([stream]) => stream === `/${fqService}/${m.name}`
      );
      if (fallback) {
        const [, unary] = fallback;
        const name = unary.split('/').pop()!;
        out.push(
          `<Callout type="info">gRPC-Web cannot carry client streams. Over gRPC-Web, call the unary [${codeCell(name)}](#${slug(`${s.name}.${name}`)}) instead (${codeCell(unary)}).</Callout>`,
          ''
        );
      }
    });
    return out;
  }

  renderPageBody(spec: PageSpec): { body: string; usesCallout: boolean } {
    const out: string[] = [spec.intro, ''];
    const services: string[] = [];
    const types: string[] = [];
    for (const name of spec.files) {
      const file = this.file(name);
      const comments = commentIndex(file);
      (file.service ?? []).forEach((s, i) =>
        services.push(...this.renderService(s, i, file, comments, spec.slug))
      );
      const fileTypes: string[] = [];
      (file.messageType ?? []).forEach((m, i) =>
        fileTypes.push(
          ...this.renderMessage(m, '', [4, i], comments, spec.slug, file.package ?? '')
        )
      );
      (file.enumType ?? []).forEach((e, i) =>
        fileTypes.push(...this.renderEnum(e, '', [5, i], comments))
      );
      if (fileTypes.length) types.push(`## Types in ${codeCell(name)}`, '', ...fileTypes);
    }
    const sources = spec.files.map((f) => codeCell(`libs/cua/proto/${f}`)).join(', ');
    out.push(`Source: ${sources}.`, '');
    out.push(...services, ...types);
    const body = out.join('\n');
    return { body, usesCallout: body.includes('<Callout') };
  }

  renderIndexBody(header = ''): string {
    const out: string[] = [
      'The gRPC contracts, generated from the `.proto` files in `libs/cua/proto`. `cua.env.v1` is served by cua-spacesd inside a sandbox; `cua.daemon.v1` is served by the local `cua daemon`. Changes are additive and pass `buf breaking`.',
      '',
      `Contract revision: \`cua.env.v1\` protocol version ${this.facts.protocolVersion}, revision ${this.facts.protocolRevision} (reported by \`SystemService.GetCapabilities\`).`,
      '',
      ...(header ? [header, ''] : []),
      '## Services',
      '',
      '| Service | Package | Page | RPCs |',
      '| --- | --- | --- | --- |',
    ];
    for (const spec of this.pages) {
      for (const name of spec.files) {
        const file = this.file(name);
        for (const s of file.service ?? []) {
          out.push(
            `| [${codeCell(s.name)}](${ROUTE}/${spec.slug}#${slug(s.name)}) | ${codeCell(file.package ?? '')} | [${escapeTableCell(spec.title)}](${ROUTE}/${spec.slug}) | ${(s.method ?? []).length} |`
          );
        }
      }
    }
    out.push('', '## Metadata and HTTP routes', '');
    out.push('Well-known metadata keys and HTTP paths (`cua_proto::metadata`).', '');
    out.push('| Constant | Value | Meaning |', '| --- | --- | --- |');
    for (const m of this.facts.metadata) {
      out.push(`| ${codeCell(m.name)} | ${codeCell(m.value)} | ${escapeTableCell(m.doc)} |`);
    }
    out.push('', '## gRPC-Web fallbacks', '');
    out.push(
      'gRPC-Web cannot carry client streams, so every client-streaming RPC has a unary fallback (`cua_proto::CLIENT_STREAM_FALLBACKS`).',
      ''
    );
    out.push('| Client stream | Unary fallback |', '| --- | --- |');
    for (const [stream, unary] of this.facts.fallbacks) {
      out.push(`| ${codeCell(stream)} | ${codeCell(unary)} |`);
    }
    out.push(
      '',
      '## Errors',
      '',
      'Errors are `google.rpc.Status` with typed details: spacesd packs [`ErrorInfo`](' +
        `${ROUTE}/env-system#errorinfo` +
        ') and the daemon packs [`DaemonErrorInfo`](' +
        `${ROUTE}/daemon-spaces#daemonerrorinfo` +
        ').',
      ''
    );
    return out.join('\n');
  }

  hasType(fq: string): boolean {
    return this.types.has(fq);
  }
}

export function generateProtoReference(
  set: FileDescriptorSet,
  facts: ContractFacts,
  version: string,
  pages: PageSpec[] = PAGES
): Map<string, string> {
  const r = new Renderer(set, pages, facts);
  const generator = GENERATOR;
  const source = 'buf build libs/cua/proto -o -#format=json';
  const files = new Map<string, string>();
  files.set(
    path.join(OUTPUT_DIR, 'index.mdx'),
    renderPage({
      title: 'Protocol',
      description:
        'The gRPC contracts of cua-spacesd (cua.env.v1) and the cua daemon (cua.daemon.v1): ports, routes, auth and every RPC.',
      generator,
      source,
      version,
      body: r.renderIndexBody(readHeader('cua-sdk/protocol/index.md', { version })),
    })
  );
  for (const spec of pages) {
    const { body, usesCallout } = r.renderPageBody(spec);
    files.set(
      path.join(OUTPUT_DIR, `${spec.slug}.mdx`),
      renderPage({
        title: spec.title,
        description: spec.description,
        generator,
        source,
        version,
        components: usesCallout ? ['Callout'] : [],
        body,
      })
    );
  }
  files.set(
    path.join(OUTPUT_DIR, 'meta.json'),
    metaJson('Protocol', pages.map((p) => p.slug))
  );
  return files;
}

function main(): void {
  const checkOnly = isCheckMode();
  console.log('cua gRPC contract reference generator');
  const set = buildDescriptorSet();
  const facts = parseContractFacts(fs.readFileSync(LIB_RS, 'utf-8'));
  const version = fs.readFileSync(VERSION_FILE, 'utf-8').trim();
  const files = generateProtoReference(set, facts, version);
  const big = [...files].filter(
    ([f, c]) => f.endsWith('.mdx') && (wordCount(c) > MAX_WORDS || Buffer.byteLength(c) > MAX_BYTES)
  );
  if (big.length) {
    for (const [f, c] of big) {
      console.error(`${path.basename(f)}: ${wordCount(c)} words, ${Buffer.byteLength(c)} bytes (max ${MAX_WORDS}, ${MAX_BYTES}); split it in PAGES`);
    }
    process.exit(1);
  }
  const drift = syncFiles(files, checkOnly, [OUTPUT_DIR], GENERATOR);
  finish('cua gRPC', drift, checkOnly, GENERATOR);
}

if (require.main === module) {
  main();
}