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.

fix(release): sync cua-sdk docs on release pull requests (#5019)

injaneityfda6f80a603d
diff --git a/.github/scripts/sync_sdk_release_docs.py b/.github/scripts/sync_sdk_release_docs.py
new file mode 100644
index 0000000000..5ff083e3f7
--- /dev/null
+++ b/.github/scripts/sync_sdk_release_docs.py
@@ -0,0 +1,22 @@
+import argparse
+from pathlib import Path
+import re
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description="Synchronize SDK release documentation.")
+ parser.add_argument("--repo-root", dest="root", type=Path, default=Path.cwd())
+ parser.add_argument("--from", dest="previous", required=True)
+ args = parser.parse_args(argv)
+ version = (args.root / "libs/cua/VERSION").read_text().strip()
+ paths = [path for folder in ("cua-cli", "cua-sdk", "fleets")
+ for path in (args.root / "docs/content/docs" / folder).rglob("*.mdx")]
+ for path in [*paths, args.root / "scripts/docs-generators/cli-specs/cua.json"]:
+ content = path.read_text()
+ updated = re.sub(r"(?<![\d.])" + re.escape(args.previous) + r"(?!\.?\d)", version, content)
+ path.write_text(updated)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.github/scripts/tests/test_sync_sdk_release_docs.py b/.github/scripts/tests/test_sync_sdk_release_docs.py
new file mode 100644
index 0000000000..493b2d0222
--- /dev/null
+++ b/.github/scripts/tests/test_sync_sdk_release_docs.py
@@ -0,0 +1,33 @@
+from pathlib import Path
+
+from sync_sdk_release_docs import main
+
+
+def test_sync_sdk_release_docs_updates_standalone_versions(tmp_path: Path):
+ version = tmp_path / "libs/cua/VERSION"
+ version.parent.mkdir(parents=True)
+ version.write_text("0.5.0\n")
+ content = (
+ ' Version: cua 0.4.1, cua-sandbox 0.9.0\n'
+ 'cua-sdk-v0.4.1\n@trycua/[email protected]\n"0.4.1"\n'
+ 'uses the `cua` 0.4.1 CLI.\nSentence ends 0.4.1.\n'
+ '10.4.1 0.4.12 0.4.1.2 1.0.4.1\n'
+ )
+ paths = [
+ tmp_path / f"docs/content/docs/{folder}/nested/page.mdx"
+ for folder in ("cua-cli", "cua-sdk", "fleets")
+ ]
+ paths.append(tmp_path / "scripts/docs-generators/cli-specs/cua.json")
+ outside = tmp_path / "docs/content/docs/other/page.mdx"
+ for path in [*paths, outside]:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(content)
+
+ assert main(["--repo-root", str(tmp_path), "--from", "0.4.1"]) == 0
+
+ expected = content.replace("0.4.1", "0.5.0").replace(
+ "10.5.0 0.5.02 0.5.0.2 1.0.5.0", "10.4.1 0.4.12 0.4.1.2 1.0.4.1"
+ )
+ for path in paths:
+ assert path.read_text() == expected
+ assert outside.read_text() == content
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index e6e936735f..146fa79b01 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -274,9 +274,12 @@ jobs:
COMMIT_MESSAGE="chore(cua-spacesd): synchronize release lockfiles"
elif [[ "$SDK" == "true" ]]; then
# Release Please bumps VERSION, pyproject, __init__, package.json
- # and package-lock.json together; only validation runs here.
+ # and package-lock.json together; the stamped docs follow here.
+ PREVIOUS=$(git show origin/main:libs/cua/VERSION)
+ python3 .github/scripts/sync_sdk_release_docs.py --from "$PREVIOUS"
python3 .github/scripts/validate_release_versions.py --product sdk
- COMMIT_MESSAGE="chore(cua-sdk): synchronize release metadata"
+ git add docs/content/docs/cua-cli docs/content/docs/cua-sdk docs/content/docs/fleets scripts/docs-generators/cli-specs/cua.json
+ COMMIT_MESSAGE="chore(cua-sdk): synchronize release documentation"
else
python3 .github/scripts/validate_release_versions.py --product sandbox
# The Sandbox reference records the package version, so regenerate
diff --git a/docs/content/docs/cua-sdk/reference/protocol/daemon-runtimes.mdx b/docs/content/docs/cua-sdk/reference/protocol/daemon-runtimes.mdx
index 0e7b0cfc6e..f58fe15c40 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/daemon-runtimes.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/daemon-runtimes.mdx
@@ -7,7 +7,7 @@ description: "cua.daemon.v1 RuntimeService: the local engines and images the cua
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
The local runtimes (gVisor, runc, QEMU, Lume) and images the `cua daemon` orchestrates.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/daemon-sandboxes.mdx b/docs/content/docs/cua-sdk/reference/protocol/daemon-sandboxes.mdx
index 0a79902495..4a4199f33d 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/daemon-sandboxes.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/daemon-sandboxes.mdx
@@ -7,7 +7,7 @@ description: "cua.daemon.v1 SandboxService: the local cua daemon API for sandbox
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
The local `cua daemon` API (a Unix socket on the host, not cua-spacesd): sandbox lifecycle across locations.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/daemon-service.mdx b/docs/content/docs/cua-sdk/reference/protocol/daemon-service.mdx
index d4f49a984c..3ec294346d 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/daemon-service.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/daemon-service.mdx
@@ -7,7 +7,7 @@ description: "cua.daemon.v1 DaemonService: the local cua daemon identity and the
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
The `cua daemon` identity (`GetInfo`) and the loopback media bridge for webviews.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx b/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx
index 1a6c40314a..b09c2c5ac1 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx
@@ -7,7 +7,7 @@ description: "cua.daemon.v1 SpaceService: Spaces and the hosts that provide them
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
Spaces through the local `cua daemon`: create, list, power, delete, and the machines that provide Spaces.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-common.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-common.mdx
index cac383e09d..4e8cb33e6a 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-common.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-common.mdx
@@ -7,7 +7,7 @@ description: "The cua.env.v1 types every spacesd service shares: ErrorInfo, prin
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
Errors (`google.rpc.Status` carrying `ErrorInfo`), principals and geometry, used by every `cua.env.v1` service.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-computer.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-computer.mdx
index 33a19eaa22..dda06dc075 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-computer.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-computer.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 ComputerService and DriverService: screenshots, pointer
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
Desktop control. These services need the desktop provider; input goes through Cua Driver, which `DriverService` also exposes tool by tool.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-diagnose.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-diagnose.mdx
index b3099bfdac..788c7c1edf 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-diagnose.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-diagnose.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 Diagnose: the image self-test report `SystemService.Dia
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
The report of the image self-test (`SystemService.Diagnose` / `DiagnoseOnce`): checks, their evidence and the summary.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-filesystem.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-filesystem.mdx
index c008f08fe2..e0dd33e3d0 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-filesystem.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-filesystem.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 FilesystemService: stat, list, watch, read, chunked upl
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-host-spaces.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-host-spaces.mdx
index aa6872e459..05d9ab10cc 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-host-spaces.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-host-spaces.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 HostSpacesService: Spaces a host creates for its owner'
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
Spaces a machine set up with `cua host setup --provide-spaces` creates for its owner's enrolled devices: settings, capacity, create and delete. The host's cua-spacesd forwards each call to its cua daemon.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-process.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-process.mdx
index 8df19f051d..476c98901d 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-process.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-process.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 ProcessService: start, attach to, feed and signal guest
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-stream.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-stream.mdx
index ad1f3f5aee..1850c30de9 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-stream.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-stream.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 StreamService and PresenceService: media sessions and m
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
Media sessions (video and audio over the media wire, see `libs/cua/proto/MEDIA.md`) and presence for shared sessions.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-system.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-system.mdx
index 5483c00098..22bc388c95 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-system.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-system.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 SystemService: capabilities, init, health, shutdown, vi
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
The handshake (`GetCapabilities`), session init, health, shutdown, viewer tickets and joining a relay (`AttachRelay`).
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-teleport-tunnel.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-teleport-tunnel.mdx
index f199285c47..1377d319de 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-teleport-tunnel.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-teleport-tunnel.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 TeleportService, TunnelService and VolumeService: recei
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
The receiving side of teleport (sending lives in the cua SDK), TCP port forwards, the reverse-SOCKS hotspot, and the guest mount of Cua Volume served by the client.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/env-windows.mdx b/docs/content/docs/cua-sdk/reference/protocol/env-windows.mdx
index 555b4153d7..39892bc74a 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/env-windows.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/env-windows.mdx
@@ -7,7 +7,7 @@ description: "cua.env.v1 WindowsService and AccessibilityService: list, watch an
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
Windows, app launch and the accessibility tree. These services need the desktop provider.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/index.mdx b/docs/content/docs/cua-sdk/reference/protocol/index.mdx
index 6cff78e2da..302eaccc91 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/index.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/index.mdx
@@ -7,7 +7,7 @@ description: "The gRPC contracts of cua-spacesd (cua.env.v1) and the cua daemon
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-proto
Source: buf build libs/cua/proto -o -#format=json
- Version: 0.2.0
+ Version: 0.4.1
*/}
The gRPC contracts, generated from the `.proto` files in `libs/cua/proto`. `cua.env.v1` is served by cua-spacesd inside a sandbox; `cua.daemon.v1` is served by the local `cua daemon`. Changes are additive and pass `buf breaking`.