Contributing, CI and releases
View as MarkdownThis page is for people working on Uncage. It follows CONTRIBUTING.md.
Develop
Section titled “Develop”The repository is a pnpm workspace (Node.js 22+, pnpm 10) built with Turborepo.
pnpm installpnpm build && pnpm typecheck && pnpm lint && pnpm testpnpm e2e:mock # Playwright against a fake runtime (uses your system Chrome)UNCAGE_LIVE=1 pnpm e2e:live # against REAL Claude Code (uses a little Claude usage; never in CI)The E2E suites run TypeScript files directly with node, so they need Node.js 22.18 or newer. Locally they use your installed Google Chrome and never download a browser; in CI (CI=true) Playwright uses its bundled Chromium.
Connected Mode suites, from e2e/ after pnpm build:
pnpm exec playwright test --project=connected-mockUNCAGE_DOCKER_TESTS=1 pnpm exec playwright test --project=connected-multinode # needs DockerUNCAGE_LIVE=1 pnpm exec playwright test --project=connected-live # real Claude CodeWhat CI runs
Section titled “What CI runs”.github/workflows/ci.yml, on every pull request and on pushes to main and feat/**:
| Job | Steps |
|---|---|
| Node 22 / Node 24 | pnpm install --frozen-lockfile, pnpm build, pnpm typecheck, pnpm lint, pnpm test, then pnpm e2e:mock with Playwright’s Chromium |
| platform (Ubuntu, macOS, Windows) | pnpm build of the CLI and hub, then on each OS: the installers (install.ps1 under Windows PowerShell 5.1 and pwsh 7, install.sh under bash with shellcheck on Ubuntu and bash 3.2 on macOS), the agent and CLI suites (paths, permissions, .cmd spawning), and the real per-user service on Windows (Task Scheduler) and Ubuntu (systemd --user), registered for the runner’s user and removed again |
| Docs (Node 24) | Build the packages the site documents, lint and type-check apps/docs, type-check every code sample on this site (pnpm --filter docs check:snippets), then build the site (pnpm --filter docs build), which also generates the API reference and validates every internal link |
Releases
Section titled “Releases”Releases are automatic, driven by Changesets. All public @uncage/* packages share one version (a fixed group).
- In every pull request with a user-visible change, run
pnpm changeset, choose the bump, write a short note, and commit the generated.changeset/*.mdfile. - When the pull request merges to
main,.github/workflows/release.ymlopens (or updates) a “chore: version packages” pull request that bumps versions and writes changelogs. - Merging that pull request makes the same workflow run
changeset publish, which publishes every unpublished version to npm (without provenance) and tags the release.
Publishing uses npm trusted publishing (OIDC). There is no NPM_TOKEN secret.
One-time setup (maintainers)
Section titled “One-time setup (maintainers)”- npm, per public package (
@uncage/protocol,core,server,client,react,react-ui,runtime-claude,runtime-codex,runtime-acp,cli,hub,agent): npmjs.com → the package → Settings → Trusted publishing → GitHub Actions, with organizationptmafia, repositoryuncage, workflowrelease.yml, environment empty. A package that was never published has no settings page yet: publish it once by hand (pnpm build, thenpnpm --filter @uncage/hub publish --access public --no-git-checkswhile logged in withnpm login), then configure trusted publishing. - GitHub: in the organization (Settings → Actions → General) and then in the repository, enable “Allow GitHub Actions to create and approve pull requests”.
First publish of a new package
Section titled “First publish of a new package”Trusted publishing (OIDC) can only publish a package that already exists on npm: it cannot create one. A new package (for example @uncage/runtime-acp in 0.3) must be published once by hand before the release workflow can publish it: pnpm build, then pnpm --filter @uncage/runtime-acp publish --access public --no-git-checks while logged in with npm login. Then configure its trusted publisher (above). Until then the release publishes the other packages and fails on the new one, which leaves a release with a missing dependency.
If that GitHub setting cannot be enabled, the workflow cannot open the version pull request. Version locally instead:
pnpm changeset version # bumps versions, updates changelogs, consumes changesetsgit commit -am "chore: version packages" && git push # via a normal pull request into mainWhen that commit lands on main there are no pending changesets and the versions are unpublished, so the workflow publishes them directly.
This help site
Section titled “This help site”The site lives in apps/docs (Astro + Starlight). It is not part of the root pnpm build, pnpm typecheck or pnpm lint (Astro needs Node.js 22.23.4 or newer; the packages support 22.0+), so it has its own CI job.
pnpm build # the packages (the API reference and the sample check use them)pnpm --filter docs dev # http://localhost:4321/docs/pnpm --filter docs check # sample type-check + full build with link validation- Pages are markdown files in
apps/docs/src/content/docs/(English) andapps/docs/src/content/docs/zh-cn/and.../ja/(Chinese and Japanese; every page except the API reference, the changelog and this one). The sidebar order is inapps/docs/src/nav.mjs;/llms.txtand/llms-full.txtfollow it. - Code samples: every code block fenced as
tsortsxis type-checked byapps/docs/scripts/check-snippets.tsagainst the workspace packages. Blocks on one page form one project; give a blocktitle="lib/tools.ts"to make it a file others can import. Add the wordnocheckto the fence (ats nocheckinfo string) only for fragments that are not a whole file (a signature, one option). - Links to other pages are absolute and include the base:
/docs/guides/define-tools/. The build fails on a broken internal link or anchor (starlight-links-validator). - API reference (
/api/…) is generated at build time from the packages’ TypeScript (TypeDoc +typedoc-plugin-markdown, viastarlight-typedoc); improve it by improving the TSDoc comments in the source. - For agents: every page is also served as
/<page>.md;/llms.txt,/llms-full.txtand/skills/uncage/SKILL.mdare generated from the pages and fromskills/uncage/SKILL.mdat the repository root. - Deploy: the site and the help site are one static Vercel deployment (
vercel.json,node scripts/build-web.mjs, outputapps/site/dist), published athttps://uncage-dev.vercel.app/docs/..github/workflows/docs.yml(the Web check) builds it, validates the links and checks the translations on every pull request and push tomain; it deploys nothing. The live demo is hosted separately (seedocs/deploy-web.mdin the repository).