Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
#!/usr/bin/env npx tsx
/**
* Lume reference generator.
*
* Builds Lume (`swift build -c release` in libs/lume), runs
* `lume dump-docs --type all --pretty` (the CLI, HTTP API and MCP tool
* definitions) and writes, through the shared renderers in lib/:
*
* - docs/content/docs/lume/reference/index.mdx (the Reference index)
* - docs/content/docs/lume/reference/cli.mdx (every command on one page)
* - docs/content/docs/lume/reference/http-api.mdx (the HTTP API, then the MCP tools)
* - scripts/docs-generators/cli-specs/lume.json (the CLI-shape lane's oracle)
*
* Usage:
* pnpm --dir docs docs:generate:lume
* pnpm --dir docs docs:check:lume # drift check (CI)
*
* LUME_BINARY=<path> skips the build and uses that binary.
*/
import { execFileSync } from 'child_process';
import * as path from 'path';
import {
type CLIDocumentation,
type CliGroup,
type CliReference,
cliIndexRows,
renderCliReference,
renderReferenceIndex,
sentence,
} from './lib/cli-mdx';
import { readHeader } from './lib/headers';
import {
type JsonSchema,
type McpCategory,
type McpReference,
mcpBody,
} from './lib/mcp-mdx';
import { DOCS_CONTENT, REPO_ROOT, codeCell, codeFence, escapeMdxText, escapeTableCell, finish, isCheckMode, metaJson, stableJson, syncFiles } from './lib/mdx';
import { normalizeEmDashes } from './prose-style';
export type { CLIDocumentation };
const LUME_DIR = path.join(REPO_ROOT, 'libs', 'lume');
const OUT_DIR = path.join(DOCS_CONTENT, 'lume', 'reference');
export const LUME_CLI_SPEC = path.join(__dirname, 'cli-specs', 'lume.json');
const REGENERATE = 'pnpm --dir docs docs:generate:lume';
export interface LumeMcpTool {
name: string;
description: string;
input_schema: JsonSchema;
annotations?: { read_only?: boolean; destructive?: boolean; idempotent?: boolean };
}
export interface LumeDumpDocs {
cli: CLIDocumentation;
api: HTTPAPIDocumentation;
mcp?: { version?: string; tools: LumeMcpTool[] };
}
// ---------------------------------------------------------------- CLI
export const CLI_GROUPS: CliGroup[] = [
{
slug: 'vms',
title: 'VMs',
summary: 'Create, run, inspect, change, clone and delete virtual machines',
commands: ['create', 'run', 'attach', 'stop', 'shutdown', 'restart', 'ls', 'get', 'set', 'clone', 'delete'],
},
{
slug: 'images',
title: 'Images',
summary: 'Pull, push and convert VM images, find restore images, and prune the cache',
commands: ['images', 'pull', 'push', 'convert', 'ipsw', 'prune'],
},
{
slug: 'guest',
title: 'Guest access',
summary: 'Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest',
commands: ['setup', 'ssh', 'cp', 'sip'],
},
{
slug: 'server',
title: 'Server',
summary: 'Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions',
commands: ['serve', 'logs', 'dump-docs'],
},
{
slug: 'config',
title: 'Configuration',
summary: 'Storage locations, the image cache and telemetry settings',
commands: ['config'],
},
{
slug: 'updates',
title: 'Updates',
summary: 'Check for, apply and choose the channel of Lume updates',
commands: ['check-update', 'update', 'channel'],
},
];
export function cliReference(cli: CLIDocumentation): CliReference {
return {
product: 'lume',
cli,
groups: CLI_GROUPS,
generator: REGENERATE,
source: 'lume dump-docs --type cli',
intro: readHeader('lume', 'cli'),
singlePage: true,
};
}
// ---------------------------------------------------------------- MCP
const MCP_CATEGORIES: McpCategory[] = [
{ slug: 'vms', title: 'VM tools', summary: 'Create, list, run, stop, clone, resize and delete VMs' },
{ slug: 'guest', title: 'Guest tools', summary: 'Run commands inside a running VM' },
{ slug: 'maintenance', title: 'Maintenance tools', summary: 'Check for Lume updates' },
];
function mcpCategory(name: string): string {
if (name === 'lume_exec') return 'guest';
if (name.startsWith('lume_')) return 'vms';
return 'maintenance';
}
export function mcpReference(mcp: NonNullable<LumeDumpDocs['mcp']>, version: string): McpReference {
return {
product: 'lume',
server: 'lume serve --mcp',
generator: REGENERATE,
source: 'lume dump-docs --type mcp',
version,
description: "Every tool Lume's MCP server exposes, with its parameters.",
categories: MCP_CATEGORIES,
tools: mcp.tools.map((t) => ({
name: t.name,
description: t.description,
category: mcpCategory(t.name),
input_schema: t.input_schema,
annotations: t.annotations,
})),
header: readHeader('lume', 'mcp-tools'),
singlePage: true,
};
}
// ---------------------------------------------------------------- main
export function renderAll(docs: LumeDumpDocs): Map<string, string> {
const cli = cliReference(docs.cli);
const rel = new Map<string, string>(renderCliReference(cli));
// The HTTP API and the MCP tools share one page: both are what `lume serve` exposes.
const mcp = docs.mcp ? mcpReference(docs.mcp, docs.cli.version) : undefined;
rel.set('http-api.mdx', normalizeEmDashes(generateHTTPAPIMDX(docs.api, mcp ? mcpBody(mcp, 3) : undefined)));
const sections = [
{ title: 'Commands', column: 'Command group', rows: cliIndexRows(cli) },
{
title: 'HTTP API and MCP tools',
column: 'API',
rows: [
{ name: 'HTTP API', href: '/lume/reference/http-api', description: 'Every endpoint `lume serve` exposes, with parameters and examples.' },
...(mcp
? [{ name: 'MCP tools', href: '/lume/reference/http-api#mcp-tools', description: mcp.description }]
: []),
],
},
];
const pages = ['index', 'cli', 'http-api'];
rel.set(
'index.mdx',
renderReferenceIndex({
productName: 'Lume',
description: 'Every lume command, HTTP endpoint and MCP tool, generated from the Lume binary.',
generator: REGENERATE,
source: 'lume dump-docs --type all',
version: docs.cli.version,
sections,
})
);
rel.set('meta.json', metaJson('Reference', pages));
const files = new Map<string, string>();
for (const [p, content] of rel) files.set(path.join(OUT_DIR, p), content);
files.set(LUME_CLI_SPEC, stableJson(docs.cli));
return files;
}
function lumeBinary(): string {
if (process.env.LUME_BINARY) return path.resolve(process.env.LUME_BINARY);
execFileSync('swift', ['build', '-c', 'release'], { cwd: LUME_DIR, stdio: 'inherit' });
return path.join(LUME_DIR, '.build', 'release', 'lume');
}
export function dumpDocs(binary: string): LumeDumpDocs {
const json = execFileSync(binary, ['dump-docs', '--type', 'all', '--pretty'], {
cwd: LUME_DIR,
encoding: 'utf-8',
maxBuffer: 64 * 1024 * 1024,
env: { ...process.env, LUME_TELEMETRY_ENABLED: 'false' },
});
return JSON.parse(json);
}
function main(): void {
const checkOnly = isCheckMode();
const docs = dumpDocs(lumeBinary());
const owned = [OUT_DIR, path.join(OUT_DIR, 'cli')];
finish('Lume', syncFiles(renderAll(docs), checkOnly, owned), checkOnly, REGENERATE);
}
if (require.main === module) main();
// ============================================================================
// HTTP API types
// ============================================================================
export interface HTTPAPIDocumentation {
base_path: string;
version: string;
description: string;
endpoints: APIEndpointDoc[];
}
export interface APIEndpointDoc {
method: string;
path: string;
description: string;
category: string;
path_parameters: APIParameterDoc[];
query_parameters: APIParameterDoc[];
request_body?: APIRequestBodyDoc;
response_body: APIResponseDoc;
status_codes: APIStatusCodeDoc[];
}
export interface APIParameterDoc {
name: string;
type: string;
required: boolean;
description: string;
}
export interface APIRequestBodyDoc {
content_type: string;
description: string;
fields: APIFieldDoc[];
}
export interface APIResponseDoc {
content_type: string;
description: string;
fields?: APIFieldDoc[];
}
export interface APIFieldDoc {
name: string;
type: string;
required: boolean;
description: string;
default_value?: string;
}
export interface APIStatusCodeDoc {
code: number;
description: string;
}
// ============================================================================
// HTTP API Reference Generator
// ============================================================================
export function generateHTTPAPIMDX(docs: HTTPAPIDocumentation, mcpTools?: string[]): string {
const lines: string[] = [];
const documentedVersion = docs.version;
// Header - frontmatter MUST be at the very beginning of the file
lines.push('---');
lines.push(mcpTools ? 'title: "HTTP API and MCP tools"' : 'title: "HTTP API"');
lines.push(
mcpTools
? 'description: "Every endpoint of the Lume HTTP API server and every tool of its MCP server (lume serve)."'
: 'description: "Every endpoint of the Lume HTTP API server (lume serve)."'
);
lines.push('---');
lines.push('');
lines.push(`{/*
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: ${REGENERATE}
Source: lume dump-docs --type api
Version: ${documentedVersion}
*/}`);
lines.push('');
lines.push("import { Tabs, Tab } from 'fumadocs-ui/components/tabs';");
lines.push('');
// Introduction
lines.push(docs.description);
lines.push('');
lines.push(
`Documented against Lume **${documentedVersion}**. Run \`lume --version\` for your installed version.`
);
lines.push('');
lines.push('## Default URL');
lines.push('');
lines.push('```');
lines.push('http://localhost:7777');
lines.push('```');
lines.push('');
lines.push(
'Start the server with `lume serve` or specify a custom port with `lume serve --port <port>`.'
);
lines.push('');
// Group endpoints by category
const categories = [...new Set(docs.endpoints.map((e) => e.category))];
for (const category of categories) {
lines.push(`## ${category}`);
lines.push('');
const categoryEndpoints = docs.endpoints.filter((e) => e.category === category);
for (const endpoint of categoryEndpoints) {
lines.push(...generateEndpointDoc(endpoint));
}
}
if (mcpTools) lines.push('## MCP tools', '', ...mcpTools);
return lines.join('\n');
}
export function generateEndpointDoc(endpoint: APIEndpointDoc): string[] {
const lines: string[] = [];
lines.push(`### ${escapeMdxText(endpoint.description)}`);
lines.push('');
lines.push(codeFence('http', `${endpoint.method} ${endpoint.path}`, 'output'));
lines.push('');
// Parameters table (path + query)
const allParams = [
...endpoint.path_parameters.map((p) => ({ ...p, location: 'path' })),
...endpoint.query_parameters.map((p) => ({ ...p, location: 'query' })),
];
if (allParams.length > 0) {
lines.push('**Parameters**');
lines.push('');
lines.push('| Parameter | In | Type | Default | Description |');
lines.push('| --- | --- | --- | --- | --- |');
for (const param of allParams) {
const def = param.required ? 'required' : '';
lines.push(
`| ${codeCell(param.name)} | ${param.location} | ${codeCell(param.type)} | ${def} | ${escapeTableCell(sentence(param.description))} |`
);
}
lines.push('');
}
// Request body
if (endpoint.request_body) {
lines.push('**Request body**');
lines.push('');
lines.push('| Field | Type | Default | Description |');
lines.push('| --- | --- | --- | --- |');
for (const field of endpoint.request_body.fields) {
const def = field.required ? 'required' : field.default_value ? codeCell(field.default_value) : '';
lines.push(
`| ${codeCell(field.name)} | ${codeCell(field.type)} | ${def} | ${escapeTableCell(sentence(field.description))} |`
);
}
lines.push('');
}
// Example request
lines.push('**Example request**');
lines.push('');
lines.push("<Tabs groupId=\"language\" persist items={['Curl', 'Python', 'TypeScript']}>");
// Generate curl example
lines.push(' <Tab value="Curl">');
lines.push('```bash');
lines.push(generateCurlExample(endpoint));
lines.push('```');
lines.push(' </Tab>');
// Generate Python example
lines.push(' <Tab value="Python">');
lines.push('```python');
lines.push(generatePythonExample(endpoint));
lines.push('```');
lines.push(' </Tab>');
// Generate TypeScript example
lines.push(' <Tab value="TypeScript">');
lines.push('```typescript');
lines.push(generateTypeScriptExample(endpoint));
lines.push('```');
lines.push(' </Tab>');
lines.push('</Tabs>');
lines.push('');
// Status codes
lines.push('**Response**');
lines.push('');
for (const status of endpoint.status_codes) {
lines.push(`- \`${status.code}\`: ${escapeMdxText(sentence(status.description))}`);
}
lines.push('');
return lines;
}
function generateCurlExample(endpoint: APIEndpointDoc): string {
const path = endpoint.path.replace(/:(\w+)/g, (_, name) => getExamplePathValue(name));
const url = `http://localhost:7777${path}`;
if (endpoint.method === 'GET' || endpoint.method === 'DELETE') {
if (endpoint.method === 'DELETE') {
return `curl -X DELETE "${url}"`;
}
return `curl "${url}"`;
}
// POST/PATCH with body
if (endpoint.request_body && endpoint.request_body.fields.length > 0) {
const bodyObj: Record<string, unknown> = {};
for (const field of endpoint.request_body.fields) {
if (field.required) {
bodyObj[field.name] = getExampleValue(field);
}
}
const bodyJson = JSON.stringify(bodyObj, null, 2);
return `curl -X ${endpoint.method} "http://localhost:7777${path}" \\
-H "Content-Type: application/json" \\
-d '${bodyJson}'`;
}
return `curl -X ${endpoint.method} "${url}"`;
}
function generatePythonExample(endpoint: APIEndpointDoc): string {
const path = endpoint.path.replace(/:(\w+)/g, (_, name) => getExamplePathValue(name));
const method = endpoint.method.toLowerCase();
const lines: string[] = [];
lines.push('import requests');
lines.push('');
if (
endpoint.request_body &&
endpoint.request_body.fields.length > 0 &&
(endpoint.method === 'POST' || endpoint.method === 'PATCH')
) {
lines.push('data = {');
for (const field of endpoint.request_body.fields) {
if (field.required) {
const value = getExampleValuePython(field);
lines.push(` "${field.name}": ${value},`);
}
}
lines.push('}');
lines.push('');
lines.push(`response = requests.${method}("http://localhost:7777${path}", json=data)`);
} else {
lines.push(`response = requests.${method}("http://localhost:7777${path}")`);
}
lines.push('print(response.json())');
return lines.join('\n');
}
function generateTypeScriptExample(endpoint: APIEndpointDoc): string {
const path = endpoint.path.replace(/:(\w+)/g, (_, name) => getExamplePathValue(name));
const lines: string[] = [];
if (
endpoint.request_body &&
endpoint.request_body.fields.length > 0 &&
(endpoint.method === 'POST' || endpoint.method === 'PATCH')
) {
lines.push(`const response = await fetch(\`http://localhost:7777${path}\`, {`);
lines.push(` method: "${endpoint.method}",`);
lines.push(' headers: { "Content-Type": "application/json" },');
lines.push(' body: JSON.stringify({');
for (const field of endpoint.request_body.fields) {
if (field.required) {
const value = getExampleValueTS(field);
lines.push(` ${field.name}: ${value},`);
}
}
lines.push(' }),');
lines.push('});');
} else if (endpoint.method === 'DELETE') {
lines.push(`const response = await fetch(\`http://localhost:7777${path}\`, {`);
lines.push(` method: "DELETE",`);
lines.push('});');
} else {
lines.push(`const response = await fetch(\`http://localhost:7777${path}\`);`);
}
lines.push('const data = await response.json();');
return lines.join('\n');
}
function getExampleValue(field: APIFieldDoc): unknown {
switch (field.type) {
case 'string':
if (field.name === 'name') return 'my-vm';
if (field.name === 'os') return 'macOS';
if (field.name === 'memory') return '8GB';
if (field.name === 'diskSize') return '50GB';
if (field.name === 'display') return '1024x768';
if (field.name === 'image') return 'macos-tahoe-vanilla:latest';
if (field.name === 'path') return '/path/to/storage';
return 'example';
case 'integer':
if (field.name === 'cpu') return 4;
return 1;
case 'boolean':
return false;
case 'array':
if (field.name === 'tags') return ['latest'];
return [];
default:
return 'value';
}
}
function getExampleValuePython(field: APIFieldDoc): string {
const val = getExampleValue(field);
if (typeof val === 'string') return `"${val}"`;
if (typeof val === 'boolean') return val ? 'True' : 'False';
if (Array.isArray(val)) return JSON.stringify(val);
return String(val);
}
function getExampleValueTS(field: APIFieldDoc): string {
const val = getExampleValue(field);
if (typeof val === 'string') return `"${val}"`;
if (Array.isArray(val)) return JSON.stringify(val);
return String(val);
}
function getExamplePathValue(name: string): string {
if (name === 'name') return 'my-vm';
if (name === 'id') return 'example-id';
return `example-${name}`;
}