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.

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

/**
 * TypeScript reference generator: typedoc + typedoc-plugin-markdown over the
 * hand-written layer of `@trycua/cua` (libs/cua/typescript/src). The UniFFI
 * glue under `src/native/` is excluded; the UniFFI reference documents it.
 *
 * typedoc renders Markdown into a temporary directory; a post-pass then turns
 * each module into an MDX page under reference/cua-sdk/typescript/ with
 * frontmatter, the AUTO-GENERATED banner, site routes for cross-page links,
 * and an explicit meta.json.
 *
 * Usage:
 *   pnpm --dir docs docs:generate:cua-sdk-ts
 *   pnpm --dir docs docs:check:cua-sdk-ts
 *
 * Needs `npm ci` in libs/cua/typescript (the package's own type dependencies)
 * and `pnpm --dir docs install` (typedoc and typedoc-plugin-markdown, pinned).
 */

import * as fs from 'fs';
import { createRequire } from 'module';
import * as os from 'os';
import * as path from 'path';
import {
  DOCS_CONTENT,
  REPO_ROOT,
  finish,
  isCheckMode,
  metaJson,
  readHeader,
  renderPage,
  slug,
  syncFiles,
} from './lib/mdx';

const PACKAGE_DIR = path.join(REPO_ROOT, 'libs', 'cua', 'typescript');
const SOURCE_DIR = path.join(PACKAGE_DIR, 'src');
const OUTPUT_DIR = path.join(DOCS_CONTENT, 'cua-sdk', 'reference', 'typescript');
const ROUTE = '/cua-sdk/reference/typescript';

/** One page per public entry point (the package.json `exports`). */
export const MODULES: Array<{
  entry: string;
  /** typedoc-plugin-markdown's file for the module (outputFileStrategy=modules). */
  typedocFile: string;
  page: string;
  title: string;
  importPath: string;
  description: string;
}> = [
  {
    entry: 'index.ts',
    typedocFile: 'index-1.md',
    page: 'index',
    title: 'TypeScript additions',
    importPath: '@trycua/cua',
    description:
      'The hand-written helpers of @trycua/cua (embedded, connect, Image, probes, sidecars, specs, MCP), and the Spaces transport and host modules.',
  },
  {
    entry: 'spaces/index.ts',
    typedocFile: 'spaces.md',
    page: 'spaces',
    title: 'Spaces (TypeScript)',
    importPath: '@trycua/cua/spaces',
    description:
      'The @trycua/cua/spaces helpers: threads, events, teleport approvals and typed errors.',
  },
  {
    entry: 'spaces/transport/index.ts',
    typedocFile: 'spaces/transport.md',
    page: 'spaces-transport',
    title: 'Spaces transport (TypeScript)',
    importPath: '@trycua/cua/spaces/transport',
    description: 'MCP-over-HTTP and Tauri transports for Spaces in webviews and browsers.',
  },
  {
    entry: 'spaces/host.ts',
    typedocFile: 'spaces/host.md',
    page: 'spaces-host',
    title: 'Spaces host (TypeScript)',
    importPath: '@trycua/cua/spaces/host',
    description: 'The @trycua/cua/spaces/host helpers for hosting a Space from Node.',
  },
];

/**
 * Modules rendered as a section of another module's page (page -> the page it
 * joins), so the TypeScript reference stays two pages within the page budget.
 */
export const TS_MERGED: Record<string, string> = { 'spaces-transport': 'index', 'spaces-host': 'index' };

/** Options passed to typedoc (and typedoc-plugin-markdown). */
export function typedocOptions(outDir: string, plugin: string): Record<string, unknown> {
  return {
    tsconfig: path.join(PACKAGE_DIR, 'tsconfig.json'),
    entryPoints: MODULES.map((m) => path.join(SOURCE_DIR, m.entry)),
    plugin: [plugin],
    out: outDir,
    readme: 'none',
    outputFileStrategy: 'modules',
    entryFileName: 'index',
    hidePageHeader: true,
    hideBreadcrumbs: true,
    parametersFormat: 'table',
    interfacePropertiesFormat: 'table',
    classPropertiesFormat: 'table',
    typeDeclarationFormat: 'table',
    enumMembersFormat: 'table',
    propertyMembersFormat: 'table',
    typeAliasPropertiesFormat: 'table',
    sanitizeComments: true,
    useCodeBlocks: true,
    excludePrivate: true,
    excludeProtected: true,
    excludeInternal: true,
    excludeExternals: true,
    sort: ['kind', 'alphabetical'],
    logLevel: 'Error',
  };
}

async function runTypedoc(outDir: string): Promise<void> {
  const docsRequire = createRequire(path.join(REPO_ROOT, 'docs', 'package.json'));
  const td = await import(docsRequire.resolve('typedoc'));
  const plugin = docsRequire.resolve('typedoc-plugin-markdown');
  if (!fs.existsSync(path.join(PACKAGE_DIR, 'node_modules'))) {
    throw new Error(
      'libs/cua/typescript/node_modules is missing: run `npm ci --ignore-scripts` there first.'
    );
  }
  const app = await td.Application.bootstrapWithPlugins(typedocOptions(outDir, plugin));
  const isHandWritten = (file: string) =>
    file.startsWith(SOURCE_DIR + path.sep) &&
    !file.startsWith(path.join(SOURCE_DIR, 'native') + path.sep);
  app.converter.on(td.Converter.EVENT_RESOLVE_BEGIN, (context: any) => {
    const project = context.project;
    // Drop the UniFFI glue re-exported from src/native, and members inherited
    // from outside the package (Error.stack and friends).
    for (const reflection of Object.values(project.reflections) as any[]) {
      if (!project.reflections[reflection.id]) continue; // already removed with a parent
      if (!reflection.kindOf(td.ReflectionKind.SomeExport | td.ReflectionKind.SomeMember)) continue;
      const file: string = reflection.sources?.[0]?.fullFileName ?? '';
      if (!file || !isHandWritten(path.resolve(file))) project.removeReflection(reflection);
    }
  });
  app.converter.on(td.Converter.EVENT_RESOLVE_END, (context: any) => {
    // Sources were only needed for the filter; the pages do not show paths.
    for (const reflection of Object.values(context.project.reflections) as any[]) {
      delete reflection.sources;
    }
  });
  const project = await app.convert();
  if (!project) throw new Error('typedoc could not convert @trycua/cua');
  await app.generateOutputs(project);
}

/** typedoc output file (relative, posix) -> site route. */
function routeFor(file: string): string | undefined {
  const m = MODULES.find((mod) => mod.typedocFile === file);
  if (!m) return undefined;
  const page = TS_MERGED[m.page] ?? m.page;
  return page === 'index' ? ROUTE : `${ROUTE}/${page}`;
}

/**
 * Drop class members that are only inherited (typedoc repeats the base
 * class's methods under every subclass), which keeps pages in the page budget.
 * Members that override or extend are kept.
 */
export function dropInheritedMembers(markdown: string): string {
  const parts = markdown.split(/^(?=#{1,6} )/m);
  const out: string[] = [];
  for (let i = 0; i < parts.length; i++) {
    const part = parts[i];
    if (/^##### /.test(part)) {
      let body = part;
      while (i + 1 < parts.length && /^#{6} /.test(parts[i + 1])) body += parts[++i];
      if (/^###### Inherited from/m.test(body) && !/^###### Overrides/m.test(body)) continue;
      out.push(body);
    } else out.push(part);
  }
  return out.join('');
}

/**
 * Post-pass over one typedoc Markdown file: drop the H1 (the page title comes
 * from frontmatter), rewrite `.md` links to site routes, and normalise
 * whitespace.
 */
export function postProcess(markdown: string, file: string): string {
  const dir = path.posix.dirname(file);
  let out = markdown.replace(/^# .*\n+/, '');
  out = out.replace(/\]\(([^)\s]+?\.md)(#[^)\s]*)?\)/g, (whole, target: string, hash = '') => {
    const resolved = path.posix.normalize(path.posix.join(dir, target));
    const route = routeFor(resolved);
    return route ? `](${route}${hash})` : whole;
  });
  // typedoc escapes `_` inside words; harmless, but keep identifiers readable.
  out = out.replace(/([A-Za-z0-9])\\_(?=[A-Za-z0-9])/g, '$1_');
  out = dropTableColumn(out, 'Defined in');
  out = dropInheritedMembers(out);
  return (
    out
      .replace(/[ \t]+$/gm, '')
      .replace(/\n{3,}/g, '\n\n')
      .trim() + '\n'
  );
}

/** The anchors a page defines: heading slugs (with rehype-slug's `-N` for repeats) and `<a id>`s. */
export function pageAnchors(markdown: string): Set<string> {
  const anchors = new Set<string>();
  const counts = new Map<string, number>();
  let fence = false;
  for (const line of markdown.split('\n')) {
    if (/^\s*```/.test(line)) fence = !fence;
    if (fence) continue;
    const heading = line.match(/^#{1,6}\s+(.*)$/);
    if (heading) {
      const text = heading[1]
        .replace(/`/g, '')
        .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
        .replace(/\\/g, '');
      const base = slug(text);
      const n = counts.get(base) ?? 0;
      counts.set(base, n + 1);
      anchors.add(n === 0 ? base : `${base}-${n}`);
    }
    for (const m of line.matchAll(/<a id="([^"]+)"><\/a>/g)) anchors.add(m[1]);
  }
  return anchors;
}

/**
 * typedoc-plugin-markdown numbers anchors of merged declarations (`#x-1`)
 * differently from rehype-slug; point every fragment link at an anchor the
 * target page really has, or drop the link and keep its text.
 */
export function fixFragments(pages: Map<string, string>): Map<string, string> {
  const anchors = new Map([...pages].map(([route, body]) => [route, pageAnchors(body)]));
  const out = new Map<string, string>();
  const route = ROUTE.replace(/[/]/g, '\\/');
  const link = new RegExp(`\\[([^\\]]*)\\]\\(((?:${route}[^)#\\s]*)?)#([^)\\s]+)\\)`, 'g');
  for (const [route, body] of pages) {
    out.set(
      route,
      body.replace(link, (whole, text: string, target: string, frag: string) => {
        const page = anchors.get(target || route);
        if (!page || page.has(frag)) return whole;
        const base = frag.replace(/-\d+$/, '');
        return page.has(base) ? `[${text}](${target}#${base})` : text;
      })
    );
  }
  return out;
}

/** Splits a Markdown table row into cells, honouring `\|` escapes. */
function splitRow(row: string): string[] {
  const cells: string[] = [];
  let cell = '';
  const inner = row.trim().replace(/^\|/, '').replace(/\|$/, '');
  for (let i = 0; i < inner.length; i += 1) {
    if (inner[i] === '\\' && inner[i + 1] === '|') {
      cell += '\\|';
      i += 1;
    } else if (inner[i] === '|') {
      cells.push(cell);
      cell = '';
    } else {
      cell += inner[i];
    }
  }
  cells.push(cell);
  return cells.map((c) => c.trim());
}

/**
 * Removes the column titled `header` from every Markdown table (sources are
 * stripped, so typedoc-plugin-markdown leaves it empty).
 */
export function dropTableColumn(markdown: string, header: string): string {
  const lines = markdown.split('\n');
  let drop = -1;
  for (let i = 0; i < lines.length; i += 1) {
    const line = lines[i];
    if (!line.trimStart().startsWith('|')) {
      drop = -1;
      continue;
    }
    const cells = splitRow(line);
    if (drop === -1 && lines[i + 1]?.trimStart().startsWith('| --')) {
      drop = cells.indexOf(header);
      if (drop === -1) {
        drop = -2; // a table without the column: leave it alone
        continue;
      }
    }
    if (drop < 0) continue;
    cells.splice(drop, 1);
    lines[i] = `| ${cells.join(' | ')} |`;
  }
  return lines.join('\n');
}

export function buildPages(typedocDir: string, version: string): Map<string, string> {
  const homes = MODULES.filter((m) => !TS_MERGED[m.page]);
  const intro = (m: (typeof MODULES)[number]) =>
    `Import from \`${m.importPath}\`.`;
  const bodies = new Map<string, string>();
  for (const home of homes) {
    const parts = [home, ...MODULES.filter((m) => TS_MERGED[m.page] === home.page)];
    const sections = parts.map((m, i) => {
      const source = path.join(typedocDir, ...m.typedocFile.split('/'));
      if (!fs.existsSync(source)) throw new Error(`typedoc produced no ${m.typedocFile}`);
      const body = postProcess(fs.readFileSync(source, 'utf-8'), m.typedocFile);
      const header = readHeader(`cua-sdk/typescript/${m.page}.md`, { version });
      // The page's own module first; each merged module under a heading of its import path.
      const lead = i === 0 ? [] : [`## ${m.importPath}`, '', `${intro(m)} ${m.description}`];
      return [...lead, header, body].filter(Boolean).join('\n\n');
    });
    bodies.set(routeFor(home.typedocFile)!, sections.join('\n\n'));
  }
  const fixed = fixFragments(bodies);
  const files = new Map<string, string>();
  for (const m of homes) {
    const lead =
      `${intro(m)} This page covers the hand-written TypeScript layer; ` +
      'the generated native binding (sandboxes, guest, spaces objects) is documented per module in the ' +
      '[Cua SDK reference](/cua-sdk/reference).';
    const merged = MODULES.filter((x) => TS_MERGED[x.page] === m.page);
    files.set(
      path.join(OUTPUT_DIR, `${m.page}.mdx`),
      renderPage({
        title: m.title,
        description: m.description,
        generator: 'pnpm --dir docs docs:generate:cua-sdk-ts',
        source: `typedoc + typedoc-plugin-markdown over ${[m, ...merged].map((x) => `libs/cua/typescript/src/${x.entry}`).join(', ')}`,
        version: `@trycua/cua ${version}`,
        body: [lead, fixed.get(routeFor(m.typedocFile)!)].filter(Boolean).join('\n\n'),
      })
    );
  }
  files.set(
    path.join(OUTPUT_DIR, 'meta.json'),
    metaJson(
      'TypeScript additions',
      homes.map((m) => m.page).filter((p) => p !== 'index')
    )
  );
  return files;
}

async function main(): Promise<void> {
  const checkOnly = isCheckMode();
  const version = JSON.parse(fs.readFileSync(path.join(PACKAGE_DIR, 'package.json'), 'utf-8'))
    .version as string;
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cua-typedoc-'));
  try {
    await runTypedoc(tmp);
    const drift = syncFiles(buildPages(tmp, version), checkOnly, [OUTPUT_DIR], 'pnpm --dir docs docs:generate:cua-sdk-ts');
    finish('TypeScript', drift, checkOnly, 'pnpm --dir docs docs:generate:cua-sdk-ts');
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
}

if (require.main === module) {
  main().catch((error) => {
    console.error('Error:', error);
    process.exit(1);
  });
}