cueapril 1.1.0 → 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 +18 -10
- package/client.mjs +3 -7
- package/commands.mjs +4 -1
- package/doctor.mjs +12 -5
- package/init.mjs +52 -7
- package/key-store.mjs +40 -0
- package/login.mjs +41 -2
- package/package.json +1 -1
- package/skill/cueapril-qa/SKILL.md +9 -8
package/README.md
CHANGED
|
@@ -9,17 +9,17 @@ It needs Node.js 20 or later and has no dependencies.
|
|
|
9
9
|
Run it without installing:
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
|
-
npx -y
|
|
12
|
+
npx -y cueapril@latest --help
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
Or install it once:
|
|
16
16
|
|
|
17
17
|
```sh
|
|
18
|
-
npm install -g
|
|
18
|
+
npm install -g cueapril
|
|
19
19
|
cueapril --help
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
The
|
|
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
23
|
|
|
24
24
|
## Set up (an agent can do this itself)
|
|
25
25
|
|
|
@@ -27,12 +27,21 @@ The examples below write `cueapril` for either form. Once the unscoped `cueapril
|
|
|
27
27
|
cueapril init
|
|
28
28
|
```
|
|
29
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
|
+
|
|
30
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`.
|
|
31
39
|
|
|
32
40
|
| Command | What it does |
|
|
33
41
|
| --- | --- |
|
|
34
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. |
|
|
35
|
-
| `cueapril
|
|
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. |
|
|
36
45
|
| `cueapril logout [--local]` | Revokes the stored key on CueApril and deletes it here (`--local` only deletes it here). |
|
|
37
46
|
|
|
38
47
|
## Configure
|
|
@@ -42,9 +51,9 @@ cueapril init
|
|
|
42
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`. |
|
|
43
52
|
| `CUEAPRIL_URL` | API origin. Default `https://app.cueapril.com`. Falls back to `TENHAW_URL`. |
|
|
44
53
|
|
|
45
|
-
The key is read from the environment
|
|
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`.
|
|
46
55
|
|
|
47
|
-
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.
|
|
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`.
|
|
48
57
|
|
|
49
58
|
## Commands
|
|
50
59
|
|
|
@@ -63,7 +72,7 @@ The CLI talks only to HTTPS origins (plain HTTP only on `localhost`), refuses re
|
|
|
63
72
|
|
|
64
73
|
`cueapril <command> --help` shows one command; `cueapril help legacy` lists the older dotted actions.
|
|
65
74
|
|
|
66
|
-
|
|
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.
|
|
67
76
|
|
|
68
77
|
## Exit codes
|
|
69
78
|
|
|
@@ -82,7 +91,7 @@ Every command except `mcp-config` calls `POST <CUEAPRIL_URL>/api/v1/quality/agen
|
|
|
82
91
|
|
|
83
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.
|
|
84
93
|
|
|
85
|
-
|
|
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.
|
|
86
95
|
|
|
87
96
|
### On GitHub
|
|
88
97
|
|
|
@@ -134,8 +143,7 @@ jobs:
|
|
|
134
143
|
env:
|
|
135
144
|
CUEAPRIL_API_KEY: ${{ secrets.CUEAPRIL_API_KEY }}
|
|
136
145
|
run: >-
|
|
137
|
-
npx -y --
|
|
138
|
-
cueapril assess --pr ${{ github.event.pull_request.number }} --wait --timeout 90
|
|
146
|
+
npx -y cueapril@latest assess --pr ${{ github.event.pull_request.number }} --wait --timeout 90
|
|
139
147
|
```
|
|
140
148
|
|
|
141
149
|
Connect an MCP client instead of shelling out:
|
package/client.mjs
CHANGED
|
@@ -1,15 +1,11 @@
|
|
|
1
1
|
import { randomUUID } from 'node:crypto';
|
|
2
2
|
|
|
3
|
-
export const CLI_VERSION = '1.
|
|
3
|
+
export const CLI_VERSION = '1.2.0';
|
|
4
4
|
export const CLIENT_IDENTIFIER = `cli/${CLI_VERSION}`;
|
|
5
5
|
export const USER_AGENT = `cueapril-cli/${CLI_VERSION}`;
|
|
6
6
|
export const DEFAULT_BASE_URL = 'https://app.cueapril.com';
|
|
7
|
-
/**
|
|
8
|
-
|
|
9
|
-
* published it is installed from the web app's tarball; afterwards this becomes
|
|
10
|
-
* 'npx -y cueapril@latest'.
|
|
11
|
-
*/
|
|
12
|
-
export const RUN_COMMAND = `npx -y --package=${DEFAULT_BASE_URL}/downloads/cueapril-cli-${CLI_VERSION}.tgz cueapril`;
|
|
7
|
+
/** The public package-manager entry point for people and coding agents. */
|
|
8
|
+
export const RUN_COMMAND = 'npx -y cueapril@latest';
|
|
13
9
|
export const AGENT_TOOL_PREFIX = 'cueapril_';
|
|
14
10
|
/** Older clients called tools with this prefix; the server still accepts it on calls. */
|
|
15
11
|
export const LEGACY_AGENT_TOOL_PREFIX = 'tenhaw_';
|
package/commands.mjs
CHANGED
|
@@ -1092,9 +1092,12 @@ Setup (a coding agent can run these itself; a person approves once in the browse
|
|
|
1092
1092
|
cueapril init [--agents auto|claude,codex,gemini,cursor] [--scope user|project]
|
|
1093
1093
|
Get a key by browser approval if none is stored, check readiness, configure Claude Code,
|
|
1094
1094
|
Codex, Gemini CLI and Cursor at user level, and install the cueapril-qa skill.
|
|
1095
|
+
--no-login --json returns auth_required with next_actions when a key is missing.
|
|
1096
|
+
--key-stdin verifies and stores an existing key from a pipe; --no-wait returns an approval link.
|
|
1095
1097
|
cueapril login [--name <label>] [--no-browser] [--no-wait]
|
|
1096
1098
|
Approve an agent key in the browser and store it for this user (never printed).
|
|
1097
|
-
|
|
1099
|
+
Or use login --key-stdin to import a key from a secret manager's output.
|
|
1100
|
+
cueapril doctor [--project <id>]
|
|
1098
1101
|
Check the API, the key, readiness, agent configuration and the skill.
|
|
1099
1102
|
cueapril logout
|
|
1100
1103
|
Revoke the stored key on CueApril and delete it here.
|
package/doctor.mjs
CHANGED
|
@@ -10,13 +10,15 @@ import { describeKeySource, maskKey, resolveApiKey } from './key-store.mjs';
|
|
|
10
10
|
import { inspectAgents } from './agents.mjs';
|
|
11
11
|
import { CHECK_SETUP_TOOL, bundledSkillPath, skillTargets, summariseSetup } from './init.mjs';
|
|
12
12
|
|
|
13
|
-
export const DOCTOR_USAGE = `Usage: cueapril doctor [--json]
|
|
13
|
+
export const DOCTOR_USAGE = `Usage: cueapril doctor [--project <id>] [--json]
|
|
14
14
|
|
|
15
15
|
Checks the CueApril server URL, your key (masked), the API health, whether the
|
|
16
16
|
key is accepted, which coding agents have a CueApril MCP entry and whether the
|
|
17
|
-
cueapril-qa skill is installed.
|
|
17
|
+
cueapril-qa skill is installed. Use --project when the key covers several
|
|
18
|
+
projects. Exit 0 when nothing fails, 5 otherwise.`;
|
|
18
19
|
|
|
19
20
|
const INIT_COMMAND = `${RUN_COMMAND} init`;
|
|
21
|
+
const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
|
|
20
22
|
const LABELS = {
|
|
21
23
|
server: 'Server',
|
|
22
24
|
key: 'Key',
|
|
@@ -38,15 +40,20 @@ function line(check) {
|
|
|
38
40
|
export async function runDoctor(argv = [], deps = {}) {
|
|
39
41
|
const io = defaultDeps(deps);
|
|
40
42
|
let flags;
|
|
43
|
+
let projectId;
|
|
41
44
|
try {
|
|
42
45
|
({ values: flags } = parseArgs({
|
|
43
46
|
args: argv,
|
|
44
47
|
allowPositionals: false,
|
|
45
48
|
strict: true,
|
|
46
|
-
options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
|
|
49
|
+
options: { json: { type: 'boolean' }, project: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
|
|
47
50
|
}));
|
|
51
|
+
if (flags.project !== undefined) {
|
|
52
|
+
projectId = String(flags.project).trim();
|
|
53
|
+
if (!PROJECT_ID.test(projectId)) throw new Error('--project must be a CueApril project id.');
|
|
54
|
+
}
|
|
48
55
|
} catch (error) {
|
|
49
|
-
writeLine(io.stderr, `${safeText(error.message)}\n\n${DOCTOR_USAGE}`);
|
|
56
|
+
writeLine(io.stderr, `${safeText(redact(error.message))}\n\n${DOCTOR_USAGE}`);
|
|
50
57
|
return { exitCode: EXIT.error, report: null };
|
|
51
58
|
}
|
|
52
59
|
if (flags.help) {
|
|
@@ -111,7 +118,7 @@ export async function runDoctor(argv = [], deps = {}) {
|
|
|
111
118
|
|
|
112
119
|
if (resolved) {
|
|
113
120
|
try {
|
|
114
|
-
const raw = await client.callTool(CHECK_SETUP_TOOL, {}, resolved.key, { timeoutMs: 30_000 });
|
|
121
|
+
const raw = await client.callTool(CHECK_SETUP_TOOL, projectId ? { project_id: projectId } : {}, resolved.key, { timeoutMs: 30_000 });
|
|
115
122
|
const setup = summariseSetup(raw, baseUrl);
|
|
116
123
|
add('key_valid', 'ok', `Accepted${setup.organisation ? ` for ${setup.organisation}` : ''}`);
|
|
117
124
|
if (setup.ready) {
|
package/init.mjs
CHANGED
|
@@ -30,7 +30,7 @@ import {
|
|
|
30
30
|
import { createHttpClient, resolveBaseUrl } from './http.mjs';
|
|
31
31
|
import { RUN_COMMAND } from './client.mjs';
|
|
32
32
|
import { describeKeySource, maskKey, resolveApiKey } from './key-store.mjs';
|
|
33
|
-
import { runLogin } from './login.mjs';
|
|
33
|
+
import { importApiKey, runLogin } from './login.mjs';
|
|
34
34
|
import { AGENT_NAMES, applyAgentChanges, detectAgents, parseAgentList, planAgentChanges } from './agents.mjs';
|
|
35
35
|
|
|
36
36
|
export const CHECK_SETUP_TOOL = 'cueapril_check_setup';
|
|
@@ -40,6 +40,7 @@ const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
|
|
|
40
40
|
|
|
41
41
|
export const INIT_USAGE = `Usage: cueapril init [--agents auto|none|claude,codex,gemini,cursor] [--scope user|project]
|
|
42
42
|
[--project <id>] [--dry-run] [--yes] [--no-login] [--json]
|
|
43
|
+
[--key-stdin | --no-wait]
|
|
43
44
|
[--name <label>] [--no-browser] [--timeout <minutes>]
|
|
44
45
|
|
|
45
46
|
Sets CueApril up for this computer and its coding agents:
|
|
@@ -54,11 +55,13 @@ Sets CueApril up for this computer and its coding agents:
|
|
|
54
55
|
--dry-run Show what would change, with the key masked; change nothing
|
|
55
56
|
--yes Do not ask for confirmation in a terminal
|
|
56
57
|
--no-login Fail instead of starting a browser approval when no key is found
|
|
58
|
+
--key-stdin Verify and store an existing agent key from a pipe; never argv or chat
|
|
59
|
+
--no-wait Return the approval link immediately (exit 4); rerun without this flag
|
|
57
60
|
--json Print one JSON object on stdout
|
|
58
61
|
--name, --no-browser, --timeout Passed to the login step (see cueapril login --help)
|
|
59
62
|
|
|
60
63
|
Rerunning init is safe. Exit codes: 0 set up (even if a project still needs
|
|
61
|
-
setup steps), 4 approval timed out, 5 error.`;
|
|
64
|
+
setup steps), 4 approval pending or timed out, 5 error.`;
|
|
62
65
|
|
|
63
66
|
export function bundledSkillPath() {
|
|
64
67
|
return fileURLToPath(new URL(`./skill/${SKILL_NAME}/SKILL.md`, import.meta.url));
|
|
@@ -227,6 +230,8 @@ function parseInitArgs(argv) {
|
|
|
227
230
|
'dry-run': { type: 'boolean' },
|
|
228
231
|
yes: { type: 'boolean', short: 'y' },
|
|
229
232
|
'no-login': { type: 'boolean' },
|
|
233
|
+
'key-stdin': { type: 'boolean' },
|
|
234
|
+
'no-wait': { type: 'boolean' },
|
|
230
235
|
json: { type: 'boolean' },
|
|
231
236
|
name: { type: 'string' },
|
|
232
237
|
'no-browser': { type: 'boolean' },
|
|
@@ -278,10 +283,19 @@ function loginArgs(flags) {
|
|
|
278
283
|
const args = [];
|
|
279
284
|
if (flags.name !== undefined) args.push('--name', flags.name);
|
|
280
285
|
if (flags['no-browser']) args.push('--no-browser');
|
|
286
|
+
if (flags['no-wait']) args.push('--no-wait');
|
|
281
287
|
if (flags.timeout !== undefined) args.push('--timeout', flags.timeout);
|
|
282
288
|
return args;
|
|
283
289
|
}
|
|
284
290
|
|
|
291
|
+
// npx and uvx do not create a permanent cueapril executable. Give agents a
|
|
292
|
+
// runnable default plus the matching Python installer and installed forms.
|
|
293
|
+
function installCommands(argv) {
|
|
294
|
+
const quote = (arg) => /^[A-Za-z0-9_.,:/=-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
|
|
295
|
+
const suffix = argv.map(quote).join(' ');
|
|
296
|
+
return { npm: `${RUN_COMMAND} ${suffix}`, pypi: `uvx cueapril ${suffix}`, installed: `cueapril ${suffix}` };
|
|
297
|
+
}
|
|
298
|
+
|
|
285
299
|
function agentPlanLine(item) {
|
|
286
300
|
const where = item.displayPath ?? item.path;
|
|
287
301
|
switch (item.action) {
|
|
@@ -346,7 +360,7 @@ export async function runInit(argv = [], deps = {}) {
|
|
|
346
360
|
try {
|
|
347
361
|
flags = parseInitArgs(argv);
|
|
348
362
|
} catch (error) {
|
|
349
|
-
writeLine(io.stderr, `${safeText(error.message)}\n\n${INIT_USAGE}`);
|
|
363
|
+
writeLine(io.stderr, `${safeText(redact(error.message))}\n\n${INIT_USAGE}`);
|
|
350
364
|
return { exitCode: EXIT.error, summary: null };
|
|
351
365
|
}
|
|
352
366
|
if (flags.help) {
|
|
@@ -373,6 +387,7 @@ export async function runInit(argv = [], deps = {}) {
|
|
|
373
387
|
restart: [],
|
|
374
388
|
next_prompt: NEXT_PROMPT,
|
|
375
389
|
messages: [],
|
|
390
|
+
next_actions: [],
|
|
376
391
|
};
|
|
377
392
|
const finish = (exitCode) => {
|
|
378
393
|
summary.exit_code = exitCode;
|
|
@@ -386,6 +401,10 @@ export async function runInit(argv = [], deps = {}) {
|
|
|
386
401
|
summary.base_url = baseUrl;
|
|
387
402
|
const scope = parseScope(flags.scope);
|
|
388
403
|
const wanted = parseAgentList(flags.agents);
|
|
404
|
+
if (flags['key-stdin'] && ['no-wait', 'no-browser', 'name', 'timeout'].some((name) => flags[name] !== undefined)) {
|
|
405
|
+
throw new CliError('--key-stdin cannot be combined with browser approval options.');
|
|
406
|
+
}
|
|
407
|
+
if (flags['no-wait'] && flags['no-login']) throw new CliError('--no-wait cannot be combined with --no-login.');
|
|
389
408
|
let projectId;
|
|
390
409
|
if (flags.project !== undefined) {
|
|
391
410
|
projectId = String(flags.project).trim();
|
|
@@ -393,7 +412,13 @@ export async function runInit(argv = [], deps = {}) {
|
|
|
393
412
|
}
|
|
394
413
|
|
|
395
414
|
// 1. Key.
|
|
396
|
-
let resolved
|
|
415
|
+
let resolved;
|
|
416
|
+
if (flags['key-stdin']) {
|
|
417
|
+
const imported = await importApiKey(io, { dryRun });
|
|
418
|
+
resolved = { key: imported.key, source: 'stdin', path: imported.credentialsPath, saved: imported.saved };
|
|
419
|
+
summary.login = { status: dryRun ? 'verified' : 'imported' };
|
|
420
|
+
if (imported.changed) summary.files_changed.push(displayPath(io, imported.credentialsPath));
|
|
421
|
+
} else resolved = await resolveApiKey(io, { baseUrl });
|
|
397
422
|
let loggedIn = false;
|
|
398
423
|
const login = async (reason) => {
|
|
399
424
|
if (reason) log(reason);
|
|
@@ -404,9 +429,22 @@ export async function runInit(argv = [], deps = {}) {
|
|
|
404
429
|
...(result.verificationUrl ? { verification_url: result.verificationUrl, code: result.code } : {}),
|
|
405
430
|
};
|
|
406
431
|
if (result.status !== 'approved' || !result.key) {
|
|
407
|
-
const code = result.exitCode === EXIT.timeout ? EXIT.timeout : EXIT.error;
|
|
432
|
+
const code = result.status === 'pending' || result.exitCode === EXIT.timeout ? EXIT.timeout : EXIT.error;
|
|
433
|
+
if (result.verificationUrl) {
|
|
434
|
+
const resumeArgv = ['init', ...argv.filter((arg) => arg !== '--no-wait')];
|
|
435
|
+
const commands = installCommands(resumeArgv);
|
|
436
|
+
const resumeCommand = commands.npm;
|
|
437
|
+
summary.login.resume_command = resumeCommand;
|
|
438
|
+
summary.login.resume_commands = commands;
|
|
439
|
+
summary.next_actions = [
|
|
440
|
+
{ action: 'approve_in_browser', owner: 'administrator', verification_url: result.verificationUrl, code: result.code },
|
|
441
|
+
{ action: 'resume_init', command: resumeCommand, commands, argv: resumeArgv },
|
|
442
|
+
];
|
|
443
|
+
}
|
|
408
444
|
summary.messages.push(
|
|
409
|
-
|
|
445
|
+
result.status === 'pending'
|
|
446
|
+
? 'Approval is required. Open the verification link, check the code, then run resume_command; it reuses this request.'
|
|
447
|
+
: code === EXIT.timeout
|
|
410
448
|
? 'Approval was not received in time. Run `cueapril init` again to keep waiting; the link and code stay the same.'
|
|
411
449
|
: 'Login did not complete.',
|
|
412
450
|
);
|
|
@@ -423,6 +461,13 @@ export async function runInit(argv = [], deps = {}) {
|
|
|
423
461
|
if (!resolved) {
|
|
424
462
|
if (dryRun) summary.login = { status: 'skipped', reason: 'dry run: no key yet; a real run asks for approval' };
|
|
425
463
|
else if (flags['no-login']) {
|
|
464
|
+
summary.login = { status: 'auth_required' };
|
|
465
|
+
const importCommands = installCommands(['init', '--key-stdin', '--json']);
|
|
466
|
+
const approvalCommands = installCommands(['init', '--no-wait', '--no-browser', '--json']);
|
|
467
|
+
summary.next_actions = [
|
|
468
|
+
{ action: 'provide_api_key', environment_variable: 'CUEAPRIL_API_KEY', secure_input_command: importCommands.npm, commands: importCommands, argv: ['init', '--key-stdin', '--json'], message: 'Supply the key through a secret manager or local secure input, never in chat.' },
|
|
469
|
+
{ action: 'browser_approval', command: approvalCommands.npm, commands: approvalCommands, argv: ['init', '--no-wait', '--no-browser', '--json'] },
|
|
470
|
+
];
|
|
426
471
|
throw new CliError('No CueApril key found. Set CUEAPRIL_API_KEY, run `cueapril login`, or run init without --no-login.');
|
|
427
472
|
} else resolved = await login();
|
|
428
473
|
}
|
|
@@ -584,7 +629,7 @@ export async function runInit(argv = [], deps = {}) {
|
|
|
584
629
|
} catch (error) {
|
|
585
630
|
const message = safeText(redact(error.message, key ? [key] : []), 500);
|
|
586
631
|
if (!error.reported) summary.messages.push(message);
|
|
587
|
-
log(`Error: ${message}`);
|
|
632
|
+
log(summary.login.status === 'pending' ? message : `Error: ${message}`);
|
|
588
633
|
return finish(error.exitCode ?? EXIT.error);
|
|
589
634
|
}
|
|
590
635
|
}
|
package/key-store.mjs
CHANGED
|
@@ -12,6 +12,7 @@ import {
|
|
|
12
12
|
defaultDeps,
|
|
13
13
|
homeDir,
|
|
14
14
|
isPosix,
|
|
15
|
+
isTTY,
|
|
15
16
|
pathFor,
|
|
16
17
|
safeText,
|
|
17
18
|
} from './io.mjs';
|
|
@@ -23,6 +24,45 @@ export const CREDENTIALS_FILE = 'credentials.json';
|
|
|
23
24
|
const FILE_VERSION = 1;
|
|
24
25
|
const MAX_FILE_BYTES = 1_000_000;
|
|
25
26
|
|
|
27
|
+
/** Read an explicitly supplied key without ever echoing it or taking it in argv. */
|
|
28
|
+
export async function readApiKeyStdin(deps = {}) {
|
|
29
|
+
const io = defaultDeps(deps);
|
|
30
|
+
if (isTTY(io.stdin)) {
|
|
31
|
+
throw new CredentialsError('--key-stdin needs a pipe, not a terminal. Supply the key through a secret manager or set CUEAPRIL_API_KEY; never paste it into chat.');
|
|
32
|
+
}
|
|
33
|
+
if (typeof io.stdin?.on !== 'function' || io.stdin.readableEnded || io.stdin.destroyed) {
|
|
34
|
+
throw new CredentialsError('--key-stdin needs a readable pipe containing one CueApril agent key.');
|
|
35
|
+
}
|
|
36
|
+
return new Promise((resolve, reject) => {
|
|
37
|
+
let input = '';
|
|
38
|
+
let settled = false;
|
|
39
|
+
const finish = (error) => {
|
|
40
|
+
if (settled) return;
|
|
41
|
+
settled = true;
|
|
42
|
+
clearTimeout(timer);
|
|
43
|
+
io.stdin.removeListener('data', onData);
|
|
44
|
+
io.stdin.removeListener('end', onEnd);
|
|
45
|
+
io.stdin.removeListener('error', onError);
|
|
46
|
+
io.stdin.pause?.();
|
|
47
|
+
if (error) return reject(error);
|
|
48
|
+
const key = input.trim();
|
|
49
|
+
if (!AGENT_KEY_PATTERN.test(key)) return reject(new CredentialsError('Standard input must contain exactly one complete CueApril agent key. Nothing was saved.'));
|
|
50
|
+
resolve(key);
|
|
51
|
+
};
|
|
52
|
+
const onData = (chunk) => {
|
|
53
|
+
input += String(chunk);
|
|
54
|
+
if (Buffer.byteLength(input, 'utf8') > 1024) finish(new CredentialsError('The --key-stdin input exceeds 1024 bytes. Nothing was saved.'));
|
|
55
|
+
};
|
|
56
|
+
const onEnd = () => finish();
|
|
57
|
+
const onError = () => finish(new CredentialsError('Could not read the key from standard input. Nothing was saved.'));
|
|
58
|
+
const timer = setTimeout(() => finish(new CredentialsError('No complete key arrived on standard input within 10 seconds. Nothing was saved.')), 10_000);
|
|
59
|
+
io.stdin.on('data', onData);
|
|
60
|
+
io.stdin.once('end', onEnd);
|
|
61
|
+
io.stdin.once('error', onError);
|
|
62
|
+
io.stdin.resume?.();
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
|
|
26
66
|
export class CredentialsError extends CliError {
|
|
27
67
|
constructor(message) {
|
|
28
68
|
super(message, { code: 'credentials' });
|
package/login.mjs
CHANGED
|
@@ -22,6 +22,7 @@ import {
|
|
|
22
22
|
displayPath,
|
|
23
23
|
isTTY,
|
|
24
24
|
pathFor,
|
|
25
|
+
redact,
|
|
25
26
|
safeText,
|
|
26
27
|
writeLine,
|
|
27
28
|
} from './io.mjs';
|
|
@@ -34,6 +35,7 @@ import {
|
|
|
34
35
|
deleteCredential,
|
|
35
36
|
maskKey,
|
|
36
37
|
readCredential,
|
|
38
|
+
readApiKeyStdin,
|
|
37
39
|
sanitiseCredentialRecord,
|
|
38
40
|
writeCredential,
|
|
39
41
|
} from './key-store.mjs';
|
|
@@ -52,6 +54,7 @@ const DEVICE_SECRET = /^[A-Za-z0-9_-]{43}$/;
|
|
|
52
54
|
const REQUEST_ID = /^[0-9a-f]{64}$/;
|
|
53
55
|
|
|
54
56
|
export const LOGIN_USAGE = `Usage: cueapril login [--name <label>] [--no-browser] [--print-key] [--timeout <minutes>] [--no-wait] [--new] [--json]
|
|
57
|
+
cueapril login --key-stdin [--json]
|
|
55
58
|
|
|
56
59
|
Connects this computer to CueApril. Open the link it prints, check the code,
|
|
57
60
|
and approve (an organisation owner or admin must approve). The key is saved in
|
|
@@ -64,6 +67,7 @@ your user configuration and is never printed unless you pass --print-key.
|
|
|
64
67
|
--no-wait Print the link and exit; run login or init again to finish
|
|
65
68
|
--new Discard a pending request and start a new one
|
|
66
69
|
--json Print machine-readable JSON lines on stdout
|
|
70
|
+
--key-stdin Verify and store an existing agent key from a pipe; never argv or chat
|
|
67
71
|
|
|
68
72
|
Exit codes: 0 approved, 4 timed out, 5 error.`;
|
|
69
73
|
|
|
@@ -237,6 +241,7 @@ function parseLoginArgs(argv) {
|
|
|
237
241
|
'print-key': { type: 'boolean' },
|
|
238
242
|
timeout: { type: 'string' },
|
|
239
243
|
'no-wait': { type: 'boolean' },
|
|
244
|
+
'key-stdin': { type: 'boolean' },
|
|
240
245
|
new: { type: 'boolean' },
|
|
241
246
|
json: { type: 'boolean' },
|
|
242
247
|
help: { type: 'boolean', short: 'h' },
|
|
@@ -249,6 +254,31 @@ function listText(list) {
|
|
|
249
254
|
return Array.isArray(list) && list.length ? list.join(', ') : 'none listed';
|
|
250
255
|
}
|
|
251
256
|
|
|
257
|
+
/** Explicit key import is independent of the resumable browser approval flow. */
|
|
258
|
+
export async function importApiKey(deps = {}, { dryRun = false } = {}) {
|
|
259
|
+
const io = defaultDeps(deps);
|
|
260
|
+
if (['CUEAPRIL_API_KEY', 'TENHAW_TOKEN'].some((name) => typeof io.env[name] === 'string' && io.env[name].trim())) {
|
|
261
|
+
throw new CliError('--key-stdin cannot be combined with CUEAPRIL_API_KEY or TENHAW_TOKEN. Use the environment key, or unset it before importing.');
|
|
262
|
+
}
|
|
263
|
+
const baseUrl = resolveBaseUrl(io.env);
|
|
264
|
+
const key = await readApiKeyStdin(io);
|
|
265
|
+
try {
|
|
266
|
+
// Unlike check_setup, this read works when the key covers multiple projects.
|
|
267
|
+
await createHttpClient(io, { baseUrl }).callTool('cueapril_list_projects', {}, key, { timeoutMs: 30_000 });
|
|
268
|
+
} catch (error) {
|
|
269
|
+
throw new CliError(`${safeText(redact(error.message, [key]), 400)} Nothing was saved.`, { code: error.code ?? 'error' });
|
|
270
|
+
}
|
|
271
|
+
const previous = await readCredential(baseUrl, io).catch(() => null);
|
|
272
|
+
const changed = !dryRun && previous?.key !== key;
|
|
273
|
+
let credentialsPath = previous?.key === key ? pathFor(io).join(configDir(io), 'credentials.json') : null;
|
|
274
|
+
try {
|
|
275
|
+
if (changed) ({ path: credentialsPath } = await writeCredential(baseUrl, { key }, io));
|
|
276
|
+
} catch (error) {
|
|
277
|
+
throw new CliError(`Key verified, but local storage could not be confirmed: ${safeText(redact(error.message, [key]), 300)}`, { code: error.code ?? 'error' });
|
|
278
|
+
}
|
|
279
|
+
return { exitCode: EXIT.ok, status: 'imported', key, credentialsPath, saved: !dryRun, changed, baseUrl };
|
|
280
|
+
}
|
|
281
|
+
|
|
252
282
|
/**
|
|
253
283
|
* Runs the device approval flow. Returns
|
|
254
284
|
* { exitCode, status, key?, record?, credentialsPath?, verificationUrl?, code? };
|
|
@@ -261,7 +291,7 @@ export async function runLogin(argv = [], deps = {}, options = {}) {
|
|
|
261
291
|
try {
|
|
262
292
|
flags = parseLoginArgs(argv);
|
|
263
293
|
} catch (error) {
|
|
264
|
-
writeLine(io.stderr, `${safeText(error.message)}\n\n${LOGIN_USAGE}`);
|
|
294
|
+
writeLine(io.stderr, `${safeText(redact(error.message))}\n\n${LOGIN_USAGE}`);
|
|
265
295
|
return { exitCode: EXIT.error, status: 'error' };
|
|
266
296
|
}
|
|
267
297
|
if (flags.help) {
|
|
@@ -275,6 +305,15 @@ export async function runLogin(argv = [], deps = {}, options = {}) {
|
|
|
275
305
|
};
|
|
276
306
|
let pending;
|
|
277
307
|
try {
|
|
308
|
+
if (flags['key-stdin']) {
|
|
309
|
+
if (['name', 'no-browser', 'print-key', 'timeout', 'no-wait', 'new'].some((name) => flags[name] !== undefined)) {
|
|
310
|
+
throw new CliError('--key-stdin cannot be combined with browser approval or --print-key options.');
|
|
311
|
+
}
|
|
312
|
+
const imported = await importApiKey(io);
|
|
313
|
+
writeLine(io.stderr, `Verified and saved key ${maskKey(imported.key)} to ${displayPath(io, imported.credentialsPath)}.`);
|
|
314
|
+
emitJson(io, mode, { event: 'login_imported', base_url: imported.baseUrl, credentials_path: displayPath(io, imported.credentialsPath), saved: true, exit_code: EXIT.ok });
|
|
315
|
+
return imported;
|
|
316
|
+
}
|
|
278
317
|
const baseUrl = resolveBaseUrl(io.env);
|
|
279
318
|
const timeoutMinutes = parseTimeoutMinutes(flags.timeout);
|
|
280
319
|
const requestedName = flags.name === undefined ? undefined : parseLabel(flags.name);
|
|
@@ -318,7 +357,7 @@ export async function runLogin(argv = [], deps = {}, options = {}) {
|
|
|
318
357
|
writeLine(io.stderr, `Waiting up to ${formatMinutes(timeoutMinutes)} for approval...`);
|
|
319
358
|
return await pollForApproval({ io, mode, baseUrl, pending, announce, timeoutMs: timeoutMinutes * 60_000 });
|
|
320
359
|
} catch (error) {
|
|
321
|
-
const message = safeText(error.message, 500);
|
|
360
|
+
const message = safeText(redact(error.message), 500);
|
|
322
361
|
writeLine(io.stderr, `Error: ${message}`);
|
|
323
362
|
emitJson(io, mode, { event: 'login_failed', reason: error.code ?? 'error', message });
|
|
324
363
|
return { exitCode: error.exitCode ?? EXIT.error, status: 'error' };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cueapril",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "CueApril CLI: connect your coding agent to CueApril in one command, then test pull requests and read verdicts, findings and suggested fixes from the terminal.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cueapril",
|
|
@@ -12,21 +12,22 @@ CueApril tests a pull request in a disposable VM under a test plan the team appr
|
|
|
12
12
|
Once per session, before relying on CueApril, run:
|
|
13
13
|
|
|
14
14
|
```bash
|
|
15
|
-
npx -y
|
|
15
|
+
npx -y cueapril@latest doctor
|
|
16
16
|
```
|
|
17
17
|
|
|
18
18
|
If it reports a problem, run:
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
|
-
npx -y
|
|
21
|
+
npx -y cueapril@latest init
|
|
22
22
|
```
|
|
23
23
|
|
|
24
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
25
|
|
|
26
|
-
- If
|
|
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.
|
|
27
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.
|
|
28
29
|
- New MCP servers load when the agent restarts. If the `cueapril_*` tools are missing in this session, use the CLI (section 3).
|
|
29
|
-
-
|
|
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+).
|
|
30
31
|
|
|
31
32
|
## 2. The loop with MCP tools
|
|
32
33
|
|
|
@@ -42,10 +43,10 @@ Also available: `cueapril_check_setup`, `cueapril_list_assessments`, `cueapril_l
|
|
|
42
43
|
## 3. The loop with the CLI
|
|
43
44
|
|
|
44
45
|
```bash
|
|
45
|
-
npx -y
|
|
46
|
+
npx -y cueapril@latest assess --pr 123 --wait --json
|
|
46
47
|
```
|
|
47
48
|
|
|
48
|
-
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
|
|
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.
|
|
49
50
|
|
|
50
51
|
## 4. Wait without wasting tokens
|
|
51
52
|
|
|
@@ -84,6 +85,6 @@ It starts (or reuses) the assessment for pull request 123, waits, prints machine
|
|
|
84
85
|
## 8. Keep the key secret
|
|
85
86
|
|
|
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.
|
|
87
|
-
- Do not open credential or MCP configuration files to read the key. `npx -y
|
|
88
|
-
- If a tool says the key is missing, expired or revoked, run `npx -y
|
|
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`.
|
|
89
90
|
- Each assessment reserves at most 300p (£3.00), and the key may carry a 30-day spend cap.
|