@argos-ci/cli 6.9.5 → 6.10.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/dist/index.mjs +187 -48
- package/package.json +13 -8
package/dist/index.mjs
CHANGED
|
@@ -44,10 +44,14 @@ const testProjectPathOption = new Option("--project <owner/project>", "Project t
|
|
|
44
44
|
const mediaProjectPathOption = new Option("--project <owner/project>", "Project the media belongs to, in owner/project format. Also ARGOS_PROJECT. Optional with a project token, which already identifies its project");
|
|
45
45
|
const managedProjectPathOption = new Option("--project <owner/project>", "Project to act on, in owner/project format. Also ARGOS_PROJECT");
|
|
46
46
|
const limitOption = new Option("--limit <number>", "Maximum number of items to fetch, following pagination as needed").default(String(100));
|
|
47
|
-
/**
|
|
48
|
-
|
|
47
|
+
/**
|
|
48
|
+
* Parse a `--limit` value into a positive integer, or abort. Pass `max` when
|
|
49
|
+
* the source caps how many items it can return.
|
|
50
|
+
*/
|
|
51
|
+
function toLimit(value, options) {
|
|
49
52
|
const limit = Number(value);
|
|
50
53
|
if (!Number.isInteger(limit) || limit < 1) fail(`--limit must be a positive integer, received "${value}".`);
|
|
54
|
+
if (options?.max !== void 0 && limit > options.max) fail(`--limit must be at most ${options.max}, received "${value}".`);
|
|
51
55
|
return limit;
|
|
52
56
|
}
|
|
53
57
|
/** Parse a `--pr` value into a pull request number, or abort. */
|
|
@@ -248,6 +252,55 @@ function unwrapEmpty(result) {
|
|
|
248
252
|
if (!result.response.ok) throwAPIError(result.error, result.response);
|
|
249
253
|
}
|
|
250
254
|
//#endregion
|
|
255
|
+
//#region src/lib/terminal.ts
|
|
256
|
+
/**
|
|
257
|
+
* Printing text the CLI did not author — an OAuth error description chosen by
|
|
258
|
+
* the authorization server, for instance.
|
|
259
|
+
*
|
|
260
|
+
* A terminal acts on what it is given: an ANSI escape sequence moves the
|
|
261
|
+
* cursor, erases a line or repaints it, and a carriage return overwrites the
|
|
262
|
+
* line just printed. Remote text reaching it unfiltered therefore doesn't just
|
|
263
|
+
* read badly, it can forge CLI output — a fake "run this command to continue"
|
|
264
|
+
* instruction under the CLI's own name (GHSA-q9j4-4h4j-mv5m).
|
|
265
|
+
*/
|
|
266
|
+
/**
|
|
267
|
+
* Longest remote string we print. A description is a sentence; a wall of text
|
|
268
|
+
* is itself a way to scroll the real message off the screen.
|
|
269
|
+
*/
|
|
270
|
+
const MAX_LENGTH = 200;
|
|
271
|
+
/**
|
|
272
|
+
* Escape sequences, matched together with the bytes that belong to them so no
|
|
273
|
+
* parameter remnant (`[2K`) is left behind as text: CSI (`ESC [`), OSC
|
|
274
|
+
* (`ESC ]`, up to its terminator) and, last, the plain escape sequences —
|
|
275
|
+
* optional intermediate bytes and a final one, which covers `ESC c` (reset the
|
|
276
|
+
* terminal) as much as `ESC 7`.
|
|
277
|
+
*/
|
|
278
|
+
const ESCAPE_SEQUENCE_REGEX = /[\u001B\u009B](?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\)?|[ -/]*[0-~])/g;
|
|
279
|
+
/** Anything else a terminal acts on rather than displays: C0, DEL and C1. */
|
|
280
|
+
const CONTROL_CHARACTER_REGEX = /[\u0000-\u001F\u007F-\u009F]/g;
|
|
281
|
+
/**
|
|
282
|
+
* Explicit directional formatting: the other way to make a line read as
|
|
283
|
+
* something other than what it says, by reordering the characters around it
|
|
284
|
+
* rather than by driving the terminal. Bidirectional text itself is untouched —
|
|
285
|
+
* only the overrides, embeddings, isolates and marks are dropped.
|
|
286
|
+
*/
|
|
287
|
+
const DIRECTIONAL_FORMATTING_REGEX = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
|
|
288
|
+
/**
|
|
289
|
+
* Reduce remote text to characters a terminal can only display, on a single
|
|
290
|
+
* line and bounded in length.
|
|
291
|
+
*
|
|
292
|
+
* Returns an empty string when nothing printable is left, so callers can fall
|
|
293
|
+
* back to a message of their own rather than print a blank error.
|
|
294
|
+
*
|
|
295
|
+
* @param text The remote value. Typed `unknown` because it comes from parsed
|
|
296
|
+
* JSON or a URL parameter and is not necessarily a string at runtime.
|
|
297
|
+
*/
|
|
298
|
+
function sanitizeTerminalText(text) {
|
|
299
|
+
if (text === null || text === void 0) return "";
|
|
300
|
+
const sanitized = String(text).replace(ESCAPE_SEQUENCE_REGEX, "").replace(DIRECTIONAL_FORMATTING_REGEX, "").replace(CONTROL_CHARACTER_REGEX, " ").replace(/\s+/g, " ").trim();
|
|
301
|
+
return sanitized.length > MAX_LENGTH ? `${sanitized.slice(0, MAX_LENGTH)}…` : sanitized;
|
|
302
|
+
}
|
|
303
|
+
//#endregion
|
|
251
304
|
//#region src/lib/format.ts
|
|
252
305
|
/** Render a scalar, using `-` for empty values. */
|
|
253
306
|
function formatValue(value) {
|
|
@@ -757,54 +810,19 @@ function formatMediaVersions(versions) {
|
|
|
757
810
|
])
|
|
758
811
|
].filter((line) => line !== null).slice(0, -1).join("\n");
|
|
759
812
|
}
|
|
760
|
-
//#endregion
|
|
761
|
-
//#region src/lib/terminal.ts
|
|
762
|
-
/**
|
|
763
|
-
* Printing text the CLI did not author — an OAuth error description chosen by
|
|
764
|
-
* the authorization server, for instance.
|
|
765
|
-
*
|
|
766
|
-
* A terminal acts on what it is given: an ANSI escape sequence moves the
|
|
767
|
-
* cursor, erases a line or repaints it, and a carriage return overwrites the
|
|
768
|
-
* line just printed. Remote text reaching it unfiltered therefore doesn't just
|
|
769
|
-
* read badly, it can forge CLI output — a fake "run this command to continue"
|
|
770
|
-
* instruction under the CLI's own name (GHSA-q9j4-4h4j-mv5m).
|
|
771
|
-
*/
|
|
772
|
-
/**
|
|
773
|
-
* Longest remote string we print. A description is a sentence; a wall of text
|
|
774
|
-
* is itself a way to scroll the real message off the screen.
|
|
775
|
-
*/
|
|
776
|
-
const MAX_LENGTH = 200;
|
|
777
813
|
/**
|
|
778
|
-
*
|
|
779
|
-
*
|
|
780
|
-
*
|
|
781
|
-
* optional intermediate bytes and a final one, which covers `ESC c` (reset the
|
|
782
|
-
* terminal) as much as `ESC 7`.
|
|
783
|
-
*/
|
|
784
|
-
const ESCAPE_SEQUENCE_REGEX = /[\u001B\u009B](?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\)?|[ -/]*[0-~])/g;
|
|
785
|
-
/** Anything else a terminal acts on rather than displays: C0, DEL and C1. */
|
|
786
|
-
const CONTROL_CHARACTER_REGEX = /[\u0000-\u001F\u007F-\u009F]/g;
|
|
787
|
-
/**
|
|
788
|
-
* Explicit directional formatting: the other way to make a line read as
|
|
789
|
-
* something other than what it says, by reordering the characters around it
|
|
790
|
-
* rather than by driving the terminal. Bidirectional text itself is untouched —
|
|
791
|
-
* only the overrides, embeddings, isolates and marks are dropped.
|
|
814
|
+
* Format documentation search results, best match first. Titles and excerpts
|
|
815
|
+
* come from the docs host, so they are sanitized before reaching the terminal;
|
|
816
|
+
* the excerpt is also cut down to a single line.
|
|
792
817
|
*/
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
* @param text The remote value. Typed `unknown` because it comes from parsed
|
|
802
|
-
* JSON or a URL parameter and is not necessarily a string at runtime.
|
|
803
|
-
*/
|
|
804
|
-
function sanitizeTerminalText(text) {
|
|
805
|
-
if (text === null || text === void 0) return "";
|
|
806
|
-
const sanitized = String(text).replace(ESCAPE_SEQUENCE_REGEX, "").replace(DIRECTIONAL_FORMATTING_REGEX, "").replace(CONTROL_CHARACTER_REGEX, " ").replace(/\s+/g, " ").trim();
|
|
807
|
-
return sanitized.length > MAX_LENGTH ? `${sanitized.slice(0, MAX_LENGTH)}…` : sanitized;
|
|
818
|
+
function formatDocsSearchResults(results, query) {
|
|
819
|
+
if (results.length === 0) return `No documentation found for "${sanitizeTerminalText(query)}".`;
|
|
820
|
+
return results.flatMap((result, index) => [
|
|
821
|
+
`${index + 1}. ${sanitizeTerminalText(result.title)}`,
|
|
822
|
+
indent(sanitizeTerminalText(result.url)),
|
|
823
|
+
result.excerpt ? indent(sanitizeTerminalText(result.excerpt)) : null,
|
|
824
|
+
""
|
|
825
|
+
]).filter((line) => line !== null).slice(0, -1).join("\n");
|
|
808
826
|
}
|
|
809
827
|
//#endregion
|
|
810
828
|
//#region src/lib/oauth.ts
|
|
@@ -3325,6 +3343,126 @@ function automationCommand(program) {
|
|
|
3325
3343
|
}));
|
|
3326
3344
|
}
|
|
3327
3345
|
//#endregion
|
|
3346
|
+
//#region src/lib/docs.ts
|
|
3347
|
+
/**
|
|
3348
|
+
* Searching the Argos documentation.
|
|
3349
|
+
*
|
|
3350
|
+
* The docs are published on GitBook, which serves every public site with a
|
|
3351
|
+
* Model Context Protocol endpoint at `<site>/~gitbook/mcp`. Its
|
|
3352
|
+
* `searchDocumentation` tool needs no token — unlike GitBook's REST search,
|
|
3353
|
+
* which wants an API token that a published CLI could not keep secret.
|
|
3354
|
+
*
|
|
3355
|
+
* The endpoint is stateless, so a single `tools/call` request is enough: no
|
|
3356
|
+
* `initialize` handshake or session to carry between calls.
|
|
3357
|
+
*/
|
|
3358
|
+
/** Root of the published Argos documentation. */
|
|
3359
|
+
const DOCS_URL = "https://argos-ci.com/docs";
|
|
3360
|
+
const MCP_ENDPOINT = `${DOCS_URL}/~gitbook/mcp`;
|
|
3361
|
+
/**
|
|
3362
|
+
* A cold search can take well over ten seconds; past this, the request is
|
|
3363
|
+
* abandoned rather than left hanging.
|
|
3364
|
+
*/
|
|
3365
|
+
const TIMEOUT_MS = 3e4;
|
|
3366
|
+
/**
|
|
3367
|
+
* One search hit, as the tool renders it:
|
|
3368
|
+
*
|
|
3369
|
+
* ```
|
|
3370
|
+
* Title: <page title>
|
|
3371
|
+
* Link: <page URL>
|
|
3372
|
+
* Content: <matching passage, possibly several paragraphs>
|
|
3373
|
+
* ```
|
|
3374
|
+
*
|
|
3375
|
+
* `Content` is left out when the page has no passage to show.
|
|
3376
|
+
*/
|
|
3377
|
+
const RESULT_REGEX = /^Title: ([^\n]*)\nLink: ([^\n]*)(?:\nContent: ([\s\S]*))?/;
|
|
3378
|
+
/** Parse the tool's text blocks into results, skipping any it can't read. */
|
|
3379
|
+
function parseDocsSearchContent(content) {
|
|
3380
|
+
const results = /* @__PURE__ */ new Map();
|
|
3381
|
+
for (const block of content) {
|
|
3382
|
+
if (block.type !== "text" || !block.text) continue;
|
|
3383
|
+
const match = RESULT_REGEX.exec(block.text);
|
|
3384
|
+
const title = match?.[1]?.trim();
|
|
3385
|
+
const url = match?.[2]?.trim();
|
|
3386
|
+
if (!title || !url || results.has(url)) continue;
|
|
3387
|
+
results.set(url, {
|
|
3388
|
+
title,
|
|
3389
|
+
url,
|
|
3390
|
+
excerpt: match?.[3]?.trim() || null
|
|
3391
|
+
});
|
|
3392
|
+
}
|
|
3393
|
+
return [...results.values()];
|
|
3394
|
+
}
|
|
3395
|
+
/**
|
|
3396
|
+
* Read the JSON-RPC response out of the body. The endpoint answers with a
|
|
3397
|
+
* server-sent event stream, each JSON-RPC message on one `data:` line, but may
|
|
3398
|
+
* answer with plain JSON, which the protocol allows too.
|
|
3399
|
+
*/
|
|
3400
|
+
function parseMcpResponse(body, contentType) {
|
|
3401
|
+
if (!contentType?.includes("text/event-stream")) return JSON.parse(body);
|
|
3402
|
+
for (const line of body.split("\n")) {
|
|
3403
|
+
if (!line.startsWith("data:")) continue;
|
|
3404
|
+
const message = JSON.parse(line.slice(5));
|
|
3405
|
+
if ("result" in message || "error" in message) return message;
|
|
3406
|
+
}
|
|
3407
|
+
throw new CliError("The documentation search returned no response.");
|
|
3408
|
+
}
|
|
3409
|
+
/** Search the Argos documentation, best match first. */
|
|
3410
|
+
async function searchDocs(query, options) {
|
|
3411
|
+
const userAgent = getUserAgent();
|
|
3412
|
+
const response = await fetch(MCP_ENDPOINT, {
|
|
3413
|
+
method: "POST",
|
|
3414
|
+
headers: {
|
|
3415
|
+
"Content-Type": "application/json",
|
|
3416
|
+
Accept: "application/json, text/event-stream",
|
|
3417
|
+
...userAgent ? { "User-Agent": userAgent } : {}
|
|
3418
|
+
},
|
|
3419
|
+
body: JSON.stringify({
|
|
3420
|
+
jsonrpc: "2.0",
|
|
3421
|
+
id: 1,
|
|
3422
|
+
method: "tools/call",
|
|
3423
|
+
params: {
|
|
3424
|
+
name: "searchDocumentation",
|
|
3425
|
+
arguments: { query }
|
|
3426
|
+
}
|
|
3427
|
+
}),
|
|
3428
|
+
signal: AbortSignal.timeout(TIMEOUT_MS)
|
|
3429
|
+
}).catch((error) => {
|
|
3430
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
3431
|
+
throw new CliError(`Could not reach ${DOCS_URL}: ${reason}`);
|
|
3432
|
+
});
|
|
3433
|
+
if (!response.ok) throw new CliError(`The documentation search failed with HTTP ${response.status}.`);
|
|
3434
|
+
const message = parseMcpResponse(await response.text(), response.headers.get("content-type"));
|
|
3435
|
+
const content = message.result?.content ?? [];
|
|
3436
|
+
if (message.error || message.result?.isError) throw new CliError(`The documentation search failed: ${sanitizeTerminalText(message.error ? message.error.message : content.map((block) => block.text ?? "").join(" ")) || "unknown error"}`);
|
|
3437
|
+
return parseDocsSearchContent(content).slice(0, options.limit);
|
|
3438
|
+
}
|
|
3439
|
+
//#endregion
|
|
3440
|
+
//#region src/commands/docs/search.ts
|
|
3441
|
+
const DEFAULT_DOCS_LIMIT = 5;
|
|
3442
|
+
function registerDocsSearch(docs) {
|
|
3443
|
+
docs.command("search").description(`Search the Argos documentation (${DOCS_URL})`).argument("<query...>", "What to look for, e.g. \"parallel builds\"").addOption(new Option("--limit <number>", `Maximum number of results, up to 10`).default(String(DEFAULT_DOCS_LIMIT))).addOption(jsonOption).addHelpText("after", [
|
|
3444
|
+
"",
|
|
3445
|
+
"No token needed. Read a result in full as Markdown by appending .md to",
|
|
3446
|
+
"its URL, or by requesting it with an `Accept: text/markdown` header:",
|
|
3447
|
+
"",
|
|
3448
|
+
" url=$(argos docs search \"parallel builds\" --json | jq -r \".[0].url\")",
|
|
3449
|
+
" curl -H \"Accept: text/markdown\" \"$url\""
|
|
3450
|
+
].join("\n")).action(async (words, options) => {
|
|
3451
|
+
try {
|
|
3452
|
+
const query = words.join(" ").trim();
|
|
3453
|
+
if (!query) fail("A search query is required.");
|
|
3454
|
+
output(await searchDocs(query, { limit: toLimit(options.limit, { max: 10 }) }), options, (data) => formatDocsSearchResults(data, query));
|
|
3455
|
+
} catch (error) {
|
|
3456
|
+
handleCliError(error);
|
|
3457
|
+
}
|
|
3458
|
+
});
|
|
3459
|
+
}
|
|
3460
|
+
//#endregion
|
|
3461
|
+
//#region src/commands/docs/index.ts
|
|
3462
|
+
function docsCommand(program) {
|
|
3463
|
+
registerDocsSearch(program.command("docs").description("Search the Argos documentation from the terminal"));
|
|
3464
|
+
}
|
|
3465
|
+
//#endregion
|
|
3328
3466
|
//#region src/index.ts
|
|
3329
3467
|
const __dirname = fileURLToPath(new URL(".", import.meta.url));
|
|
3330
3468
|
const rawPkg = await readFile(resolve(__dirname, "..", "package.json"), "utf8");
|
|
@@ -3349,6 +3487,7 @@ testCommand(program);
|
|
|
3349
3487
|
accountCommand(program);
|
|
3350
3488
|
projectCommand(program);
|
|
3351
3489
|
automationCommand(program);
|
|
3490
|
+
docsCommand(program);
|
|
3352
3491
|
if (!process.argv.slice(2).length) program.outputHelp();
|
|
3353
3492
|
else program.parse(process.argv);
|
|
3354
3493
|
//#endregion
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@argos-ci/cli",
|
|
3
3
|
"description": "Command-line (CLI) for visual testing with Argos.",
|
|
4
|
-
"version": "6.
|
|
4
|
+
"version": "6.10.0",
|
|
5
5
|
"bin": {
|
|
6
6
|
"argos": "./bin/argos-cli.js"
|
|
7
7
|
},
|
|
@@ -23,19 +23,24 @@
|
|
|
23
23
|
},
|
|
24
24
|
"license": "MIT",
|
|
25
25
|
"keywords": [
|
|
26
|
-
"cli",
|
|
27
26
|
"argos",
|
|
27
|
+
"argos-ci",
|
|
28
|
+
"cli",
|
|
28
29
|
"testing",
|
|
29
|
-
"visual
|
|
30
|
-
"regression",
|
|
31
|
-
"visual
|
|
30
|
+
"visual-testing",
|
|
31
|
+
"visual-regression",
|
|
32
|
+
"visual-regression-testing",
|
|
33
|
+
"screenshot-testing",
|
|
34
|
+
"snapshot-testing",
|
|
35
|
+
"continuous-integration",
|
|
36
|
+
"ci"
|
|
32
37
|
],
|
|
33
38
|
"publishConfig": {
|
|
34
39
|
"access": "public"
|
|
35
40
|
},
|
|
36
41
|
"dependencies": {
|
|
37
|
-
"@argos-ci/api-client": "0.31.
|
|
38
|
-
"@argos-ci/core": "6.8.
|
|
42
|
+
"@argos-ci/api-client": "0.31.3",
|
|
43
|
+
"@argos-ci/core": "6.8.8",
|
|
39
44
|
"@vercel/detect-agent": "^1.2.5",
|
|
40
45
|
"commander": "^15.0.0",
|
|
41
46
|
"open": "^11.0.4",
|
|
@@ -54,5 +59,5 @@
|
|
|
54
59
|
"check-format": "prettier --check --ignore-unknown --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
|
|
55
60
|
"lint": "eslint ."
|
|
56
61
|
},
|
|
57
|
-
"gitHead": "
|
|
62
|
+
"gitHead": "810aab42c890851ea19ba96f49c4f167a5f2e3df"
|
|
58
63
|
}
|