@getantidote/cli 0.1.0 → 1.0.0

package/README.md

@@ -64,9 +64,9 @@ jobs:
 (`ANTIDOTE_OIDC_TOKEN` or `ANTIDOTE_OIDC_TOKEN_FILE`), without `ANTIDOTE_SERVICE_IDENTITY`.
 The platform finds the identity from the token itself: the one that belongs to
 your organisation's connection to that CI platform (Settings → Integrations →
-Source control & CI/CD), so there is nothing to create or name. No CI
-platform's connection provides one yet; until one does, the platform refuses
-these tokens. The token's audience must be the platform's URL (the origin of
+Source control & CI/CD), so there is nothing to create or name. Connecting
+GitLab CI/CD creates it, for GitLab jobs' ID tokens; the platform refuses
+other CI platforms' tokens this way. The token's audience must be the platform's URL (the origin of
 `ANTIDOTE_API_URL`). When the platform refuses a token, the CLI prints its reason as
 it gave it.
 
@@ -142,6 +142,8 @@ empty one.
 antidote whoami             # the signed-in user (or service identity), organisation and auth mode (a tool command, below)
 antidote tools              # the tools available to the CLI
 antidote tools --refresh    # re-fetch the tool list
+antidote wait-for-deployment --product-id <id> --commit-sha <sha>
+                            # poll the environment's URL until it serves the commit (--help: its flags)
 antidote logout             # revoke the session and delete this machine's credentials
 antidote --version
 ```
@@ -214,6 +216,10 @@ the tool's input schema. `antidote <tool> --help` lists its flags.
 
 ### In CI
 
+On GitLab, the `preview` and `release` components (`actions-repo/gitlab`) make
+these calls for you and run the CLI's major version, `@getantidote/cli@1`. The
+jobs below show the calls themselves.
+
 A job that needs a tool's result in a later job writes it as a dotenv file. In
 GitLab, with `ANTIDOTE_API_KEY` set as a masked CI/CD variable and the product's
 id given to the tool as `ANTIDOTE_INPUT_PRODUCT_ID`:
@@ -226,7 +232,7 @@ antidote-preview:
   rules:
     - if: $CI_MERGE_REQUEST_IID
   script:
-    - npx -y @getantidote/cli@0.1 record-preview --provider gitlab --host "$CI_SERVER_FQDN" --repository "$CI_PROJECT_PATH" --repository-id "$CI_PROJECT_ID" --number "$CI_MERGE_REQUEST_IID" --head-sha "$CI_COMMIT_SHA" --branch "$CI_COMMIT_REF_NAME" --pipeline-id "$CI_PIPELINE_ID" --dotenv antidote.env
+    - npx -y @getantidote/cli@1 record-preview --provider gitlab --host "$CI_SERVER_FQDN" --repository "$CI_PROJECT_PATH" --repository-id "$CI_PROJECT_ID" --number "$CI_MERGE_REQUEST_IID" --head-sha "$CI_COMMIT_SHA" --branch "$CI_COMMIT_REF_NAME" --pipeline-id "$CI_PIPELINE_ID" --dotenv antidote.env
   artifacts:
     when: always
     reports:
@@ -254,7 +260,7 @@ antidote-release:
   variables:
     ANTIDOTE_INPUT_PRODUCT_ID: prod_123
   script:
-    - npx -y @getantidote/cli@0.1 record-release --environment staging --build-sha "$CI_COMMIT_SHA" --provider gitlab --host "$CI_SERVER_FQDN" --repository "$CI_PROJECT_PATH" --repository-id "$CI_PROJECT_ID" --dotenv antidote.env
+    - npx -y @getantidote/cli@1 record-release --environment staging --build-sha "$CI_COMMIT_SHA" --provider gitlab --host "$CI_SERVER_FQDN" --repository "$CI_PROJECT_PATH" --repository-id "$CI_PROJECT_ID" --dotenv antidote.env
   artifacts:
     when: always
     reports:

package/dist/antidote.mjs

@@ -16941,7 +16941,7 @@ async function openMcpSession(apiUrl, credentials, deps) {
 
 // src/tool-commands.ts
 import { parseArgs } from "node:util";
-var BUILTIN_COMMANDS = ["login", "logout", "tools"];
+var BUILTIN_COMMANDS = ["login", "logout", "tools", "wait-for-deployment"];
 var RESERVED_FLAGS = /* @__PURE__ */ new Set(["json", "help", "version", "device", "refresh", "dotenv"]);
 var UsageError = class extends Error {
   /** The --dotenv the strict parse accepted, when the mistake came after it. */
@@ -17135,6 +17135,74 @@ async function loadTools(source, opts = {}) {
   return list;
 }
 
+// src/wait-for-deployment.ts
+var DEFAULT_WAIT_COMMIT_HEADER = "x-commit-sha";
+var DEFAULT_WAIT_COMMIT_PATH = "/";
+var DEFAULT_WAIT_TIMEOUT_SECONDS = 300;
+var DEFAULT_WAIT_INTERVAL_SECONDS = 10;
+var PROBE_TIMEOUT_MS = 1e4;
+function buildPollUrl(baseUrl, path) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const trimmed = (path || "").trim() || "/";
+  const suffix = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return `${base}${suffix}`;
+}
+function commitHeaderMatches(headerValue, expectedSha) {
+  const normalized = (headerValue || "").trim().toLowerCase();
+  const expected = (expectedSha || "").trim().toLowerCase();
+  if (!normalized || !expected) return false;
+  if (normalized === expected) return true;
+  return normalized === expected.slice(0, 7);
+}
+function fetchProbe(http, headerName) {
+  return async (url2) => {
+    const response = await http(url2, { headers: { accept: "*/*" }, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    await response.body?.cancel().catch(() => void 0);
+    return response.headers.get(headerName);
+  };
+}
+function environmentUrl(environments, name) {
+  const target = environments.find((e) => name ? e.name?.text === name : e.is_default);
+  if (!target) throw new Error(name ? `The product has no environment named ${name}.` : "The product has no default environment.");
+  if (!target.url) throw new Error(`Environment ${name || "(the default)"} has no URL in Duku.`);
+  return target.url;
+}
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForDeployment(opts) {
+  const { pollUrl, expectedSha, headerName, timeoutSeconds, intervalSeconds, probe, sleep = defaultSleep, now = Date.now, log } = opts;
+  const expected = expectedSha.trim();
+  const short = expected.slice(0, 7);
+  log?.(`Waiting up to ${timeoutSeconds}s for ${pollUrl} to serve commit ${short} (header \`${headerName}\`)...`);
+  const deadline = now() + timeoutSeconds * 1e3;
+  let attempt = 0;
+  for (; ; ) {
+    attempt += 1;
+    let value = null;
+    try {
+      value = await probe(pollUrl);
+    } catch (err) {
+      log?.(`Attempt ${attempt}: request to ${pollUrl} failed (${err instanceof Error ? err.message : String(err)}) \u2014 retrying...`);
+    }
+    if (value !== null && commitHeaderMatches(value, expected)) {
+      log?.(`Attempt ${attempt}: ${pollUrl} serves commit ${short} \u2014 proceeding.`);
+      return;
+    }
+    if (value !== null) {
+      log?.(`Attempt ${attempt}: serves '${value.trim() || "(empty)"}' \u2014 waiting for '${short}'...`);
+    } else if (attempt === 1) {
+      log?.(`Attempt 1: no \`${headerName}\` header yet \u2014 waiting for '${short}'...`);
+    }
+    if (now() >= deadline) break;
+    const remaining = deadline - now();
+    await sleep(Math.min(intervalSeconds * 1e3, Math.max(remaining, 0)));
+  }
+  throw new Error(
+    `Timed out after ${timeoutSeconds}s waiting for ${pollUrl} to serve commit ${expected}. Expose the commit as response header \`${headerName}\` (e.g. \`res.setHeader('${headerName}', process.env.COMMIT_SHA)\`) so the job can tell the new deploy apart from the previous build.`
+  );
+}
+
 // src/cli.ts
 var USAGE = `Usage: antidote <command> [--json]
 
@@ -17143,6 +17211,8 @@ Commands:
             the default over SSH or without a display)
   logout    Sign out and forget this machine's credentials
   tools     List the tools available to the CLI (--refresh: re-fetch the list)
+  wait-for-deployment
+            Wait until an environment serves a commit (--help: its flags)
 
 The platform's tools are commands too, such as \`antidote whoami\`.
 \`antidote <tool> --help\` shows a tool's flags.
@@ -17221,6 +17291,9 @@ async function run(argv, deps) {
     return ctx;
   };
   try {
+    if (command === "wait-for-deployment" && !leading.some((arg) => VERSION_FLAGS.has(arg))) {
+      return await runWaitForDeployment(argv.slice(commandAt + 1), deps, context);
+    }
     return isBuiltin ? await runBuiltin(argv, deps, context) : await runTool(command, [...argv.slice(0, commandAt), ...argv.slice(commandAt + 1)], deps, context);
   } catch (e) {
     if (e instanceof UsageError) {
@@ -17329,6 +17402,73 @@ async function runBuiltin(argv, deps, context) {
       return 2;
   }
 }
+var WAIT_USAGE = `Usage: antidote wait-for-deployment --product-id <id> --commit-sha <sha> [flags]
+
+Poll the environment's URL, as Duku has it, until the response header names
+the commit (its full or 7-character SHA).
+
+  --product-id <id>          The Duku product
+  --environment <name>       The environment (default: the product's default)
+  --commit-sha <sha>         The commit to wait for
+  --commit-header <name>     Response header the app exposes its deployed
+                             commit on (default ${DEFAULT_WAIT_COMMIT_HEADER})
+  --commit-path <path>       Path polled on the environment's URL (default ${DEFAULT_WAIT_COMMIT_PATH})
+  --timeout-seconds <n>      How long to wait before failing (default ${DEFAULT_WAIT_TIMEOUT_SECONDS})
+  --interval-seconds <n>     Delay between polls (default ${DEFAULT_WAIT_INTERVAL_SECONDS})`;
+async function runWaitForDeployment(args, deps, context) {
+  let values;
+  try {
+    ({ values } = parseArgs2({
+      args,
+      options: {
+        "product-id": { type: "string" },
+        environment: { type: "string", default: "" },
+        "commit-sha": { type: "string" },
+        "commit-header": { type: "string", default: DEFAULT_WAIT_COMMIT_HEADER },
+        "commit-path": { type: "string", default: DEFAULT_WAIT_COMMIT_PATH },
+        "timeout-seconds": { type: "string", default: String(DEFAULT_WAIT_TIMEOUT_SECONDS) },
+        "interval-seconds": { type: "string", default: String(DEFAULT_WAIT_INTERVAL_SECONDS) },
+        help: { type: "boolean", short: "h", default: false }
+      }
+    }));
+  } catch (e) {
+    deps.err(e.message);
+    deps.err(WAIT_USAGE);
+    return 2;
+  }
+  if (values.help) {
+    deps.out(WAIT_USAGE);
+    return 0;
+  }
+  const productId = values["product-id"]?.trim();
+  const commitSha = values["commit-sha"]?.trim();
+  const headerName = values["commit-header"].trim();
+  const timeoutSeconds = Number(values["timeout-seconds"]);
+  const intervalSeconds = Number(values["interval-seconds"]);
+  if (!productId || !commitSha || !headerName || !(timeoutSeconds > 0) || !(intervalSeconds > 0)) {
+    deps.err("--product-id, --commit-sha and a --commit-header are required, and the seconds must be numbers above 0.");
+    deps.err(WAIT_USAGE);
+    return 2;
+  }
+  const result = await (await context().session()).callTool("get_product", { product_id: productId });
+  if (result.isError) {
+    deps.err(`Error: ${printable(contentText(result.content)) || "get_product failed"}`);
+    return 1;
+  }
+  const environments = result.structuredContent?.environments ?? [];
+  const pollUrl = buildPollUrl(environmentUrl(environments, values.environment.trim()), values["commit-path"]);
+  await waitForDeployment({
+    pollUrl,
+    expectedSha: commitSha,
+    headerName,
+    timeoutSeconds,
+    intervalSeconds,
+    probe: fetchProbe(deps.http, headerName),
+    sleep: deps.sleep,
+    log: (line) => deps.err(printable(line))
+  });
+  return 0;
+}
 async function runTool(name, args, deps, context) {
   const files = {
     writeFile: deps.writeFile ?? ((path, data) => writeFile2(path, data, { flag: "wx" })),
@@ -17428,7 +17568,7 @@ var code = await run(process.argv.slice(2), {
   err: (line) => process.stderr.write(`${line}
 `),
   openBrowser,
-  version: true ? "0.1.0" : "0.0.0-dev"
+  version: true ? "1.0.0" : "0.0.0-dev"
 });
 process.exitCode = code;
 /*! Bundled license information:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getantidote/cli",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Antidote command-line interface",
   "license": "MIT",
   "type": "module",