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
// Every product has the same sections, in the same order, with the same names,
// and its Reference holds only generated pages that `docs:check` covers.
//
// pnpm exec tsx --test scripts/product-structure.test.ts
import assert from 'node:assert/strict';
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import path from 'node:path';
import test from 'node:test';
const docs = path.resolve(__dirname, '..');
const repo = path.resolve(docs, '..');
const content = path.join(docs, 'content/docs');
// In sidebar order. The product switcher shows Cua Spaces and Cua Driver; the
// renderer lists the rest (Lume, SDK, CLI, Bench) under "More docs".
const PRODUCTS: Array<[string, string]> = [
['spaces', 'Cua Spaces'],
['cua-driver', 'Cua Driver'],
['lume', 'Lume'],
['cua-sdk', 'Cua SDK'],
['cua-cli', 'Cua CLI'],
['cua-bench', 'Cua Bench'],
];
// The root meta.json: the products in order, no group headings.
const ROOT_ORDER = [
'index',
'spaces',
'cua-driver',
'lume',
'cua-sdk',
'cua-cli',
'cua-bench',
];
// Sections in their only allowed order; `examples` is optional. "How X works"
// pages from `concepts/` are listed by path right after the Overview and
// Quickstart (no Concepts group in the sidebar); Cua Driver also opens with
// its "What is computer use" explainer. A product whose guides fall into
// groups lists them inline instead of `guides` (`---Get started---`,
// `guides/install`, ...), so each group is a sidebar section of its own.
const SECTIONS = ['index', 'quickstart', 'guides', 'examples', 'reference'];
const OPTIONAL = new Set(['examples']);
const INTRO_PAGES = new Set(['what-is-computer-use']);
const SECTION_TITLES: Record<string, string> = {
guides: 'Guides',
examples: 'Examples',
concepts: 'Concepts',
reference: 'Reference',
};
// The docs home is the designed landing; its frontmatter feeds it.
// Each example: a title, a page, alt text and its media (an image, or a
// video with its poster); the description is optional.
const LANDING_EXAMPLE_KEYS = ['title', 'href', 'alt'];
// Pages allowed at the root besides the product folders.
const ROOT_PAGES = new Set(['index.mdx', 'docs-for-agents.mdx']);
const GENERATED_MARKER = /AUTO-GENERATED|\{\/\*\s*GENERATED:[\w-]+:start\s*\*\/\}/;
type Meta = { title?: string; root?: boolean; pages?: string[] };
function meta(dir: string): Meta {
return JSON.parse(readFileSync(path.join(content, dir, 'meta.json'), 'utf8'));
}
function walk(dir: string): string[] {
if (!existsSync(dir)) return [];
return readdirSync(dir).flatMap((name) => {
const full = path.join(dir, name);
return statSync(full).isDirectory() ? walk(full) : [full];
});
}
function slugs(): Set<string> {
return new Set(
walk(content)
.filter((f) => f.endsWith('.mdx'))
.map((f) =>
path
.relative(content, f)
.replace(/\.mdx$/, '')
.replace(/(^|\/)index$/, '')
)
);
}
test('the root lists every product in order, with no group headings', () => {
assert.deepEqual(meta('').pages, ROOT_ORDER);
assert.deepEqual(
ROOT_ORDER.filter((page) => page !== 'index' && !page.startsWith('---')),
PRODUCTS.map(([dir]) => dir)
);
const stray = readdirSync(content).filter(
(name) =>
name.endsWith('.mdx') && !ROOT_PAGES.has(name)
);
assert.deepEqual(stray, [], 'pages at the root belong in a product');
const dirs = readdirSync(content).filter((name) =>
statSync(path.join(content, name)).isDirectory()
);
// `agents` holds the pages an AI agent reads from a one-line prompt
// (cua.ai/docs/agents/*). It is not a product: no sidebar entry, no sections.
assert.deepEqual(
dirs.sort(),
[...PRODUCTS.map(([dir]) => dir), 'agents'].sort()
);
});
test('the docs home features its examples with real pages and media', () => {
const home = readFileSync(path.join(content, 'index.mdx'), 'utf8');
const frontmatter = home.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '';
assert.match(frontmatter, /^landing:/m, 'index.mdx has landing frontmatter');
const featured = frontmatter.match(/^ products: \[(.*)\]$/m)?.[1].split(/,\s*/) ?? [];
assert.ok(featured.length <= 4, 'the landing features at most four products (one row)');
for (const dir of featured) {
assert.ok(PRODUCTS.some(([p]) => p === dir), `featured product ${dir} is not a product`);
}
const live = slugs();
const examples = frontmatter.split(/\n - title: /).slice(1);
assert.ok(examples.length > 0, 'the landing features at least one example');
for (const example of examples) {
const fields = `title: ${example}`;
for (const key of LANDING_EXAMPLE_KEYS) {
assert.match(fields, new RegExp(`^\\s*${key}: `, 'm'), `example lacks ${key}`);
}
for (const [, link] of fields.matchAll(/href: (\S+)/g)) {
if (/^https:\/\//.test(link)) continue;
assert.ok(live.has(link.replace(/^\//, '')), `example link ${link} is not a page`);
}
const media = ['image', 'video', 'poster'].map(
(key) => fields.match(new RegExp(`^\\s*${key}: (\\S+)`, 'm'))?.[1]
);
const [image, video, poster] = media;
assert.ok(image || (video && poster), 'example has an image, or a video with its poster');
for (const src of media) {
if (!src || /^https:\/\//.test(src)) continue;
assert.ok(existsSync(path.join(docs, 'public', src)), `example media ${src} is missing`);
}
}
});
for (const [dir, title] of PRODUCTS) {
test(`${title} has the standard sections`, () => {
const m = meta(dir);
assert.equal(m.title, title);
assert.equal(m.root, true, `${dir}/meta.json must be a root folder (its own sidebar tab)`);
const authored = m.pages ?? [];
const inline = authored.filter((p) => p.startsWith('guides/'));
// Inline guides stand in for the `guides` folder, at its place.
const all = authored.flatMap((p, i) =>
p.startsWith('guides/') || p.startsWith('---')
? authored.slice(0, i).some((q) => q.startsWith('guides/') || q.startsWith('---'))
? []
: ['guides']
: [p]
);
if (inline.length) {
assert.ok(!existsSync(path.join(content, dir, 'guides/meta.json')), `${dir}: list guides inline or in guides/meta.json, not both`);
const files = readdirSync(path.join(content, dir, 'guides')).filter((f) => f.endsWith('.mdx')).map((f) => `guides/${f.replace(/\.mdx$/, '')}`);
assert.deepEqual([...inline].sort(), files.sort(), `${dir}: every guide is listed once`);
assert.ok(authored.indexOf(inline[0]) > 0 && authored[authored.indexOf(inline[0]) - 1].startsWith('---'), `${dir}: inline guides start under a ---Section--- heading`);
}
const concepts = all.filter((p) => p.startsWith('concepts/'));
const pages = all.filter((p) => !p.startsWith('concepts/') && !INTRO_PAGES.has(p));
const expected = SECTIONS.filter(
(section) => !OPTIONAL.has(section) || pages.includes(section)
);
assert.deepEqual(pages, expected, `${dir}/meta.json pages must be ${expected.join(', ')}`);
// Concept pages sit between the Quickstart and the Guides, and no page is left out.
assert.deepEqual(all.slice(all.indexOf('quickstart') + 1, all.indexOf('guides')).filter((p) => !p.startsWith('concepts/')), []);
assert.ok(all.indexOf('quickstart') < all.indexOf('guides'));
const listed = new Set([...concepts, ...(existsSync(path.join(content, dir, 'reference/meta.json')) ? (meta(path.join(dir, 'reference')).pages ?? []).filter((p) => p.startsWith('../concepts/')).map((p) => p.slice(3)) : [])]);
const conceptDir = path.join(content, dir, 'concepts');
if (existsSync(conceptDir)) {
for (const file of readdirSync(conceptDir).filter((f) => f.endsWith('.mdx'))) {
assert.ok(listed.has(`concepts/${file.replace(/\.mdx$/, '')}`), `${dir}/concepts/${file} is not in the sidebar`);
}
}
assert.ok(existsSync(path.join(content, dir, 'index.mdx')), `${dir}/index.mdx (Overview)`);
assert.ok(existsSync(path.join(content, dir, 'quickstart.mdx')), `${dir}/quickstart.mdx`);
for (const page of all.filter((p) => INTRO_PAGES.has(p))) {
assert.ok(existsSync(path.join(content, dir, `${page}.mdx`)), `${dir}/${page}.mdx`);
}
for (const section of pages.filter((p) => SECTION_TITLES[p] && !(p === 'guides' && inline.length))) {
assert.equal(meta(path.join(dir, section)).title, SECTION_TITLES[section]);
}
const extra = readdirSync(path.join(content, dir)).filter(
(name) =>
name !== 'meta.json' &&
name !== 'concepts' &&
!all.includes(name.replace(/\.mdx$/, ''))
);
assert.deepEqual(extra, [], `${dir} has files outside its sections`);
});
test(`${title} Reference holds only generated pages covered by docs:check`, () => {
const config = JSON.parse(
readFileSync(path.join(repo, 'scripts/docs-generators/config.json'), 'utf8')
) as { generators: Record<string, { enabled: boolean; docsOutputPath: string; outputs: Array<{ outputFile: string }> }> };
const owned = Object.values(config.generators)
.filter((g) => g.enabled)
.flatMap((g) => [
path.join(repo, g.docsOutputPath),
...g.outputs.map((o) => path.dirname(path.join(repo, g.docsOutputPath, o.outputFile))),
]);
const pages = walk(path.join(content, dir, 'reference')).filter((f) => f.endsWith('.mdx'));
for (const file of pages) {
const rel = path.relative(content, file);
assert.ok(GENERATED_MARKER.test(readFileSync(file, 'utf8')), `${rel} lacks the generator marker`);
assert.ok(
owned.some((out) => path.dirname(file) === out || path.dirname(file).startsWith(out + path.sep)),
`${rel} is not under an enabled generator's output in scripts/docs-generators/config.json`
);
}
});
}
test('redirects point at pages that exist', () => {
const { redirects } = JSON.parse(
readFileSync(path.join(content, 'redirects.json'), 'utf8')
) as { redirects: Record<string, string> };
const live = slugs();
for (const [from, to] of Object.entries(redirects)) {
assert.ok(!live.has(from), `redirect source ${from} is a live page`);
let target = to;
for (let hop = 0; hop < 8 && Object.hasOwn(redirects, target); hop++) target = redirects[target];
assert.ok(live.has(target.replace(/#.*$/, '')), `redirect ${from} -> ${to} does not reach a page`);
assert.ok(!Object.hasOwn(redirects, to.replace(/#.*$/, '')), `redirect ${from} -> ${to} is a chain: point it at the final page`);
}
});