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.

feat: add immutable Driver and Lume nightly releases

Francesco Bonacci8cef90b7ce6f
diff --git a/.github/release-manifest.schema.json b/.github/release-manifest.schema.json
index f1a57a0725..bdfa7ea0d0 100644
--- a/.github/release-manifest.schema.json
+++ b/.github/release-manifest.schema.json
@@ -28,6 +28,7 @@
"repository": { "type": "string", "pattern": "^[^/]+/[^/]+$" },
"product": { "type": "string", "minLength": 1 },
"displayName": { "type": "string", "minLength": 1 },
+ "channel": { "enum": ["stable", "nightly"] },
"version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+" },
"bump": { "enum": ["patch", "minor", "major"] },
"tag": { "type": "string", "minLength": 1 },
@@ -46,13 +47,26 @@
"visualRequested": { "type": "boolean" },
"changes": {
"type": "array",
- "minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": ["type", "scope", "summary", "breaking", "pr", "issues", "contributors"],
"properties": {
- "type": { "enum": ["feat", "fix", "perf", "revert"] },
+ "type": {
+ "enum": [
+ "build",
+ "chore",
+ "ci",
+ "docs",
+ "feat",
+ "fix",
+ "perf",
+ "refactor",
+ "revert",
+ "style",
+ "test"
+ ]
+ },
"scope": { "type": ["string", "null"] },
"summary": { "type": "string", "minLength": 1 },
"breaking": { "type": "boolean" },
@@ -80,6 +94,26 @@
}
}
},
+ "allOf": [
+ {
+ "if": {
+ "required": ["channel"],
+ "properties": { "channel": { "const": "nightly" } }
+ },
+ "else": {
+ "properties": {
+ "changes": {
+ "minItems": 1,
+ "items": {
+ "properties": {
+ "type": { "enum": ["feat", "fix", "perf", "revert"] }
+ }
+ }
+ }
+ }
+ }
+ }
+ ],
"$defs": {
"sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
"changeContributor": {
diff --git a/.github/releases/README.md b/.github/releases/README.md
new file mode 100644
index 0000000000..94dec75b35
--- /dev/null
+++ b/.github/releases/README.md
@@ -0,0 +1,24 @@
+# Release-channel component registry
+
+`components.json` is the small, shared contract for immutable release channels.
+It identifies a component's Release Please entry, disjoint stable and nightly
+tag namespaces, build-time version sites, builder workflow, and change paths.
+It intentionally does not describe signing, packaging, or registry publishing;
+those remain owned by each component workflow.
+
+To add a component, add one descriptor, keep its stable prefix identical to its
+Release Please component tag, choose a unique `nightly-` prefix, declare only
+version sites that affect built nightly artifacts, and add focused tests to
+`test_release_channels.py`. Run:
+
+```bash
+python3 .github/scripts/release_channels.py validate
+python3 -m pytest .github/scripts/tests/test_release_channels.py
+```
+
+Nightly versions are staged only in an ephemeral CI checkout. The script must
+never rewrite stable baked installer defaults or published-version pointers.
+Nightly release notes reuse the repository's PR-first attribution collector.
+The first nightly is bounded by the component's current stable tag; later
+nightlies are bounded by the previous published nightly. A component therefore
+needs a reachable stable tag before its nightly channel is enabled.
diff --git a/.github/releases/component.schema.json b/.github/releases/component.schema.json
new file mode 100644
index 0000000000..cef696c9b3
--- /dev/null
+++ b/.github/releases/component.schema.json
@@ -0,0 +1,112 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://github.com/trycua/cua/.github/releases/component.schema.json",
+ "title": "Cua release-channel component registry",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["schemaVersion", "sharedChangePaths", "components"],
+ "properties": {
+ "$schema": { "type": "string" },
+ "schemaVersion": { "const": 1 },
+ "sharedChangePaths": {
+ "type": "array",
+ "items": { "$ref": "#/$defs/repositoryPath" },
+ "uniqueItems": true
+ },
+ "components": {
+ "type": "object",
+ "minProperties": 1,
+ "additionalProperties": { "$ref": "#/$defs/component" }
+ }
+ },
+ "$defs": {
+ "repositoryPath": {
+ "type": "string",
+ "minLength": 1,
+ "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+ },
+ "component": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "releasePleasePath",
+ "displayName",
+ "stableTagPrefix",
+ "nightlyTagPrefix",
+ "versionAuthorityFile",
+ "changelog",
+ "builderWorkflow",
+ "changeDetectionPaths",
+ "buildVersionSites",
+ "channels"
+ ],
+ "properties": {
+ "releasePleasePath": { "$ref": "#/$defs/repositoryPath" },
+ "displayName": { "type": "string", "minLength": 1 },
+ "stableTagPrefix": { "type": "string", "minLength": 1 },
+ "nightlyTagPrefix": { "type": "string", "pattern": "^nightly-.+" },
+ "versionAuthorityFile": { "$ref": "#/$defs/repositoryPath" },
+ "changelog": { "$ref": "#/$defs/repositoryPath" },
+ "builderWorkflow": { "$ref": "#/$defs/repositoryPath" },
+ "changeDetectionPaths": {
+ "type": "array",
+ "minItems": 1,
+ "items": { "$ref": "#/$defs/repositoryPath" },
+ "uniqueItems": true
+ },
+ "buildVersionSites": {
+ "type": "array",
+ "minItems": 1,
+ "items": { "$ref": "#/$defs/versionSite" }
+ },
+ "channels": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["nightly", "registries"],
+ "properties": {
+ "nightly": { "const": true },
+ "registries": {
+ "type": "array",
+ "maxItems": 0
+ }
+ }
+ }
+ }
+ },
+ "versionSite": {
+ "oneOf": [
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["kind", "path"],
+ "properties": {
+ "kind": { "const": "plain" },
+ "path": { "$ref": "#/$defs/repositoryPath" }
+ }
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["kind", "path", "pattern", "replacement", "expectedMatches"],
+ "properties": {
+ "kind": { "const": "regex" },
+ "path": { "$ref": "#/$defs/repositoryPath" },
+ "pattern": { "type": "string", "minLength": 1 },
+ "replacement": { "type": "string" },
+ "expectedMatches": { "type": "integer", "minimum": 1 }
+ }
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["kind", "path", "manifestPath"],
+ "properties": {
+ "kind": { "const": "cargo-workspace-lock" },
+ "path": { "$ref": "#/$defs/repositoryPath" },
+ "manifestPath": { "$ref": "#/$defs/repositoryPath" }
+ }
+ }
+ ]
+ }
+ }
+}
diff --git a/.github/releases/components.json b/.github/releases/components.json
new file mode 100644
index 0000000000..2894657636
--- /dev/null
+++ b/.github/releases/components.json
@@ -0,0 +1,88 @@
+{
+ "$schema": "./component.schema.json",
+ "schemaVersion": 1,
+ "sharedChangePaths": [
+ ".github/release-manifest.schema.json",
+ ".github/releases",
+ ".github/scripts/github_release.py",
+ ".github/scripts/release_channels.py",
+ ".github/workflows/nightly-component-plan.yml"
+ ],
+ "components": {
+ "cua-driver-rs": {
+ "releasePleasePath": "libs/cua-driver",
+ "displayName": "Cua Driver",
+ "stableTagPrefix": "cua-driver-rs-v",
+ "nightlyTagPrefix": "nightly-cua-driver-rs-v",
+ "versionAuthorityFile": "libs/cua-driver/rust/VERSION",
+ "changelog": "libs/cua-driver/rust/CHANGELOG.md",
+ "builderWorkflow": ".github/workflows/cd-rust-cua-driver.yml",
+ "changeDetectionPaths": [
+ "libs/cua-driver",
+ ".github/scripts/verify_cua_driver_release_archives.py",
+ ".github/workflows/cd-rust-cua-driver.yml",
+ ".github/workflows/nightly-cua-driver.yml"
+ ],
+ "buildVersionSites": [
+ {
+ "kind": "plain",
+ "path": "libs/cua-driver/rust/VERSION"
+ },
+ {
+ "kind": "regex",
+ "path": "libs/cua-driver/rust/Cargo.toml",
+ "pattern": "(?m)^(version = \")\\d+\\.\\d+\\.\\d+(\")$",
+ "replacement": "\\g<1>{version}\\g<2>",
+ "expectedMatches": 1
+ },
+ {
+ "kind": "cargo-workspace-lock",
+ "path": "libs/cua-driver/rust/Cargo.lock",
+ "manifestPath": "libs/cua-driver/rust/Cargo.toml"
+ },
+ {
+ "kind": "regex",
+ "path": "libs/cua-driver/rust/Skills/cua-driver/SKILL.md",
+ "pattern": "(?m)^(version: )\\d+\\.\\d+\\.\\d+( # x-release-please-version)$",
+ "replacement": "\\g<1>{version}\\g<2>",
+ "expectedMatches": 1
+ }
+ ],
+ "channels": {
+ "nightly": true,
+ "registries": []
+ }
+ },
+ "lume": {
+ "releasePleasePath": "libs/lume",
+ "displayName": "Lume",
+ "stableTagPrefix": "lume-v",
+ "nightlyTagPrefix": "nightly-lume-v",
+ "versionAuthorityFile": "libs/lume/VERSION",
+ "changelog": "libs/lume/CHANGELOG.md",
+ "builderWorkflow": ".github/workflows/cd-swift-lume.yml",
+ "changeDetectionPaths": [
+ "libs/lume",
+ ".github/workflows/cd-swift-lume.yml",
+ ".github/workflows/nightly-lume.yml"
+ ],
+ "buildVersionSites": [
+ {
+ "kind": "plain",
+ "path": "libs/lume/VERSION"
+ },
+ {
+ "kind": "regex",
+ "path": "libs/lume/src/Main.swift",
+ "pattern": "(?m)^( static let current: String = \")\\d+\\.\\d+\\.\\d+(\" // x-release-please-version)$",
+ "replacement": "\\g<1>{version}\\g<2>",
+ "expectedMatches": 1
+ }
+ ],
+ "channels": {
+ "nightly": true,
+ "registries": []
+ }
+ }
+ }
+}
diff --git a/.github/scripts/github_release.py b/.github/scripts/github_release.py
index c2883827a6..8f454c351b 100644
--- a/.github/scripts/github_release.py
+++ b/.github/scripts/github_release.py
@@ -15,6 +15,8 @@ from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen
+import release_channels
+
class ReleaseError(RuntimeError):
"""A release lifecycle invariant failed."""
@@ -115,6 +117,9 @@ class GitHubApi:
def delete(self, path: str) -> None:
self.request("DELETE", path)
+ def post(self, path: str, body: Mapping[str, Any]) -> Any:
+ return self.request("POST", path, json_body=body)
+
def patch(self, path: str, body: Mapping[str, Any]) -> Any:
return self.request("PATCH", path, json_body=body)
@@ -143,6 +148,72 @@ def unique_release(api: GitHubApi, repository: str, tag: str) -> dict[str, Any]:
return matches[0]
+def validate_registered_nightly_tag(tag: str) -> None:
+ registry = release_channels.load_registry()
+ matches = []
+ for name, component in registry["components"].items():
+ try:
+ release_channels.parse_tag(component, "nightly", tag)
+ except release_channels.ChannelError:
+ continue
+ matches.append(name)
+ if len(matches) != 1:
+ raise ReleaseError(
+ f"nightly tag {tag!r} must match exactly one registered component; matched {matches}"
+ )
+
+
+def ensure_release(
+ api: GitHubApi,
+ repository: str,
+ tag: str,
+ expected_sha: str,
+ *,
+ channel: str,
+ create_if_missing: bool,
+) -> dict[str, Any]:
+ matches = releases_by_tag(api, repository, tag)
+ if len(matches) > 1:
+ ids = [release.get("id") for release in matches]
+ raise ReleaseError(f"expected one GitHub release for {tag}, found {ids}")
+ if matches:
+ return matches[0]
+ if not create_if_missing:
+ raise ReleaseError(f"Release Please draft for {tag} does not exist")
+ if channel != "nightly":
+ raise ReleaseError("automatic draft creation is allowed only for the nightly channel")
+ validate_registered_nightly_tag(tag)
+ if not release_channels.SHA_RE.fullmatch(expected_sha):
+ raise ReleaseError("nightly draft target must be an exact lowercase commit SHA")
+ commit = api.get(f"repos/{repository}/commits/{expected_sha}")
+ if str(commit.get("sha")) != expected_sha:
+ raise ReleaseError(f"GitHub did not resolve expected commit {expected_sha}")
+ try:
+ created = api.post(
+ f"repos/{repository}/releases",
+ {
+ "tag_name": tag,
+ "target_commitish": expected_sha,
+ "name": tag,
+ "body": "",
+ "draft": True,
+ "prerelease": True,
+ "make_latest": "false",
+ },
+ )
+ except ReleaseError:
+ # A retry or concurrent job may have committed the draft after the
+ # initial read. Reconcile by identity; every other error remains fatal.
+ matches = releases_by_tag(api, repository, tag)
+ if len(matches) != 1:
+ raise
+ created = matches[0]
+ if str(created.get("tag_name")) != tag or not created.get("draft"):
+ raise ReleaseError(f"GitHub did not create the expected draft for {tag}")
+ print(f"created private nightly draft for {tag}")
+ return dict(created)
+
+
def tag_commit_sha(api: GitHubApi, repository: str, tag: str) -> str:
reference = api.get(f"repos/{repository}/git/ref/tags/{quote(tag, safe='')}")
target = reference["object"]
@@ -237,11 +308,38 @@ def finalize_release(
asset_dir: Path,
prerelease: bool,
make_latest: bool,
+ channel: str = "stable",
+ create_if_missing: bool = False,
) -> dict[str, Any]:
- actual_sha = tag_commit_sha(api, repository, tag)
- if actual_sha != expected_sha:
- raise ReleaseError(f"tag {tag} points to {actual_sha}, expected {expected_sha}")
- release = unique_release(api, repository, tag)
+ if channel not in {"stable", "nightly"}:
+ raise ReleaseError(f"unsupported release channel: {channel}")
+ if channel == "nightly" and (not prerelease or make_latest):
+ raise ReleaseError("nightly releases must be prereleases and must not become latest")
+ release: dict[str, Any] | None = None
+ if create_if_missing:
+ release = ensure_release(
+ api,
+ repository,
+ tag,
+ expected_sha,
+ channel=channel,
+ create_if_missing=True,
+ )
+ if release is None:
+ actual_sha = tag_commit_sha(api, repository, tag)
+ if actual_sha != expected_sha:
+ raise ReleaseError(f"tag {tag} points to {actual_sha}, expected {expected_sha}")
+ release = unique_release(api, repository, tag)
+ elif release.get("draft"):
+ target = str(release.get("target_commitish") or "")
+ if target != expected_sha:
+ raise ReleaseError(
+ f"nightly draft {tag} targets {target or '<missing>'}, expected {expected_sha}"
+ )
+ else:
+ actual_sha = tag_commit_sha(api, repository, tag)
+ if actual_sha != expected_sha:
+ raise ReleaseError(f"tag {tag} points to {actual_sha}, expected {expected_sha}")
if not release.get("draft"):
same_state = (
str(release.get("body") or "") == body and bool(release.get("prerelease")) == prerelease
@@ -269,6 +367,11 @@ def finalize_release(
"make_latest": "true" if make_latest else "false",
},
)
+ actual_sha = tag_commit_sha(api, repository, tag)
+ if actual_sha != expected_sha:
+ raise ReleaseError(
+ f"published tag {tag} points to {actual_sha}, expected {expected_sha}"
+ )
print(f"published {tag}: {release.get('html_url')}")
return dict(release)
@@ -282,6 +385,8 @@ def build_parser() -> argparse.ArgumentParser:
parser.add_argument("--asset-dir", type=Path, required=True)
parser.add_argument("--prerelease", action="store_true")
parser.add_argument("--make-latest", action="store_true")
+ parser.add_argument("--channel", choices=("stable", "nightly"), default="stable")
+ parser.add_argument("--create-if-missing", action="store_true")
return parser
@@ -301,6 +406,8 @@ def main(argv: Sequence[str] | None = None) -> int:
asset_dir=args.asset_dir,
prerelease=args.prerelease,
make_latest=args.make_latest,
+ channel=args.channel,
+ create_if_missing=args.create_if_missing,
)
except (OSError, ReleaseError, ValueError) as error:
print(f"release finalization error: {error}", file=sys.stderr)
diff --git a/.github/scripts/release_attribution.py b/.github/scripts/release_attribution.py
index d564ee9b63..efa4717c4e 100644
--- a/.github/scripts/release_attribution.py
+++ b/.github/scripts/release_attribution.py
@@ -223,7 +223,13 @@ def parse_conventional_line(line: str) -> ConventionalEntry | None:
)
-def release_entries(subject: str, commit_body: str, pull_body: str) -> list[ConventionalEntry]:
+def release_entries(
+ subject: str,
+ commit_body: str,
+ pull_body: str,
+ *,
+ allowed_types: set[str] = RELEASING_TYPES,
+) -> list[ConventionalEntry]:
override = OVERRIDE_RE.search(pull_body or "")
candidates = override.group("body").splitlines() if override else [subject]
entries = [entry for line in candidates if (entry := parse_conventional_line(line))]
@@ -232,7 +238,7 @@ def release_entries(subject: str, commit_body: str, pull_body: str) -> list[Conv
ConventionalEntry(entry.change_type, entry.scope, entry.summary, True)
for entry in entries
]
- return [entry for entry in entries if entry.change_type in RELEASING_TYPES]
+ return [entry for entry in entries if entry.change_type in allowed_types]
def validate_pr_title(
@@ -846,7 +852,10 @@ def build_manifest(
release_ref: str | None = None,
exclude_paths: Sequence[str] = (),
asset_dir: Path | None = None,
+ channel: str = "stable",
) -> dict[str, Any]:
+ if channel not in {"stable", "nightly"}:
+ raise ReleaseError(f"unsupported release channel: {channel}")
current_ref = release_ref or tag
actual_sha = resolve_tag_sha(repo_root, current_ref)
if actual_sha != expected_sha:
@@ -866,23 +875,27 @@ def build_manifest(
) or LEGACY_RELEASE_BUMP_RE.match(commit.subject):
continue
parsed_subject = parse_conventional_line(commit.subject)
- subject_is_releasing = bool(
- parsed_subject and parsed_subject.change_type in RELEASING_TYPES
- )
+ included_types = ALLOWED_TITLE_TYPES if channel == "nightly" else RELEASING_TYPES
+ subject_is_included = bool(parsed_subject and parsed_subject.change_type in included_types)
pull = resolve_pull_for_commit(
github,
repository,
commit,
- required=subject_is_releasing,
+ required=subject_is_included,
)
if pull is None:
continue
pull_body = str(pull.get("body") or "")
- if not subject_is_releasing and not OVERRIDE_RE.search(pull_body):
+ if not subject_is_included and not OVERRIDE_RE.search(pull_body):
continue
pull_number = int(pull["number"])
pull_commits[pull_number].add(commit.sha)
- entries = release_entries(commit.subject, commit.body, pull_body)
+ entries = release_entries(
+ commit.subject,
+ commit.body,
+ pull_body,
+ allowed_types=included_types,
+ )
if not entries:
continue
contributors, issues, pull_visual = _change_contributors(
@@ -908,33 +921,37 @@ def build_manifest(
}
)
- if not changes:
+ if not changes and channel == "stable":
raise ReleaseError(f"no releasing pull requests found for {tag}")
- changelog_section = extract_changelog_section(changelog_path, version)
- missing_prs = sorted(
- {
- int(change["pr"])
- for change in changes
- if not changelog_references_change(
- changelog_section,
- int(change["pr"]),
- pull_commits[int(change["pr"])],
- )
- }
- )
- if missing_prs:
- raise ReleaseError(f"changelog section is missing pull requests: {missing_prs}")
+ if channel == "stable":
+ changelog_content = extract_changelog_section(changelog_path, version)
+ missing_prs = sorted(
+ {
+ int(change["pr"])
+ for change in changes
+ if not changelog_references_change(
+ changelog_content,
+ int(change["pr"]),
+ pull_commits[int(change["pr"])],
+ )
+ }
+ )
+ if missing_prs:
+ raise ReleaseError(f"changelog section is missing pull requests: {missing_prs}")
+ else:
+ changelog_content = changelog_path.read_text()
- bump = release_bump(changes, version)
+ bump = release_bump(changes, version) if changes else "patch"
owner, repo = repository.split("/", 1)
+ compare_target = actual_sha if channel == "nightly" else tag
compare_url = (
- f"https://github.com/{owner}/{repo}/compare/{quote(previous_tag)}...{quote(tag)}"
+ f"https://github.com/{owner}/{repo}/compare/{quote(previous_tag)}...{quote(compare_target)}"
if previous_tag
else f"https://github.com/{owner}/{repo}/releases/tag/{quote(tag)}"
)
- return {
+ manifest = {
"schema": (
f"https://raw.githubusercontent.com/{repository}/{actual_sha}/"
".github/release-manifest.schema.json"
@@ -951,16 +968,19 @@ def build_manifest(
"compareUrl": compare_url,
"changelog": {
"path": changelog_path.relative_to(repo_root).as_posix(),
- "sha256": sha256(changelog_section.encode()).hexdigest(),
+ "sha256": sha256(changelog_content.encode()).hexdigest(),
},
- "visualRequested": visual_requested or bump == "major",
+ "visualRequested": channel == "stable" and (visual_requested or bump == "major"),
"changes": changes,
"contributors": merge_contributors(all_contributors),
"assets": asset_checksums(asset_dir),
}
+ if channel == "nightly":
+ manifest["channel"] = "nightly"
+ return manifest
-def _thanks(change: Mapping[str, Any]) -> str:
+def format_change_thanks(change: Mapping[str, Any]) -> str:
external: dict[str, Mapping[str, Any]] = {}
reporters: dict[str, Mapping[str, Any]] = {}
for item in change.get("contributors", []):
@@ -977,14 +997,9 @@ def _thanks(change: Mapping[str, Any]) -> str:
parts: list[str] = []
if external:
- parts.append(
- "Thanks " + ", ".join(f"@{item['login']}" for item in external.values())
- )
+ parts.append("Thanks " + ", ".join(f"@{item['login']}" for item in external.values()))
if reporters:
- parts.append(
- "reported by "
- + ", ".join(f"@{item['login']}" for item in reporters.values())
- )
+ parts.append("reported by " + ", ".join(f"@{item['login']}" for item in reporters.values()))
return "; ".join(parts)
@@ -1027,7 +1042,7 @@ def render_body(manifest: Mapping[str, Any], footer: str = "") -> str:
continue
lines.extend(["", f"## {TYPE_HEADINGS[change_type]}", ""])
for change in grouped[change_type]:
- suffix = _thanks(change)
+ suffix = format_change_thanks(change)
bullet = (
f"- {change['summary']}. ([#{change['pr']}]({repository_url}/pull/{change['pr']}))"
)
@@ -1144,6 +1159,7 @@ def collect_command(args: argparse.Namespace) -> None:
release_ref=args.ref,
exclude_paths=args.exclude_path,
asset_dir=args.asset_dir.resolve() if args.asset_dir else None,
+ channel=args.channel,
)
write_json(args.output, manifest)
print(f"wrote {args.output} with {len(manifest['changes'])} changes")
@@ -1240,6 +1256,7 @@ def build_parser() -> argparse.ArgumentParser:
"--config", type=Path, default=Path(".github/release-attribution-config.json")
)
collect.add_argument("--asset-dir", type=Path)
+ collect.add_argument("--channel", choices=("stable", "nightly"), default="stable")
collect.add_argument("--output", type=Path, required=True)
render = subparsers.add_parser("render")
diff --git a/.github/scripts/release_channels.py b/.github/scripts/release_channels.py
new file mode 100644
index 0000000000..a8d6e6b49a
--- /dev/null
+++ b/.github/scripts/release_channels.py
@@ -0,0 +1,639 @@
+#!/usr/bin/env python3
+"""Plan and stage immutable component releases without changing stable state."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import subprocess
+import sys
+from typing import Any, Mapping, Sequence
+
+import release_attribution
+
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_REGISTRY = ROOT / ".github/releases/components.json"
+SEMVER_PATTERN = r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)"
+SEMVER_RE = re.compile(rf"^{SEMVER_PATTERN}$")
+NIGHTLY_VERSION_RE = re.compile(
+ rf"^(?P<base>{SEMVER_PATTERN})-nightly\."
+ r"(?P<date>[0-9]{8})\.(?P<run>[1-9][0-9]*)$"
+)
+SHA_RE = re.compile(r"^[0-9a-f]{40}$")
+
+
+class ChannelError(RuntimeError):
+ """A release-channel invariant failed."""
+
+
+def read_json(path: Path) -> Any:
+ try:
+ return json.loads(path.read_text())
+ except (OSError, json.JSONDecodeError) as error:
+ raise ChannelError(f"cannot read JSON from {path}: {error}") from error
+
+
+def repository_path(root: Path, value: str) -> Path:
+ pure = PurePosixPath(value)
+ if pure.is_absolute() or ".." in pure.parts:
+ raise ChannelError(f"repository path must be relative and confined: {value!r}")
+ resolved = (root / pure).resolve()
+ try:
+ resolved.relative_to(root.resolve())
+ except ValueError as error:
+ raise ChannelError(f"repository path escapes the checkout: {value!r}") from error
+ return resolved
+
+
+def load_registry(path: Path = DEFAULT_REGISTRY, *, root: Path = ROOT) -> dict[str, Any]:
+ registry = read_json(path)
+ if registry.get("schemaVersion") != 1:
+ raise ChannelError("component registry schemaVersion must be 1")
+ components = registry.get("components")
+ if not isinstance(components, dict) or not components:
+ raise ChannelError("component registry must contain components")
+ shared = registry.get("sharedChangePaths")
+ if not isinstance(shared, list):
+ raise ChannelError("component registry sharedChangePaths must be a list")
+
+ prefixes: dict[str, str] = {}
+ for name, component in components.items():
+ if not isinstance(component, dict):
+ raise ChannelError(f"component {name} must be an object")
+ for field in (
+ "releasePleasePath",
+ "displayName",
+ "stableTagPrefix",
+ "nightlyTagPrefix",
+ "versionAuthorityFile",
+ "changelog",
+ "builderWorkflow",
+ "changeDetectionPaths",
+ "buildVersionSites",
+ "channels",
+ ):
+ if field not in component:
+ raise ChannelError(f"component {name} is missing {field}")
+ if component["stableTagPrefix"] == component["nightlyTagPrefix"]:
+ raise ChannelError(f"component {name} has overlapping channel prefixes")
+ if not str(component["nightlyTagPrefix"]).startswith("nightly-"):
+ raise ChannelError(f"component {name} nightlyTagPrefix must start with nightly-")
+ for channel in ("stableTagPrefix", "nightlyTagPrefix"):
+ prefix = str(component[channel])
+ if prefix in prefixes:
+ raise ChannelError(
+ f"tag prefix {prefix!r} is shared by {prefixes[prefix]} and {name}"
+ )
+ prefixes[prefix] = name
+ for field in ("versionAuthorityFile", "changelog", "builderWorkflow"):
+ if not repository_path(root, str(component[field])).is_file():
+ raise ChannelError(f"component {name} {field} does not exist: {component[field]}")
+ sites = component["buildVersionSites"]
+ if not isinstance(sites, list) or not sites:
+ raise ChannelError(f"component {name} must declare buildVersionSites")
+ for site in sites:
+ if not repository_path(root, str(site["path"])).is_file():
+ raise ChannelError(f"component {name} version site does not exist: {site['path']}")
+ channels = component["channels"]
+ if channels != {"nightly": True, "registries": []}:
+ raise ChannelError(
+ f"component {name} v1 channels must enable nightly and declare no registries"
+ )
+
+ release_config = read_json(root / "release-please-config.json")
+ release_manifest = read_json(root / ".release-please-manifest.json")
+ packages = release_config.get("packages", {})
+ for name, component in components.items():
+ package_path = component["releasePleasePath"]
+ package = packages.get(package_path)
+ if not isinstance(package, dict):
+ raise ChannelError(f"component {name} has no Release Please package {package_path}")
+ if package.get("component") != name:
+ raise ChannelError(
+ f"component {name} does not match Release Please component {package.get('component')!r}"
+ )
+ expected_prefix = f"{name}-v"
+ if component["stableTagPrefix"] != expected_prefix:
+ raise ChannelError(
+ f"component {name} stable prefix must match Release Please: {expected_prefix}"
+ )
+ authority = repository_path(root, component["versionAuthorityFile"]).read_text().strip()
+ if not SEMVER_RE.fullmatch(authority):
+ raise ChannelError(f"component {name} authority is not a stable version: {authority!r}")
+ if release_manifest.get(package_path) != authority:
+ raise ChannelError(
+ f"component {name} authority {authority} differs from Release Please manifest "
+ f"{release_manifest.get(package_path)!r}"
+ )
+ return registry
+
+
+def component_descriptor(
+ name: str, path: Path = DEFAULT_REGISTRY, *, root: Path = ROOT
+) -> dict[str, Any]:
+ registry = load_registry(path, root=root)
+ try:
+ return dict(registry["components"][name])
+ except KeyError as error:
+ raise ChannelError(f"unknown release component: {name}") from error
+
+
+def stable_version(value: str) -> tuple[int, int, int]:
+ if not SEMVER_RE.fullmatch(value):
+ raise ChannelError(f"invalid stable version: {value!r}")
+ return tuple(int(part) for part in value.split(".")) # type: ignore[return-value]
+
+
+def nightly_version(value: str) -> re.Match[str]:
+ match = NIGHTLY_VERSION_RE.fullmatch(value)
+ if not match:
+ raise ChannelError(f"invalid nightly version: {value!r}")
+ try:
+ datetime.strptime(match.group("date"), "%Y%m%d")
+ except ValueError as error:
+ raise ChannelError(f"invalid nightly date in version: {value!r}") from error
+ return match
+
+
+def derive_nightly_version(base: str, date: str, run: str) -> str:
+ major, minor, patch = stable_version(base)
+ candidate = f"{major}.{minor}.{patch + 1}-nightly.{date}.{run}"
+ nightly_version(candidate)
+ return candidate
+
+
+def format_tag(component: Mapping[str, Any], channel: str, version: str) -> str:
+ if channel == "stable":
+ stable_version(version)
+ return f"{component['stableTagPrefix']}{version}"
+ if channel == "nightly":
+ nightly_version(version)
+ return f"{component['nightlyTagPrefix']}{version}"
+ raise ChannelError(f"unsupported channel: {channel}")
+
+
+def parse_tag(component: Mapping[str, Any], channel: str, tag: str) -> str:
+ prefix_key = "stableTagPrefix" if channel == "stable" else "nightlyTagPrefix"
+ if channel not in {"stable", "nightly"}:
+ raise ChannelError(f"unsupported channel: {channel}")
+ prefix = str(component[prefix_key])
+ if not tag.startswith(prefix):
+ raise ChannelError(f"tag {tag!r} is outside the {channel} namespace {prefix!r}")
+ version = tag[len(prefix) :]
+ if channel == "stable":
+ stable_version(version)
+ else:
+ nightly_version(version)
+ if format_tag(component, channel, version) != tag:
+ raise ChannelError(f"tag {tag!r} is not canonical")
+ return version
+
+
+def _workspace_package_names(manifest_path: Path) -> set[str]:
+ manifest = manifest_path.read_text()
+ members_match = re.search(r"(?ms)^members\s*=\s*\[(.*?)\]", manifest)
+ if not members_match:
+ raise ChannelError(f"Cargo workspace members are missing from {manifest_path}")
+ members = re.findall(r'"([^"]+)"', members_match.group(1))
+ names: set[str] = set()
+ for pattern in members:
+ for member in manifest_path.parent.glob(str(pattern)):
+ package_manifest = member / "Cargo.toml"
+ if package_manifest.is_file():
+ package_text = package_manifest.read_text()
+ package_block = re.search(r"(?ms)^\[package\]\s*(.*?)(?=^\[|\Z)", package_text)
+ if not package_block or not re.search(
+ r"(?m)^version\.workspace\s*=\s*true\s*$", package_block.group(1)
+ ):
+ continue
+ name_match = re.search(r'(?m)^name\s*=\s*"([^"]+)"\s*$', package_block.group(1))
+ if not name_match:
+ raise ChannelError(f"Cargo package name is missing from {package_manifest}")
+ names.add(name_match.group(1))
+ if not names:
+ raise ChannelError(
+ f"no version-inheriting Cargo workspace packages found in {manifest_path}"
+ )
+ return names
+
+
+def _rewrite_cargo_lock(
+ lock_path: Path, manifest_path: Path, old_version: str, new_version: str
+) -> int:
+ names = _workspace_package_names(manifest_path)
+ original = lock_path.read_text()
+ seen: set[str] = set()
+
+ def replace_block(match: re.Match[str]) -> str:
+ block = match.group(0)
+ name_match = re.search(r'(?m)^name = "([^"]+)"$', block)
+ version_match = re.search(r'(?m)^version = "([^"]+)"$', block)
+ if not name_match or not version_match or name_match.group(1) not in names:
+ return block
+ if re.search(r"(?m)^source = ", block):
+ raise ChannelError(f"workspace package {name_match.group(1)} unexpectedly has a source")
+ if version_match.group(1) != old_version:
+ raise ChannelError(
+ f"workspace package {name_match.group(1)} has lock version "
+ f"{version_match.group(1)}, expected {old_version}"
+ )
+ seen.add(name_match.group(1))
+ start, end = version_match.span(1)
+ return f"{block[:start]}{new_version}{block[end:]}"
+
+ rewritten = re.sub(
+ r"(?ms)^\[\[package\]\]\n.*?(?=^\[\[package\]\]\n|\Z)", replace_block, original
+ )
+ missing = names - seen
+ if missing:
+ raise ChannelError(
+ f"Cargo.lock is missing workspace packages: {', '.join(sorted(missing))}"
+ )
+ lock_path.write_text(rewritten)
+ return len(seen)
+
+
+def apply_version(
+ name: str,
+ version: str,
+ *,
+ registry_path: Path = DEFAULT_REGISTRY,
+ root: Path = ROOT,
+) -> list[str]:
+ nightly_version(version)
+ component = component_descriptor(name, registry_path, root=root)
+ authority = repository_path(root, component["versionAuthorityFile"])
+ old_version = authority.read_text().strip()
+ stable_version(old_version)
+ changed: list[str] = []
+ for site in component["buildVersionSites"]:
+ path = repository_path(root, site["path"])
+ kind = site["kind"]
+ if kind == "plain":
+ if path.read_text().strip() != old_version:
+ raise ChannelError(f"plain version site {site['path']} differs from {old_version}")
+ path.write_text(f"{version}\n")
+ elif kind == "regex":
+ original = path.read_text()
+ replacement = str(site["replacement"]).replace("{version}", version)
+ rewritten, count = re.subn(str(site["pattern"]), replacement, original)
+ if count != int(site["expectedMatches"]):
+ raise ChannelError(
+ f"version site {site['path']} matched {count} times, "
+ f"expected {site['expectedMatches']}"
+ )
+ path.write_text(rewritten)
+ elif kind == "cargo-workspace-lock":
+ manifest = repository_path(root, site["manifestPath"])
+ _rewrite_cargo_lock(path, manifest, old_version, version)
+ else:
+ raise ChannelError(f"unsupported version site kind: {kind!r}")
+ changed.append(str(site["path"]))
+ return changed
+
+
+def _git(root: Path, *args: str) -> str:
+ result = subprocess.run(["git", *args], cwd=root, check=False, text=True, capture_output=True)
+ if result.returncode != 0:
+ raise ChannelError(f"git {' '.join(args)} failed: {result.stderr.strip()}")
+ return result.stdout.strip()
+
+
+def plan_nightly(
+ name: str,
+ source_sha: str,
+ date: str,
+ run: str,
+ releases: Sequence[Mapping[str, Any]],
+ *,
+ force: bool = False,
+ registry_path: Path = DEFAULT_REGISTRY,
+ root: Path = ROOT,
+) -> dict[str, Any]:
+ if not SHA_RE.fullmatch(source_sha):
+ raise ChannelError(f"source SHA must be 40 lowercase hex characters: {source_sha!r}")
+ component = component_descriptor(name, registry_path, root=root)
+ base = repository_path(root, component["versionAuthorityFile"]).read_text().strip()
+ version = derive_nightly_version(base, date, run)
+ tag = format_tag(component, "nightly", version)
+ candidates: list[Mapping[str, Any]] = []
+ for release in releases:
+ if release.get("draft"):
+ continue
+ candidate_tag = str(release.get("tag_name", ""))
+ try:
+ parse_tag(component, "nightly", candidate_tag)
+ except ChannelError:
+ continue
+ candidates.append(release)
+ candidates.sort(
+ key=lambda value: str(value.get("published_at") or value.get("created_at") or "")
+ )
+ previous_tag = str(candidates[-1]["tag_name"]) if candidates else None
+ previous_sha = _git(root, "rev-list", "-n", "1", previous_tag) if previous_tag else None
+ attribution_base_tag = previous_tag or format_tag(component, "stable", base)
+ attribution_base_sha = previous_sha or _git(root, "rev-list", "-n", "1", attribution_base_tag)
+ if not attribution_base_sha:
+ raise ChannelError(f"attribution base tag has no commit: {attribution_base_tag}")
+ _git(root, "merge-base", "--is-ancestor", attribution_base_sha, source_sha)
+ paths = list(component["changeDetectionPaths"])
+ paths.extend(load_registry(registry_path, root=root)["sharedChangePaths"])
+ paths = sorted(set(str(path) for path in paths))
+ if force:
+ should_build, reason = True, "forced"
+ elif previous_sha is None:
+ should_build, reason = True, "first-nightly"
+ elif previous_sha == source_sha:
+ should_build, reason = False, "source-unchanged"
+ else:
+ changed = _git(root, "diff", "--name-only", previous_sha, source_sha, "--", *paths)
+ should_build = bool(changed)
+ reason = "relevant-changes" if should_build else "component-unchanged"
+ return {
+ "component": name,
+ "channel": "nightly",
+ "version": version,
+ "bundleVersion": version.split("-", 1)[0],
+ "tag": tag,
+ "sourceSha": source_sha,
+ "previousTag": previous_tag,
+ "previousNightlyTag": previous_tag,
+ "previousSha": previous_sha,
+ "attributionBaseTag": attribution_base_tag,
+ "attributionBaseSha": attribution_base_sha,
+ "shouldBuild": should_build,
+ "reason": reason,
+ }
+
+
+def build_manifest(
+ name: str,
+ version: str,
+ tag: str,
+ source_sha: str,
+ previous_tag: str | None,
+ asset_dir: Path,
+ *,
+ repository: str,
+ registry_path: Path = DEFAULT_REGISTRY,
+ root: Path = ROOT,
+ attribution_config_path: Path | None = None,
+ github: release_attribution.GitHubClient | None = None,
+) -> dict[str, Any]:
+ component = component_descriptor(name, registry_path, root=root)
+ parsed = parse_tag(component, "nightly", tag)
+ if parsed != version:
+ raise ChannelError(f"tag version {parsed} differs from requested version {version}")
+ if not SHA_RE.fullmatch(source_sha):
+ raise ChannelError(f"invalid source SHA: {source_sha!r}")
+ if not previous_tag:
+ raise ChannelError("nightly attribution requires a bounded previous tag")
+ if not asset_dir.is_dir() or not any(path.is_file() for path in asset_dir.rglob("*")):
+ raise ChannelError(f"asset directory {asset_dir} is empty")
+ base_sha = _git(root, "rev-list", "-n", "1", previous_tag)
+ if not base_sha:
+ raise ChannelError(f"nightly attribution base has no commit: {previous_tag}")
+ _git(root, "merge-base", "--is-ancestor", base_sha, source_sha)
+ registry = load_registry(registry_path, root=root)
+ paths = sorted(
+ {
+ *(str(path) for path in component["changeDetectionPaths"]),
+ *(str(path) for path in registry["sharedChangePaths"]),
+ }
+ )
+ config_path = attribution_config_path or root / ".github/release-attribution-config.json"
+ client = github or release_attribution.GitHubClient(
+ os.environ.get("GH_TOKEN", ""),
+ os.environ.get("GITHUB_API_URL", "https://api.github.com"),
+ )
+ try:
+ return release_attribution.build_manifest(
+ repo_root=root,
+ repository=repository,
+ product=name,
+ display_name=str(component["displayName"]),
+ version=version,
+ tag=tag,
+ previous_tag=previous_tag,
+ expected_sha=source_sha,
+ paths=paths,
+ changelog_path=repository_path(root, component["changelog"]),
+ attribution_config=read_json(config_path),
+ github=client,
+ release_ref=source_sha,
+ asset_dir=asset_dir,
+ channel="nightly",
+ )
+ except release_attribution.ReleaseError as error:
+ raise ChannelError(str(error)) from error
+
+
+def render_nightly_body(manifest: Mapping[str, Any]) -> str:
+ if manifest.get("channel") != "nightly":
+ raise ChannelError("nightly body rendering requires a nightly manifest")
+ product = str(manifest["product"])
+ version = str(manifest["version"])
+ tag = str(manifest["tag"])
+ source_sha = str(manifest["sha"])
+ repository = str(manifest["repository"])
+ if product == "cua-driver-rs":
+ install = (
+ f"CUA_DRIVER_RS_VERSION={tag} "
+ '/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"'
+ )
+ elif product == "lume":
+ install = f"curl -fsSL https://cua.ai/lume/install.sh | LUME_VERSION={tag} bash"
+ else:
+ raise ChannelError(f"no exact nightly installation contract for {product}")
+ lines = [
+ f"# {manifest['displayName']} {version} (nightly)",
+ "",
+ "Automated immutable nightly built from an exact `main` commit. Nightlies are",
+ "opt-in, may be less stable than regular releases, and never replace stable",
+ "update discovery.",
+ "",
+ "## Source",
+ "",
+ f"- Commit: [`{source_sha}`](https://github.com/{repository}/commit/{source_sha})",
+ f"- Changes: [{manifest['previousTag'] or 'first nightly'}…`{source_sha[:12]}`]({manifest['compareUrl']})",
+ ]
+ changes = list(manifest["changes"])
+ lines.extend(["", "## Changes", ""])
+ if changes:
+ for change in changes:
+ label = str(change["type"]).replace("-", " ").title()
+ suffix = release_attribution.format_change_thanks(change)
+ bullet = (
+ f"- **{label}:** {change['summary']}. "
+ f"([#{change['pr']}](https://github.com/{repository}/pull/{change['pr']}))"
+ )
+ if suffix:
+ bullet += f" {suffix}."
+ lines.append(bullet)
+ else:
+ lines.append("No conventional pull-request changes matched this component's paths.")
+
+ external = [item for item in manifest["contributors"] if item.get("external")]
+ lines.extend(["", "## Contributors", ""])
+ if external:
+ lines.append(
+ "Thanks to "
+ + ", ".join(f"@{item['login']}" for item in external)
+ + " for contributing to or reporting changes in this nightly."
+ )
+ else:
+ lines.append("This nightly contains maintainer changes only.")
+
+ lines.extend(
+ [
+ "",
+ "## Exact installation",
+ "",
+ "```bash",
+ install,
+ "```",
+ "",
+ "## SHA256 checksums",
+ "",
+ "```text",
+ ]
+ )
+ lines.extend(f"{asset['sha256']} {asset['name']}" for asset in manifest["assets"])
+ lines.extend(["```", ""])
+ return "\n".join(lines)
+
+
+def write_github_outputs(values: Mapping[str, Any], path: Path) -> None:
+ lines = []
+ for key, value in values.items():
+ rendered = (
+ json.dumps(value, separators=(",", ":"))
+ if isinstance(value, (list, dict))
+ else str(value)
+ )
+ if isinstance(value, bool):
+ rendered = str(value).lower()
+ if value is None:
+ rendered = ""
+ lines.append(f"{key}={rendered}")
+ with path.open("a") as handle:
+ handle.write("\n".join(lines) + "\n")
+
+
+def parser() -> argparse.ArgumentParser:
+ result = argparse.ArgumentParser(description=__doc__)
+ result.add_argument("--registry", type=Path, default=DEFAULT_REGISTRY)
+ subparsers = result.add_subparsers(dest="command", required=True)
+ subparsers.add_parser("validate")
+
+ derive = subparsers.add_parser("derive")
+ derive.add_argument("--component", required=True)
+ derive.add_argument("--date", default=datetime.now(timezone.utc).strftime("%Y%m%d"))
+ derive.add_argument("--run", required=True)
+
+ parse = subparsers.add_parser("parse-tag")
+ parse.add_argument("--component", required=True)
+ parse.add_argument("--channel", choices=("stable", "nightly"), required=True)
+ parse.add_argument("--tag", required=True)
+
+ apply = subparsers.add_parser("apply-version")
+ apply.add_argument("--component", required=True)
+ apply.add_argument("--version", required=True)
+
+ plan = subparsers.add_parser("plan")
+ plan.add_argument("--component", required=True)
+ plan.add_argument("--source-sha", required=True)
+ plan.add_argument("--date", required=True)
+ plan.add_argument("--run", required=True)
+ plan.add_argument("--releases", type=Path, required=True)
+ plan.add_argument("--force", action="store_true")
+ plan.add_argument("--output", type=Path)
+ plan.add_argument("--github-output", type=Path)
+
+ manifest = subparsers.add_parser("manifest")
+ manifest.add_argument("--component", required=True)
+ manifest.add_argument("--version", required=True)
+ manifest.add_argument("--tag", required=True)
+ manifest.add_argument("--source-sha", required=True)
+ manifest.add_argument("--previous-tag")
+ manifest.add_argument("--asset-dir", type=Path, required=True)
+ manifest.add_argument("--repository", required=True)
+ manifest.add_argument("--output", type=Path, required=True)
+ render = subparsers.add_parser("render-nightly")
+ render.add_argument("--manifest", type=Path, required=True)
+ render.add_argument("--body", type=Path, required=True)
+ return result
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+ args = parser().parse_args(argv)
+ try:
+ root = ROOT
+ if args.command == "validate":
+ registry = load_registry(args.registry, root=root)
+ print(f"validated {len(registry['components'])} release-channel components")
+ elif args.command == "derive":
+ component = component_descriptor(args.component, args.registry, root=root)
+ base = repository_path(root, component["versionAuthorityFile"]).read_text().strip()
+ version = derive_nightly_version(base, args.date, args.run)
+ print(
+ json.dumps({"version": version, "tag": format_tag(component, "nightly", version)})
+ )
+ elif args.command == "parse-tag":
+ component = component_descriptor(args.component, args.registry, root=root)
+ print(parse_tag(component, args.channel, args.tag))
+ elif args.command == "apply-version":
+ for changed in apply_version(
+ args.component, args.version, registry_path=args.registry, root=root
+ ):
+ print(changed)
+ elif args.command == "plan":
+ releases = read_json(args.releases)
+ if not isinstance(releases, list):
+ raise ChannelError("releases input must be a JSON array")
+ result = plan_nightly(
+ args.component,
+ args.source_sha,
+ args.date,
+ args.run,
+ releases,
+ force=args.force,
+ registry_path=args.registry,
+ root=root,
+ )
+ rendered = json.dumps(result, indent=2) + "\n"
+ if args.output:
+ args.output.write_text(rendered)
+ else:
+ print(rendered, end="")
+ if args.github_output:
+ write_github_outputs(result, args.github_output)
+ elif args.command == "manifest":
+ manifest = build_manifest(
+ args.component,
+ args.version,
+ args.tag,
+ args.source_sha,
+ args.previous_tag,
+ args.asset_dir,
+ repository=args.repository,
+ registry_path=args.registry,
+ root=root,
+ )
+ args.output.write_text(json.dumps(manifest, indent=2) + "\n")
+ elif args.command == "render-nightly":
+ manifest = read_json(args.manifest)
+ args.body.write_text(render_nightly_body(manifest))
+ except (ChannelError, OSError, ValueError) as error:
+ print(f"release channel error: {error}", file=sys.stderr)
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.github/scripts/tests/test_cua_driver_release_wiring.py b/.github/scripts/tests/test_cua_driver_release_wiring.py
index d003110e97..8a13f338b6 100644
--- a/.github/scripts/tests/test_cua_driver_release_wiring.py
+++ b/.github/scripts/tests/test_cua_driver_release_wiring.py
@@ -491,8 +491,19 @@ class TestCuaDriverReleaseWiring(unittest.TestCase):
"libs/cua-driver/rust/crates/cua-driver/src/skills.rs"
)
self.assertIn(
- "releases/download/cua-driver-rs-v{version}/"
- "cua-driver-rs-v{version}-skills.tar.gz",
+ 'const STABLE_RELEASE_TAG_PREFIX: &str = "cua-driver-rs-v"',
+ skill_installer,
+ )
+ self.assertIn(
+ 'const NIGHTLY_RELEASE_TAG_PREFIX: &str = "nightly-cua-driver-rs-v"',
+ skill_installer,
+ )
+ self.assertIn(
+ "releases/download/{tag_prefix}{version}/",
+ skill_installer,
+ )
+ self.assertIn(
+ "{STABLE_RELEASE_TAG_PREFIX}{version}-skills.tar.gz",
skill_installer,
)
self.assertIn(
diff --git a/.github/scripts/tests/test_github_release.py b/.github/scripts/tests/test_github_release.py
index 6ea81bfffa..7dbc12ca41 100644
--- a/.github/scripts/tests/test_github_release.py
+++ b/.github/scripts/tests/test_github_release.py
@@ -9,6 +9,7 @@ import pytest
import github_release
from github_release import (
+ ensure_release,
GitHubApi,
ReleaseError,
finalize_release,
@@ -23,6 +24,7 @@ class FakeApi:
self.deleted: list[str] = []
self.uploaded: list[tuple[str, str]] = []
self.patches: list[tuple[str, dict]] = []
+ self.posts: list[tuple[str, dict]] = []
self.assets = [{"id": 21, "name": "old.zip", "state": "starter", "size": 0}]
self.release = {
"id": 7,
@@ -37,14 +39,18 @@ class FakeApi:
def get(self, path: str):
if path.endswith("/git/ref/tags/lume-v0.4.0"):
return {"object": {"type": "tag", "sha": "annotated"}}
+ if "/git/ref/tags/nightly-" in path:
+ return {"object": {"type": "commit", "sha": self.expected_sha}}
if path.endswith("/git/tags/annotated"):
return {"object": {"type": "commit", "sha": self.expected_sha}}
if "/releases?" in path:
return [self.release] if self.release else []
- if path.endswith("/releases/7/assets?per_page=100&page=1"):
+ if path.endswith("/assets?per_page=100&page=1"):
return list(self.assets)
if path.endswith("/releases/latest"):
return self.release
+ if "/commits/" in path:
+ return {"sha": path.rsplit("/", 1)[1]}
raise AssertionError(path)
def delete(self, path: str):
@@ -58,6 +64,20 @@ class FakeApi:
self.release.update(body)
return self.release
+ def post(self, path: str, body: dict):
+ self.posts.append((path, body))
+ self.release = {
+ "id": 8,
+ "tag_name": body["tag_name"],
+ "draft": body["draft"],
+ "prerelease": body["prerelease"],
+ "body": body["body"],
+ "target_commitish": body["target_commitish"],
+ "upload_url": "https://uploads.example/releases/8/assets{?name,label}",
+ "html_url": f"https://github.com/trycua/cua/releases/tag/{body['tag_name']}",
+ }
+ return self.release
+
def test_finalize_verifies_tag_replaces_incomplete_assets_then_publishes(tmp_path: Path):
(tmp_path / "old.zip").write_bytes(b"new archive")
@@ -171,3 +191,129 @@ def test_github_api_retries_transient_server_error(monkeypatch: pytest.MonkeyPat
api = GitHubApi("token", max_attempts=3, retry_base_seconds=0.1)
assert api.get("repos/trycua/cua/releases") == {"ok": True}
assert sleeps == [0.25]
+
+
+def test_nightly_can_create_a_private_draft_at_the_exact_sha():
+ sha = "a" * 40
+ tag = "nightly-lume-v0.5.4-nightly.20260812.42"
+ api = FakeApi(sha)
+ api.release = None
+
+ release = ensure_release(
+ api,
+ "trycua/cua",
+ tag,
+ sha,
+ channel="nightly",
+ create_if_missing=True,
+ )
+
+ assert release["draft"] is True
+ assert api.posts == [
+ (
+ "repos/trycua/cua/releases",
+ {
+ "tag_name": tag,
+ "target_commitish": sha,
+ "name": tag,
+ "body": "",
+ "draft": True,
+ "prerelease": True,
+ "make_latest": "false",
+ },
+ )
+ ]
+
+
+def test_stable_and_unregistered_tags_cannot_create_drafts():
+ api = FakeApi("a" * 40)
+ api.release = None
+ with pytest.raises(ReleaseError, match="only for the nightly channel"):
+ ensure_release(
+ api,
+ "trycua/cua",
+ "lume-v0.5.4",
+ "a" * 40,
+ channel="stable",
+ create_if_missing=True,
+ )
+ with pytest.raises(ReleaseError, match="exactly one registered component"):
+ ensure_release(
+ api,
+ "trycua/cua",
+ "nightly-other-v0.5.4-nightly.20260812.42",
+ "a" * 40,
+ channel="nightly",
+ create_if_missing=True,
+ )
+ assert api.posts == []
+
+
+def test_nightly_draft_requires_an_exact_commit_sha_before_creation():
+ api = FakeApi("a" * 40)
+ api.release = None
+ with pytest.raises(ReleaseError, match="exact lowercase commit SHA"):
+ ensure_release(
+ api,
+ "trycua/cua",
+ "nightly-lume-v0.5.4-nightly.20260812.42",
+ "main",
+ channel="nightly",
+ create_if_missing=True,
+ )
+ assert api.posts == []
+
+
+def test_nightly_publication_flags_fail_closed_before_mutation(tmp_path: Path):
+ api = FakeApi("a" * 40)
+ with pytest.raises(ReleaseError, match="must be prereleases"):
+ finalize_release(
+ api=api,
+ repository="trycua/cua",
+ tag="nightly-lume-v0.5.4-nightly.20260812.42",
+ expected_sha="a" * 40,
+ body="body",
+ asset_dir=tmp_path,
+ prerelease=False,
+ make_latest=True,
+ channel="nightly",
+ create_if_missing=True,
+ )
+ assert api.posts == []
+
+
+def test_nightly_creation_upload_and_publish_is_one_idempotent_transaction(tmp_path: Path):
+ artifact = tmp_path / "lume.tar.gz"
+ artifact.write_bytes(b"nightly archive")
+ sha = "a" * 40
+ tag = "nightly-lume-v0.5.4-nightly.20260812.42"
+ api = FakeApi(sha)
+ api.release = None
+ api.assets = []
+
+ release = finalize_release(
+ api=api,
+ repository="trycua/cua",
+ tag=tag,
+ expected_sha=sha,
+ body="nightly body",
+ asset_dir=tmp_path,
+ prerelease=True,
+ make_latest=False,
+ channel="nightly",
+ create_if_missing=True,
+ )
+
+ assert release["draft"] is False
+ assert [name for _, name in api.uploaded] == ["lume.tar.gz"]
+ assert api.patches == [
+ (
+ "repos/trycua/cua/releases/8",
+ {
+ "body": "nightly body",
+ "draft": False,
+ "prerelease": True,
+ "make_latest": "false",
+ },
+ )
+ ]
diff --git a/.github/scripts/tests/test_nightly_release_wiring.py b/.github/scripts/tests/test_nightly_release_wiring.py
new file mode 100644
index 0000000000..a72f2d7f61
--- /dev/null
+++ b/.github/scripts/tests/test_nightly_release_wiring.py
@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[3]
+WORKFLOWS = ROOT / ".github/workflows"
+
+
+def source(name: str) -> str:
+ return (WORKFLOWS / name).read_text()
+
+
+def test_driver_stable_publish_gate_and_workflow_name_are_frozen():
+ driver = source("cd-rust-cua-driver.yml")
+ assert driver.startswith('name: "CD: Cua Driver (cross-platform)"')
+ assert "if: github.event_name == 'workflow_dispatch' && inputs.publish == true" in driver
+ sdk = source("cd-py-cua-driver.yml")
+ assert 'workflows: ["CD: Cua Driver (cross-platform)"]' in sdk
+
+
+def test_lume_stable_publish_gate_remains_tag_only():
+ lume = source("cd-swift-lume.yml")
+ assert "if: startsWith(github.ref, 'refs/tags/lume-v')" in lume
+ assert (
+ "BUNDLE_VERSION: ${{ inputs.bundle_version || steps.set_version.outputs.version }}" in lume
+ )
+
+
+def test_driver_nightly_reuses_builder_without_stable_state_mutation():
+ nightly = source("nightly-cua-driver.yml")
+ assert "uses: ./.github/workflows/cd-rust-cua-driver.yml" in nightly
+ assert "channel: nightly" in nightly
+ assert "--create-if-missing" in nightly
+ assert "--prerelease" in nightly
+ assert "--make-latest" not in nightly
+ assert "update_cua_driver_installer_version.py" not in nightly
+ assert ".github/release-state" not in nightly
+ assert "Collect PR-first attribution and render nightly body" in nightly
+ assert "GH_TOKEN: ${{ github.token }}" in nightly
+ assert "needs.plan.outputs.attribution_base_tag" in nightly
+ assert "issues: read" in nightly
+ assert "pull-requests: read" in nightly
+
+
+def test_lume_nightly_reuses_notarized_builder_and_never_becomes_latest():
+ nightly = source("nightly-lume.yml")
+ assert "uses: ./.github/workflows/cd-swift-lume.yml" in nightly
+ assert "bundle_version: ${{ needs.plan.outputs.bundle_version }}" in nightly
+ assert "--create-if-missing" in nightly
+ assert "--prerelease" in nightly
+ assert "--make-latest" not in nightly
+ assert "Collect PR-first attribution and render nightly body" in nightly
+ assert "GH_TOKEN: ${{ github.token }}" in nightly
+ assert "needs.plan.outputs.attribution_base_tag" in nightly
+ assert "issues: read" in nightly
+ assert "pull-requests: read" in nightly
+
+
+def test_planner_requires_main_ancestry_and_preserves_immutable_evidence():
+ planner = source("nightly-component-plan.yml")
+ assert "SOURCE_SHA: ${{ inputs.source_sha }}" in planner
+ assert 'git merge-base --is-ancestor "$SOURCE_SHA" origin/main' in planner
+ assert "fetch-depth: 0" in planner
+ assert "nightly-plan-${{ inputs.component }}" in planner
+ assert "attribution_base_tag" in planner
+ assert "cancel-in-progress: false" in source("nightly-cua-driver.yml")
+ assert "cancel-in-progress: false" in source("nightly-lume.yml")
+
+
+def test_registered_builder_workflows_match_the_orchestrators():
+ components = json.loads((ROOT / ".github/releases/components.json").read_text())["components"]
+ assert components["cua-driver-rs"]["builderWorkflow"] == (
+ ".github/workflows/cd-rust-cua-driver.yml"
+ )
+ assert components["lume"]["builderWorkflow"] == ".github/workflows/cd-swift-lume.yml"
+ for component in components.values():
+ assert (ROOT / component["builderWorkflow"]).is_file()
+
+
+def test_driver_nightly_version_is_staged_in_each_platform_builder():
+ driver = source("cd-rust-cua-driver.yml")
+ command = "release_channels.py apply-version --component cua-driver-rs --version"
+ assert driver.count(command) == 3
+ assert "inputs.source_ref || github.workflow_sha" in driver
+ assert 'BUNDLE_VERSION="${VERSION%%-*}"' in driver
+ assert 'CFBundleShortVersionString -string "$BUNDLE_VERSION"' in driver
+ assert 'CFBundleVersion -string "$BUNDLE_VERSION"' in driver
+
+
+def test_nightly_workflow_names_cannot_trigger_stable_driver_sdk_publish():
+ for name in ("nightly-cua-driver.yml", "nightly-lume.yml"):
+ first_line = source(name).splitlines()[0]
+ assert "CD: Cua Driver (cross-platform)" not in first_line
diff --git a/.github/scripts/tests/test_release_attribution.py b/.github/scripts/tests/test_release_attribution.py
index b610c7be5e..28060efe7f 100644
--- a/.github/scripts/tests/test_release_attribution.py
+++ b/.github/scripts/tests/test_release_attribution.py
@@ -153,8 +153,7 @@ def test_release_notes_dedupe_contributors_across_roles_and_login_case():
"repository": "trycua/cua",
"tag": "cua-driver-rs-v0.13.1",
"compareUrl": (
- "https://github.com/trycua/cua/compare/"
- "cua-driver-rs-v0.12.6...cua-driver-rs-v0.13.1"
+ "https://github.com/trycua/cua/compare/cua-driver-rs-v0.12.6...cua-driver-rs-v0.13.1"
),
"visualRequested": False,
"changes": [
@@ -183,8 +182,7 @@ def test_cua_driver_release_footer_explains_github_prerelease_label():
"repository": "trycua/cua",
"tag": "cua-driver-rs-v0.17.0",
"compareUrl": (
- "https://github.com/trycua/cua/compare/"
- "cua-driver-rs-v0.16.0...cua-driver-rs-v0.17.0"
+ "https://github.com/trycua/cua/compare/cua-driver-rs-v0.16.0...cua-driver-rs-v0.17.0"
),
"visualRequested": False,
"changes": [],
@@ -491,6 +489,85 @@ def test_manifest_is_pr_first_and_renders_deterministically(tmp_path: Path):
assert preflight["sha"] == commit_sha
+def test_nightly_manifest_attributes_maintenance_prs_without_a_versioned_changelog(
+ tmp_path: Path,
+):
+ git(tmp_path, "init")
+ git(tmp_path, "config", "user.name", "Release Test")
+ git(tmp_path, "config", "user.email", "[email protected]")
+ product = tmp_path / "libs/cua-driver/rust"
+ product.mkdir(parents=True)
+ (product / "CHANGELOG.md").write_text("# Changelog\n")
+ (product / "driver.txt").write_text("initial\n")
+ git(tmp_path, "add", ".")
+ git(tmp_path, "commit", "-m", "chore: seed fixture")
+ git(tmp_path, "tag", "cua-driver-rs-v0.8.1")
+
+ (product / "driver.txt").write_text("documented\n")
+ git(tmp_path, "add", ".")
+ git(tmp_path, "commit", "-m", "docs(driver): explain nightly sessions")
+ commit_sha = git(tmp_path, "rev-parse", "HEAD")
+
+ config = {
+ "bots": [],
+ "coauthorOverrides": {},
+ "ignoredCoauthorEmails": [],
+ "identityOverrides": {},
+ "internalHandles": [],
+ "optOutHandles": [],
+ }
+ manifest = build_manifest(
+ repo_root=tmp_path,
+ repository="trycua/cua",
+ product="cua-driver-rs",
+ display_name="Cua Driver",
+ version="0.8.2-nightly.20260812.42",
+ tag="nightly-cua-driver-rs-v0.8.2-nightly.20260812.42",
+ release_ref=commit_sha,
+ previous_tag="cua-driver-rs-v0.8.1",
+ expected_sha=commit_sha,
+ paths=("libs/cua-driver",),
+ changelog_path=product / "CHANGELOG.md",
+ attribution_config=config,
+ github=FakeGitHub(commit_sha),
+ channel="nightly",
+ )
+
+ assert manifest["channel"] == "nightly"
+ assert manifest["compareUrl"].endswith(f"/compare/cua-driver-rs-v0.8.1...{commit_sha}")
+ assert manifest["visualRequested"] is False
+ assert manifest["changes"][0]["type"] == "docs"
+ assert manifest["changes"][0]["pr"] == 12
+ assert {item["login"] for item in manifest["contributors"]} == {
+ "bug-reporter",
+ "pr-author",
+ "source-author",
+ }
+ schema = json.loads((REPO_ROOT / ".github/release-manifest.schema.json").read_text())
+ validator = Draft202012Validator(schema, format_checker=None)
+ validator.validate(manifest)
+ stable_shaped = dict(manifest)
+ stable_shaped.pop("channel")
+ assert any("is not one of" in error.message for error in validator.iter_errors(stable_shaped))
+
+ with pytest.raises(ReleaseError, match="no releasing pull requests"):
+ build_manifest(
+ repo_root=tmp_path,
+ repository="trycua/cua",
+ product="cua-driver-rs",
+ display_name="Cua Driver",
+ version="0.8.2",
+ tag="cua-driver-rs-v0.8.2",
+ release_ref=commit_sha,
+ previous_tag="cua-driver-rs-v0.8.1",
+ expected_sha=commit_sha,
+ paths=("libs/cua-driver",),
+ changelog_path=product / "CHANGELOG.md",
+ attribution_config=config,
+ github=FakeGitHub(commit_sha),
+ )
+
+
def test_unresolved_human_coauthor_fails_closed():
commit = CommitRecord(
"deadbeef",
diff --git a/.github/scripts/tests/test_release_channel_installers.py b/.github/scripts/tests/test_release_channel_installers.py
new file mode 100644
index 0000000000..3b1b5376d5
--- /dev/null
+++ b/.github/scripts/tests/test_release_channel_installers.py
@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import subprocess
+import textwrap
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[3]
+LUME_INSTALLER = ROOT / "libs/lume/scripts/install.sh"
+
+
+def shell_function(source: str, name: str) -> str:
+ start = source.index(f"{name}() {{")
+ depth = 0
+ for index in range(start, len(source)):
+ if source[index] == "{":
+ depth += 1
+ elif source[index] == "}":
+ depth -= 1
+ if depth == 0:
+ return source[start : index + 1]
+ raise AssertionError(f"could not find end of {name}")
+
+
+def run_lume_resolver(tmp_path: Path, version: str, baked: str = "") -> subprocess.CompletedProcess[str]:
+ source = LUME_INSTALLER.read_text()
+ script = tmp_path / "lume-resolver.sh"
+ script.write_text(
+ textwrap.dedent(
+ f"""\
+ set -e
+ RED=""
+ NORMAL=""
+ BOLD=""
+ GITHUB_REPO="trycua/cua"
+ LUME_VERSION="{version}"
+ LUME_BAKED_VERSION="{baked}"
+ {shell_function(source, "get_latest_lume_tag")}
+ get_latest_lume_tag
+ """
+ )
+ )
+ return subprocess.run(["bash", str(script)], capture_output=True, text=True)
+
+
+ ("value", "expected"),
+ [
+ ("1.2.3", "lume-v1.2.3"),
+ ("lume-v1.2.3", "lume-v1.2.3"),
+ (
+ "1.2.4-nightly.20260812.42",
+ "nightly-lume-v1.2.4-nightly.20260812.42",
+ ),
+ (
+ "nightly-lume-v1.2.4-nightly.20260812.42",
+ "nightly-lume-v1.2.4-nightly.20260812.42",
+ ),
+ ],
+)
+def test_lume_exact_pin_selects_only_its_stable_or_nightly_namespace(
+ tmp_path: Path, value: str, expected: str
+):
+ result = run_lume_resolver(tmp_path, value)
+ assert result.returncode == 0, result.stderr
+ assert result.stdout.strip() == expected
+
+
+ "value",
+ [
+ "nightly-cua-driver-rs-v1.2.4-nightly.20260812.42",
+ "lume-v1.2.4-nightly.20260812.42",
+ "nightly-lume-v1.2.4-rc.1",
+ "1.2",
+ ],
+)
+def test_lume_exact_pin_rejects_cross_component_and_malformed_tags(
+ tmp_path: Path, value: str
+):
+ result = run_lume_resolver(tmp_path, value)
+ assert result.returncode != 0
+ assert "exact x.y.z stable version or canonical nightly tag" in result.stderr
+
+
+def test_lume_stable_api_filter_is_exact_draft_aware_and_nightly_blind():
+ body = shell_function(LUME_INSTALLER.read_text(), "get_latest_lume_tag")
+ assert "tag ~ /^lume-v[0-9]+\\.[0-9]+\\.[0-9]+$/" in body
+ assert '"draft"[[:space:]]*:[[:space:]]*false' in body
+ assert "nightly-lume" not in body.split('if [ -n "$LUME_BAKED_VERSION" ]', 1)[1]
+
+
+def test_driver_download_uses_the_resolved_tag_not_the_stable_prefix():
+ source = (ROOT / "libs/cua-driver/scripts/_install-rust.sh").read_text()
+ body = shell_function(source, "download_release_tarball")
+ assert "releases/download/${TAG}/" in body
+ assert "releases/download/${TAG_PREFIX}" not in body
+
+
+def test_windows_driver_has_disjoint_exact_pin_grammars():
+ source = (ROOT / "libs/cua-driver/scripts/install.ps1").read_text(encoding="utf-8-sig")
+ assert '$NightlyTagPrefix = "nightly-cua-driver-rs-v"' in source
+ stable = re.search(
+ r"\^\(\?:cua-driver-rs-v\|v\)\?\(\[0-9\]\+.*?\$", source
+ )
+ assert stable
+ assert "^nightly-cua-driver-rs-v" in source
+ assert "releases/download/$Script:CuaDriverRsReleaseTag/" in source
diff --git a/.github/scripts/tests/test_release_channels.py b/.github/scripts/tests/test_release_channels.py
new file mode 100644
index 0000000000..a1840ff1c8
--- /dev/null
+++ b/.github/scripts/tests/test_release_channels.py
@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+from jsonschema import Draft202012Validator
+
+import release_channels
+from release_channels import (
+ ChannelError,
+ apply_version,
+ build_manifest,
+ component_descriptor,
+ derive_nightly_version,
+ format_tag,
+ load_registry,
+ parse_tag,
+ plan_nightly,
+ render_nightly_body,
+)
+
+
+ROOT = Path(__file__).resolve().parents[3]
+REGISTRY = ROOT / ".github/releases/components.json"
+
+
+def git(root: Path, *args: str) -> str:
+ return subprocess.run(
+ ["git", *args], cwd=root, check=True, text=True, capture_output=True
+ ).stdout.strip()
+
+
+def test_registry_matches_release_please_and_channel_prefixes_are_disjoint():
+ schema = json.loads((ROOT / ".github/releases/component.schema.json").read_text())
+ Draft202012Validator(schema).validate(json.loads(REGISTRY.read_text()))
+ registry = load_registry(REGISTRY, root=ROOT)
+ assert set(registry["components"]) == {"cua-driver-rs", "lume"}
+ all_prefixes = {
+ component[key]
+ for component in registry["components"].values()
+ for key in ("stableTagPrefix", "nightlyTagPrefix")
+ }
+ assert len(all_prefixes) == 4
+
+
+ ("component_name", "stable", "nightly"),
+ [
+ (
+ "cua-driver-rs",
+ "cua-driver-rs-v1.2.3",
+ "nightly-cua-driver-rs-v1.2.3-nightly.20260812.42",
+ ),
+ ("lume", "lume-v1.2.3", "nightly-lume-v1.2.3-nightly.20260812.42"),
+ ],
+)
+def test_strict_tag_grammars_do_not_cross_channels(component_name, stable, nightly):
+ component = component_descriptor(component_name, REGISTRY, root=ROOT)
+ assert parse_tag(component, "stable", stable) == "1.2.3"
+ assert parse_tag(component, "nightly", nightly) == "1.2.3-nightly.20260812.42"
+ with pytest.raises(ChannelError):
+ parse_tag(component, "stable", nightly)
+ with pytest.raises(ChannelError):
+ parse_tag(component, "nightly", stable)
+
+
+ "value",
+ [
+ "1.2.3-nightly.20261301.1",
+ "1.2.3-nightly.20260812.0",
+ "1.2.3-nightly.20260812.latest",
+ "01.2.3-nightly.20260812.1",
+ "1.2.3-beta.1",
+ ],
+)
+def test_nightly_grammar_rejects_noncanonical_versions(value):
+ with pytest.raises(ChannelError):
+ release_channels.nightly_version(value)
+
+
+def test_derivation_increments_patch_and_is_deterministic():
+ assert derive_nightly_version("0.19.3", "20260812", "3097") == ("0.19.4-nightly.20260812.3097")
+
+
+def copy_version_fixture(tmp_path: Path, component_name: str) -> tuple[Path, Path]:
+ registry = json.loads(REGISTRY.read_text())
+ wanted = {
+ "release-please-config.json",
+ ".release-please-manifest.json",
+ }
+ for component in registry["components"].values():
+ wanted.update(
+ {
+ component["versionAuthorityFile"],
+ component["changelog"],
+ component["builderWorkflow"],
+ }
+ )
+ for site in component["buildVersionSites"]:
+ wanted.add(site["path"])
+ if site["kind"] == "cargo-workspace-lock":
+ wanted.add(site["manifestPath"])
+ manifest_parent = ROOT / Path(site["manifestPath"]).parent
+ for package_manifest in manifest_parent.glob("crates/*/Cargo.toml"):
+ wanted.add(str(package_manifest.relative_to(ROOT)))
+ for relative in wanted:
+ source = ROOT / relative
+ destination = tmp_path / relative
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(source, destination)
+ registry_path = tmp_path / ".github/releases/components.json"
+ registry_path.parent.mkdir(parents=True, exist_ok=True)
+ registry_path.write_text(json.dumps(registry))
+ return registry_path, tmp_path
+
+
+def test_driver_version_staging_updates_only_declared_build_sites(tmp_path: Path):
+ registry, root = copy_version_fixture(tmp_path, "cua-driver-rs")
+ changed = apply_version(
+ "cua-driver-rs",
+ "0.19.4-nightly.20260812.3097",
+ registry_path=registry,
+ root=root,
+ )
+ assert set(changed) == {
+ "libs/cua-driver/rust/VERSION",
+ "libs/cua-driver/rust/Cargo.toml",
+ "libs/cua-driver/rust/Cargo.lock",
+ "libs/cua-driver/rust/Skills/cua-driver/SKILL.md",
+ }
+ assert (root / "libs/cua-driver/rust/VERSION").read_text().strip().endswith(".3097")
+ lock = (root / "libs/cua-driver/rust/Cargo.lock").read_text()
+ assert 'name = "cua-driver"\nversion = "0.19.4-nightly.20260812.3097"' in lock
+ assert 'name = "cursor-overlay"\nversion = "0.19.4-nightly.20260812.3097"' in lock
+ assert 'name = "serde"\nversion = "0.19.4-nightly.20260812.3097"' not in lock
+
+
+def test_lume_version_staging_preserves_stable_installer_default(tmp_path: Path):
+ registry, root = copy_version_fixture(tmp_path, "lume")
+ stable_installer = ROOT / "libs/lume/scripts/install.sh"
+ destination = root / "libs/lume/scripts/install.sh"
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(stable_installer, destination)
+ before = destination.read_text()
+ apply_version(
+ "lume",
+ "0.5.4-nightly.20260812.3097",
+ registry_path=registry,
+ root=root,
+ )
+ assert "0.5.4-nightly.20260812.3097" in (root / "libs/lume/src/Main.swift").read_text()
+ assert destination.read_text() == before
+
+
+def test_first_nightly_plan_is_reproducible_and_uses_stable_attribution_base(
+ monkeypatch: pytest.MonkeyPatch,
+):
+ source_sha = "a" * 40
+
+ def fake_git(_root, command, *args):
+ if command == "rev-list":
+ assert args == ("-n", "1", "lume-v0.5.3")
+ return "d" * 40
+ assert command == "merge-base"
+ assert args == ("--is-ancestor", "d" * 40, source_sha)
+ return ""
+
+ monkeypatch.setattr(release_channels, "_git", fake_git)
+ plan = plan_nightly(
+ "lume",
+ source_sha,
+ "20260812",
+ "42",
+ [],
+ registry_path=REGISTRY,
+ root=ROOT,
+ )
+ assert plan["shouldBuild"] is True
+ assert plan["reason"] == "first-nightly"
+ assert plan["tag"] == "nightly-lume-v0.5.4-nightly.20260812.42"
+ assert plan["bundleVersion"] == "0.5.4"
+ assert plan["previousNightlyTag"] is None
+ assert plan["attributionBaseTag"] == "lume-v0.5.3"
+
+
+def test_plan_skips_an_identical_published_source(monkeypatch: pytest.MonkeyPatch):
+ source_sha = "b" * 40
+ monkeypatch.setattr(release_channels, "_git", lambda *_args: source_sha)
+ plan = plan_nightly(
+ "lume",
+ source_sha,
+ "20260812",
+ "43",
+ [
+ {
+ "tag_name": "nightly-lume-v0.5.4-nightly.20260811.41",
+ "draft": False,
+ "published_at": "2026-08-11T04:43:00Z",
+ }
+ ],
+ registry_path=REGISTRY,
+ root=ROOT,
+ )
+ assert plan["shouldBuild"] is False
+ assert plan["reason"] == "source-unchanged"
+
+
+def test_plan_builds_only_for_declared_relevant_changes(monkeypatch: pytest.MonkeyPatch):
+ previous_sha = "b" * 40
+ source_sha = "c" * 40
+
+ def fake_git(_root, command, *args):
+ if command == "rev-list":
+ return previous_sha
+ if command == "merge-base":
+ assert args == ("--is-ancestor", previous_sha, source_sha)
+ return ""
+ assert command == "diff"
+ assert "libs/cua-driver" in args
+ return "libs/cua-driver/rust/crates/cua-driver/src/main.rs"
+
+ monkeypatch.setattr(release_channels, "_git", fake_git)
+ plan = plan_nightly(
+ "cua-driver-rs",
+ source_sha,
+ "20260812",
+ "44",
+ [
+ {
+ "tag_name": "nightly-cua-driver-rs-v0.19.4-nightly.20260811.41",
+ "draft": False,
+ "published_at": "2026-08-11T04:17:00Z",
+ }
+ ],
+ registry_path=REGISTRY,
+ root=ROOT,
+ )
+ assert plan["shouldBuild"] is True
+ assert plan["reason"] == "relevant-changes"
+ assert plan["previousNightlyTag"] == ("nightly-cua-driver-rs-v0.19.4-nightly.20260811.41")
+ assert plan["attributionBaseTag"] == plan["previousNightlyTag"]
+
+
+def test_nightly_manifest_reuses_pr_attribution_and_renders_contributors(tmp_path: Path):
+ registry, root = copy_version_fixture(tmp_path, "lume")
+ git(root, "init")
+ git(root, "config", "user.name", "Release Test")
+ git(root, "config", "user.email", "[email protected]")
+ git(root, "add", ".")
+ git(root, "commit", "-m", "chore: seed fixture")
+ git(root, "tag", "lume-v0.5.3")
+ main = root / "libs/lume/src/Main.swift"
+ main.write_text(main.read_text() + "\n// Nightly install notes\n")
+ git(root, "add", ".")
+ git(root, "commit", "-m", "docs(lume): explain nightly installation")
+ source_sha = git(root, "rev-parse", "HEAD")
+
+ class NightlyGitHub:
+ def pulls_for_commit(self, repository: str, commit_sha: str):
+ assert repository == "trycua/cua"
+ assert commit_sha == source_sha
+ return [{"number": 42, "merge_commit_sha": commit_sha, "merged_at": "now"}]
+
+ def pull(self, repository: str, number: int):
+ assert repository == "trycua/cua"
+ assert number == 42
+ return {
+ "number": 42,
+ "user": {"login": "nightly-contributor"},
+ "author_association": "NONE",
+ "body": "",
+ "labels": [],
+ }
+
+ def issue(self, repository: str, number: int):
+ raise AssertionError("the nightly fixture does not reference issues")
+
+ assets = root / "artifacts"
+ assets.mkdir()
+ (assets / "artifact.tar.gz").write_bytes(b"nightly")
+ version = "0.5.4-nightly.20260812.42"
+ component = component_descriptor("lume", registry, root=root)
+ manifest = build_manifest(
+ "lume",
+ version,
+ format_tag(component, "nightly", version),
+ source_sha,
+ "lume-v0.5.3",
+ assets,
+ repository="trycua/cua",
+ registry_path=registry,
+ root=root,
+ attribution_config_path=ROOT / ".github/release-attribution-config.json",
+ github=NightlyGitHub(),
+ )
+ assert manifest["channel"] == "nightly"
+ schema = json.loads((ROOT / ".github/release-manifest.schema.json").read_text())
+ Draft202012Validator(schema, format_checker=None).validate(manifest)
+ assert manifest["changes"][0]["type"] == "docs"
+ assert manifest["contributors"] == [
+ {
+ "login": "nightly-contributor",
+ "roles": ["author"],
+ "external": True,
+ }
+ ]
+ assert manifest["assets"][0]["sha256"] == (
+ "2a3b62b53ddb9f167b63d22202a360811ba78df015021f704d01ee9abad4169c"
+ )
+ body = render_nightly_body(manifest)
+ assert "LUME_VERSION=nightly-lume-v0.5.4-nightly.20260812.42" in body
+ assert "never replace stable" in body
+ assert "[#42](https://github.com/trycua/cua/pull/42)" in body
+ assert body.count("@nightly-contributor") == 2
diff --git a/.github/scripts/tests/test_validate_release_versions.py b/.github/scripts/tests/test_validate_release_versions.py
index 0a8ab5a44d..f44d42f82a 100644
--- a/.github/scripts/tests/test_validate_release_versions.py
+++ b/.github/scripts/tests/test_validate_release_versions.py
@@ -19,7 +19,11 @@ def copy_release_sources(destination: Path) -> None:
source = REPO_ROOT / relative
target = destination / relative
target.parent.mkdir(parents=True, exist_ok=True)
- shutil.copytree(source, target)
+ shutil.copytree(
+ source,
+ target,
+ ignore=shutil.ignore_patterns(".build", ".swiftpm", "target", "node_modules"),
+ )
for product in ("cua-driver", "lume"):
docs = f"docs/content/docs/reference/{product}"
shutil.copytree(REPO_ROOT / docs, destination / docs)
diff --git a/.github/workflows/cd-rust-cua-driver.yml b/.github/workflows/cd-rust-cua-driver.yml
index 73b23b1bea..9efe3dd81f 100644
--- a/.github/workflows/cd-rust-cua-driver.yml
+++ b/.github/workflows/cd-rust-cua-driver.yml
@@ -11,6 +11,43 @@ name: "CD: Cua Driver (cross-platform)"
# without needing to unpack a directory structure first.
on:
+ workflow_call:
+ inputs:
+ version:
+ description: "Exact artifact version"
+ required: true
+ type: string
+ channel:
+ description: "Release channel"
+ required: false
+ default: stable
+ type: string
+ source_ref:
+ description: "Exact source SHA or immutable ref to build"
+ required: true
+ type: string
+ notarize:
+ description: "Codesign and notarize macOS artifacts"
+ required: false
+ default: true
+ type: boolean
+ secrets:
+ APPLICATION_CERT_BASE64:
+ required: false
+ CERT_PASSWORD:
+ required: false
+ APPLE_ID:
+ required: false
+ APP_SPECIFIC_PASSWORD:
+ required: false
+ DEVELOPER_NAME:
+ required: false
+ TEAM_ID:
+ required: false
+ RELEASE_APP_ID:
+ required: false
+ RELEASE_APP_PRIVATE_KEY:
+ required: false
push:
tags:
- "cua-driver-rs-v*"
@@ -52,7 +89,7 @@ jobs:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ ref: ${{ inputs.source_ref || github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
- name: Check out release control tooling
uses: actions/checkout@v4
@@ -142,12 +179,15 @@ jobs:
# RemoteDesktop/libei input is pure Rust plus libxkbcommon and ships
# in these portable release binaries.
apt-get install -y --no-install-recommends \
- git ca-certificates curl build-essential pkg-config \
+ git ca-certificates curl python3 build-essential pkg-config \
libx11-dev libxi-dev libxtst-dev libxext-dev libwayland-dev \
libxkbcommon-dev
- uses: actions/checkout@v4
with:
- ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ ref: ${{ inputs.source_ref || github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ - name: Stage nightly artifact version
+ if: inputs.channel == 'nightly'
+ run: python3 .github/scripts/release_channels.py apply-version --component cua-driver-rs --version "${{ inputs.version }}"
- uses: actions/setup-node@v4
with:
node-version: "22"
@@ -157,7 +197,9 @@ jobs:
id: version
shell: bash
run: |
- if [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
+ if [[ "${{ inputs.channel }}" == "nightly" ]]; then
+ VERSION="${{ inputs.version }}"
+ elif [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
VERSION="${GITHUB_REF#refs/tags/cua-driver-rs-v}"
else
VERSION="${{ inputs.version }}"
@@ -232,7 +274,11 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
- ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ ref: ${{ inputs.source_ref || github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ - name: Stage nightly artifact version
+ if: inputs.channel == 'nightly'
+ shell: bash
+ run: python .github/scripts/release_channels.py apply-version --component cua-driver-rs --version "${{ inputs.version }}"
- uses: actions/setup-node@v4
with:
node-version: "22"
@@ -242,7 +288,9 @@ jobs:
id: version
shell: bash
run: |
- if [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
+ if [[ "${{ inputs.channel }}" == "nightly" ]]; then
+ VERSION="${{ inputs.version }}"
+ elif [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
VERSION="${GITHUB_REF#refs/tags/cua-driver-rs-v}"
else
VERSION="${{ inputs.version }}"
@@ -367,7 +415,7 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
- ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ ref: ${{ inputs.source_ref || github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
- uses: actions/setup-node@v4
with:
node-version: "22"
@@ -435,7 +483,10 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
- ref: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ ref: ${{ inputs.source_ref || github.event_name == 'workflow_dispatch' && inputs.publish && format('refs/tags/cua-driver-rs-v{0}', inputs.version) || github.ref }}
+ - name: Stage nightly artifact version
+ if: inputs.channel == 'nightly'
+ run: python3 .github/scripts/release_channels.py apply-version --component cua-driver-rs --version "${{ inputs.version }}"
- uses: actions/setup-node@v4
with:
node-version: "22"
@@ -445,7 +496,9 @@ jobs:
id: version
shell: bash
run: |
- if [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
+ if [[ "${{ inputs.channel }}" == "nightly" ]]; then
+ VERSION="${{ inputs.version }}"
+ elif [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
VERSION="${GITHUB_REF#refs/tags/cua-driver-rs-v}"
else
VERSION="${{ inputs.version }}"
@@ -593,9 +646,10 @@ jobs:
# checked in. Without this the in-tree Info.plist's
# CFBundleShortVersionString drifts from the release tag on
# every cut. CodeRabbit #4.
- plutil -replace CFBundleShortVersionString -string "$VERSION" \
+ BUNDLE_VERSION="${VERSION%%-*}"
+ plutil -replace CFBundleShortVersionString -string "$BUNDLE_VERSION" \
release/CuaDriver.app/Contents/Info.plist
- plutil -replace CFBundleVersion -string "$VERSION" \
+ plutil -replace CFBundleVersion -string "$BUNDLE_VERSION" \
release/CuaDriver.app/Contents/Info.plist
# Remove the .gitkeep we use in source control — it's not
# part of the runtime bundle.
@@ -689,12 +743,14 @@ jobs:
# immutable tag that predates this script. Candidate artifacts still
# come from that exact tag; the release control comes from the commit
# that defined this workflow run.
- ref: ${{ github.workflow_sha }}
+ ref: ${{ inputs.source_ref || github.workflow_sha }}
- name: Determine version
id: version
run: |
- if [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
+ if [[ "${{ inputs.channel }}" == "nightly" ]]; then
+ VERSION="${{ inputs.version }}"
+ elif [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
VERSION="${GITHUB_REF#refs/tags/cua-driver-rs-v}"
else
VERSION="${{ inputs.version }}"
@@ -724,7 +780,7 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
- ref: ${{ github.workflow_sha }}
+ ref: ${{ inputs.source_ref || github.workflow_sha }}
- uses: actions/setup-node@v4
with:
node-version: "22"
@@ -734,7 +790,9 @@ jobs:
- name: Determine version
id: version
run: |
- if [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
+ if [[ "${{ inputs.channel }}" == "nightly" ]]; then
+ VERSION="${{ inputs.version }}"
+ elif [[ "$GITHUB_REF" == refs/tags/cua-driver-rs-v* ]]; then
VERSION="${GITHUB_REF#refs/tags/cua-driver-rs-v}"
else
VERSION="${{ inputs.version }}"
diff --git a/.github/workflows/cd-swift-lume.yml b/.github/workflows/cd-swift-lume.yml
index 0b98f5c467..2f9fe2651c 100644
--- a/.github/workflows/cd-swift-lume.yml
+++ b/.github/workflows/cd-swift-lume.yml
@@ -16,6 +16,21 @@ on:
description: "Version to notarize"
required: true
type: string
+ channel:
+ description: "Release channel"
+ required: false
+ default: stable
+ type: string
+ source_ref:
+ description: "Exact source SHA or immutable ref to build"
+ required: false
+ default: ""
+ type: string
+ bundle_version:
+ description: "Numeric Apple bundle/package version"
+ required: false
+ default: ""
+ type: string
secrets:
APPLICATION_CERT_BASE64:
required: true
@@ -60,6 +75,12 @@ jobs:
version: ${{ steps.set_version.outputs.version }}
steps:
- uses: actions/checkout@v4
+ with:
+ ref: ${{ inputs.source_ref || github.ref }}
+
+ - name: Stage nightly artifact version
+ if: inputs.channel == 'nightly'
+ run: python3 .github/scripts/release_channels.py apply-version --component lume --version "${{ inputs.version }}"
- name: Select Xcode 16.3
run: |
@@ -93,7 +114,14 @@ jobs:
echo "Tag/input version $VERSION does not match libs/lume/VERSION ($SOURCE_VERSION)"
exit 1
fi
- python3 .github/scripts/validate_release_versions.py --product lume
+ if [[ "${{ inputs.channel }}" == "nightly" ]]; then
+ python3 .github/scripts/release_channels.py parse-tag \
+ --component lume \
+ --channel nightly \
+ --tag "nightly-lume-v${VERSION}" >/dev/null
+ else
+ python3 .github/scripts/validate_release_versions.py --product lume
+ fi
# Set output for later steps
echo "version=$VERSION" >> $GITHUB_OUTPUT
@@ -163,6 +191,7 @@ jobs:
CERT_APPLICATION_NAME: "Developer ID Application: ${{ secrets.DEVELOPER_NAME }} (${{ secrets.TEAM_ID }})"
CERT_INSTALLER_NAME: "Developer ID Installer: ${{ secrets.DEVELOPER_NAME }} (${{ secrets.TEAM_ID }})"
VERSION: ${{ steps.set_version.outputs.version }}
+ BUNDLE_VERSION: ${{ inputs.bundle_version || steps.set_version.outputs.version }}
working-directory: ./libs/lume
run: |
# Minimal debug information
diff --git a/.github/workflows/nightly-component-plan.yml b/.github/workflows/nightly-component-plan.yml
new file mode 100644
index 0000000000..3b8716196e
--- /dev/null
+++ b/.github/workflows/nightly-component-plan.yml
@@ -0,0 +1,100 @@
+name: "Nightly: component plan"
+
+on:
+ workflow_call:
+ inputs:
+ component:
+ description: "Registered component name"
+ required: true
+ type: string
+ source_sha:
+ description: "Exact source commit"
+ required: true
+ type: string
+ force:
+ description: "Build even when no relevant paths changed"
+ required: false
+ default: false
+ type: boolean
+ outputs:
+ should_build:
+ value: ${{ jobs.plan.outputs.should_build }}
+ version:
+ value: ${{ jobs.plan.outputs.version }}
+ bundle_version:
+ value: ${{ jobs.plan.outputs.bundle_version }}
+ tag:
+ value: ${{ jobs.plan.outputs.tag }}
+ previous_tag:
+ value: ${{ jobs.plan.outputs.previous_tag }}
+ attribution_base_tag:
+ value: ${{ jobs.plan.outputs.attribution_base_tag }}
+ reason:
+ value: ${{ jobs.plan.outputs.reason }}
+
+permissions:
+ contents: read
+
+jobs:
+ plan:
+ runs-on: ubuntu-latest
+ outputs:
+ should_build: ${{ steps.plan.outputs.shouldBuild }}
+ version: ${{ steps.plan.outputs.version }}
+ bundle_version: ${{ steps.plan.outputs.bundleVersion }}
+ tag: ${{ steps.plan.outputs.tag }}
+ previous_tag: ${{ steps.plan.outputs.previousTag }}
+ attribution_base_tag: ${{ steps.plan.outputs.attributionBaseTag }}
+ reason: ${{ steps.plan.outputs.reason }}
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ ref: ${{ inputs.source_sha }}
+ fetch-depth: 0
+ persist-credentials: false
+
+ - name: Verify source is an exact main commit
+ env:
+ SOURCE_SHA: ${{ inputs.source_sha }}
+ run: |
+ set -euo pipefail
+ test "$(git rev-parse HEAD)" = "$SOURCE_SHA"
+ git fetch --no-tags origin main
+ git merge-base --is-ancestor "$SOURCE_SHA" origin/main
+
+ - name: Fetch published release inventory
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ gh api --paginate --slurp \
+ "repos/${{ github.repository }}/releases?per_page=100" \
+ | jq 'add' > "$RUNNER_TEMP/releases.json"
+
+ - name: Plan immutable nightly
+ id: plan
+ env:
+ COMPONENT: ${{ inputs.component }}
+ FORCE_REQUESTED: ${{ inputs.force }}
+ SOURCE_SHA: ${{ inputs.source_sha }}
+ run: |
+ set -euo pipefail
+ FORCE=()
+ if [[ "$FORCE_REQUESTED" == "true" ]]; then FORCE+=(--force); fi
+ python3 .github/scripts/release_channels.py plan \
+ --component "$COMPONENT" \
+ --source-sha "$SOURCE_SHA" \
+ --date "$(date -u +%Y%m%d)" \
+ --run "${{ github.run_id }}" \
+ --releases "$RUNNER_TEMP/releases.json" \
+ --output "$RUNNER_TEMP/nightly-plan.json" \
+ --github-output "$GITHUB_OUTPUT" \
+ "${FORCE[@]}"
+ cat "$RUNNER_TEMP/nightly-plan.json"
+
+ - name: Preserve plan
+ uses: actions/upload-artifact@v4
+ with:
+ name: nightly-plan-${{ inputs.component }}
+ path: ${{ runner.temp }}/nightly-plan.json
+ if-no-files-found: error
+ retention-days: 30
diff --git a/.github/workflows/nightly-cua-driver.yml b/.github/workflows/nightly-cua-driver.yml
new file mode 100644
index 0000000000..9162d457dc
--- /dev/null
+++ b/.github/workflows/nightly-cua-driver.yml
@@ -0,0 +1,142 @@
+name: "Nightly: Cua Driver"
+
+on:
+ schedule:
+ - cron: "17 4 * * *"
+ workflow_dispatch:
+ inputs:
+ source_sha:
+ description: "Exact main SHA (defaults to the workflow revision)"
+ required: false
+ type: string
+ force:
+ description: "Build even when relevant paths are unchanged"
+ required: false
+ default: false
+ type: boolean
+
+permissions:
+ contents: write
+ issues: read
+ pull-requests: read
+
+concurrency:
+ group: nightly-cua-driver
+ cancel-in-progress: false
+
+jobs:
+ plan:
+ uses: ./.github/workflows/nightly-component-plan.yml
+ with:
+ component: cua-driver-rs
+ source_sha: ${{ inputs.source_sha || github.sha }}
+ force: ${{ inputs.force || false }}
+
+ build:
+ needs: plan
+ if: needs.plan.outputs.should_build == 'true'
+ uses: ./.github/workflows/cd-rust-cua-driver.yml
+ with:
+ version: ${{ needs.plan.outputs.version }}
+ channel: nightly
+ source_ref: ${{ inputs.source_sha || github.sha }}
+ notarize: true
+ secrets: inherit
+
+ publish:
+ needs: [plan, build]
+ if: needs.plan.outputs.should_build == 'true' && needs.build.result == 'success'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ ref: ${{ inputs.source_sha || github.sha }}
+ fetch-depth: 0
+ persist-credentials: false
+
+ - name: Download verified candidate archives
+ uses: actions/download-artifact@v4
+ with:
+ pattern: cua-driver-rs-*
+ path: artifacts
+ merge-multiple: true
+
+ - name: Stage exact nightly assets
+ run: |
+ set -euo pipefail
+ VERSION="${{ needs.plan.outputs.version }}"
+ python3 .github/scripts/release_channels.py apply-version \
+ --component cua-driver-rs --version "$VERSION"
+ mkdir -p release-upload release-metadata
+ find artifacts -type f \( -name "*.tar.gz" -o -name "*.zip" \) \
+ -exec cp {} release-upload/ \;
+ cp libs/cua-driver/scripts/install.sh release-upload/install.sh
+ cp libs/cua-driver/scripts/install.ps1 release-upload/install.ps1
+ cp libs/cua-driver/scripts/_install-rust.sh release-upload/_install-rust.sh
+ cp libs/cua-driver/scripts/uninstall.sh release-upload/uninstall.sh
+ cp libs/cua-driver/scripts/uninstall.ps1 release-upload/uninstall.ps1
+ SKILLS_STAGE="cua-driver-rs-v${VERSION}-skills"
+ mkdir -p "$SKILLS_STAGE"
+ cp -R libs/cua-driver/rust/Skills/cua-driver/. "$SKILLS_STAGE/"
+ tar -czf "release-upload/${SKILLS_STAGE}.tar.gz" "$SKILLS_STAGE"
+ (
+ cd release-upload
+ shasum -a 256 * | sort > checksums.txt
+ )
+
+ - name: Collect PR-first attribution and render nightly body
+ env:
+ GH_TOKEN: ${{ github.token }}
+ SOURCE_SHA: ${{ inputs.source_sha || github.sha }}
+ run: |
+ set -euo pipefail
+ python3 .github/scripts/release_channels.py manifest \
+ --component cua-driver-rs \
+ --version "${{ needs.plan.outputs.version }}" \
+ --tag "${{ needs.plan.outputs.tag }}" \
+ --source-sha "$SOURCE_SHA" \
+ --previous-tag "${{ needs.plan.outputs.attribution_base_tag }}" \
+ --asset-dir release-upload \
+ --repository "${{ github.repository }}" \
+ --output release-metadata/release-manifest.json
+ python3 .github/scripts/release_channels.py render-nightly \
+ --manifest release-metadata/release-manifest.json \
+ --body release-metadata/release-body.md
+ cp release-metadata/release-manifest.json release-upload/
+
+ - name: Preserve nightly evidence
+ uses: actions/upload-artifact@v4
+ with:
+ name: cua-driver-nightly-metadata-${{ needs.plan.outputs.version }}
+ path: release-metadata/
+ if-no-files-found: error
+ retention-days: 90
+
+ - name: Publish immutable nightly release
+ env:
+ GH_TOKEN: ${{ github.token }}
+ SOURCE_SHA: ${{ inputs.source_sha || github.sha }}
+ run: |
+ python3 .github/scripts/github_release.py \
+ --repository "${{ github.repository }}" \
+ --tag "${{ needs.plan.outputs.tag }}" \
+ --sha "$SOURCE_SHA" \
+ --body release-metadata/release-body.md \
+ --asset-dir release-upload \
+ --channel nightly \
+ --create-if-missing \
+ --prerelease
+
+ - name: Verify release visibility and exact assets
+ env:
+ GH_TOKEN: ${{ github.token }}
+ SOURCE_SHA: ${{ inputs.source_sha || github.sha }}
+ run: |
+ python3 .github/scripts/github_release.py \
+ --repository "${{ github.repository }}" \
+ --tag "${{ needs.plan.outputs.tag }}" \
+ --sha "$SOURCE_SHA" \
+ --body release-metadata/release-body.md \
+ --asset-dir release-upload \
+ --channel nightly \
+ --prerelease
diff --git a/.github/workflows/nightly-lume.yml b/.github/workflows/nightly-lume.yml
new file mode 100644
index 0000000000..473d3b923a
--- /dev/null
+++ b/.github/workflows/nightly-lume.yml
@@ -0,0 +1,127 @@
+name: "Nightly: Lume"
+
+on:
+ schedule:
+ - cron: "43 4 * * *"
+ workflow_dispatch:
+ inputs:
+ source_sha:
+ description: "Exact main SHA (defaults to the workflow revision)"
+ required: false
+ type: string
+ force:
+ description: "Build even when relevant paths are unchanged"
+ required: false
+ default: false
+ type: boolean
+
+permissions:
+ contents: write
+ issues: read
+ pull-requests: read
+
+concurrency:
+ group: nightly-lume
+ cancel-in-progress: false
+
+jobs:
+ plan:
+ uses: ./.github/workflows/nightly-component-plan.yml
+ with:
+ component: lume
+ source_sha: ${{ inputs.source_sha || github.sha }}
+ force: ${{ inputs.force || false }}
+
+ build:
+ needs: plan
+ if: needs.plan.outputs.should_build == 'true'
+ uses: ./.github/workflows/cd-swift-lume.yml
+ with:
+ version: ${{ needs.plan.outputs.version }}
+ channel: nightly
+ source_ref: ${{ inputs.source_sha || github.sha }}
+ bundle_version: ${{ needs.plan.outputs.bundle_version }}
+ secrets: inherit
+
+ publish:
+ needs: [plan, build]
+ if: needs.plan.outputs.should_build == 'true' && needs.build.result == 'success'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ ref: ${{ inputs.source_sha || github.sha }}
+ fetch-depth: 0
+ persist-credentials: false
+
+ - name: Download notarized candidate assets
+ uses: actions/download-artifact@v4
+ with:
+ name: lume-release-assets
+ path: release-upload
+
+ - name: Generate checksums
+ run: |
+ set -euo pipefail
+ mkdir -p release-metadata
+ (
+ cd release-upload
+ shasum -a 256 * | sort > checksums.txt
+ )
+
+ - name: Collect PR-first attribution and render nightly body
+ env:
+ GH_TOKEN: ${{ github.token }}
+ SOURCE_SHA: ${{ inputs.source_sha || github.sha }}
+ run: |
+ set -euo pipefail
+ python3 .github/scripts/release_channels.py manifest \
+ --component lume \
+ --version "${{ needs.plan.outputs.version }}" \
+ --tag "${{ needs.plan.outputs.tag }}" \
+ --source-sha "$SOURCE_SHA" \
+ --previous-tag "${{ needs.plan.outputs.attribution_base_tag }}" \
+ --asset-dir release-upload \
+ --repository "${{ github.repository }}" \
+ --output release-metadata/release-manifest.json
+ python3 .github/scripts/release_channels.py render-nightly \
+ --manifest release-metadata/release-manifest.json \
+ --body release-metadata/release-body.md
+ cp release-metadata/release-manifest.json release-upload/
+
+ - name: Preserve nightly evidence
+ uses: actions/upload-artifact@v4
+ with:
+ name: lume-nightly-metadata-${{ needs.plan.outputs.version }}
+ path: release-metadata/
+ if-no-files-found: error
+ retention-days: 90
+
+ - name: Publish immutable nightly release
+ env:
+ GH_TOKEN: ${{ github.token }}
+ SOURCE_SHA: ${{ inputs.source_sha || github.sha }}
+ run: |
+ python3 .github/scripts/github_release.py \
+ --repository "${{ github.repository }}" \
+ --tag "${{ needs.plan.outputs.tag }}" \
+ --sha "$SOURCE_SHA" \
+ --body release-metadata/release-body.md \
+ --asset-dir release-upload \
+ --channel nightly \
+ --create-if-missing \
+ --prerelease
+
+ - name: Verify release visibility and exact assets
+ env:
+ GH_TOKEN: ${{ github.token }}
+ SOURCE_SHA: ${{ inputs.source_sha || github.sha }}
+ run: |
+ python3 .github/scripts/github_release.py \
+ --repository "${{ github.repository }}" \
+ --tag "${{ needs.plan.outputs.tag }}" \
+ --sha "$SOURCE_SHA" \
+ --body release-metadata/release-body.md \
+ --asset-dir release-upload \
+ --channel nightly \
+ --prerelease
diff --git a/docs/content/docs/how-to-guides/driver/install.mdx b/docs/content/docs/how-to-guides/driver/install.mdx
index 84e605288a..a83d8589fd 100644
--- a/docs/content/docs/how-to-guides/driver/install.mdx
+++ b/docs/content/docs/how-to-guides/driver/install.mdx
@@ -92,6 +92,37 @@ cua-driver doctor
`doctor` checks the version, install layout, and telemetry setup on every platform. It also runs platform probes for TCC on macOS, the interactive session on Windows, and AT-SPI plus the display server on Linux.
+## Install an exact nightly
+
+Nightlies are immutable builds of exact `main` commits. They are opt-in and do
+not replace stable update discovery. Copy the full
+`nightly-cua-driver-rs-v…` tag from the component's GitHub release, then pin
+that tag during installation:
+
+<Tabs items={['macOS and Linux', 'Windows']}>
+ <Tab value="macOS and Linux">
+
+```bash
+CUA_DRIVER_RS_VERSION=nightly-cua-driver-rs-v0.19.4-nightly.20260812.123456789 \
+ /bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
+```
+
+ </Tab>
+ <Tab value="Windows">
+
+```powershell
+$env:CUA_DRIVER_RS_VERSION = "nightly-cua-driver-rs-v0.19.4-nightly.20260812.123456789"
+irm https://cua.ai/driver/install.ps1 | iex
+Remove-Item Env:CUA_DRIVER_RS_VERSION
+```
+
+ </Tab>
+</Tabs>
+
+The pin is one-shot: later runs of the ordinary installer return to the baked
+stable release. Exact pins never fall back to another release when an asset is
+missing.
+
## Choose a permission mode
Cua Driver authorizes every agent action inside the native runtime, and the mode is fixed when that runtime starts. An agent cannot change it, and neither can you change it on a running daemon — you restart the daemon with different flags. Decide which mode you want before starting the daemon below.
diff --git a/docs/content/docs/how-to-guides/lume/install-lume.mdx b/docs/content/docs/how-to-guides/lume/install-lume.mdx
index 25040b9d91..bfbb3977db 100644
--- a/docs/content/docs/how-to-guides/lume/install-lume.mdx
+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx
@@ -43,6 +43,21 @@ lume update --apply
The installer no longer creates scheduled auto-updaters. Older `lume-update` cron jobs and
LaunchAgents are removed the next time the installer runs.
+## Install an exact nightly
+
+Nightlies are immutable builds of exact `main` commits. Copy the full
+`nightly-lume-v…` tag from the component's GitHub release and pass it as an
+explicit, one-shot pin:
+
+```bash
+curl -fsSL https://cua.ai/lume/install.sh | \
+ LUME_VERSION=nightly-lume-v0.5.4-nightly.20260812.123456789 bash
+```
+
+Nightlies do not participate in `lume check-update` or stable installer
+discovery. Run the ordinary installer again to return to the baked stable
+release.
+
## Manual installation
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.
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
index 27858cf2e8..6c7c459903 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
@@ -27,12 +27,11 @@
//! ## Fetch source
//!
//! The default fetch URL is the versioned release asset matched to the
-//! binary's own version: `cua-driver-rs-v<v>-skills.tar.gz` from
-//! `https://github.com/trycua/cua/releases/...`. This pins the skill
+//! binary's own version: `cua-driver-rs-v<v>-skills.tar.gz` from the
+//! matching stable or nightly GitHub release tag. This pins the skill
//! content to the binary release so an agent loading the doc knows
//! every example matches the daemon it'll talk to.
//!
-//! `--from <tag>` lets the user pin a different release tag.
//! `--from main` fetches the latest from the `main` branch via the
//! `Skills/cua-driver/` directory (one HTTP call per file — used
//! for bleeding-edge dev validation; not the default).
@@ -66,6 +65,8 @@ use std::fs;
use std::path::{Path, PathBuf};
const SKILL_PACK_NAME: &str = "cua-driver";
+const STABLE_RELEASE_TAG_PREFIX: &str = "cua-driver-rs-v";
+const NIGHTLY_RELEASE_TAG_PREFIX: &str = "nightly-cua-driver-rs-v";
/// Pre-rename name. The skill pack used to install as `cua-driver-rs`
/// (when the Rust port lived at `libs/cua-driver-rs/`). On install /
/// uninstall we sweep this name out of every agent skills dir and the
@@ -541,14 +542,40 @@ fn fetch_into(dest: &Path, from_main: bool, all_platforms: bool) -> Result<()> {
// Versioned release asset.
let version = env!("CARGO_PKG_VERSION");
- let url = format!(
- "https://github.com/trycua/cua/releases/download/cua-driver-rs-v{version}/cua-driver-rs-v{version}-skills.tar.gz"
- );
+ let url = skill_release_url(version);
let bytes = http_get_bytes(&url).with_context(|| format!("GET {url}"))?;
extract_tar_gz(&bytes, dest, all_platforms)?;
Ok(())
}
+fn skill_release_url(version: &str) -> String {
+ let tag_prefix = if is_nightly_version(version) {
+ NIGHTLY_RELEASE_TAG_PREFIX
+ } else {
+ STABLE_RELEASE_TAG_PREFIX
+ };
+ format!(
+ "https://github.com/trycua/cua/releases/download/{tag_prefix}{version}/\
+ {STABLE_RELEASE_TAG_PREFIX}{version}-skills.tar.gz"
+ )
+}
+
+fn is_nightly_version(version: &str) -> bool {
+ let Ok(version) = semver::Version::parse(version) else {
+ return false;
+ };
+ if !version.build.is_empty() {
+ return false;
+ }
+ let parts = version.pre.as_str().split('.').collect::<Vec<_>>();
+ matches!(parts.as_slice(), ["nightly", date, run]
+ if date.len() == 8
+ && date.bytes().all(|byte| byte.is_ascii_digit())
+ && !run.is_empty()
+ && !run.starts_with('0')
+ && run.bytes().all(|byte| byte.is_ascii_digit()))
+}
+
fn http_get_text(url: &str) -> Result<String> {
let resp = ureq::get(url)
.call()
@@ -781,7 +808,7 @@ fn print_path() -> Result<()> {
#[cfg(test)]
mod tests {
- use super::{extract_tar_gz, AgentParent, AGENTS, SKILL_FILES};
+ use super::{extract_tar_gz, skill_release_url, AgentParent, AGENTS, SKILL_FILES};
use std::path::PathBuf;
use tempfile::tempdir;
@@ -798,6 +825,25 @@ mod tests {
));
}
+ #[test]
+ fn stable_skill_pack_uses_the_stable_release_tag() {
+ assert_eq!(
+ skill_release_url("0.19.3"),
+ "https://github.com/trycua/cua/releases/download/\
+ cua-driver-rs-v0.19.3/cua-driver-rs-v0.19.3-skills.tar.gz"
+ );
+ }
+
+ #[test]
+ fn nightly_skill_pack_uses_the_nightly_tag_and_compatible_asset_name() {
+ assert_eq!(
+ skill_release_url("0.19.4-nightly.20260812.3097"),
+ "https://github.com/trycua/cua/releases/download/\
+ nightly-cua-driver-rs-v0.19.4-nightly.20260812.3097/\
+ cua-driver-rs-v0.19.4-nightly.20260812.3097-skills.tar.gz"
+ );
+ }
+
/// Build a gzipped tarball with the entries given as
/// `(path, contents)` pairs. Returns the raw `.tar.gz` bytes.
fn build_tarball(entries: &[(&str, &[u8])]) -> Vec<u8> {
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/version_check.rs b/libs/cua-driver/rust/crates/cua-driver/src/version_check.rs
index 59c306315f..fa14a8f3e0 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/version_check.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/version_check.rs
@@ -578,7 +578,11 @@ pub(crate) fn pick_latest_release(body: &serde_json::Value) -> Option<String> {
if r.get("draft").and_then(|d| d.as_bool()).unwrap_or(false) {
return None;
}
- semver::Version::parse(bare).ok()
+ let version = semver::Version::parse(bare).ok()?;
+ if !version.pre.is_empty() || !version.build.is_empty() {
+ return None;
+ }
+ Some(version)
})
.collect();
versions.sort();
@@ -1045,6 +1049,24 @@ mod tests {
assert_eq!(pick_latest_release(&body).as_deref(), Some("0.1.5"));
}
+ #[test]
+ fn pick_latest_release_rejects_every_nightly_shape() {
+ let body = serde_json::json!([
+ {
+ "tag_name": "nightly-cua-driver-rs-v0.2.1-nightly.20260812.42",
+ "draft": false,
+ "prerelease": true
+ },
+ {
+ "tag_name": "cua-driver-rs-v0.2.1-nightly.20260812.42",
+ "draft": false,
+ "prerelease": true
+ },
+ {"tag_name": "cua-driver-rs-v0.2.0", "draft": false, "prerelease": true},
+ ]);
+ assert_eq!(pick_latest_release(&body).as_deref(), Some("0.2.0"));
+ }
+
#[test]
fn pick_latest_release_returns_none_for_empty_array() {
assert_eq!(pick_latest_release(&serde_json::json!([])), None);
diff --git a/libs/cua-driver/scripts/_install-rust.sh b/libs/cua-driver/scripts/_install-rust.sh
index e88faca962..4853d8f143 100644
--- a/libs/cua-driver/scripts/_install-rust.sh
+++ b/libs/cua-driver/scripts/_install-rust.sh
@@ -23,7 +23,9 @@
# --no-modify-path skip auto-appending an `export PATH=...` line
#
# Env overrides:
-# CUA_DRIVER_RS_VERSION=0.1.2 pin a specific release tag
+# CUA_DRIVER_RS_VERSION=0.1.2 pin a stable release
+# CUA_DRIVER_RS_VERSION=nightly-cua-driver-rs-v0.1.3-nightly.20260812.42
+# pin an exact nightly release
# CUA_DRIVER_RS_INSTALL_DIR=PATH same as --bin-dir; sets the visible
# binary location
# CUA_DRIVER_RS_BIN_DIR=PATH legacy alias for INSTALL_DIR
@@ -112,6 +114,7 @@ fi
REPO="trycua/cua"
BINARY_NAME="cua-driver"
TAG_PREFIX="cua-driver-rs-v"
+NIGHTLY_TAG_PREFIX="nightly-cua-driver-rs-v"
# CUA_DRIVER_RS_INSTALL_DIR is the documented name; CUA_DRIVER_RS_BIN_DIR is
# the legacy alias kept for users with the old env in their shell rc.
BIN_DIR="${CUA_DRIVER_RS_INSTALL_DIR:-${CUA_DRIVER_RS_BIN_DIR:-$HOME/.local/bin}}"
@@ -606,12 +609,39 @@ resolve_latest_version_from_api() {
# CD path advances it only after every staged release asset is public; fallback
# remains defense in depth for manual edits, asset removal, or an interrupted
# legacy release flow.
+resolve_explicit_release_tag() {
+ local value="$1" stable_version nightly_version
+ if [[ "$value" =~ ^(cua-driver-rs-v|v)?([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+ stable_version="${BASH_REMATCH[2]}"
+ printf '%s%s' "$TAG_PREFIX" "$stable_version"
+ return 0
+ fi
+ if [[ "$value" =~ ^nightly-cua-driver-rs-v([0-9]+\.[0-9]+\.[0-9]+-nightly\.[0-9]{8}\.[1-9][0-9]*)$ ]]; then
+ nightly_version="${BASH_REMATCH[1]}"
+ printf '%s%s' "$NIGHTLY_TAG_PREFIX" "$nightly_version"
+ return 0
+ fi
+ if [[ "$value" =~ ^([0-9]+\.[0-9]+\.[0-9]+-nightly\.[0-9]{8}\.[1-9][0-9]*)$ ]]; then
+ nightly_version="${BASH_REMATCH[1]}"
+ printf '%s%s' "$NIGHTLY_TAG_PREFIX" "$nightly_version"
+ return 0
+ fi
+ return 1
+}
+
if [[ -n "${CUA_DRIVER_RS_VERSION:-}" ]]; then
VERSION_SOURCE="pin"
- TAG="${TAG_PREFIX}${CUA_DRIVER_RS_VERSION#v}"
+ if ! TAG="$(resolve_explicit_release_tag "$CUA_DRIVER_RS_VERSION")"; then
+ err "CUA_DRIVER_RS_VERSION must be an exact x.y.z stable version or canonical nightly tag"
+ exit 1
+ fi
log "using version from CUA_DRIVER_RS_VERSION: $TAG"
elif [[ -n "${CUA_DRIVER_RS_BAKED_VERSION:-}" ]]; then
VERSION_SOURCE="baked"
+ if ! [[ "$CUA_DRIVER_RS_BAKED_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ err "baked Cua Driver version must be an exact stable x.y.z version"
+ exit 1
+ fi
TAG="${TAG_PREFIX}${CUA_DRIVER_RS_BAKED_VERSION#v}"
log "using baked release: $TAG"
else
@@ -626,7 +656,11 @@ else
log "latest release: $TAG"
fi
-VERSION="${TAG#${TAG_PREFIX}}"
+if [[ "$TAG" == "$NIGHTLY_TAG_PREFIX"* ]]; then
+ VERSION="${TAG#${NIGHTLY_TAG_PREFIX}}"
+else
+ VERSION="${TAG#${TAG_PREFIX}}"
+fi
# Releases through 0.12.6 predate semantic cursor themes.
# Newer releases must contain both packaged copies.
@@ -634,6 +668,7 @@ CURSOR_THEME_REQUIRED_FROM="0.12.7"
version_is_at_least() {
local version="$1" minimum="$2"
local v_major v_minor v_patch m_major m_minor m_patch
+ version="${version%%-*}"
IFS=. read -r v_major v_minor v_patch <<< "$version"
IFS=. read -r m_major m_minor m_patch <<< "$minimum"
if (( v_major != m_major )); then (( v_major > m_major )); return; fi
@@ -671,7 +706,7 @@ release_tarball_name() {
download_release_tarball() {
local version="$1" tarball url partial http_code curl_status attempt retryable
tarball="$(release_tarball_name "$version")"
- url="https://github.com/$REPO/releases/download/${TAG_PREFIX}${version}/$tarball"
+ url="https://github.com/$REPO/releases/download/${TAG}/$tarball"
partial="$TMP_DIR/$tarball.partial"
log "downloading $url"
for attempt in 1 2 3; do
diff --git a/libs/cua-driver/scripts/install.ps1 b/libs/cua-driver/scripts/install.ps1
index be67777219..f8723ecc6d 100644
--- a/libs/cua-driver/scripts/install.ps1
+++ b/libs/cua-driver/scripts/install.ps1
@@ -39,7 +39,7 @@
# privileges or Developer Mode. So the whole installer stays sudo-free.
#
# Env overrides:
-# $env:CUA_DRIVER_RS_VERSION pin a specific release (e.g. "0.2.0")
+# $env:CUA_DRIVER_RS_VERSION pin an exact stable version or nightly tag
# $env:CUA_DRIVER_RS_INSTALL_DIR override the visible PATH-entry dir
# (default %LOCALAPPDATA%\Programs\Cua\cua-driver\bin)
# $env:CUA_DRIVER_RS_HOME override the package home
@@ -52,7 +52,8 @@
# independently of each other.
#
# Params:
-# -Release release tag to install ("latest" or a bare version like "0.2.0").
+# -Release release to install ("latest", a bare stable version, or a
+# canonical nightly-cua-driver-rs-v* tag).
# Overridden by $env:CUA_DRIVER_RS_VERSION when set.
# -AutoStart register a Scheduled Task that runs `cua-driver serve` at
# every logon (Windows-native equivalent of macOS LaunchAgent).
@@ -99,6 +100,7 @@ $ProgressPreference = "SilentlyContinue"
$Repo = "trycua/cua"
$TagPrefix = "cua-driver-rs-v"
+$NightlyTagPrefix = "nightly-cua-driver-rs-v"
$BinaryName = "cua-driver.exe"
$ThemeBinaryName = "cua-cursor-theme.exe"
@@ -861,6 +863,7 @@ function Invoke-OldReleasesGc {
# 'api' — already the API's answer; nothing left to fall
# back to.
$Script:CuaDriverRsVersionSource = $null
+$Script:CuaDriverRsReleaseTag = $null
function Get-GitHubApiHeaders {
# GH_TOKEN matches the GitHub CLI's precedence. Keep the token in a header
@@ -885,6 +888,21 @@ function Assert-StableVersion([string]$version, [string]$source) {
}
}
+function Resolve-ExplicitRelease([string]$value, [string]$source) {
+ if ($value -match '^(?:cua-driver-rs-v|v)?([0-9]+\.[0-9]+\.[0-9]+)$') {
+ $version = $Matches[1]
+ return @{ Version = $version; Tag = "$TagPrefix$version" }
+ }
+ if ($value -match '^nightly-cua-driver-rs-v([0-9]+\.[0-9]+\.[0-9]+-nightly\.[0-9]{8}\.[1-9][0-9]*)$') {
+ return @{ Version = $Matches[1]; Tag = $value }
+ }
+ if ($value -match '^([0-9]+\.[0-9]+\.[0-9]+-nightly\.[0-9]{8}\.[1-9][0-9]*)$') {
+ return @{ Version = $Matches[1]; Tag = "$NightlyTagPrefix$($Matches[1])" }
+ }
+ Write-ErrorStep "$source must be an exact x.y.z stable version or canonical nightly tag (got '$value')"
+ exit 1
+}
+
function Get-LatestVersionFromApi {
# Highest SemVer $TagPrefix* version published on the repo, or $null when
# the API is unreachable or has no matching tag. Never exits: callers
@@ -937,16 +955,18 @@ function Get-LatestVersionFromApi {
function Resolve-Version {
if ($env:CUA_DRIVER_RS_VERSION) {
- $v = $env:CUA_DRIVER_RS_VERSION -replace '^v', ''
- Assert-StableVersion $v 'CUA_DRIVER_RS_VERSION'
- Write-Step "using version from `$env:CUA_DRIVER_RS_VERSION: $v"
+ $release = Resolve-ExplicitRelease $env:CUA_DRIVER_RS_VERSION 'CUA_DRIVER_RS_VERSION'
+ $v = $release.Version
+ $Script:CuaDriverRsReleaseTag = $release.Tag
+ Write-Step "using version from `$env:CUA_DRIVER_RS_VERSION: $($release.Tag)"
$Script:CuaDriverRsVersionSource = 'env'
return $v
}
if ($Release -ne "latest") {
- $v = $Release -replace '^v', ''
- Assert-StableVersion $v '-Release'
- Write-Step "using -Release $v"
+ $release = Resolve-ExplicitRelease $Release '-Release'
+ $v = $release.Version
+ $Script:CuaDriverRsReleaseTag = $release.Tag
+ Write-Step "using -Release $($release.Tag)"
$Script:CuaDriverRsVersionSource = 'release-arg'
return $v
}
@@ -957,6 +977,7 @@ function Resolve-Version {
$v = $Script:CuaDriverRsBakedVersion -replace '^v', ''
Assert-StableVersion $v 'baked release'
Write-Step "using baked release: $TagPrefix$v"
+ $Script:CuaDriverRsReleaseTag = "$TagPrefix$v"
$Script:CuaDriverRsVersionSource = 'baked'
return $v
}
@@ -966,6 +987,7 @@ function Resolve-Version {
exit 1
}
$Script:CuaDriverRsVersionSource = 'api'
+ $Script:CuaDriverRsReleaseTag = "$TagPrefix$v"
return $v
}
@@ -997,7 +1019,7 @@ function Get-ReleaseZip([string]$version, [string]$archLabel, [string]$destDir)
# never confused with a transient network, server, or authentication
# failure. Only the former may activate baked-version fallback.
$zipName = "cua-driver-rs-$version-$archLabel.zip"
- $url = "https://github.com/$Repo/releases/download/$TagPrefix$version/$zipName"
+ $url = "https://github.com/$Repo/releases/download/$Script:CuaDriverRsReleaseTag/$zipName"
$zipPath = Join-Path $destDir $zipName
$maxAttempts = 3
@@ -1079,6 +1101,7 @@ function Get-ReleaseAsset([string]$version, [string]$archLabel, [string]$destDir
else {
Write-WarningStep "temporary fallback: baked release $TagPrefix$resolvedVersion is missing its $archLabel asset (HTTP 404); installing latest published release $TagPrefix$apiVersion instead"
$resolvedVersion = $apiVersion
+ $Script:CuaDriverRsReleaseTag = "$TagPrefix$resolvedVersion"
$download = Get-ReleaseZip $resolvedVersion $archLabel $destDir
if ($download.ErrorMessage) {
if (Test-TransientDownloadFailure $download.StatusCode) {
diff --git a/libs/cua-driver/scripts/tests/test_install_version_fallback.py b/libs/cua-driver/scripts/tests/test_install_version_fallback.py
index 98bedea507..98bdda2d18 100644
--- a/libs/cua-driver/scripts/tests/test_install_version_fallback.py
+++ b/libs/cua-driver/scripts/tests/test_install_version_fallback.py
@@ -603,6 +603,7 @@ def _run_download(tmp_path: Path, scenario: str, token_env: str = "") -> tuple[i
set -uo pipefail
REPO="trycua/cua"
TAG_PREFIX="cua-driver-rs-v"
+ TAG="cua-driver-rs-v1.2.3"
LABEL="linux-x86_64"
TMP_DIR="{tmp_path.as_posix()}"
{token_env}
@@ -688,6 +689,74 @@ def test_unix_public_asset_download_does_not_forward_api_token(tmp_path: Path) -
assert "api-token" not in stderr
+@requires_posix_bash
+ ("value", "expected"),
+ [
+ ("1.2.3", "cua-driver-rs-v1.2.3"),
+ ("cua-driver-rs-v1.2.3", "cua-driver-rs-v1.2.3"),
+ (
+ "1.2.4-nightly.20260812.42",
+ "nightly-cua-driver-rs-v1.2.4-nightly.20260812.42",
+ ),
+ (
+ "nightly-cua-driver-rs-v1.2.4-nightly.20260812.42",
+ "nightly-cua-driver-rs-v1.2.4-nightly.20260812.42",
+ ),
+ ],
+)
+def test_unix_explicit_pin_selects_an_exact_stable_or_nightly_tag(
+ tmp_path: Path, value: str, expected: str
+) -> None:
+ script = tmp_path / "resolve-pin.sh"
+ script.write_text(
+ textwrap.dedent(
+ f"""\
+ set -euo pipefail
+ TAG_PREFIX="cua-driver-rs-v"
+ NIGHTLY_TAG_PREFIX="nightly-cua-driver-rs-v"
+ {_extract_shell_function(_unix_source(), "resolve_explicit_release_tag")}
+ resolve_explicit_release_tag "{value}"
+ """
+ ),
+ encoding="utf-8",
+ )
+ result = subprocess.run(
+ ["bash", script.as_posix()], capture_output=True, text=True, check=True
+ )
+ assert result.stdout == expected
+
+
+@requires_posix_bash
+ "value",
+ [
+ "nightly-cua-driver-rs-v1.2.4-rc.1",
+ "cua-driver-rs-v1.2.4-nightly.20260812.42",
+ "nightly-lume-v1.2.4-nightly.20260812.42",
+ "1.2",
+ ],
+)
+def test_unix_explicit_pin_rejects_cross_channel_and_malformed_tags(
+ tmp_path: Path, value: str
+) -> None:
+ script = tmp_path / "resolve-bad-pin.sh"
+ script.write_text(
+ textwrap.dedent(
+ f"""\
+ set -euo pipefail
+ TAG_PREFIX="cua-driver-rs-v"
+ NIGHTLY_TAG_PREFIX="nightly-cua-driver-rs-v"
+ {_extract_shell_function(_unix_source(), "resolve_explicit_release_tag")}
+ resolve_explicit_release_tag "{value}"
+ """
+ ),
+ encoding="utf-8",
+ )
+ result = subprocess.run(["bash", script.as_posix()], capture_output=True, text=True)
+ assert result.returncode != 0
+
+
def _run_fallback_flow(
tmp_path: Path, *, version_source: str, download_statuses: list[int]
) -> tuple[subprocess.CompletedProcess[str], list[str]]:
diff --git a/libs/lume/scripts/build/build-release-notarized.sh b/libs/lume/scripts/build/build-release-notarized.sh
index 5506347e67..a359f75b7a 100755
--- a/libs/lume/scripts/build/build-release-notarized.sh
+++ b/libs/lume/scripts/build/build-release-notarized.sh
@@ -52,6 +52,11 @@ done
# Get VERSION from environment or use default
VERSION=${VERSION:-"0.1.0"}
+BUNDLE_VERSION=${BUNDLE_VERSION:-"$VERSION"}
+if ! [[ "$BUNDLE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ log "error" "Error: BUNDLE_VERSION must be a numeric x.y.z version"
+ exit 1
+fi
# Move to the project root directory
cd "$LUME_DIR"
@@ -86,7 +91,7 @@ fi
cp -f ./resources/AppIcon.icns "$APP_BUNDLE/Contents/Resources/AppIcon.icns"
# Stamp and copy Info.plist
-sed "s/__VERSION__/$VERSION/g" "./resources/Info.plist" > "$APP_BUNDLE/Contents/Info.plist"
+sed "s/__VERSION__/$BUNDLE_VERSION/g" "./resources/Info.plist" > "$APP_BUNDLE/Contents/Info.plist"
# Embed the provisioning profile
PROVISION_PROFILE="./resources/embedded.provisionprofile"
@@ -135,7 +140,7 @@ ditto "$APP_BUNDLE" "$TEMP_ROOT/usr/local/share/lume/lume.app"
if ! pkgbuild --root "$TEMP_ROOT" \
--identifier "com.trycua.lume" \
- --version "$VERSION" \
+ --version "$BUNDLE_VERSION" \
--install-location "/" \
--sign "$CERT_INSTALLER_NAME" \
./.release/lume.pkg; then
diff --git a/libs/lume/scripts/install.sh b/libs/lume/scripts/install.sh
index 5fc5e920a8..e918736eef 100755
--- a/libs/lume/scripts/install.sh
+++ b/libs/lume/scripts/install.sh
@@ -43,7 +43,9 @@ INSTALL_AUTO_UPDATER=false
UPDATE_ON_LOGIN=false
# Release selection:
-# LUME_VERSION=0.3.10 pins a specific `lume-v0.3.10` release.
+# LUME_VERSION=0.3.10 pins a specific stable `lume-v0.3.10` release.
+# LUME_VERSION=nightly-lume-v0.3.11-nightly.20260812.42 pins an exact
+# immutable nightly release. Stable discovery never selects nightlies.
# LUME_BAKED_VERSION is updated in the release PR so the default
# installer path does not need a GitHub API call.
LUME_VERSION="${LUME_VERSION:-}"
@@ -176,15 +178,28 @@ create_temp_dir() {
# Get the latest lume release tag
get_latest_lume_tag() {
if [ -n "$LUME_VERSION" ]; then
- local pinned="${LUME_VERSION#lume-v}"
- pinned="${pinned#v}"
- echo "Using Lume release from LUME_VERSION: ${BOLD}lume-v$pinned${NORMAL}" >&2
- echo "lume-v$pinned"
+ local selected=""
+ if [[ "$LUME_VERSION" =~ ^(lume-v|v)?([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+ selected="lume-v${BASH_REMATCH[2]}"
+ elif [[ "$LUME_VERSION" =~ ^nightly-lume-v([0-9]+\.[0-9]+\.[0-9]+-nightly\.[0-9]{8}\.[1-9][0-9]*)$ ]]; then
+ selected="nightly-lume-v${BASH_REMATCH[1]}"
+ elif [[ "$LUME_VERSION" =~ ^([0-9]+\.[0-9]+\.[0-9]+-nightly\.[0-9]{8}\.[1-9][0-9]*)$ ]]; then
+ selected="nightly-lume-v${BASH_REMATCH[1]}"
+ else
+ echo "${RED}Error: LUME_VERSION must be an exact x.y.z stable version or canonical nightly tag.${NORMAL}" >&2
+ return 1
+ fi
+ echo "Using Lume release from LUME_VERSION: ${BOLD}$selected${NORMAL}" >&2
+ echo "$selected"
return 0
fi
if [ -n "$LUME_BAKED_VERSION" ]; then
local baked="${LUME_BAKED_VERSION#v}"
+ if ! [[ "$baked" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "${RED}Error: baked Lume version must be an exact stable x.y.z version.${NORMAL}" >&2
+ return 1
+ fi
echo "Using baked Lume release: ${BOLD}lume-v$baked${NORMAL}" >&2
echo "lume-v$baked"
return 0
@@ -196,6 +211,7 @@ get_latest_lume_tag() {
local per_page=100
local max_pages=10 # Safety limit (1000 tags max)
local LUME_TAG=""
+ local versions=""
while [ $page -le $max_pages ]; do
echo "Checking page $page..." >&2
@@ -212,22 +228,45 @@ get_latest_lume_tag() {
fi
fi
- LUME_TAG=$(echo "$response" \
- | grep -oE '"tag_name":\s*"lume-[^"]*"' \
- | head -n 1 \
- | cut -d '"' -f 4)
+ local page_versions
+ page_versions=$(printf '%s' "$response" | awk '
+ /"tag_name"[[:space:]]*:/ {
+ tag = $0
+ sub(/^.*"tag_name"[[:space:]]*:[[:space:]]*"/, "", tag)
+ sub(/".*$/, "", tag)
+ next
+ }
+ tag != "" && /"draft"[[:space:]]*:/ {
+ if ($0 ~ /"draft"[[:space:]]*:[[:space:]]*false/ &&
+ tag ~ /^lume-v[0-9]+\.[0-9]+\.[0-9]+$/) {
+ sub(/^lume-v/, "", tag)
+ print tag
+ }
+ tag = ""
+ }
+ ')
+ if [ -n "$page_versions" ]; then
+ versions="${versions}${versions:+$'\n'}${page_versions}"
+ fi
- if [ -n "$LUME_TAG" ]; then
- echo "Found latest Lume release: ${BOLD}$LUME_TAG${NORMAL}" >&2
- echo "$LUME_TAG"
- return 0
+ local page_count
+ page_count=$(printf '%s' "$response" | awk '{ count += gsub(/"tag_name"[[:space:]]*:/, "&") } END { print count + 0 }')
+ if [ "$page_count" -lt "$per_page" ]; then
+ break
fi
page=$((page + 1))
done
- echo "${RED}Error: Could not find any lume tags after checking $max_pages pages.${NORMAL}" >&2
- exit 1
+ local latest
+ latest=$(printf '%s\n' "$versions" | sed '/^$/d' | sort -t. -k1,1nr -k2,2nr -k3,3nr | head -n 1)
+ if [ -z "$latest" ]; then
+ echo "${RED}Error: Could not find any published stable lume tags after checking $max_pages pages.${NORMAL}" >&2
+ return 1
+ fi
+ LUME_TAG="lume-v$latest"
+ echo "Found latest Lume release: ${BOLD}$LUME_TAG${NORMAL}" >&2
+ echo "$LUME_TAG"
}
# Download the latest release
diff --git a/libs/lume/src/Update/VersionCheck.swift b/libs/lume/src/Update/VersionCheck.swift
index fe5fedb295..6f3157cc9b 100644
--- a/libs/lume/src/Update/VersionCheck.swift
+++ b/libs/lume/src/Update/VersionCheck.swift
@@ -220,13 +220,7 @@ enum LumeVersionCheck {
throw VersionCheckError.invalidResponse
}
- versions.append(
- contentsOf: releases
- .compactMap { $0["tag_name"] as? String }
- .filter { $0.hasPrefix(releaseTagPrefix) }
- .map { String($0.dropFirst(releaseTagPrefix.count)) }
- .filter { isPlainSemver($0) }
- )
+ versions.append(contentsOf: publishedStableVersions(from: releases))
if releases.count < 100 {
break
@@ -249,6 +243,17 @@ enum LumeVersionCheck {
.map { Int($0) ?? 0 } ?? []
}
+ static func publishedStableVersions(from releases: [[String: Any]]) -> [String] {
+ releases.compactMap { release in
+ if release["draft"] as? Bool == true { return nil }
+ guard let tag = release["tag_name"] as? String,
+ tag.hasPrefix(releaseTagPrefix)
+ else { return nil }
+ let version = String(tag.dropFirst(releaseTagPrefix.count))
+ return isPlainSemver(version) ? version : nil
+ }
+ }
+
private static func isPlainSemver(_ version: String) -> Bool {
let parts = version.split(separator: ".")
guard parts.count == 3 else { return false }
diff --git a/libs/lume/tests/VersionCheckTests.swift b/libs/lume/tests/VersionCheckTests.swift
index c89cf151c3..e3d88bdd16 100644
--- a/libs/lume/tests/VersionCheckTests.swift
+++ b/libs/lume/tests/VersionCheckTests.swift
@@ -20,4 +20,14 @@ struct VersionCheckTests {
== "curl -fsSL file:///tmp/lume-install.sh | LUME_VERSION=0.3.10 bash"
)
}
+
+ @Test func stableDiscoveryRejectsDraftAndNightlyTags() {
+ let releases: [[String: Any]] = [
+ ["tag_name": "lume-v0.6.0", "draft": true],
+ ["tag_name": "nightly-lume-v0.5.4-nightly.20260812.42", "draft": false],
+ ["tag_name": "lume-v0.5.4-nightly.20260812.42", "draft": false],
+ ["tag_name": "lume-v0.5.3", "draft": false],
+ ]
+ #expect(LumeVersionCheck.publishedStableVersions(from: releases) == ["0.5.3"])
+ }
}
diff --git a/rfcs/3096-immutable-nightly-release-channels.md b/rfcs/3096-immutable-nightly-release-channels.md
new file mode 100644
index 0000000000..21ccb8d8a5
--- /dev/null
+++ b/rfcs/3096-immutable-nightly-release-channels.md
@@ -0,0 +1,311 @@
+---
+title: Immutable nightly release channels for Cua components
+authors:
+ - f-trycua
+created: 2026-08-12
+last_updated: 2026-08-12
+status: accepted
+discussion: https://github.com/trycua/cua/issues/3096
+rfc_pr: https://github.com/trycua/cua/pull/3097
+implementation:
+ - https://github.com/trycua/cua/pull/3097
+supersedes:
+superseded_by:
+---
+
+# RFC: Immutable nightly release channels for Cua components
+
+## Summary
+
+Cua will publish immutable, signed nightly releases for Cua Driver and Lume
+through one small release-channel contract. Stable and nightly tags use
+disjoint namespaces, Release Please remains the stable version authority,
+component workflows retain platform-specific build and signing behavior, and
+nightly installation requires explicit opt-in.
+
+## Motivation
+
+Cua Driver and Lume have independent stable workflows, version discovery
+rules, signing requirements, and publication behavior. Neither exposes a
+supported nightly channel. Reusing stable tag prefixes is unsafe because
+already-fielded resolvers can accept prerelease-shaped tags, and GitHub's
+prerelease flag is metadata rather than a channel boundary.
+
+Adding unrelated nightly workflows would also copy planning, tag validation,
+publication, and recovery logic. A future component would have to repeat that
+work and preserve the same security invariant by convention.
+
+## Goals
+
+- Publish immutable Driver and Lume nightlies from exact `main` commits.
+- Keep stable clients unable to discover a nightly without explicit opt-in.
+- Reuse one strict tag grammar, component registry, manifest contract, and
+ GitHub draft publication transaction.
+- Keep platform matrices, signing, notarization, packaging, and archive
+ verification component-owned.
+- Skip unchanged components while rebuilding after relevant shared release
+ infrastructure changes.
+- Make retries idempotent and keep failed publication attempts private as
+ drafts.
+- Publish PR-level changes and contributor/reporting credit from the exact
+ nightly range by reusing the stable attribution engine.
+- Give future components a small documented onboarding contract.
+
+## Non-goals
+
+- Publishing nightly npm, PyPI, container, Homebrew, or other registry
+ channels in the first implementation.
+- Persisting a user's update channel in product configuration.
+- Replacing Release Please or changing stable version decisions.
+- Treating GitHub `prerelease=true` as the channel boundary.
+- Introducing an object-store mirror before GitHub reliability or rate limits
+ require it.
+- Changing Cua Driver's explicit stable certification and publish gate.
+
+## Terminology
+
+**Stable tag** is an exact component prefix followed by `X.Y.Z`, such as
+`cua-driver-rs-v0.20.0`.
+
+**Nightly tag** uses a channel-first prefix and a deterministic prerelease
+identity, such as
+`nightly-cua-driver-rs-v0.20.1-nightly.20260812.123456789`.
+
+**Component descriptor** is the small registry entry that connects Release
+Please identity to shared channel machinery. It does not describe how a
+component builds or signs its artifacts.
+
+**Build version sites** are version-bearing files that affect the nightly
+artifact. They exclude stable-only state such as baked installer defaults and
+published-version pointers.
+
+## Current state
+
+Release Please owns independent Cua Driver and Lume stable versions in
+[`release-please-config.json`](../release-please-config.json). Cua Driver's
+cross-platform workflow builds candidates on a tag and publishes only after an
+explicit dispatch. Lume signs, notarizes, and publishes after a stable tag.
+
+The Driver's fielded Rust update checker accepts any SemVer tag under
+`cua-driver-rs-v`. The Lume shell installer has historically used a broad
+`lume-*` fallback. A same-prefix nightly could therefore enter a stable
+discovery path. GitHub prerelease metadata cannot repair that because stable
+Driver releases currently use that metadata too.
+
+The repository already has a release manifest schema and an idempotent GitHub
+draft finalizer. It also has an older generic GitHub release workflow used by
+legacy package lanes. The nightly implementation extends the tested scripts
+and manifest rather than creating a second generic publisher.
+
+## Proposal
+
+### Channel identity
+
+Stable tags retain their current names. Nightlies use channel-first prefixes:
+
+| Component | Stable | Nightly |
+| --- | --- | --- |
+| Cua Driver | `cua-driver-rs-vX.Y.Z` | `nightly-cua-driver-rs-vX.Y.Z-nightly.YYYYMMDD.RUN` |
+| Lume | `lume-vX.Y.Z` | `nightly-lume-vX.Y.Z-nightly.YYYYMMDD.RUN` |
+
+Every resolver matches one strict grammar. Stable discovery never considers a
+nightly prefix. GitHub's draft, prerelease, and latest fields do not determine
+the channel.
+
+### Shared ownership
+
+The shared release layer owns:
+
+- descriptor validation and Release Please consistency;
+- tag parsing, formatting, and version derivation;
+- component change detection;
+- release channel and source-SHA manifest fields;
+- PR-first change and contributor attribution;
+- nightly-only GitHub draft creation;
+- asset upload, verification, and final publication;
+- common wiring tests and onboarding documentation.
+
+Component adapters own:
+
+- build matrices and toolchains;
+- signing identities and protected environments;
+- notarization and platform-specific version mapping;
+- archive contents and verification;
+- installer UX;
+- certification scope and evidence;
+- registry package ordering and publication.
+
+The descriptor is referential. It names the matching Release Please component
+and contains only its stable/nightly prefixes, version authority, build-time
+version sites, builder ownership, change paths, and enabled channels. It does
+not duplicate the full Release Please extra-file list.
+
+### Nightly versioning
+
+The planner derives a version from the current stable authority by incrementing
+the patch component and appending `nightly.YYYYMMDD.RUN`. It rewrites only the
+component's declared build version sites in the ephemeral CI checkout. It
+never commits nightly versions or changes baked stable installer defaults.
+
+Components may map the release identity to platform metadata where a platform
+does not accept SemVer prerelease strings. The public binary version, release
+tag, archive names, and manifest retain the full nightly identity.
+
+### Publication transaction
+
+Publication progresses through these states:
+
+```text
+planned -> built -> verified -> draft -> assets verified -> published
+```
+
+The draft-to-public update is the commit point. Before that update, retries may
+reuse the same tag and draft only when their source SHA, channel, and version
+agree. Conflicting identity fails closed. Published nightly releases and their
+assets are immutable.
+
+Nightlies never advance stable baked versions, release-state files, stable
+documentation release automation, or SDK registry publication. A distinct
+workflow name and stable-grammar checks keep existing `workflow_run` registry
+publishing isolated.
+
+Each nightly manifest and release body journals the conventional pull requests
+that touched the component or shared release paths. The shared stable-release
+collector resolves commit-to-PR provenance, authors, coauthors, and linked issue
+reporters. Nightlies include maintenance types such as `docs`, `test`, and `ci`;
+stable manifests retain their existing release-type and versioned-changelog
+requirements. The first nightly compares against the current stable component
+tag, and each later nightly compares against the previous published nightly.
+
+### Installation
+
+The first public contract supports exact nightly versions. Stable installation
+and update discovery remain unchanged. A later additive change may resolve the
+newest nightly for a one-shot `--channel nightly` installation. Persisted
+channel state requires its own cross-platform contract and certification.
+
+### Scheduling
+
+Each component can run daily and by manual dispatch. A scheduled run compares
+the newest published nightly's source SHA with `main` over the descriptor's
+change paths. Component source, its builder, shared channel scripts, and
+declared cross-component inputs participate in the comparison. The first run
+and a forced manual run always build. Attribution is bounded by the newest
+published nightly tag, or by the current stable tag when no nightly exists.
+
+## Alternatives considered
+
+### Same-prefix SemVer prereleases
+
+Rejected because already-fielded stable resolvers can see them. Resolver
+hardening cannot change binaries and scripts already installed.
+
+### Separate hand-written nightly workflows
+
+Rejected because channel safety, manifest fields, and publication recovery
+would drift across components.
+
+### Generic signing and build framework
+
+Rejected because platform packaging and signing have different trust,
+environment, and verification requirements. Reuse stops at the builder
+interface.
+
+### Mutable nightly release
+
+Rejected because overwriting a tag or asset weakens provenance, rollback, and
+exact-version reproduction.
+
+### Object-store channel pointer
+
+Deferred. Immutable object storage plus a small mutable pointer is a sound
+future backend, but GitHub Releases and exact pins meet the initial contract
+without another credential or consistency domain.
+
+### Stable publication refactor first
+
+Rejected because it puts certified stable behavior at risk before nightlies
+provide evidence. The implementation first extracts reusable build and verify
+boundaries while keeping stable publication gates unchanged.
+
+## Compatibility and migration
+
+Resolver isolation and its visibility matrix land before any nightly tag is
+created. Shared parsing and publication are additive. Stable Release Please
+tags, baked installer versions, update discovery, certification, and explicit
+Driver publication remain unchanged.
+
+Nightly tags are in a namespace that current stable workflows do not match.
+Exact nightly installation is opt-in. Returning to stable uses the existing
+stable installer path. A later one-shot channel resolver must preserve exact
+pin support as the rollback mechanism.
+
+## Security, privacy, and telemetry
+
+Channel choice comes from explicit user input and is never inferred from
+GitHub prerelease metadata. Workflows use least-privilege permissions,
+protected signing environments, pinned actions, and existing identities.
+
+Release metadata contains public component identity, channel, version, source
+SHA, pull requests, public contributor handles, linked public issue reporters,
+asset names, sizes, and digests. It must not contain credentials, runner
+identities, private infrastructure, user data, session data, or private test
+evidence. Existing attribution opt-outs and identity policy remain binding. The
+component descriptor contains no secrets.
+
+## Implementation plan
+
+1. Harden stable resolvers and add a cross-component visibility matrix.
+2. Add the minimal descriptor schema and strict channel grammar.
+3. Add nightly version staging, manifest channel metadata, and bounded
+ PR-first attribution through the shared release collector.
+4. Extend GitHub release publication with nightly-only draft creation.
+5. Extract Driver build and verification jobs behind a reusable boundary while
+ leaving its stable publish job unchanged.
+6. Add signed Driver and Lume nightly orchestrators.
+7. Add exact nightly installation and operator documentation.
+8. Prove the workflow locally and through ordinary pull-request CI before any
+ public nightly is dispatched.
+
+## Test and acceptance plan
+
+- Registry/schema/parser and release-wiring tests pass.
+- A visibility matrix proves every stable resolver rejects both components'
+ nightly tags.
+- Stable workflow publication gates and registry triggers remain unchanged.
+- Driver artifacts pass existing cross-platform archive and MCP discovery
+ contracts.
+- Lume artifacts pass existing signing, notarization, and manifest checks.
+- Nightly retries reuse the same tag, SHA, and draft and reject conflicting
+ identity.
+- Nightly publication never updates baked stable versions or triggers stable
+ SDK or documentation publication.
+- First-nightly attribution starts at the current stable tag; later attribution
+ starts at the previous nightly and includes maintenance PRs and contributor
+ credit without weakening stable release-note validation.
+- The first public nightly, when separately authorized, is certified at its
+ exact SHA and states the automated evidence that actually ran.
+
+## Unresolved questions
+
+- Which retention policy should apply after observing 60 to 90 days of release
+ volume?
+- When should newest-nightly resolution and persistent channel selection ship?
+- When do registry channels or an object-store pointer become justified?
+- Should Driver's existing GitHub prerelease metadata convention change in
+ separate work?
+
+## Decision record
+
+The maintainer selected this direction after comparing Cua's current release
+machinery with T3 Code and `openai/codex`, followed by an independent Claude
+Fable architecture review.
+
+Accepted amendments were a minimal referential registry, channel-first tags,
+component-owned builders, exact pins before persistent channels, GitHub draft
+publication as the first transaction boundary, and no automatic retention
+initially. Same-prefix tags, automatic fourteen-release deletion, and stable
+publication refactoring before nightly behavior is proven were rejected.
+
+Disposition: accepted for implementation. Registry publishing, object storage,
+automatic retention, and persistent channel state remain deferred.