@azx-pbc/helix-cli 0.5.0 → 0.6.0

package/README.md

@@ -66,6 +66,7 @@ helix deploy   [--dir <dir>] [--bundle <zip>] [--promote]    # upload a version
 helix versions                                               # list versions
 helix promote  <number>                                      # make a version live
 helix rollback [number]                                      # revert the live pointer
+helix capabilities [--json]                                  # what this deployment offers
 helix skill    [--path <file>]                               # write this deployment's agent skill to disk
 helix ci init  [--repo <owner/name>] [--branch <b>] [--reusable] [--force]   # deploy from GitHub Actions
 helix ci show | helix ci remove                              # the app's repo binding
@@ -75,12 +76,38 @@ helix ci show | helix ci remove                              # the app's repo bi
 same step (architecture §5.1). `visibility` is `internal | group:<id>[,<id>…] | password
 | public`.
 
-`helix skill` fetches this deployment's rendered agent skill (`GET /api/v1/skill`,
-ADR-0036) — the same document the portal's **How to develop** modal hands out, with
-this deployment's hosts, servable models, and approval baselines already substituted
-in. It needs no app slug or `helix.json`, only a portal URL and a token. Defaults to
-`./SKILL.md`; `--path .claude/skills/helix/SKILL.md` drops it where a Claude Code
-agent reads it off disk.
+`helix capabilities` prints the deployment capability catalogue
+(`GET /api/v1/capabilities`, ADR-0036) in readable form:
+
+- servable models;
+- approval baselines;
+- named connections and OAuth providers;
+- visibility modes;
+- deploy caps;
+- the dev gateway;
+- which requests queue for an admin.
+
+`--json` prints the raw catalogue. If the portal sends a shape this CLI can't
+format, it prints the JSON instead of failing.
+
+`helix skill` fetches this deployment's rendered agent skill (`GET /api/v1/skill`).
+It is the same document the portal's **How to develop** modal hands out: this
+deployment's hosts, plus pointers to `helix capabilities` and the public docs.
+
+Neither command needs an app slug or `helix.json`, only a portal URL and a token.
+`helix skill` writes `./SKILL.md` by default; `--path .claude/skills/helix/SKILL.md`
+puts it where a Claude Code agent reads it from disk.
+
+### Compatibility with the portal
+
+Every command except `logout` first reads the public `GET /api/v1/config`. If
+the portal states a `cli.minVersion` newer than this CLI, the CLI prints a
+warning to stderr suggesting `@latest`. The warning never fails the command.
+
+A 404 from a missing _route_ (the portal's not-found handler, as opposed to "app
+not found") means the portal is older than the CLI, and the error says so. The
+floor is `MIN_CLI_VERSION` in `@azx-pbc/shared`. Bump it by hand when the portal
+removes or changes something an older CLI relies on (ADR-0052).
 
 ### Deploying from GitHub Actions
 
@@ -138,15 +165,29 @@ Two paths, in precedence order:
 
 ## Running it
 
-### Installed from npm
+### From npm
+
+App authors and agents run it with `npx`, so it is always the current release
+and there is nothing to keep updated (ADR-0052):
 
 ```bash
-npm i -g @azx-pbc/helix-cli
 cd my-app
-export HELIX_TOKEN="…"
+npx -y @azx-pbc/helix-cli@latest deploy --promote
+```
+
+Write `@latest` explicitly, because a bare package name lets `npx` reuse a copy
+it cached earlier. `-y` skips the install prompt.
+
+To install it once instead:
+
+```bash
+npm i -g @azx-pbc/helix-cli          # update with: npm i -g @azx-pbc/helix-cli@latest
 helix deploy --promote
 ```
 
+CI workflows pin an exact version; `helix ci init` writes the one it was run
+with.
+
 Needs **Node 22.12+** (or 24+). The engines range and the bundle's esbuild
 target move together (see `scripts/build.mjs`), so the declared floor is real:
 older runtimes may not merely warn, they may fail to parse it.

package/dist/helix.js

@@ -17,6 +17,7 @@ var options = {
   branch: { type: "string" },
   reusable: { type: "boolean" },
   force: { type: "boolean" },
+  json: { type: "boolean" },
   help: { type: "boolean" }
 };
 function parseCliArgs(argv) {
@@ -233,7 +234,7 @@ var HEADER_VALUE_SAFE = /^[\t\x20-\x7e]*$/;
 var HEADER_VALUE_WIRE = /^[\t\x20-\x7e\x80-\xff]*$/;
 var headerName = (from) => {
   const base = z6.string().min(1);
-  return (from === "request" ? base.max(64).regex(HEADER_TOKEN, "must be an RFC 7230 token") : base).transform((n) => n.trim().toLowerCase()).refine((n) => !FORBIDDEN_HEADER_NAMES.has(n), "reserved header name").refine((n) => !n.startsWith("x-helix-"), "reserved header prefix");
+  return (from === "request" ? base.max(64).regex(HEADER_TOKEN, "must be an RFC 7230 token") : base).transform((n2) => n2.trim().toLowerCase()).refine((n2) => !FORBIDDEN_HEADER_NAMES.has(n2), "reserved header name").refine((n2) => !n2.startsWith("x-helix-"), "reserved header prefix");
 };
 var headerTemplate = (from) => from === "request" ? z6.string().max(512).regex(HEADER_VALUE_SAFE) : z6.string().regex(HEADER_VALUE_WIRE);
 var injectionRecipe = (from) => z6.discriminatedUnion("kind", [
@@ -1285,7 +1286,16 @@ var DeploymentConfigResponseSchema = z13.object({
     enabled: z13.boolean(),
     audience: z13.url(),
     serverUrl: z13.url()
-  }).optional()
+  }).optional(),
+  /**
+   * The CLI compatibility floor. A CLI older than `minVersion` warns and tells
+   * the user to run `@latest`; it does not refuse to run. Absent on a portal
+   * that predates the handshake, so a CLI treats absence as "no floor stated",
+   * not as an error. `minVersion` is a plain string rather than a validated
+   * semver: the CLI parses this whole response, so a stricter schema would turn
+   * an unexpected format into a failed command instead of a skipped check.
+   */
+  cli: z13.object({ minVersion: z13.string() }).optional()
 });
 
 // ../shared/src/catalogue.ts
@@ -2309,6 +2319,9 @@ var SessionRevokeResultSchema = z28.object({
   apps: z28.array(z28.string())
 });
 
+// src/version.ts
+var CLI_VERSION = true ? "0.6.0" : "latest";
+
 // src/client.ts
 var CliError = class extends Error {
   code;
@@ -2330,6 +2343,7 @@ var VersionListSchema = z29.array(VersionSchema);
 var PortalClient = class {
   #baseUrl;
   #tokenProvider;
+  #deploymentConfig;
   /** `token` may be a static string (dev token) or an async provider (OIDC). */
   constructor(baseUrl, token) {
     this.#baseUrl = baseUrl.replace(/\/+$/, "");
@@ -2352,9 +2366,22 @@ var PortalClient = class {
   getAuthConfig() {
     return this.#json(AuthConfigResponseSchema, "GET", "/api/v1/auth/config", {});
   }
-  /** Public deployment topology (`GET /api/v1/config`), incl. the CI token audience. */
+  /**
+   * Public deployment topology (`GET /api/v1/config`), incl. the CI token
+   * audience and the CLI version floor. Fetched once per client: the
+   * compatibility check and the command that follows it share one request.
+   */
   getDeploymentConfig() {
-    return this.#json(DeploymentConfigResponseSchema, "GET", "/api/v1/config", {});
+    this.#deploymentConfig ??= this.#json(
+      DeploymentConfigResponseSchema,
+      "GET",
+      "/api/v1/config",
+      {}
+    ).catch((err) => {
+      this.#deploymentConfig = void 0;
+      throw err;
+    });
+    return this.#deploymentConfig;
   }
   /** The app's GitHub binding (ADR-0051), or null when it has none. */
   async getRepoBinding(slug) {
@@ -2386,13 +2413,20 @@ var PortalClient = class {
   }
   /**
    * The deployment-rendered agent skill (`GET /api/v1/skill`, ADR-0036) —
-   * `text/markdown`, already substituted with this deployment's hosts, servable
-   * models, and approval baselines. Authed like every other `/api/v1` read.
-   * Powers `helix skill`.
+   * `text/markdown`, with this deployment's hosts filled in. Authed like every
+   * other `/api/v1` read. Powers `helix skill`.
    */
   getSkill() {
     return this.#text("/api/v1/skill", { auth: true });
   }
+  /**
+   * The deployment capability catalogue (`GET /api/v1/capabilities`), unparsed.
+   * `helix capabilities` validates it when formatting, and falls back to the raw
+   * JSON when a portal of a different version sends a shape this CLI doesn't know.
+   */
+  getCapabilities() {
+    return this.#json(z29.unknown(), "GET", "/api/v1/capabilities", { auth: true });
+  }
   listVersions(slug) {
     return this.#json(VersionListSchema, "GET", `/api/v1/apps/${enc(slug)}/versions`, {
       auth: true
@@ -2458,12 +2492,7 @@ var PortalClient = class {
     const text = await res.text();
     const data = text ? JSON.parse(text) : void 0;
     if (!res.ok) {
-      const parsed = ApiErrorSchema.safeParse(data);
-      if (parsed.success) {
-        const { message, code, details } = parsed.data.error;
-        throw new CliError(message, code, details);
-      }
-      throw new CliError(`request failed (HTTP ${res.status})`);
+      throw errorFromResponse(res.status, data);
     }
     return schema.parse(data);
   }
@@ -2474,16 +2503,24 @@ var PortalClient = class {
     const body = await res.text();
     if (!res.ok) {
       const data = body ? safeJsonParse(body) : void 0;
-      const parsed = ApiErrorSchema.safeParse(data);
-      if (parsed.success) {
-        const { message, code, details } = parsed.data.error;
-        throw new CliError(message, code, details);
-      }
-      throw new CliError(`request failed (HTTP ${res.status})`);
+      throw errorFromResponse(res.status, data);
     }
     return body;
   }
 };
+function errorFromResponse(status, data) {
+  const parsed = ApiErrorSchema.safeParse(data);
+  if (!parsed.success) return new CliError(`request failed (HTTP ${status})`);
+  const { message, code, details } = parsed.data.error;
+  if (status === 404 && code === "not_found" && message.startsWith("route ")) {
+    return new CliError(
+      `${message}. This portal is probably older than this CLI (${CLI_VERSION}); ask your operator to update Helix, or run an older @azx-pbc/helix-cli`,
+      code,
+      details
+    );
+  }
+  return new CliError(message, code, details);
+}
 function enc(segment) {
   return encodeURIComponent(segment);
 }
@@ -2516,6 +2553,60 @@ function zipDirectory(dir) {
   });
 }
 
+// src/capabilities.ts
+var TRIGGER_LABELS = {
+  externalOrigins: "any externalOrigins entry",
+  fetchOrigins: "any fetch.origins entry",
+  mcp: "any mcp server",
+  publicVisibility: "public visibility",
+  budgetAboveBaseline: "any budget above its baseline",
+  uncuratedLlmModel: "an LLM model not in the list above"
+};
+var n = (value) => value.toLocaleString("en-US");
+function formatCapabilities(c) {
+  const b = c.approval.baselines;
+  const lines = [
+    "Helix capabilities on this deployment",
+    "",
+    `Visibility modes:   ${c.visibility.modes.join(", ")}`,
+    "",
+    "LLM (capabilities.llm)",
+    `  models:           ${c.llm.models.length ? c.llm.models.join(", ") : "(none servable)"}`,
+    `  baseline:         $${n(b.dollarsPerDay)}/day`,
+    "",
+    "App data (capabilities.data)",
+    `  available:        ${c.data.provisioned ? "yes" : "no"}`,
+    `  baselines:        ${n(b.writesPerDay)} writes/day, ${n(b.bytesPerDay)} bytes/day`,
+    "",
+    "Outbound HTTP (capabilities.fetch, externalOrigins)",
+    `  connections:      ${c.fetch.connections.length ? c.fetch.connections.map((x) => x.name).join(", ") : "(none)"}`,
+    ...c.fetch.providers.length ? [
+      "  providers:",
+      ...c.fetch.providers.map(
+        (p) => `    ${p.ref} (${p.displayName}, ${p.env}) \u2192 ${p.apiOrigins.join(", ")}`
+      )
+    ] : ["  providers:        (none)"],
+    `  externalOrigins:  ${c.fetch.externalOriginsPermitted ? "may be requested" : "not permitted"}`,
+    `  baseline:         ${n(b.fetchRequestsPerDay)} proxied requests/day`,
+    "",
+    `MCP:                ${c.mcp.enforced ? "enforced" : "carried in the manifest, not enforced"}`,
+    `Offline:            ${c.offline.available ? `available \u2014 ${c.offline.scopeRule}` : "not available"}`,
+    `Deploy limits:      ${n(c.deploy.maxFileMb)} MB per file, ${n(c.deploy.maxBundleMb)} MB per bundle`,
+    `Dev gateway:        ${c.devApiBase ? `${c.devApiBase}/<slug>` : "not deployed"}`,
+    "",
+    "Needs admin approval:",
+    ...c.approval.elevationTriggers.map((t) => `  - ${TRIGGER_LABELS[t]}`),
+    "Everything else applies immediately."
+  ];
+  return lines.join("\n");
+}
+function renderCapabilities(raw, opts) {
+  if (opts.json) return JSON.stringify(raw, null, 2);
+  const parsed = CapabilityCatalogueSchema.safeParse(raw);
+  if (parsed.success) return formatCapabilities(parsed.data);
+  return "(this CLI could not format the portal's response; showing it as JSON)\n" + JSON.stringify(raw, null, 2);
+}
+
 // src/auth/deviceFlow.ts
 import * as oidc from "openid-client";
 var DEVICE_SCOPES = "openid profile email offline_access";
@@ -2820,6 +2911,9 @@ async function skillCommand(client, _config, opts) {
   await writeFile2(outPath, skill, "utf8");
   console.log(`Wrote skill to ${outPath}`);
 }
+async function capabilitiesCommand(client, opts) {
+  console.log(renderCapabilities(await client.getCapabilities(), opts));
+}
 
 // src/auth/session.ts
 var REFRESH_MARGIN_MS = 6e4;
@@ -2897,9 +2991,6 @@ async function resolveConfig(flags, env = process.env, cwd = process.cwd()) {
   };
 }
 
-// src/version.ts
-var CLI_VERSION = true ? "0.5.0" : "latest";
-
 // src/ci/remote.ts
 function parseGithubRemote(remote, githubHost = "github.com") {
   const url = remote.trim();
@@ -3232,9 +3323,39 @@ function isLocalPortal(url) {
   return host === "localhost" || host === "127.0.0.1" || host.endsWith(".local") || host === "::1";
 }
 
+// src/compat.ts
+var NPX_LATEST = "npx -y @azx-pbc/helix-cli@latest";
+function parseVersion(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function isOlderThan(version, floor) {
+  const a = parseVersion(version);
+  const b = parseVersion(floor);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i];
+  }
+  return false;
+}
+async function warnIfCliTooOld(client, cliVersion, warn = (msg) => console.error(msg)) {
+  try {
+    const floor = (await client.getDeploymentConfig()).cli?.minVersion;
+    if (floor && isOlderThan(cliVersion, floor)) {
+      warn(
+        `warning: this portal needs helix-cli ${floor} or newer (you have ${cliVersion}). Run \`${NPX_LATEST} \u2026\`, or update your global install.`
+      );
+    }
+  } catch {
+  }
+}
+
 // src/bin.ts
 var USAGE = `helix \u2014 Helix deploy CLI
 
+Run it with \`npx -y @azx-pbc/helix-cli@latest <command>\` to always use the newest
+version, or install it with \`npm i -g @azx-pbc/helix-cli\`.
+
 Usage:
   helix login                # sign in via the browser (OIDC device flow)
   helix logout
@@ -3244,6 +3365,7 @@ Usage:
   helix versions
   helix promote  <number>
   helix rollback [number]
+  helix capabilities [--json]     # what this deployment offers: models, baselines, connections\u2026
   helix skill    [--path <file>]   # write this deployment's agent skill to disk
   helix ci init  [--repo <owner/name>] [--branch <b>] [--reusable] [--force]
                                    # connect the app to its GitHub repo and write the workflow
@@ -3273,6 +3395,7 @@ async function main() {
     config.portalUrl,
     makeTokenProvider({ portalUrl: config.portalUrl, staticToken: config.token })
   );
+  if (command !== "logout") await warnIfCliTooOld(client, CLI_VERSION);
   switch (command) {
     case "login":
       await loginCommand(client, config);
@@ -3283,6 +3406,9 @@ async function main() {
     case "whoami":
       await whoamiCommand(client);
       break;
+    case "capabilities":
+      await capabilitiesCommand(client, { json: values.json });
+      break;
     case "skill":
       await skillCommand(client, config, { path: values.path });
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azx-pbc/helix-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Deploy CLI for Helix, the AZX App Platform",
   "license": "MIT",
   "repository": {
@@ -32,9 +32,9 @@
     "esbuild": "^0.28.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "@azx-pbc/deploy-skill": "0.0.0",
+    "@azx-pbc/dev-idp": "0.0.0",
     "@azx-pbc/shared": "0.0.0",
-    "@azx-pbc/dev-idp": "0.0.0"
+    "@azx-pbc/deploy-skill": "0.0.0"
   },
   "scripts": {
     "helix": "tsx src/bin.ts",