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
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cueapril-qa
|
|
3
|
+
description: Test a GitHub pull request with CueApril's hosted QA and act on the verdict. Use right after you push commits to a branch that has an open pull request, after opening a pull request, when asked to QA, test or verify a pull request with CueApril, or when a CueApril check or comment reports a failure. Checks setup (cueapril doctor and init), starts the assessment, waits for it without wasting tokens, reads the failures and suggested fixes, and fixes them before pushing again.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CueApril QA
|
|
7
|
+
|
|
8
|
+
CueApril tests a pull request in a disposable VM under a test plan the team approved, then returns a verdict, the failures, suggested fixes, coverage and evidence. You check setup once, start an assessment, wait for it, read the results and fix what failed. Full guide: https://app.cueapril.com/agents/README.md
|
|
9
|
+
|
|
10
|
+
## 1. Check setup first
|
|
11
|
+
|
|
12
|
+
Once per session, before relying on CueApril, run:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npx -y cueapril@latest doctor
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
If it reports a problem, run:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npx -y cueapril@latest init
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`init` connects this computer to CueApril, adds the `cueapril` MCP server to the coding agents it finds (user level only, never inside the repository) and installs this skill. If it needs a key it prints a link and a code, and may open a browser. Give the person the link and the code exactly as printed and ask them to approve; an organisation owner or admin must do it, once.
|
|
25
|
+
|
|
26
|
+
- If the person wants to supply an API key, run `npx -y cueapril@latest init --no-login --json`. Missing credentials return exit 5, `login.status: "auth_required"` and `next_actions`. Ask for secure local input or a secret manager setting `CUEAPRIL_API_KEY`, never a key in chat. A secret manager can pipe the key to `npx -y cueapril@latest init --key-stdin --json`; the CLI verifies and stores it without printing it. Do not run `echo <key>` or put a literal key on a command line.
|
|
27
|
+
- If your shell stops long commands, run `npx -y cueapril@latest init --no-wait --no-browser --json` first. Exit 4, `login.status: "pending"` and `next_actions` identify the approval step. Give the person `login.verification_url` and `login.code`, then execute `login.resume_command` after approval (`login.resume_commands.pypi` when using uvx). Reuse your installer; npx and uvx do not install a persistent `cueapril` executable. It resumes the same request, so the link stays valid. Rerunning `init` after a timeout also resumes it.
|
|
28
|
+
- If `init` or `doctor` lists setup steps with links (for example installing the GitHub App), pass them to the person. Only they can do these in the browser.
|
|
29
|
+
- New MCP servers load when the agent restarts. If the `cueapril_*` tools are missing in this session, use the CLI (section 3).
|
|
30
|
+
- The public npm package is `cueapril`; `pnpm dlx cueapril`, `bunx cueapril` and `yarn dlx cueapril` also work. PyPI's `cueapril` package uses the same CLI: `uvx cueapril init` (Python 3.10+ and installed Node.js 20+).
|
|
31
|
+
|
|
32
|
+
## 2. The loop with MCP tools
|
|
33
|
+
|
|
34
|
+
1. **Start.** First call `cueapril_get_assessment` with `{"pull_request": <number>}`. If its `head_sha` is the commit you pushed, CueApril is already testing it: use that `assessment_id` and go to step 2. Otherwise call `cueapril_start_assessment` with `{"pull_request": <number>}` or `{"pull_request_url": "<url>"}`. Add `project_id` only if the key covers more than one project. Repeating the start for the same head commit is safe; it returns the same assessment.
|
|
35
|
+
- `status: "accepted"`: keep `assessment_id` and go to step 2.
|
|
36
|
+
- `status: "blocked"`: do not retry in a loop. Tell the person each blocker's `message`, its `owner` (`customer` means their team, `platform` means CueApril) and its `fix_url`, and suggest `cueapril_check_setup`. Stop. Agent keys start assessments only under the project's approved standing plan, so `human_start_required` or `plan_required` usually means a project owner must turn on Test every commit.
|
|
37
|
+
2. **Wait.** Call `cueapril_wait_for_assessment` with `{"assessment_id": "<id>"}`. It returns as soon as the assessment finishes, and never later than 50 seconds. While `still_running` is true, call it again straight away.
|
|
38
|
+
3. **Read.** When `terminal` is true, branch on `outcome` (section 5). For failures, call `cueapril_get_assessment_results` with `{"assessment_id": "<id>", "sections": ["findings", "fixes"]}` and follow `next_cursor` to page.
|
|
39
|
+
4. **Fix and push** (section 6), then go back to step 1 for the new head commit.
|
|
40
|
+
|
|
41
|
+
Also available: `cueapril_check_setup`, `cueapril_list_assessments`, `cueapril_list_projects`, `cueapril_cancel_assessment` and `cueapril_get_costs`.
|
|
42
|
+
|
|
43
|
+
## 3. The loop with the CLI
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx -y cueapril@latest assess --pr 123 --wait --json
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
It starts (or reuses) the assessment for pull request 123, waits, prints machine-readable results and sets the exit code in section 7. It uses the key that `init` stored, or `CUEAPRIL_API_KEY`. Run `npx -y cueapril@latest --help` for status, wait, results and cancel. Give it a long timeout, or run it in the background and read its JSON when it exits.
|
|
50
|
+
|
|
51
|
+
## 4. Wait without wasting tokens
|
|
52
|
+
|
|
53
|
+
- An assessment takes 20 to 75 minutes. Use `cueapril_wait_for_assessment` or the CLI's `--wait`, not repeated `cueapril_get_assessment` calls, and do not add your own sleeps.
|
|
54
|
+
- Do not narrate each wait. One short progress line every few minutes is enough, or none. Carry on with other work if you can.
|
|
55
|
+
- If you must stop before it finishes, tell the person the `assessment_id` and `links.ui` so the assessment can be picked up later with `cueapril_get_assessment`.
|
|
56
|
+
- Run one assessment at a time for a pull request. A new push supersedes the previous one.
|
|
57
|
+
|
|
58
|
+
## 5. Outcomes
|
|
59
|
+
|
|
60
|
+
- `queued`, `running`: not finished. Keep waiting.
|
|
61
|
+
- `passed`: the assessment completed and the gate allows the pull request. Report it with `links.ui`.
|
|
62
|
+
- `failed`: checks failed, or the gate blocks the pull request. Read the results and fix them.
|
|
63
|
+
- `incomplete`: the assessment ended without a full verdict, for example an infrastructure error, a timeout or missing required coverage. **This is not a pass.** Report `reason`. Starting again for the same head commit returns this same assessment (`duplicate: true`), so do not retry. If the reason points to a temporary problem, ask the person to rerun it from the assessment page (`links.ui`), or push a new commit.
|
|
64
|
+
- `cancelled`: someone or something cancelled it. It is not a pass either. Report `reason` if there is one.
|
|
65
|
+
|
|
66
|
+
## 6. Act on failures
|
|
67
|
+
|
|
68
|
+
1. For each failed finding, read `expected`, `observed`, `file`, `line` and `reproduction`.
|
|
69
|
+
2. A suggested fix holds only the changed lines: `path`, `start_line`, `end_line`, `original` and `replacement`. It is not verified (`verified: false`), so apply it only when it is right for the code, and run the relevant tests locally.
|
|
70
|
+
3. Commit and push to the same branch. Test every commit starts the next assessment for the new head commit; go back to section 2, step 1, which finds it. Then wait again.
|
|
71
|
+
4. Never weaken, skip, delete or rewrite tests or expectations to get a pass. Fix the code, or explain why the expectation is wrong and let a person decide. Surviving mutants are reported as test gaps; they do not block unless the team set a minimum mutation score.
|
|
72
|
+
|
|
73
|
+
## 7. CLI exit codes
|
|
74
|
+
|
|
75
|
+
| Exit code | Meaning |
|
|
76
|
+
|---|---|
|
|
77
|
+
| 0 | `passed` |
|
|
78
|
+
| 1 | `failed` |
|
|
79
|
+
| 2 | `incomplete` (never a pass) |
|
|
80
|
+
| 2 | `cancelled` (never a pass) |
|
|
81
|
+
| 3 | `blocked`: CueApril listed blockers, for example Test every commit is off, or setup or funding needs attention |
|
|
82
|
+
| 4 | `timeout`: the CLI stopped waiting; the assessment is still running, so wait again |
|
|
83
|
+
| 5 | `error`: for example a missing, expired or revoked key, a key without the permission or project the call needs (HTTP 403), or no connection |
|
|
84
|
+
|
|
85
|
+
## 8. Keep the key secret
|
|
86
|
+
|
|
87
|
+
- Never print, echo, log or commit the CueApril key, and never put it in a prompt, pull request, issue or chat. `init` keeps it in the person's user configuration and the agents' MCP settings, never in the repository.
|
|
88
|
+
- Do not open credential or MCP configuration files to read the key. `npx -y cueapril@latest doctor` reports what is configured, with the key masked.
|
|
89
|
+
- If a tool says the key is missing, expired or revoked, run `npx -y cueapril@latest init` (it asks for a new approval); do not search for a key. If a call is refused as not allowed (HTTP 403), the key lacks that permission or does not cover the project, and `init` would keep the same key: tell the person that an organisation owner or admin must approve a key with Run assessments access to this project. If a key may have leaked, run `npx -y cueapril@latest logout`, which revokes it, then `init`.
|
|
90
|
+
- Each assessment reserves at most 300p (£3.00), and the key may carry a 30-day spend cap.
|