Files
james.maesandClaude Opus 5.5 2c156f3884
node / node (push) Successful in 50s
build / node (push) Successful in 50s
ci: build on the shared ci-workflows node.yaml, remove CircleCI
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>
2026-11-07 16:12:34 -06:00

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):

  1. npm ci
  2. npm run generate, then git diff --exit-code on schema.ts and operations.ts (generated-code drift)
  3. 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-core is not published. @qrun-io/qqq-cli depends on it, so the CLI package the orb publishes cannot be installed until core is published by hand (scripts/release.mjs prints the command). Add it to cli_publish.sh, before the CLI, with the same destination check.
  • No lint. Commit 7f1ad5e added prepublishOnly and lint for the orb's node profile, but this repo uses the cli profile, which runs neither. npm run lint now 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 test failed 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.ts drift is regenerated by npm run generate but not diffed; add it to the git diff --exit-code line (scripts/release.mjs already 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 cli profile: publish @qrun-io/qqq-core, and opt-in macOS/Windows lanes

qqq-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, but cli_publish.sh publishes only the client, conformance and CLI. A tagged release would publish a CLI that npm install cannot 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 rc

Core already has publishConfig for GitHub Packages, so the destination check passes. While there, cli_verify.sh should also run npm run lint (it now checks that the release versions agree) and diff packages/core/src/api/operations.ts next to schema.ts. Workaround until then: publish core by hand right after the orb job (scripts/release.mjs prints the command).

1b. Final versions as latest (needed for 1.0.0). cli_publish.sh always publishes with --tag rc, so 1.0.0 would land under rc. 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 as rc; only when all four are final, as latest. qqq-cli's release.mjs gate 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 key platforms: [macos-arm64, windows-x64] that cli_template turns into one job per platform, required before publishing on tags. macOS and Windows executors cost more credits and need the plan to include m4pro.medium and windows.medium. A repository without the key gets exactly today's pipeline.

Details and the job YAML: docs/ci-lanes.md in 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).

The cli profile is the one place CLI CI is defined, so the lanes belong there. Changes in qqq-orb:

  1. a new job src/jobs/cli_platform.yml (the job below, with the executors inlined as parameters);

  2. cli_template in src/scripts/generate_pipeline.py appends one qqq-orb/cli_platform job per entry of a new optional manifest key, and makes cli_verify_publish require them on tags (sketch; the manifest validation in generate_pipeline.py has 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})
    
  3. cli_verify.sh: npm run lint, and operations.ts in the drift check; cli_publish.sh: publish @qrun-io/qqq-core; the image to a current cimg/node:22.x, plus a Node 20 run of npm 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.