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
docs(lume): restore Diátaxis-aligned reference and install docs
Francesco Bonacci48a198b5b628
diff --git a/docs/content/docs/how-to-guides/index.mdx b/docs/content/docs/how-to-guides/index.mdxindex 5f3f4ccd40..b81b8e7f84 100644--- a/docs/content/docs/how-to-guides/index.mdx+++ b/docs/content/docs/how-to-guides/index.mdx@@ -5,4 +5,4 @@ description: 'Follow recipes for specific Cua goals.'How-to guides are recipes for **a specific goal**. They assume you already know the basics, so do a tutorial first if not. Unlike tutorials, they are *not a lesson*; they get you to a result and stop.-They are grouped by surface: Cua Driver for operating apps on a real machine, sandbox for cloud desktops, plus recipes, skills, and agent context.+They are grouped by surface: Cua Driver for operating apps on a real machine, sandbox for cloud desktops, Lume for local Apple Silicon VMs, plus recipes, skills, and agent context.diff --git a/docs/content/docs/how-to-guides/lume/install-lume.mdx b/docs/content/docs/how-to-guides/lume/install-lume.mdxnew file mode 100644index 0000000000..230786d7a4--- /dev/null+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx@@ -0,0 +1,64 @@+---+title: Install Lume+description: Install Lume, Cua's local Apple Silicon VM manager for macOS and Linux guests.+---++import { Callout } from 'fumadocs-ui/components/callout';++Lume is Cua's local VM manager for Apple Silicon Macs. Use it when you want to create, run, or serve macOS and Linux VMs on your own machine. If you want disposable desktops hosted for you, start with [Cua Sandbox](/tutorials/your-first-cloud-sandbox) instead.++## Requirements++- Apple Silicon Mac (M1, M2, M3, etc.)+- macOS 13.0 or later+- At least 8GB of RAM (16GB recommended)+- At least 50GB of free disk space++## Install Lume++Install with a single command:++```bash+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"+```++## Verify the install++```bash+lume --version+```++## Run a prebuilt VM++Pull and start a prebuilt macOS image:++```bash+lume run macos-sequoia-vanilla:latest+```++<Callout title="Security Note">+ Prebuilt images use the default password `lume`. Change this immediately after your first login+ using the `passwd` command.+</Callout>++## Start the API service manually++By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the `--no-background-service` option:++```bash+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"+```++<Callout title="Note">+ With this option, you'll need to manually start the Lume API service by running `lume serve` in+ your terminal whenever you need tools or libraries that rely on the local Lume HTTP API.+</Callout>++## Manual download++You can also download the `lume.pkg.tar.gz` archive from the [latest release](https://github.com/trycua/cua/releases?q=lume&expanded=true), extract it, and install the package manually.++## Next steps++- [Lume CLI reference](/reference/lume/cli-reference): inspect every command and option.+- [Lume HTTP API reference](/reference/lume/http-api): use the local API from tools and scripts.diff --git a/docs/content/docs/how-to-guides/lume/meta.json b/docs/content/docs/how-to-guides/lume/meta.jsonnew file mode 100644index 0000000000..b060387bc5--- /dev/null+++ b/docs/content/docs/how-to-guides/lume/meta.json@@ -0,0 +1 @@+{ "title": "Lume", "pages": ["install-lume"] }diff --git a/docs/content/docs/how-to-guides/meta.json b/docs/content/docs/how-to-guides/meta.jsonindex ec338b048b..9f12de433e 100644--- a/docs/content/docs/how-to-guides/meta.json+++ b/docs/content/docs/how-to-guides/meta.json@@ -1 +1,13 @@-{ "title": "How-to guides", "icon": "Wrench", "pages": ["index", "driver", "recipes", "sandbox", "skills", "agent-context"] }+{+ "title": "How-to guides",+ "icon": "Wrench",+ "pages": [+ "index",+ "driver",+ "recipes",+ "sandbox",+ "lume",+ "skills",+ "agent-context"+ ]+}diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdxindex a212ff2ae1..3aa594a6e1 100644--- a/docs/content/docs/index.mdx+++ b/docs/content/docs/index.mdx@@ -32,4 +32,4 @@ How-to guides: recipes for a goal. Start with [How-to guides](/how-to-guides).Reference: precise technical description. Start with [Reference](/reference).-Cua also has an Agent SDK, a Computer SDK, CLIs, and an MCP server.+Cua also has an Agent SDK, a Computer SDK, CLIs, an MCP server, and Lume for local Apple Silicon VMs.diff --git a/docs/content/docs/reference/index.mdx b/docs/content/docs/reference/index.mdxindex 935d97b7c7..67807c8149 100644--- a/docs/content/docs/reference/index.mdx+++ b/docs/content/docs/reference/index.mdx@@ -1,11 +1,12 @@---title: 'Reference'-description: 'Index of reference material for Cua Driver and the Sandbox SDK.'+description: 'Index of reference material for Cua Driver, Lume, and the Sandbox SDK.'----Reference documents the full technical specification for Cua's subsystems. It covers `cua-driver` and `sandbox-sdk`. The pages define commands, APIs, exposed tools, types, and stated limits.+Reference documents the full technical specification for Cua's subsystems. It covers `cua-driver`, Lume, and `sandbox-sdk`. The pages define commands, APIs, exposed tools, types, and stated limits.| Section | What it documents ||---------|-------------------|| [`cua-driver`](/reference/cua-driver/cli-reference) | CLI commands, 35 MCP tools exposed via the stdio MCP server, and known behavioral limits, including platform-specific constraints on the no-foreground-steal contract. |+| [Lume](/reference/lume/cli-reference) | CLI commands and local HTTP API for creating, running, and managing macOS and Linux VMs on Apple Silicon Macs. || [`sandbox-sdk`](/reference/sandbox-sdk) | Sandbox SDK API, documented by a separate agent. |diff --git a/docs/content/docs/reference/lume/cli-reference.mdx b/docs/content/docs/reference/lume/cli-reference.mdxnew file mode 100644index 0000000000..c13bfcaa79--- /dev/null+++ b/docs/content/docs/reference/lume/cli-reference.mdx@@ -0,0 +1,352 @@+---+title: CLI Reference+description: Command Line Interface reference for Lume+---++{/*+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY+ Generated by: npx tsx scripts/docs-generators/lume.ts+ Source: lume dump-docs --type cli+ Version: 0.3.10+*/}++A lightweight CLI and local API server to build, run and manage macOS VMs.++Documented against Lume **0.3.10**. Run `lume --version` for your installed version.++For installation steps, see [Install Lume](/how-to-guides/lume/install-lume).++## VM Management++### lume create++Create a new virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name for the virtual machine |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--os` | String | macOS | Operating system to install (macOS or linux) |+| `--cpu` | Int | 4 | Number of CPU cores |+| `--memory` | String | 8GB | Memory size (e.g., 8GB) |+| `--disk-size` | String | 50GB | Disk size (e.g., 50GB) |+| `--display` | String | 1024x768 | Display resolution (e.g., 1024x768) |+| `--ipsw` | String | - | Path to IPSW file or 'latest' for macOS VMs |+| `--storage` | String | - | VM storage location to use |+| `--unattended` | String | - | [Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe. Only supported for macOS VMs. |+| `--debug-dir` | String | - | Custom directory for debug screenshots during unattended setup (defaults to unique folder in system temp) |+| `--vnc-port` | Int | 0 | Port to use for the VNC server during unattended setup. Defaults to 0 (auto-assign) |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `--debug` | false | Enable debug mode for unattended setup - saves screenshots with click coordinates |+| `--no-display` | false | Do not open the VNC client during unattended setup (default: true for unattended) |++### lume clone++Clone an existing virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the source VM |+| `<new-name>` | String | Yes | Name for the cloned VM |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--source-storage` | String | - | Source VM storage location |+| `--dest-storage` | String | - | Destination VM storage location |++### lume run++Run a virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the VM or image to run (format: name or name:tag) |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--shared-dir` | [String] | - | Directory to share with the VM (format: path or path:ro or path:rw) |+| `--mount` | String | - | For Linux VMs only, attach a read-only disk image |+| `--usb-storage` | [String] | - | Disk image to attach as USB mass storage device |+| `--registry` | String | ghcr.io | Container registry URL |+| `--organization` | String | trycua | Organization to pull from |+| `--vnc-port` | Int | 0 | Port for VNC server (0 for auto-assign) |+| `--recovery-mode` | Bool | false | For macOS VMs only, boot in recovery mode |+| `--storage` | String | - | VM storage location to use |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `-d, --no-display` | false | Do not start the VNC client |++### lume stop++Stop a virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the VM to stop |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--storage` | String | - | VM storage location to use |++### lume delete++Delete a virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the VM to delete |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--storage` | String | - | VM storage location to use |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `--force` | false | Force deletion without confirmation |++## VM Information and Configuration++### lume get++Get detailed information about a virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the VM |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `-f, --format` | String | text | Output format |+| `--storage` | String | - | VM storage location to use |++### lume set++Set new values for CPU, memory, and disk size of a virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the VM |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--cpu` | Int | - | New number of CPU cores |+| `--memory` | String | - | New memory size (e.g., 8GB) |+| `--disk-size` | String | - | New disk size (e.g., 100GB) |+| `--display` | String | - | New display resolution |+| `--storage` | String | - | VM storage location to use |++### lume ls++List virtual machines++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `-f, --format` | String | text | Output format (json or text) |+| `--storage` | String | - | Filter by storage location name |++## Image Management++### lume pull++Pull a macOS image from GitHub Container Registry++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<image>` | String | Yes | Image to pull (format: name:tag) |+| `<name>` | String | No | Name for the resulting VM |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--registry` | String | ghcr.io | Container registry URL |+| `--organization` | String | trycua | Organization to pull from |+| `--storage` | String | - | VM storage location to use |++### lume push++Push a macOS VM to GitHub Container Registry++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of VM to push |+| `<image>` | String | Yes | Image tag (format: name:tag) |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--additional-tags` | [String] | - | Additional tags to push |+| `--registry` | String | ghcr.io | Container registry URL |+| `--organization` | String | trycua | Organization to push to |+| `--storage` | String | - | VM storage location to use |+| `--chunk-size-mb` | Int | 512 | Chunk size for upload in MB |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `--verbose` | false | Enable verbose logging |+| `--dry-run` | false | Prepare files without uploading |+| `--reassemble` | true | Verify integrity by reassembling chunks |++### lume images++List available macOS images from local cache++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--organization` | String | trycua | Organization to list images for |++### lume ipsw++Get macOS restore image IPSW URL++### lume prune++Remove cached images++## Guest Access and Setup++### lume ssh++Connect to a VM via SSH or execute commands remotely++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the virtual machine |+| `<command>` | [String] | No | Command to execute (omit for interactive shell) |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `-u, --user` | String | lume | SSH username |+| `-p, --password` | String | lume | SSH password |+| `--storage` | String | - | Storage location name or path |+| `-t, --timeout` | Int | 60 | Command timeout in seconds (0 for no timeout) |++### lume setup++[Preview] Run unattended Setup Assistant automation on a macOS VM++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the virtual machine |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--unattended` | String | - | Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe. |+| `--storage` | String | - | VM storage location to use or direct path to VM location |+| `--vnc-port` | Int | 0 | Port to use for the VNC server. Defaults to 0 (auto-assign) |+| `--debug-dir` | String | - | Custom directory for debug screenshots (defaults to unique folder in system temp) |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `--no-display` | false | Do not open the VNC client automatically |+| `--debug` | false | Enable debug mode - saves screenshots with click coordinates |++## Configuration and Server++### lume serve++Start the VM management server++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--port` | Int | 7777 | Port to listen on |++### lume config++Get or set lume configuration++**Subcommands:**++- `lume config get` - Get current configuration+- `lume config storage` - Manage VM storage locations+ - `lume config storage add` - Add a new VM storage location+ - `lume config storage remove` - Remove a VM storage location+ - `lume config storage list` - List all VM storage locations+ - `lume config storage default` - Set the default VM storage location+- `lume config cache` - Manage image cache settings+ - `lume config cache status` - Show cache status and directory+ - `lume config cache dir` - Get or set cache directory+ - `lume config cache enable` - Enable image caching+ - `lume config cache disable` - Disable image caching++### lume logs++View lume serve logs++**Subcommands:**++- `lume logs info` - View info logs from the daemon+ - `-n, --lines` - Number of lines to display+- `lume logs error` - View error logs from the daemon+ - `-n, --lines` - Number of lines to display+- `lume logs all` - View both info and error logs+ - `-n, --lines` - Number of lines to display++## Global Options++These options are available for all commands:++- `--help` - Show help information+- `--version` - Show version numberdiff --git a/docs/content/docs/reference/lume/http-api.mdx b/docs/content/docs/reference/lume/http-api.mdxnew file mode 100644index 0000000000..bec78d3ea6--- /dev/null+++ b/docs/content/docs/reference/lume/http-api.mdx@@ -0,0 +1,1064 @@+---+title: API Reference+description: HTTP API reference for Lume server+---++{/*+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY+ Generated by: npx tsx scripts/docs-generators/lume.ts+ Source: lume dump-docs --type api+ Version: 0.3.10+*/}++import { Tabs, Tab } from 'fumadocs-ui/components/tabs';++HTTP API for managing macOS and Linux virtual machines++Documented against Lume **0.3.10**. Run `lume --version` for your installed version.++## Default URL++```+http://localhost:7777+```++Start the server with `lume serve` or specify a custom port with `lume serve --port <port>`.++## VM Management++### List all virtual machines++List all virtual machines++`GET: /lume/vms`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| storage | string | No | Filter by storage location name |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl "http://localhost:7777/lume/vms"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.get("http://localhost:7777/lume/vms")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Success+- **400**: Bad request++---++### Get detailed information about a specific virtual machine++Get detailed information about a specific virtual machine++`GET: /lume/vms/:name`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the VM |+| storage | string | No | VM storage location to use |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl "http://localhost:7777/lume/vms/my-vm"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.get("http://localhost:7777/lume/vms/my-vm")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms/my-vm`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Success+- **400**: VM not found or invalid request++---++### Create a new virtual machine++Create a new virtual machine++`POST: /lume/vms`++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name for the virtual machine |+| os | string | Yes | Operating system to install (macOS or linux) |+| cpu | integer | Yes | Number of CPU cores |+| memory | string | Yes | Memory size (e.g., 8GB) |+| diskSize | string | Yes | Disk size (e.g., 50GB) |+| display | string | Yes | Display resolution (e.g., 1024x768) |+| ipsw | string | No | Path to IPSW file or 'latest' for macOS VMs |+| storage | string | No | VM storage location to use |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/vms" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "my-vm",+ "os": "macOS",+ "cpu": 4,+ "memory": "8GB",+ "diskSize": "50GB",+ "display": "1024x768"+}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+ "name": "my-vm",+ "os": "macOS",+ "cpu": 4,+ "memory": "8GB",+ "diskSize": "50GB",+ "display": "1024x768",+}++response = requests.post("http://localhost:7777/lume/vms", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ name: "my-vm",+ os: "macOS",+ cpu: 4,+ memory: "8GB",+ diskSize: "50GB",+ display: "1024x768",+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: VM created successfully+- **400**: Invalid request body or VM creation failed++---++### Delete a virtual machine and its associated files++Delete a virtual machine and its associated files++`DELETE: /lume/vms/:name`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the VM to delete |+| storage | string | No | VM storage location |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X DELETE "http://localhost:7777/lume/vms/my-vm"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.delete("http://localhost:7777/lume/vms/my-vm")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms/my-vm`, {+ method: "DELETE",+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: VM deleted successfully+- **400**: VM not found or deletion failed++---++### Create a copy of an existing virtual machine++Create a copy of an existing virtual machine++`POST: /lume/vms/clone`++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the source VM |+| newName | string | Yes | Name for the cloned VM |+| sourceLocation | string | No | Source VM storage location |+| destLocation | string | No | Destination VM storage location |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/vms/clone" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "my-vm",+ "newName": "example"+}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+ "name": "my-vm",+ "newName": "example",+}++response = requests.post("http://localhost:7777/lume/vms/clone", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms/clone`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ name: "my-vm",+ newName: "example",+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: VM cloned successfully+- **400**: Clone operation failed++---++### Update virtual machine configuration settings++Update virtual machine configuration settings++`PATCH: /lume/vms/:name`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the VM to update |++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| cpu | integer | No | New number of CPU cores |+| memory | string | No | New memory size (e.g., 16GB) |+| diskSize | string | No | New disk size (e.g., 100GB) |+| display | string | No | New display resolution |+| storage | string | No | VM storage location |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X PATCH "http://localhost:7777/lume/vms/my-vm" \+ -H "Content-Type: application/json" \+ -d '{}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+}++response = requests.patch("http://localhost:7777/lume/vms/my-vm", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms/my-vm`, {+ method: "PATCH",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Settings updated successfully+- **400**: Invalid settings or update failed++---++### Start a virtual machine++Start a virtual machine++`POST: /lume/vms/:name/run`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the VM to start |++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| noDisplay | boolean | No | Run without VNC display (default: false) |+| sharedDirectories | array | No | Directories to share with the VM |+| recoveryMode | boolean | No | Boot macOS VM in recovery mode (default: false) |+| storage | string | No | VM storage location |+| clipboard | boolean | No | Enable bidirectional clipboard sync via SSH (experimental) (default: false) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/vms/my-vm/run" \+ -H "Content-Type: application/json" \+ -d '{}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+}++response = requests.post("http://localhost:7777/lume/vms/my-vm/run", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms/my-vm/run`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **202**: VM start initiated (async operation)+- **400**: Invalid request or VM not found++---++### Stop a running virtual machine++Stop a running virtual machine++`POST: /lume/vms/:name/stop`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the VM to stop |++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| storage | string | No | VM storage location |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/vms/my-vm/stop" \+ -H "Content-Type: application/json" \+ -d '{}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+}++response = requests.post("http://localhost:7777/lume/vms/my-vm/stop", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms/my-vm/stop`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: VM stopped successfully+- **400**: Stop operation failed++---++## Image Management++### List available images from local cache++List available images from local cache++`GET: /lume/images`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| organization | string | No | Organization to list images for (default: trycua) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl "http://localhost:7777/lume/images"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.get("http://localhost:7777/lume/images")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/images`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Success+- **400**: Failed to list images++---++### Get the latest macOS restore image (IPSW) URL++Get the latest macOS restore image (IPSW) URL++`GET: /lume/ipsw`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl "http://localhost:7777/lume/ipsw"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.get("http://localhost:7777/lume/ipsw")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/ipsw`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Success+- **400**: Failed to get IPSW URL++---++### Pull a VM image from a container registry++Pull a VM image from a container registry++`POST: /lume/pull`++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| image | string | Yes | Image to pull (format: name:tag) |+| name | string | No | Name for the resulting VM |+| registry | string | No | Container registry URL (default: ghcr.io) |+| organization | string | No | Organization to pull from (default: trycua) |+| storage | string | No | VM storage location |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/pull" \+ -H "Content-Type: application/json" \+ -d '{+ "image": "macos-tahoe-vanilla:latest"+}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+ "image": "macos-tahoe-vanilla:latest",+}++response = requests.post("http://localhost:7777/lume/pull", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/pull`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ image: "macos-tahoe-vanilla:latest",+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Image pulled successfully+- **400**: Pull operation failed++---++### Push a VM image to a container registry++Push a VM image to a container registry++`POST: /lume/vms/push`++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the local VM to push |+| imageName | string | Yes | Base name for the image in the registry |+| tags | array | Yes | List of tags to push |+| registry | string | No | Container registry URL (default: ghcr.io) |+| organization | string | No | Organization to push to (default: trycua) |+| storage | string | No | VM storage location |+| chunkSizeMb | integer | No | Chunk size for upload in MB (default: 512) |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/vms/push" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "my-vm",+ "imageName": "example",+ "tags": [+ "latest"+ ]+}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+ "name": "my-vm",+ "imageName": "example",+ "tags": ["latest"],+}++response = requests.post("http://localhost:7777/lume/vms/push", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/vms/push`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ name: "my-vm",+ imageName: "example",+ tags: ["latest"],+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **202**: Push initiated (async operation)+- **400**: Invalid request++---++### Remove cached images to free up disk space++Remove cached images to free up disk space++`POST: /lume/prune`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/prune"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.post("http://localhost:7777/lume/prune")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/prune`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Images pruned successfully+- **400**: Prune operation failed++---++## Configuration++### Get current Lume configuration settings++Get current Lume configuration settings++`GET: /lume/config`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl "http://localhost:7777/lume/config"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.get("http://localhost:7777/lume/config")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/config`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Success+- **400**: Failed to get config++---++### Update Lume configuration settings++Update Lume configuration settings++`POST: /lume/config`++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| homeDirectory | string | No | VM home directory path |+| cacheDirectory | string | No | Cache directory path |+| cachingEnabled | boolean | No | Enable or disable image caching |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/config" \+ -H "Content-Type: application/json" \+ -d '{}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+}++response = requests.post("http://localhost:7777/lume/config", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/config`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Configuration updated successfully+- **400**: Invalid request++---++### List all VM storage locations++List all VM storage locations++`GET: /lume/config/locations`++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl "http://localhost:7777/lume/config/locations"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.get("http://localhost:7777/lume/config/locations")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/config/locations`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Success+- **400**: Failed to get locations++---++### Add a new VM storage location++Add a new VM storage location++`POST: /lume/config/locations`++#### Request Body++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Storage location name |+| path | string | Yes | Path to storage directory |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/config/locations" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "my-vm",+ "path": "/path/to/storage"+}'+```+ </Tab>+ <Tab value="Python">+```python+import requests++data = {+ "name": "my-vm",+ "path": "/path/to/storage",+}++response = requests.post("http://localhost:7777/lume/config/locations", json=data)+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/config/locations`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ name: "my-vm",+ path: "/path/to/storage",+ }),+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Location added successfully+- **400**: Invalid request or location already exists++---++### Remove a VM storage location++Remove a VM storage location++`DELETE: /lume/config/locations/:name`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the location to remove |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X DELETE "http://localhost:7777/lume/config/locations/my-vm"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.delete("http://localhost:7777/lume/config/locations/my-vm")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/config/locations/my-vm`, {+ method: "DELETE",+});+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Location removed successfully+- **400**: Location not found or cannot be removed++---++### Set the default VM storage location++Set the default VM storage location++`POST: /lume/config/locations/default/:name`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| name | string | Yes | Name of the location to set as default |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl -X POST "http://localhost:7777/lume/config/locations/default/my-vm"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.post("http://localhost:7777/lume/config/locations/default/my-vm")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/config/locations/default/my-vm`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Default location set successfully+- **400**: Location not found++---++## Logs++### Retrieve Lume server logs++Retrieve Lume server logs++`GET: /lume/logs`++#### Parameters++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| type | string | No | Log type: 'info', 'error', or 'all' (default: all) |+| lines | integer | No | Number of lines to return from end of log |++#### Example Request++<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>+ <Tab value="Curl">+```bash+curl "http://localhost:7777/lume/logs"+```+ </Tab>+ <Tab value="Python">+```python+import requests++response = requests.get("http://localhost:7777/lume/logs")+print(response.json())+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const response = await fetch(`http://localhost:7777/lume/logs`);+const data = await response.json();+```+ </Tab>+</Tabs>++#### Response++- **200**: Success+- **400**: Failed to read logs++---diff --git a/docs/content/docs/reference/lume/meta.json b/docs/content/docs/reference/lume/meta.jsonnew file mode 100644index 0000000000..41b74da377--- /dev/null+++ b/docs/content/docs/reference/lume/meta.json@@ -0,0 +1 @@+{ "title": "Lume", "pages": ["cli-reference", "http-api"] }diff --git a/docs/content/docs/reference/meta.json b/docs/content/docs/reference/meta.jsonindex 0ccc7d0d66..7317a8232d 100644--- a/docs/content/docs/reference/meta.json+++ b/docs/content/docs/reference/meta.json@@ -1 +1,11 @@-{ "title": "Reference", "icon": "BookText", "pages": ["index", "cua-driver", "sandbox-sdk", "docs-code-mcp"] }+{+ "title": "Reference",+ "icon": "BookText",+ "pages": [+ "index",+ "cua-driver",+ "lume",+ "sandbox-sdk",+ "docs-code-mcp"+ ]+}diff --git a/libs/lume/src/Utils/CommandDocExtractor.swift b/libs/lume/src/Utils/CommandDocExtractor.swiftindex f0e52a56ec..c8f5e6ec72 100644--- a/libs/lume/src/Utils/CommandDocExtractor.swift+++ b/libs/lume/src/Utils/CommandDocExtractor.swift@@ -437,30 +437,18 @@ enum CommandDocExtractor {),CommandDoc(name: "cache",- abstract: "Manage cache settings",+ abstract: "Manage image cache settings",discussion: nil,arguments: [],options: [],flags: [],subcommands: [- CommandDoc(name: "get", abstract: "Get current cache directory", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),- CommandDoc(name: "set", abstract: "Set cache directory", discussion: nil, arguments: [- ArgumentDoc(name: "path", help: "Path to cache directory", type: "String", isOptional: false),- ], options: [], flags: [], subcommands: []),- ]- ),- CommandDoc(- name: "caching",- abstract: "Manage image caching settings",- discussion: nil,- arguments: [],- options: [],- flags: [],- subcommands: [- CommandDoc(name: "get", abstract: "Show current caching status", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),- CommandDoc(name: "set", abstract: "Enable or disable image caching", discussion: nil, arguments: [- ArgumentDoc(name: "enabled", help: "Enable or disable caching (true/false)", type: "Bool", isOptional: false),+ CommandDoc(name: "status", abstract: "Show cache status and directory", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),+ CommandDoc(name: "dir", abstract: "Get or set cache directory", discussion: nil, arguments: [+ ArgumentDoc(name: "path", help: "Path to cache directory. Omit to show current directory.", type: "String", isOptional: true),], options: [], flags: [], subcommands: []),+ CommandDoc(name: "enable", abstract: "Enable image caching", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),+ CommandDoc(name: "disable", abstract: "Disable image caching", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),]),]diff --git a/scripts/docs-generators/config.json b/scripts/docs-generators/config.jsonindex 2a009ccd31..70b6e4ac27 100644--- a/scripts/docs-generators/config.json+++ b/scripts/docs-generators/config.json@@ -35,7 +35,7 @@"name": "Lume VM Manager","language": "swift","sourcePath": "libs/lume/src",- "docsOutputPath": "docs/content/docs/lume/reference",+ "docsOutputPath": "docs/content/docs/reference/lume","generatorScript": "scripts/docs-generators/lume.ts","watchPaths": ["libs/lume/src/Commands/**/*.swift",@@ -58,7 +58,8 @@"extractCommand": ".build/release/lume dump-docs --type api"}],- "enabled": true+ "enabled": true,+ "notes": "Generates cli-reference.mdx + http-api.mdx from the Swift binary's `dump-docs` output. These files live under the Diátaxis Reference tree; task-oriented Lume docs belong under how-to-guides/lume."},"cua-cli": {"name": "Cua CLI",diff --git a/scripts/docs-generators/generate-versioned-docs.ts b/scripts/docs-generators/generate-versioned-docs.tsindex 53cd2cf52e..aba93b2916 100644--- a/scripts/docs-generators/generate-versioned-docs.ts+++ b/scripts/docs-generators/generate-versioned-docs.ts@@ -525,7 +525,7 @@ function generateVersionedLumeMDX(// Insert old-version callout insteadresult.push('<Callout type="warn">');result.push(- ` This is documentation for **v${majorMinor}**. [View latest version](/lume/reference/cli-reference).`+ ` This is documentation for **v${majorMinor}**. [View latest version](/reference/lume/cli-reference).`);result.push('</Callout>');result.push('');diff --git a/scripts/docs-generators/lume.ts b/scripts/docs-generators/lume.tsindex ddddf5b0f5..f6828fded3 100644--- a/scripts/docs-generators/lume.ts+++ b/scripts/docs-generators/lume.ts@@ -116,7 +116,7 @@ export interface APIStatusCodeDoc {const ROOT_DIR = path.resolve(__dirname, '../..');const LUME_DIR = path.join(ROOT_DIR, 'libs', 'lume');-const DOCS_OUTPUT_DIR = path.join(ROOT_DIR, 'docs', 'content', 'docs', 'lume', 'reference');+const DOCS_OUTPUT_DIR = path.join(ROOT_DIR, 'docs', 'content', 'docs', 'reference', 'lume');const TAG_PREFIX = 'lume-v';// ============================================================================@@ -157,7 +157,7 @@ export function discoverVersions(currentVersion: string): VersionInfo[] {// Add current version (latest)versions.push({version: currentMajorMinor,- href: '/lume/reference/cli-reference',+ href: '/reference/lume/cli-reference',isCurrent: true,});@@ -170,7 +170,7 @@ export function discoverVersions(currentVersion: string): VersionInfo[] {if (version === currentMajorMinor) continue;versions.push({version,- href: `/lume/reference/${entry.name}/cli-reference`,+ href: `/reference/lume/${entry.name}/cli-reference`,isCurrent: false,});}@@ -299,10 +299,7 @@ async function main() {export function generateCLIReferenceMDX(docs: CLIDocumentation): string {const lines: string[] = [];- // Discover version info- const releasedVersion = getLatestReleasedVersion();- const currentMajorMinor = releasedVersion.split('.').slice(0, 2).join('.');- const versions = discoverVersions(releasedVersion);+ const documentedVersion = docs.version || getLatestReleasedVersion();// Header - frontmatter MUST be at the very beginning of the filelines.push('---');@@ -313,45 +310,25 @@ export function generateCLIReferenceMDX(docs: CLIDocumentation): string {lines.push(`{/*AUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: npx tsx scripts/docs-generators/lume.ts- Source: libs/lume/src/Commands/*.swift- Version: ${releasedVersion}+ Source: lume dump-docs --type cli+ Version: ${documentedVersion}*/}`);lines.push('');- lines.push("import { Callout } from 'fumadocs-ui/components/callout';");- lines.push("import { VersionHeader } from '@/components/version-selector';");+ lines.push(`${docs.abstract}`);lines.push('');-- // Version selector and badge- lines.push('<VersionHeader');- lines.push(` versions={${JSON.stringify(versions)}}`);- lines.push(` currentVersion="${currentMajorMinor}"`);- lines.push(` fullVersion="${releasedVersion}"`);- lines.push(` packageName="lume"`);lines.push(- ` installCommand="curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash"`+ `Documented against Lume **${documentedVersion}**. Run \`lume --version\` for your installed version.`);- lines.push('/>');- lines.push('');-- // Introduction- lines.push(`${docs.abstract}`);lines.push('');- lines.push('## Quick Start');- lines.push('');- lines.push('```bash');- lines.push('# Run a prebuilt macOS VM');- lines.push('lume run macos-tahoe-vanilla:latest');- lines.push('');- lines.push('# Create a custom VM');- lines.push('lume create my-vm --cpu 4 --memory 8GB --disk-size 50GB');- lines.push('```');+ lines.push('For installation steps, see [Install Lume](/how-to-guides/lume/install-lume).');lines.push('');// Group commands by categoryconst vmManagement = ['create', 'run', 'stop', 'delete', 'clone'];const vmInfo = ['ls', 'get', 'set'];const imageManagement = ['images', 'pull', 'push', 'ipsw', 'prune'];- const configuration = ['config', 'serve', 'logs', 'setup'];+ const guestAccess = ['ssh', 'setup'];+ const configuration = ['config', 'serve', 'logs'];lines.push('## VM Management');lines.push('');@@ -371,6 +348,12 @@ export function generateCLIReferenceMDX(docs: CLIDocumentation): string {lines.push(...generateCommandDoc(cmd, '###'));}+ lines.push('## Guest Access and Setup');+ lines.push('');+ for (const cmd of docs.commands.filter((c) => guestAccess.includes(c.name))) {+ lines.push(...generateCommandDoc(cmd, '###'));+ }+lines.push('## Configuration and Server');lines.push('');for (const cmd of docs.commands.filter((c) => configuration.includes(c.name))) {@@ -401,9 +384,11 @@ export function generateCommandDoc(cmd: CommandDoc, heading: string): string[] {if (cmd.arguments.length > 0) {lines.push('**Arguments:**');lines.push('');+ lines.push('| Name | Type | Required | Description |');+ lines.push('| ---- | ---- | -------- | ----------- |');for (const arg of cmd.arguments) {- const optional = arg.is_optional ? ' (optional)' : '';- lines.push(`- \`<${arg.name}>\` - ${arg.help}${optional}`);+ const required = arg.is_optional ? 'No' : 'Yes';+ lines.push(`| \`<${arg.name}>\` | ${arg.type} | ${required} | ${arg.help} |`);}lines.push('');}@@ -412,10 +397,12 @@ export function generateCommandDoc(cmd: CommandDoc, heading: string): string[] {if (cmd.options.length > 0) {lines.push('**Options:**');lines.push('');+ lines.push('| Name | Type | Default | Description |');+ lines.push('| ---- | ---- | ------- | ----------- |');for (const opt of cmd.options) {const shortFlag = opt.short_name ? `-${opt.short_name}, ` : '';- const defaultVal = opt.default_value ? ` (default: ${opt.default_value})` : '';- lines.push(`- \`${shortFlag}--${opt.name}\` - ${opt.help}${defaultVal}`);+ const defaultVal = opt.default_value || '-';+ lines.push(`| \`${shortFlag}--${opt.name}\` | ${opt.type} | ${defaultVal} | ${opt.help} |`);}lines.push('');}@@ -424,9 +411,11 @@ export function generateCommandDoc(cmd: CommandDoc, heading: string): string[] {if (cmd.flags.length > 0) {lines.push('**Flags:**');lines.push('');+ lines.push('| Name | Default | Description |');+ lines.push('| ---- | ------- | ----------- |');for (const flag of cmd.flags) {const shortFlag = flag.short_name ? `-${flag.short_name}, ` : '';- lines.push(`- \`${shortFlag}--${flag.name}\` - ${flag.help}`);+ lines.push(`| \`${shortFlag}--${flag.name}\` | ${flag.default_value} | ${flag.help} |`);}lines.push('');}@@ -469,10 +458,7 @@ export function generateCommandDoc(cmd: CommandDoc, heading: string): string[] {export function generateHTTPAPIMDX(docs: HTTPAPIDocumentation): string {const lines: string[] = [];- // Discover version info- const releasedVersion = getLatestReleasedVersion();- const currentMajorMinor = releasedVersion.split('.').slice(0, 2).join('.');- const versions = discoverVersions(releasedVersion);+ const documentedVersion = docs.version || getLatestReleasedVersion();// Header - frontmatter MUST be at the very beginning of the filelines.push('---');@@ -483,30 +469,20 @@ export function generateHTTPAPIMDX(docs: HTTPAPIDocumentation): string {lines.push(`{/*AUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: npx tsx scripts/docs-generators/lume.ts- Source: libs/lume/src/Server/*.swift- Version: ${releasedVersion}+ Source: lume dump-docs --type api+ Version: ${documentedVersion}*/}`);lines.push('');- lines.push("import { Callout } from 'fumadocs-ui/components/callout';");lines.push("import { Tabs, Tab } from 'fumadocs-ui/components/tabs';");- lines.push("import { VersionHeader } from '@/components/version-selector';");- lines.push('');-- // Version selector and badge- lines.push('<VersionHeader');- lines.push(` versions={${JSON.stringify(versions)}}`);- lines.push(` currentVersion="${currentMajorMinor}"`);- lines.push(` fullVersion="${releasedVersion}"`);- lines.push(` packageName="lume"`);- lines.push(- ` installCommand="curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash"`- );- lines.push('/>');lines.push('');// Introductionlines.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('```');@@ -538,12 +514,7 @@ export function generateHTTPAPIMDX(docs: HTTPAPIDocumentation): string {export function generateEndpointDoc(endpoint: APIEndpointDoc): string[] {const lines: string[] = [];- // Title from description- const title = endpoint.description.replace(- /^Get |^List |^Create |^Delete |^Update |^Set |^Add |^Remove |^Pull |^Push |^Prune |^Stop |^Run |^Retrieve /,- ''- );- lines.push(`### ${capitalizeFirst(title)}`);+ lines.push(`### ${endpoint.description}`);lines.push('');lines.push(endpoint.description);lines.push('');@@ -628,7 +599,7 @@ export function generateEndpointDoc(endpoint: APIEndpointDoc): string[] {}function generateCurlExample(endpoint: APIEndpointDoc): string {- const path = endpoint.path.replace(/:(\w+)/g, '{$1}');+ const path = endpoint.path.replace(/:(\w+)/g, (_, name) => getExamplePathValue(name));const url = `http://localhost:7777${path}`;if (endpoint.method === 'GET' || endpoint.method === 'DELETE') {@@ -656,7 +627,7 @@ function generateCurlExample(endpoint: APIEndpointDoc): string {}function generatePythonExample(endpoint: APIEndpointDoc): string {- const path = endpoint.path.replace(/:(\w+)/g, '{$1}');+ const path = endpoint.path.replace(/:(\w+)/g, (_, name) => getExamplePathValue(name));const method = endpoint.method.toLowerCase();const lines: string[] = [];@@ -688,7 +659,7 @@ function generatePythonExample(endpoint: APIEndpointDoc): string {}function generateTypeScriptExample(endpoint: APIEndpointDoc): string {- const path = endpoint.path.replace(/:(\w+)/g, '${$1}');+ const path = endpoint.path.replace(/:(\w+)/g, (_, name) => getExamplePathValue(name));const lines: string[] = [];@@ -761,8 +732,10 @@ function getExampleValueTS(field: APIFieldDoc): string {return String(val);}-function capitalizeFirst(str: string): string {- return str.charAt(0).toUpperCase() + str.slice(1);+function getExamplePathValue(name: string): string {+ if (name === 'name') return 'my-vm';+ if (name === 'id') return 'example-id';+ return `example-${name}`;}// ============================================================================