Gitea CI runs npm ci, the generated-code drift check, build, test and lint through KofTwentyTwo/ci-workflows node.yaml. Removes the retired qqq-orb files (.circleci, .qqq-ci.yml and the copies seeded into the Homebrew tap) and updates the docs that described them. Publishing is not ported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
CI lanes for the qqq CLI
What runs today
CircleCI and the qqq-orb were retired on 2026-11-07. CI is the shared Gitea workflow
KofTwentyTwo/ci-workflows node.yaml, called from
.gitea/workflows/build.yaml on every push, Linux only (node:22-bookworm):
npm cinpm run generate, thengit diff --exit-codeonschema.tsandoperations.ts(generated-code drift)npm run build,npm test,npm run lint
Not in CI: publishing (packages, binaries, Homebrew/Scoop updates are release-machine steps in
docs/release-runbook.md until a release workflow is decided), the macOS arm64 and Windows x64 lanes,
the Prism smoke, the TUI (npm run test:tui, typecheck:tui, which need Bun) and the platform binaries.
Everything below describes the retired CircleCI setup and is kept for the record.
History
Before orb 0.8.33 the profile generated only cli_verify_publish (on cimg/node:22.12), without lint,
without the operations.ts drift check, without publishing @qrun-io/qqq-core, always with the
dist-tag rc, and with no macOS or Windows lane. The gap list and proposal below are what led to
0.8.33; they are kept for the record.
Checked on 2026-10-31 by running the orb's own cli_verify.sh in Docker on the release branch, plus
npm run prepublishOnly and npm run lint:
| Image | Result |
|---|---|
node:20-bookworm-slim (Node 20.20.2) |
all green |
cimg/node:22.12 (the orb's image) |
all green since 2026-10-31. Before, two prompt tests (Ctrl-D and Ctrl-C at a question) hung: on 22.12 readline leaves a pending question unsettled when Ctrl-D closes the interface. prompt.ts now also settles the question when the interface closes; checked on Node 20.20, 22.12 and 24.22. |
Gaps in the profile as of 0.8.32 (all closed in 0.8.33 except the TUI, which still needs Bun):
@qrun-io/qqq-coreis not published.@qrun-io/qqq-clidepends on it, so the CLI package the orb publishes cannot be installed until core is published by hand (scripts/release.mjsprints the command). Add it tocli_publish.sh, before the CLI, with the same destination check.- No lint. Commit
7f1ad5eaddedprepublishOnlyandlintfor the orb's node profile, but this repo uses thecliprofile, which runs neither.npm run lintnow also checks that the release versions agree; it should gate a publish. - One Node version. The packages declare
engines.node >=20; the orb tests only 22.12. Until this release,npm testfailed on Node 20 (the quoted test glob needs Node 21+), and nothing noticed. - No macOS or Windows. The keyring has three platform paths (Keychain, Secret Service, DPAPI through PowerShell), the binaries are built for five targets, and only Linux runs anything.
operations.tsdrift is regenerated bynpm run generatebut not diffed; add it to thegit diff --exit-codeline (scripts/release.mjsalready checks both).- The TUI (
npm run test:tui,typecheck:tui) needs Bun, which the image does not have.
Proposal for James: two orb changes
Written before 1.0.0-rc.1 and kept as sent. Part 1b became qqq-orb PR #165; all of it, and the platform lanes of Option A below, shipped in qqq-orb 0.8.33, and this repository has opted in.
Subject: qqq-orb
cliprofile: publish @qrun-io/qqq-core, and opt-in macOS/Windows lanesqqq-cli 1.0.0-rc.1 is ready to tag except for two things only the orb can fix.
1. Publish
@qrun-io/qqq-core(blocking). The CLI now depends on the kernel package@qrun-io/qqq-core, butcli_publish.shpublishes only the client, conformance and CLI. A tagged release would publish a CLI thatnpm installcannot resolve. Change (src/scripts/cli_publish.sh):const packages = [ ['packages/ui-api-client/package.json', '@qrun-io/qqq-ui-api-client'], + ['packages/core/package.json', '@qrun-io/qqq-core'], ['packages/conformance/package.json', '@qrun-io/qqq-ui-api-conformance'], ['packages/cli/package.json', '@qrun-io/qqq-cli'], ]; @@ npm publish -w @qrun-io/qqq-ui-api-client --registry https://npm.pkg.github.com --tag rc +npm publish -w @qrun-io/qqq-core --registry https://npm.pkg.github.com --tag rc npm publish -w @qrun-io/qqq-ui-api-conformance --registry https://npm.pkg.github.com --tag rc npm publish -w @qrun-io/qqq-cli --registry https://npm.pkg.github.com --tag rcCore already has
publishConfigfor GitHub Packages, so the destination check passes. While there,cli_verify.shshould also runnpm run lint(it now checks that the release versions agree) and diffpackages/core/src/api/operations.tsnext toschema.ts. Workaround until then: publish core by hand right after the orb job (scripts/release.mjsprints the command).1b. Final versions as
latest(needed for 1.0.0).cli_publish.shalways publishes with--tag rc, so 1.0.0 would land underrc. Taken up in qqq-orb PR #165 (head 4119818) with the rule James accepted: if any of the four versions (client, core, conformance, CLI) has a prerelease part, all four publish asrc; only when all four are final, aslatest. qqq-cli'srelease.mjsgate refuses a final CLI version while any of the four is a prerelease.2. Opt-in platform lanes (not blocking 1.0.0-rc.1, wanted before 1.0). The CLI ships binaries for macOS, Linux and Windows and has three keyring backends, but CI runs only Linux. Proposal: a new orb job
cli_platform(the YAML below) and a manifest keyplatforms: [macos-arm64, windows-x64]thatcli_templateturns into one job per platform, required before publishing on tags. macOS and Windows executors cost more credits and need the plan to includem4pro.mediumandwindows.medium. A repository without the key gets exactly today's pipeline.Details and the job YAML:
docs/ci-lanes.mdin qqq-cli.
Platform lanes in detail
Two lanes, both on pull requests and tags: macOS arm64 (tier 1 in the design, Keychain) and
Windows x64 (tier 2, DPAPI, PowerShell completion, the cross-compiled .exe actually run). Each
installs Node 20 and Bun 1.4.4, runs build, test and lint, builds the binary for its own platform with
scripts/build-binaries.mjs --host and smoke-runs it. Linux arm64 and musl can be added the same way
later (arm.medium machine executor, node:20-alpine).
Option A (recommended, shipped in qqq-orb 0.8.33): an orb change
The cli profile is the one place CLI CI is defined, so the lanes belong there. Changes in qqq-orb:
-
a new job
src/jobs/cli_platform.yml(the job below, with the executors inlined as parameters); -
cli_templateinsrc/scripts/generate_pipeline.pyappends oneqqq-orb/cli_platformjob per entry of a new optional manifest key, and makescli_verify_publishrequire them on tags (sketch; the manifest validation ingenerate_pipeline.pyhas to accept the key):platforms = config.get("platforms", []) # validated: subset of ("macos-arm64", "windows-x64") jobs = [{"qqq-orb/cli_platform": {"name": f"cli-{p}", "platform": p, "filters": filters}} for p in platforms] options["requires"] = [f"cli-{p}" for p in platforms] if publish else [] jobs.append({"qqq-orb/cli_verify_publish": options}) -
cli_verify.sh:npm run lint, andoperations.tsin the drift check;cli_publish.sh: publish@qrun-io/qqq-core; the image to a currentcimg/node:22.x, plus a Node 20 run ofnpm test.
Then this repository opts in with two lines and no change to .circleci/config.yml:
# .qqq-ci.yml
platforms: [macos-arm64, windows-x64]
Option B: a second pipeline in this repository (not needed since 0.8.33)
If the orb change has to wait: CircleCI projects on the GitHub App integration can have more than one
pipeline, each with its own config file (Project Settings, Pipelines, "Add pipeline", config path
.circleci/platforms.yml, trigger on pushes and tags). The orb's setup pipeline stays as it is. The file
below validates with circleci config validate (CLI 1.13.0); it has not run on CircleCI, and the macOS
and Windows resource classes need the plan to include them. This option was not applied: the
repository's .circleci/config.yml is unchanged and still only the orb stub.
version: 2.1
executors:
macos-arm64:
macos:
xcode: 16.4.0
resource_class: m4pro.medium
windows-x64:
machine:
image: windows-server-2022-gui:current
resource_class: windows.medium
shell: bash.exe
jobs:
cli_platform:
parameters:
platform:
type: executor
binary:
type: string
executor: << parameters.platform >>
environment:
BUN_VERSION: 1.4.4
NODE_VERSION: 20.20.2
steps:
- checkout
- run:
name: Node and Bun
command: |
if [[ "$OSTYPE" == darwin* ]]; then
brew install node@20 >/dev/null && echo 'export PATH="$(brew --prefix node@20)/bin:$PATH"' >> "$BASH_ENV"
curl -fsSL https://bun.sh/install | bash -s "bun-v$BUN_VERSION"
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> "$BASH_ENV"
else
nvm install "$NODE_VERSION" && nvm use "$NODE_VERSION"
powershell.exe -NoProfile -Command "\$env:BUN_INSTALL='C:\bun'; & ([scriptblock]::Create((irm https://bun.sh/install.ps1))) -Version $BUN_VERSION"
echo 'export PATH="/c/bun/bin:$PATH"' >> "$BASH_ENV"
fi
- run: node --version && bun --version
- run: npm ci
- run: npm run build
- run: npm test
- run: npm run lint
- run:
name: Binary for this platform
command: node scripts/build-binaries.mjs --no-build --host
- run:
name: Binary smoke (scripts/verify-binary.sh / .ps1)
command: |
if [[ "$OSTYPE" == darwin* ]]; then
scripts/verify-binary.sh ./dist/<< parameters.binary >>
else
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/verify-binary.ps1 -Binary dist/<< parameters.binary >>
fi
- store_artifacts:
path: dist
workflows:
platforms:
jobs:
- cli_platform:
name: macos-arm64
platform: macos-arm64
binary: qqq-darwin-arm64
- cli_platform:
name: windows-x64
platform: windows-x64
binary: qqq-windows-x64.exe
The smoke is scripts/verify-binary.sh (macOS, Linux) or scripts/verify-binary.ps1 (Windows):
version with binary with ui, completion, qqq ui --check naming the build, and with --server /
-Server also login, doctor, whoami, a query and a process run. Without a QQQ server in CI the lanes
run the offline half; a lane with the sample server (Java 21) or a Prism mock can add --server. Both
scripts were run here: the .sh on darwin-arm64 (file keyring and the macOS Keychain) and in Debian
amd64, the .ps1 with PowerShell 7 in mcr.microsoft.com/powershell on the linux-x64 binary, all
against the sample server. Neither has run on Windows: Windows x64 and macOS x64 are unverified
until these lanes run.
Notes on the YAML: Windows runs steps in Git Bash (shell: bash.exe), so the same commands work on
both lanes; nvm comes with the Windows image; QQQ_CONFIG_DIR keeps the smoke away from the agent's
profile. A Keychain round trip (qqq login against a Prism mock with QQQ_EXTENSION_CHECK=off, then
logout) is the next step for the macOS lane; on Windows the DPAPI store is covered by the kernel's unit
tests only.