cueapril 0.0.0-stage → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +173 -2
- package/agents.mjs +996 -0
- package/cli.mjs +4 -0
- package/client.mjs +360 -0
- package/commands.mjs +1273 -0
- package/doctor.mjs +186 -0
- package/http.mjs +263 -0
- package/init.mjs +635 -0
- package/io.mjs +379 -0
- package/key-store.mjs +287 -0
- package/login.mjs +601 -0
- package/package.json +39 -4
- package/skill/cueapril-qa/SKILL.md +90 -0
package/README.md
CHANGED
|
@@ -1,3 +1,174 @@
|
|
|
1
|
-
#
|
|
1
|
+
# CueApril CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`cueapril` asks CueApril to assess a GitHub pull request, waits for the outcome and exits with a code that a coding agent (Claude Code, Codex, Gemini CLI) or a CI job can branch on. It reads findings, suggested fixes, coverage and evidence links, and prints MCP configuration for agent clients.
|
|
4
|
+
|
|
5
|
+
It needs Node.js 20 or later and has no dependencies.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Run it without installing:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npx -y cueapril@latest --help
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Or install it once:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install -g cueapril
|
|
19
|
+
cueapril --help
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The public npm package is `cueapril`. `pnpm dlx cueapril`, `bunx cueapril` and `yarn dlx cueapril` work too. Python users can use `uvx cueapril init` or `pipx install cueapril`; Python 3.10+ and an installed Node.js 20+ are required. The examples below write `cueapril` for any form. A versioned fallback download is available at https://app.cueapril.com/downloads/cueapril-cli-1.2.0.tgz.
|
|
23
|
+
|
|
24
|
+
## Set up (an agent can do this itself)
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
cueapril init
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
A coding agent can follow this single prompt:
|
|
31
|
+
|
|
32
|
+
> Install CueApril from the public `cueapril` npm package and connect it to this coding agent. Use `CUEAPRIL_API_KEY` if already supplied. Otherwise run `npx -y cueapril@latest init --no-login --json` and ask me to supply a CueApril API key through a secret manager or secure local input, or offer browser approval with `init --no-wait --no-browser --json`. Never ask me to paste a key into chat. Complete init, run doctor, and report any remaining project setup steps without starting a paid assessment.
|
|
33
|
+
|
|
34
|
+
For an existing key, set `CUEAPRIL_API_KEY` through your secret manager and run `init --no-login --json`, or pipe the secret manager's output into `cueapril init --key-stdin --json`. `--key-stdin` accepts one complete key, verifies read access, then saves it privately. It refuses terminal input and conflicting browser or environment credentials; it never accepts a key as a command-line argument. Add `--dry-run` to verify and preview without saving.
|
|
35
|
+
|
|
36
|
+
For browser approval in a short agent shell, run `cueapril init --no-wait --no-browser --json`. Exit 4 and `login.status: "pending"` mean approval is still required. Give the person `login.verification_url` and `login.code`; after approval execute `login.resume_command` for npm, or `login.resume_commands.pypi` for uvx. The `next_actions` entries include `commands.npm`, `commands.pypi`, `commands.installed` and logical CLI `argv` so agents can reuse their installer. Repeating the pending command reuses the same request. With no key, `init --no-login --json` returns exit 5, `login.status: "auth_required"` and structured `next_actions`; it changes nothing.
|
|
37
|
+
|
|
38
|
+
`init` gets a key by one browser approval if none is stored: it prints a link and a code, an organisation owner or admin opens the link, checks the code and approves, and the key is saved in your user configuration (`~/.config/cueapril/credentials.json`, mode 0600, never inside a repository, even through a symbolic link). It then checks the project's setup and prints a link for anything a person must do, adds the `cueapril` MCP server to Claude Code, Codex, Gemini CLI and Cursor at user level (backing up any file it edits), and installs the `cueapril-qa` skill. Claude Code's entry is added with `claude mcp add-json` and holds no key: its `headersHelper` reads the key from `~/.config/cueapril/claude-code-headers.json` (mode 0600) each time Claude Code connects. Re-running it changes nothing. Useful flags: `--agents claude,codex`, `--scope project` (installs the skill in this repository), `--dry-run`, `--json`.
|
|
39
|
+
|
|
40
|
+
| Command | What it does |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `cueapril login [--name <label>] [--no-browser] [--no-wait]` | Only the browser approval, storing the key. `--no-wait` prints the link and returns; the next `login` or `init` resumes the same request. |
|
|
43
|
+
| `cueapril login --key-stdin [--json]` | Verifies and privately stores an existing agent key from a pipe. |
|
|
44
|
+
| `cueapril doctor [--project <id>] [--json]` | Checks the API, the key, readiness, agent configuration and the skill. Supply `--project` when the key covers several projects. Exit 0 when nothing fails. |
|
|
45
|
+
| `cueapril logout [--local]` | Revokes the stored key on CueApril and deletes it here (`--local` only deletes it here). |
|
|
46
|
+
|
|
47
|
+
## Configure
|
|
48
|
+
|
|
49
|
+
| Variable | Meaning |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `CUEAPRIL_API_KEY` | Agent key, `cueapril_sk_...`, from `cueapril login` or created by an organisation admin in the CueApril web app settings (projects, scopes, expiry and optional spend cap). Falls back to `TENHAW_TOKEN`, then to the key stored by `login` or `init`. |
|
|
52
|
+
| `CUEAPRIL_URL` | API origin. Default `https://app.cueapril.com`. Falls back to `TENHAW_URL`. |
|
|
53
|
+
|
|
54
|
+
The key is read from the environment, the user store or an explicit `--key-stdin` pipe, sent only as `Authorization: Bearer`, never printed or logged, and never passed on a command line; only `login` and `init` write it, to the user store and user-level agent configuration (files of mode 0600, outside any repository). Keep it in your CI secret store. Starting an assessment needs the `quality:run` scope and cancelling needs `quality:cancel`; reading needs `quality:read`.
|
|
55
|
+
|
|
56
|
+
The CLI talks only to HTTPS origins (plain HTTP only on `localhost`), refuses redirects, caps response size at 10 MB and identifies itself with `X-CueApril-Client: cli/1.2.0`.
|
|
57
|
+
|
|
58
|
+
## Commands
|
|
59
|
+
|
|
60
|
+
| Command | What it does |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `cueapril assess --pr <number\|url> [--project <id>] [--wait] [--timeout <minutes>] [--idempotency-key <key>] [--json]` | Starts an assessment of the pull request under the project's approved standing plan. With `--wait` it waits for the outcome (default 90 minutes) and exits with its code. |
|
|
63
|
+
| `cueapril status <assessment-id>` <br> `cueapril status --pr <number> [--project <id>]` <br> `cueapril status --commit <full-sha> [--project <id>]` | Shows one assessment: outcome, verdict, gate, task counts and up to ten failures with expected and observed values. `--commit` takes the full 40- or 64-character SHA of the tested head (`git rev-parse HEAD`), not a short one. Add `--project` when the key covers several projects. |
|
|
64
|
+
| `cueapril wait <assessment-id> [--timeout <minutes>] [--json]` | Waits until the assessment finishes. |
|
|
65
|
+
| `cueapril results <assessment-id> [--limit <1-50>] [--all] [--sections findings,fixes,coverage,evidence] [--json]` | Findings, suggested fixes (changed lines only), coverage by test method and evidence links. `--all` reads every page. |
|
|
66
|
+
| `cueapril cancel <assessment-id> [--reason <text>] [--idempotency-key <key>]` | Asks CueApril to stop an assessment. |
|
|
67
|
+
| `cueapril setup [--project <id>]` | Checks that a project is ready to assess pull requests and says what to fix, and who owns the fix. |
|
|
68
|
+
| `cueapril list [--project <id>] [--pr <number>] [--limit <1-20>]` | Recent assessments. |
|
|
69
|
+
| `cueapril projects` | Projects the key can see. |
|
|
70
|
+
| `cueapril mcp-config [--client claude\|codex\|gemini\|cursor\|vscode]` | Prints MCP client configuration that reads the key from `CUEAPRIL_API_KEY`. Makes no network request. |
|
|
71
|
+
| `cueapril tool <tool-name> [--data '<json>' \| --file <path> \| --stdin]` | Calls any CueApril agent tool, for example `cueapril_get_run` (or `get_run`). |
|
|
72
|
+
|
|
73
|
+
`cueapril <command> --help` shows one command; `cueapril help legacy` lists the older dotted actions.
|
|
74
|
+
|
|
75
|
+
Assessment commands call `POST <CUEAPRIL_URL>/api/v1/quality/agent-tools/<tool>`, the REST form of the CueApril MCP tools, so the CLI, MCP and REST give the same answers. `init`, `login`, `logout` and `doctor` also manage local credentials or client configuration; `mcp-config` only prints configuration.
|
|
76
|
+
|
|
77
|
+
## Exit codes
|
|
78
|
+
|
|
79
|
+
| Code | Meaning |
|
|
80
|
+
| --- | --- |
|
|
81
|
+
| 0 | passed |
|
|
82
|
+
| 1 | failed: a check failed or the gate blocked the pull request |
|
|
83
|
+
| 2 | incomplete or cancelled: CueApril could not finish; this is not a product failure |
|
|
84
|
+
| 3 | blocked: the start was refused, or `setup` found the project not ready |
|
|
85
|
+
| 4 | still running: `--timeout` passed, or the command did not wait |
|
|
86
|
+
| 5 | usage, authentication or API error |
|
|
87
|
+
|
|
88
|
+
`assess`, `status`, `wait` and `results` exit 0 only when the assessment passed. `assess` without `--wait` exits 4 once the assessment is accepted, because it has not finished. `cancel`, `list`, `projects`, `mcp-config` and `tool` exit 0 when the request succeeded.
|
|
89
|
+
|
|
90
|
+
## Output
|
|
91
|
+
|
|
92
|
+
By default the CLI prints a summary for people: outcome, verdict, gate, task counts, the first failures with expected and observed values, suggested fix locations and a link to the assessment in the web app.
|
|
93
|
+
|
|
94
|
+
Assessment commands with `--json` print exactly one JSON object on stdout, the final tool result plus `"exit_code"`, and nothing else. Errors become `{"error": {"message": ...}, "exit_code": 5}`. `init --json` prints one setup summary with `exit_code` and `next_actions`; device `login --json` prints event JSON lines. Progress and error messages always go to stderr, so output can be parsed by an agent.
|
|
95
|
+
|
|
96
|
+
### On GitHub
|
|
97
|
+
|
|
98
|
+
The CueApril pull request comment ends with a collapsed `<details>` section, after the marker `<!-- cueapril:assessment:v1 -->`, holding a fenced `json` object with schema `cueapril.assessment.v1`: `assessment_id`, `project_id`, `repository`, `pull_request`, `head_sha`, `base_sha`, `lifecycle`, `outcome`, `verdict`, `gate_decision`, `counts`, up to ten `failures`, suggested fix metadata, `next` (the MCP tool and REST call that return the full results) and `ui`. The `CueApril` check run carries the same block in its output text. Anyone who can comment can post a look-alike, so trust a comment only if its author is `cue-april[bot]`, or read the check run whose `app.slug` is `cue-april`, and never send your key to an address taken from GitHub. An agent that reads a trusted block can go straight to `cueapril results <assessment_id>`.
|
|
99
|
+
|
|
100
|
+
## Waiting
|
|
101
|
+
|
|
102
|
+
`--wait` and `wait` long-poll `cueapril_wait_for_assessment`, which answers as soon as the assessment finishes and holds each call for at most 50 seconds. While waiting the CLI writes a progress line to stderr at least once a minute (Gemini CLI stops a shell command after five minutes of silence). When `--timeout` passes it exits 4 and prints the command that resumes the wait; the assessment itself keeps running. Interrupting the CLI never cancels an assessment.
|
|
103
|
+
|
|
104
|
+
Agent shells often stop a command after a few minutes. Wait in slices instead: start with `cueapril assess --pr 42` (exit 4 once accepted), then repeat `cueapril wait <assessment-id> --timeout 4` while it exits 4. The MCP tool `cueapril_wait_for_assessment` holds each call for at most 50 seconds for the same reason.
|
|
105
|
+
|
|
106
|
+
## Retries
|
|
107
|
+
|
|
108
|
+
- Reads are retried after network errors and HTTP 429, 502, 503, 504, 522 and 524, with backoff of 1, 2, 4 and 8 seconds (longer when the server sends `Retry-After`). While waiting, they are retried until the timeout.
|
|
109
|
+
- `assess` resends the identical request: with your `--idempotency-key`, or with none, in which case the server derives the key from the pull request head. Sending it again for the same head never starts a second run. The CLI never invents a random key.
|
|
110
|
+
- `cancel` and `tool` are never resent automatically. If their outcome is unknown, check with `cueapril status` and run them again.
|
|
111
|
+
|
|
112
|
+
## Examples
|
|
113
|
+
|
|
114
|
+
A coding agent starts an assessment of its pull request and branches on the result:
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
export CUEAPRIL_API_KEY=cueapril_sk_...
|
|
118
|
+
cueapril assess --pr 42 --wait --json > assessment.json
|
|
119
|
+
case $? in
|
|
120
|
+
0) echo "passed" ;;
|
|
121
|
+
1) cueapril results "$(jq -r .assessment_id assessment.json)" --sections findings,fixes ;;
|
|
122
|
+
4) echo "still running: cueapril wait $(jq -r .assessment_id assessment.json)" ;;
|
|
123
|
+
*) echo "incomplete, blocked or error" ;;
|
|
124
|
+
esac
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Look an assessment up later from any session:
|
|
128
|
+
|
|
129
|
+
```sh
|
|
130
|
+
cueapril status --pr 42
|
|
131
|
+
cueapril results <assessment-id> --all
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
GitHub Actions, on `pull_request`:
|
|
135
|
+
|
|
136
|
+
```yaml
|
|
137
|
+
jobs:
|
|
138
|
+
cueapril:
|
|
139
|
+
runs-on: ubuntu-latest
|
|
140
|
+
steps:
|
|
141
|
+
- name: CueApril assessment
|
|
142
|
+
timeout-minutes: 100
|
|
143
|
+
env:
|
|
144
|
+
CUEAPRIL_API_KEY: ${{ secrets.CUEAPRIL_API_KEY }}
|
|
145
|
+
run: >-
|
|
146
|
+
npx -y cueapril@latest assess --pr ${{ github.event.pull_request.number }} --wait --timeout 90
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Connect an MCP client instead of shelling out:
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
cueapril init --agents claude,codex # edits each agent's user settings in place; safe to rerun
|
|
153
|
+
cueapril mcp-config --client claude # print .mcp.json for Claude Code
|
|
154
|
+
cueapril mcp-config --client codex # print the Codex tables to merge by hand
|
|
155
|
+
cueapril mcp-config # every client
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Merge printed configuration into the file by hand. If `~/.codex/config.toml` already has an `[mcp_servers.cueapril]` table (for example from `init`), edit that table instead: appending a second copy makes Codex refuse to start. `mcp-config --client codex` warns when the table is already there.
|
|
159
|
+
|
|
160
|
+
## Legacy dotted actions
|
|
161
|
+
|
|
162
|
+
Commands written for the earlier `tenhaw-quality` binary still work under both names, for example `cueapril runs.get --data '{"id":"run-id"}'` or `tenhaw-quality projects.list`. Arguments are one JSON object from `--data`, `--file` or `--stdin` (use `--stdin` for sensitive input). By default an action calls the `cueapril_` agent tool of the same name. `TENHAW_AUTH_MODE=human` calls the native REST routes with a signed-in person's session token instead; human-only operations such as approvals, source review and administrator actions work only in that mode. Mutations take an explicit `idempotency_key`; reuse it when retrying an uncertain outcome. Errors print a JSON object on stderr and exit 5. `cueapril help legacy` lists every action.
|
|
163
|
+
|
|
164
|
+
`developer_review.export --data '<json>' --output reviewed.patch` saves an independently approved patch after checking its SHA-256, and never overwrites an existing file.
|
|
165
|
+
|
|
166
|
+
## Development
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
npm run test --workspace=@tenhaw/quality-cli # fake transports and a localhost server only
|
|
170
|
+
node scripts/quality/pack-cli.mjs # rebuild webapp/public/downloads/cueapril-cli-<version>.tgz
|
|
171
|
+
node scripts/quality/pack-cli.mjs --check # fail if the committed tarball is stale
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The root `.gitignore` ignores `*.tgz`, so add a new tarball with `git add -f`. A test runs the check, so CI fails when the served tarball no longer matches these sources. To release a new version, change `version` in `package.json`, `CLI_VERSION` in `client.mjs` and the download URLs in this README together (a test checks they agree), then rebuild the tarball.
|