@argos-ci/cli 6.9.6 → 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.
Files changed (2) hide show
  1. package/dist/index.mjs +187 -48
  2. 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
- /** Parse a `--limit` value into a positive integer, or abort. */
48
- function toLimit(value) {
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
- * Escape sequences, matched together with the bytes that belong to them so no
779
- * parameter remnant (`[2K`) is left behind as text: CSI (`ESC [`), OSC
780
- * (`ESC ]`, up to its terminator) and, last, the plain escape sequences —
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
- const DIRECTIONAL_FORMATTING_REGEX = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
794
- /**
795
- * Reduce remote text to characters a terminal can only display, on a single
796
- * line and bounded in length.
797
- *
798
- * Returns an empty string when nothing printable is left, so callers can fall
799
- * back to a message of their own rather than print a blank error.
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.9.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 testing",
30
- "regression",
31
- "visual regression"
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.2",
38
- "@argos-ci/core": "6.8.7",
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": "e9d0b2fb39001683230eff86f9c39e0016b5cf27"
62
+ "gitHead": "810aab42c890851ea19ba96f49c4f167a5f2e3df"
58
63
  }