@maxceem/agw 0.1.4 → 0.1.6

package/README.md

@@ -1,63 +1,131 @@
 # App AI Gateway CLI
 
-The `@maxceem/agw` package provides the `agw` executable. Node.js 22.19 or newer is required. It includes the compatible gateway release and Wrangler toolchain; end users do not need Git, pnpm, a global Wrangler installation, or a repository checkout.
+`agw` sets up and manages [App AI Gateway](https://github.com/maxceem/app-ai-gateway)
+from a terminal or a coding agent: providers, apps, usage, and your own
+deployment. Requires Node.js 22.19+.
 
 ```sh
-npx @maxceem/agw provider add --type openai
-npx @maxceem/agw app add --type ios --team-id ABCDE12345 --bundle-id com.example.app
+npm install -g @maxceem/agw
 ```
 
-A fresh cloud connection creates your account only when adding a provider, provider gateway, or application. Help, lists, status, validation and dry runs never create accounts. Logout retains your selected deployment and prior account marker; invalid or revoked access requires login, with no automatic fallback or second account.
+## Quick start
 
-For automation, have a human supply a provider credential in their own browser:
+```sh
+# 1. Sign in. Create a management key in the console: user menu -> Management keys.
+agw account login
+
+# 2. Add a provider. Paste the API key into the hidden prompt.
+agw provider add --type openai
+
+# 3. Add an app. It uses every provider you have added.
+agw app add --type ios --team-id ABCDE12345 --bundle-id com.example.app
+
+# 4. Print the Swift code that calls the gateway from that app.
+agw app snippet <app-id> --provider openai
+```
+
+Self-hosted? Replace step 1 with a connect to your gateway. It asks for the
+same kind of key:
 
 ```sh
-agw provider add --type openai --browser --no-open --json
-agw operation wait <operation-id> --timeout 300 --json
+agw deployment connect --url https://ai.example.com
 ```
 
-Share the returned URL. Hidden terminal input only prevents echo; an agent controlling that terminal can still observe it. The browser must be outside the agent's observable browser surface for credential isolation. Never pass credentials as command arguments. `--key-stdin` explicitly reads a single secret line. `--no-input` prohibits terminal prompts, and `--no-open` returns a browser operation without waiting.
+> **No account yet?** Skip step 1. The first `add` creates a free account on
+> the hosted gateway for you. Attach a sign-in to it later with
+> `agw account claim`. Help, status, lists, validation and dry runs never
+> create an account.
+
+## Self-host on Cloudflare
+
+The package drives Wrangler and installs the gateway release of its own version.
+No checkout needed. The gateway itself downloads once from the project's GitHub
+release and is cached, after the CLI matches it against a digest built into the
+executable.
 
-Run `agw --help` for the complete command surface and `agw <group> <command> --help` for its flags. Resource IDs and slugs are exact; display names are not selectors. File outputs never overwrite existing files. Server application keys are written with mode 0600 and never included in stdout. If persistence fails, the CLI attempts immediate revocation and reports the key ID for recovery.
+```sh
+agw deployment setup --name my-gateway --no-domain   # deploy and connect
+agw deployment update                                 # move to this CLI's release
+agw deployment domain --hostname ai.example.com       # attach a custom domain
+```
 
-Application JSON uses the gateway's shared complete write schema (`name`, `config`, optional `status`). Derive an editable definition from a saved app with `agw app show <app-id> --json | jq '.result.app | {name, config, status}'`; `app validate --file` and `app add --file --dry-run` validate it without account creation. Offline validation reports skipped remote checks. File mode preserves omission of App Attest environments; the simple iOS flags explicitly enable production and development. Application updates require the original ETag in `If-Match`; conflicting edits return an error instead of overwriting changes. Retained selected providers keep their detailed policies.
+Setup signs in to Cloudflare through Wrangler, or uses `CLOUDFLARE_API_TOKEN`
+if set. Add `--dry-run` to any of these to see what would happen. See the
+[self-hosting guide](https://docs.appaigateway.com/self-hosting/deploy-to-cloudflare).
 
-Swift snippets use the current package at `https://github.com/maxceem/app-ai-gateway-swift` (from version 1.0.0), actual application/provider IDs, and the saved authentication mode. Issuer examples require replacing the indicated identity SDK call. Requests still need a provider-native body and must be sent by the caller. No setup or readiness check sends paid inference or proves physical-device attestation.
+No route to GitHub from that machine? Fetch the `gateway-<version>.tar.gz` asset
+elsewhere and pass `--release-archive <path>`.
 
-## Output and state
+## Commands
 
-`--json` emits exactly one JSON document to stdout. Progress goes to stderr. The result envelope is `{schemaVersion:1,ok:true,context:{url,accountId?,deploymentId?},result}`. Errors are `{schemaVersion:1,ok:false,error:{code,message,nextAction,details?}}`. Unknown remote fields are excluded from output; complete validated application config preserves provider-native endpoint parameters.
+| Group | What it manages |
+| --- | --- |
+| `provider` | Provider credentials: `add`, `list`, `show`, `update`, `rotate-key`, `remove` |
+| `provider-gateway` | Cloudflare AI Gateway in front of a provider |
+| `app` | Apps and their config: `add`, `list`, `show`, `update`, `validate`, `check`, `snippet`, `remove`, `key` |
+| `usage` | Spend and requests: `show`, `breakdown` |
+| `account` | `status`, `claim`, `login`, `logout` |
+| `deployment` | `setup`, `connect`, `status`, `update`, `domain` |
+| `operation` | `status` and `wait` for browser handoffs |
 
-Exit statuses: `0` success (including pending handoff initiation), `2` input/validation error, `3` remote/connectivity or failed handoff, `4` local state/recovery/authentication issue, `5` wait timeout. Timeout includes still-pending operation metadata and does not cancel or extend the server operation. Poll authorization is stored separately from public operation IDs/URLs. Authentication handoff completion is persisted before output, and replay cannot undo a logout or later connection switch.
+`agw --help` lists every command; `agw <group> <command> --help` lists its flags.
 
-State is `$XDG_STATE_HOME/agw` or `~/.local/state/agw` on Unix, and `%LOCALAPPDATA%/agw` on Windows. The directory is mode 0700 and files are mode 0600. It contains one active connection, the previous connection for intentional recovery, pending operations, creation retry proofs, application keys, and protected installation journals. No public profile selectors or gateway credential environment overrides exist. Back up this directory securely. Concurrent commands use an exclusive lock; after a crashed process, inspect the PID in `connection.lock` before removing that lock. Never delete connection state merely to resolve an authentication error.
+## Using `agw` from an agent
 
-Public API URLs require HTTPS, no userinfo, query, fragment or path. Only `localhost`, `127.0.0.1` and `[::1]` permit HTTP for local development. Authenticated HTTP redirects are refused. Connecting authenticates only to the requested origin and selects it after success.
+Full guide: [docs.appaigateway.com/automation/cli](https://docs.appaigateway.com/automation/cli).
+The whole documentation is also published as
+[agents.md](https://docs.appaigateway.com/agents.md).
 
-## Self-hosting
+**Output.** Add `--json` for exactly one JSON document on stdout; progress goes
+to stderr. Add `--no-input` to fail instead of prompting.
 
-```sh
-agw deployment setup --name my-gateway --no-domain
-agw deployment update --dry-run
-agw deployment domain --hostname ai.example.com --dry-run
+```json
+{ "schemaVersion": 1, "ok": true,  "context": { "url": "...", "accountId": "..." }, "result": { } }
+{ "schemaVersion": 1, "ok": false, "error": { "code": "...", "message": "...", "nextAction": "...", "details": { } } }
 ```
 
-Setup obtains Cloudflare authorization using bundled Wrangler OAuth, or accepts standard securely configured Cloudflare credentials such as `CLOUDFLARE_API_TOKEN`. If more than one Cloudflare account is accessible, choose one with `--cloudflare-account-id`. Noninteractive mutations require explicit configuration and `--yes`; `--yes` does not grant Cloudflare permissions or approve browser identity ceremonies.
+Every error names a `code` and a `nextAction`. Follow the `nextAction`.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | Success, including a browser handoff that is still pending |
+| `2` | Invalid input or validation failure |
+| `3` | Gateway unreachable, remote error, or failed handoff |
+| `4` | Local state or authentication problem |
+| `5` | `operation wait` timed out; the operation is still pending |
 
-The npm package contains a versioned Worker bundle, console assets, migrations, configuration, and SHA-256 manifest. npm package integrity authenticates the package; local manifest/file digests detect corrupt assets before deployment. `--version` selects only the bundled compatible release; use the matching CLI package version for another release. No unversioned source download or arbitrary downgrade is performed. Release format/schema versions are checked before mutation.
+**Secrets.** Never put a key in a command argument. Either pipe it with
+`--key-stdin`, or hand the browser to a human:
 
-Installation journals are written before creating resources, keep generated vault/signing/bootstrap secrets across retries, and bind the Cloudflare account, Worker, D1 database and immutable deployment ID. A Worker name collision never authorizes takeover. Retry an incomplete setup with the same name/account; its previous active gateway connection remains selected until bootstrap succeeds. A completed setup does not replay retired bootstrap credentials or overwrite subsequently rotated secrets. Updates preserve existing secrets and reject unsupported schema transitions. Database migrations do not have an automatic rollback.
+```sh
+agw provider add --type openai --browser --no-open --json   # prints a URL
+agw operation wait <operation-id> --timeout 300 --json      # resumes when done
+```
 
-A URL-only connection can be matched interactively to an explicitly selected accessible Worker only when its Cloudflare `DEPLOYMENT_ID` matches the gateway. Unsupported extra resource bindings fail rather than being discarded. Noninteractive deployment administration needs the existing installation journal. Dry runs discover/validate only; they do not provision resources, generate/upload secrets, change DNS, bootstrap accounts or select connections.
+Share the URL with the person who holds the credential. Nothing typed on that
+page reaches the CLI or its output.
 
-Custom domains require an accessible active zone. Existing unrelated DNS or Worker domain attachments are refused. The new endpoint must identify the same deployment before credentials follow it. Existing hostnames remain served; mobile applications keep their embedded URL until updated. Changing from cloud to self-hosting does not migrate app IDs, provider credentials, usage or existing applications.
+**Editing apps.** Read before you write. `app show --json` returns the full
+config; save `{name, config, status}` from `result.app`, edit it, and pass it
+back with `app update <id> --file`. A concurrent change is rejected rather than
+overwritten. `app validate --file` checks a file without touching the account.
 
-## Release verification for contributors
+**State.** Connection, credentials and pending operations live in
+`~/.local/state/agw` (`$XDG_STATE_HOME/agw`, or `%LOCALAPPDATA%/agw` on
+Windows), mode 0700. Do not delete it to fix an authentication error; run
+`agw account login` instead. Output files are never overwritten.
 
-`pnpm run cli:check` type-checks the CLI with `tsgo` and then bundles the portable schemas and executable. `pnpm run cli:test` runs parser, state, transport, command and mocked deployment tests; both are included in root verification. `pnpm --filter @maxceem/agw release:build` builds the actual deployable bundle locally. `npm pack` runs that release build and packages only `dist`, this README and the Apache-2.0 license. Verify the tarball and invoke its installed executable outside the repository before publishing. Publishing and live Cloudflare operations are separate release decisions.
+## Contributing
 
-Creation retries persist a request proof before sending provider, gateway, app or application-key creation. Repeating an unfinished saved request returns its original result. After successful output delivery, its local pending receipt is acknowledged, so a later invocation is a new intentional creation. A server key response can be recovered remotely for 15 minutes; after that, the error identifies the existing resource so you can inspect and replace its key intentionally. Non-secret receipt records prevent duplicate creation for the lifetime of the account. An unfinished local request older than 90 days refuses to submit again automatically.
+The CLI lives in `cli/` of the
+[main repository](https://github.com/maxceem/app-ai-gateway). From the repo root:
 
-The CLI saves a one-time key response in protected local state before writing the selected `--key-output` file. If the file write fails, repeat the same command to complete that file, or choose a new unused output path; this uses the saved active key and does not mint another. Once file delivery completes, the recovery copy is removed; a retry before successful command output verifies that original file. After stdout delivery is acknowledged, a later key creation is a new request and requires a new unused output file. Existing unrelated files and replaced output reservations are never overwritten.
+```sh
+pnpm run cli:check   # type-check and bundle
+pnpm run cli:test    # run the CLI tests
+```
 
-Unfinished bootstrap attempts also have a 90-day local retry deadline. Missing or expired timestamps fail closed and preserve the proof for recovery. Server cleanup retains only a non-secret, proof-bound bootstrap tombstone after deleting an expired account, so an old retry cannot recreate that account. The tombstone contains no account identity or credential and is intentionally retained beyond ordinary challenge expiry.
+Both are part of `pnpm run verify`. Releasing is two steps in order:
+`pnpm run cli:release:github` builds the gateway archive and uploads it to the
+GitHub release, then `npm publish` from `cli/` ships the executable that
+demands that exact archive. Licensed under Apache-2.0.

package/dist/agw.mjs

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 };
 
 // <define:__AGW_MANIFEST__>
-var define_AGW_MANIFEST_default = { version: "0.1.4", wrangler: "4.96.0", upgradeFrom: ["0.1.4", "0.1.3", "0.1.2", "0.1.1", "0.1.0"] };
+var define_AGW_MANIFEST_default = { version: "0.1.6", wrangler: "4.96.0", upgradeFrom: ["0.1.6", "0.1.5", "0.1.4", "0.1.3", "0.1.2", "0.1.1", "0.1.0"], release: { url: "https://github.com/maxceem/app-ai-gateway/releases/download/v0.1.6/gateway-0.1.6.tar.gz", sha256: "991b01cceb651259fdd340c6010bd254f1f2c4d0363d6c20028dda40c03d01d9", manifest: "cd0e66ec52965108fddc50ee3e36e5fb39f5a2e868061d333279c3fdb609e57d" } };
 
 // src/main.ts
 import { Writable } from "node:stream";
@@ -7649,8 +7649,8 @@ function ko_default() {
 }
 
 // ../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/locales/lt.js
-var capitalizeFirstCharacter = (text) => {
-  return text.charAt(0).toUpperCase() + text.slice(1);
+var capitalizeFirstCharacter = (text2) => {
+  return text2.charAt(0).toUpperCase() + text2.slice(1);
 };
 function getUnitTypeFromNumber(number4) {
   const abs = Math.abs(number4);
@@ -15511,7 +15511,6 @@ var CliOperationRequestSchema = external_exports.object({
 var CliSubmissionRequestSchema = external_exports.object({
   submissionToken: CliProofSchema,
   approve: external_exports.literal(true).optional(),
-  allowServiceAccess: external_exports.boolean().optional(),
   email: external_exports.email().optional(),
   password: external_exports.string().min(8).max(256).optional(),
   name: external_exports.string().min(1).max(100).optional(),
@@ -15530,11 +15529,27 @@ var CliAccountSchema = external_exports.object({
   claimed: external_exports.boolean(),
   expiresAt: external_exports.string().nullable()
 });
+var CliApprovalRefusalSchema = external_exports.enum([
+  "registration_required",
+  "sign_out_required"
+]);
+var CliViewerSchema = external_exports.object({
+  name: external_exports.string().nullable(),
+  email: external_exports.string().nullable()
+});
 var CliBrowserDetailsResponseSchema = external_exports.object({
   kind: CliOperationRequestSchema.shape.kind,
   payload: external_exports.record(external_exports.string(), external_exports.unknown()),
   account: CliAccountSchema,
-  signedIn: external_exports.boolean(),
+  viewer: CliViewerSchema.nullable(),
+  /**
+   * What stands between this browser and the Approve button, or null when
+   * nothing does — which is every non-claim kind, since only a claim asks who
+   * is holding the browser. One field decides the whole screen: each value
+   * names the single thing the page may offer, so the page never has to
+   * consult the handoff kind to know what to put in front of a person.
+   */
+  blockedBy: CliApprovalRefusalSchema.nullable(),
   googleEnabled: external_exports.boolean(),
   expiresAt: external_exports.string()
 });
@@ -15569,8 +15584,6 @@ var CliOperationResponseSchema = external_exports.object({
 var CliOperationResultSchema = external_exports.object({
   /** The account a claim acted on. */
   accountId: external_exports.string().optional(),
-  /** Whether the claiming human left the CLI's service access in place. */
-  accessGranted: external_exports.boolean().optional(),
   /** The stored row a provider submission created or rotated. */
   provider: ProviderSummarySchema.optional(),
   gateway: ProviderGatewaySummarySchema.optional()
@@ -15961,11 +15974,12 @@ function fromPackageJson() {
   if (typeof packaged.version !== "string" || typeof wrangler !== "string") {
     throw new Error("cli/package.json must declare a version and a pinned wrangler dependency");
   }
-  return { version: packaged.version, wrangler };
+  return { version: packaged.version, wrangler, release: null };
 }
 var manifest = typeof define_AGW_MANIFEST_default === "object" && define_AGW_MANIFEST_default !== null ? define_AGW_MANIFEST_default : fromPackageJson();
 var VERSION = manifest.version;
 var WRANGLER_VERSION = manifest.wrangler;
+var RELEASE = manifest.release ?? null;
 
 // src/common.ts
 var CLOUD = "https://api.appaigateway.com";
@@ -16104,15 +16118,21 @@ var common = "json! no-input!";
 var commands = {
   "deployment setup": {
     args: 0,
-    flags: "name cloudflare-account-id domain no-domain! version dry-run! yes!"
+    flags: "name cloudflare-account-id domain no-domain! version release-archive dry-run! yes!"
   },
   "deployment connect": {
     args: 0,
     flags: `url cloud! ${managementKey}`
   },
   "deployment status": { args: 0, flags: "" },
-  "deployment update": { args: 0, flags: "version dry-run! yes!" },
-  "deployment domain": { args: 0, flags: "hostname dry-run! yes!" },
+  "deployment update": {
+    args: 0,
+    flags: "version release-archive dry-run! yes!"
+  },
+  "deployment domain": {
+    args: 0,
+    flags: "hostname release-archive dry-run! yes!"
+  },
   "account status": { args: 0, flags: "" },
   "account claim": { args: 0, flags: browser },
   "account login": { args: 0, flags: managementKey },
@@ -16528,6 +16548,14 @@ function stateDirectory() {
     "agw"
   );
 }
+function cacheDirectory() {
+  if (platform() === "win32")
+    return join(
+      process.env["LOCALAPPDATA"] || join(homedir(), "AppData", "Local"),
+      "agw"
+    );
+  return join(process.env["XDG_CACHE_HOME"] || join(homedir(), ".cache"), "agw");
+}
 async function protectedDirectory(path) {
   await mkdir(path, { recursive: true, mode: 448 });
   const s = await lstat(path);
@@ -16566,14 +16594,14 @@ async function reserveOutput(path, { reservation, retain = false } = {}) {
     },
     async write(value) {
       if (!handle) throw new Error("The reserved output is closed");
-      const text = typeof value === "string" ? value : JSON.stringify(value, null, 2) + "\n";
+      const text2 = typeof value === "string" ? value : JSON.stringify(value, null, 2) + "\n";
       try {
         if (retain) {
           const existing = await handle.readFile("utf8");
-          if (existing && !text.startsWith(existing)) fail("output_changed", "The reserved output contains different data.", "Choose a new --key-output path; no existing data was overwritten.", 4);
+          if (existing && !text2.startsWith(existing)) fail("output_changed", "The reserved output contains different data.", "Choose a new --key-output path; no existing data was overwritten.", 4);
           await handle.truncate(0);
-          await handle.write(text, 0, "utf8");
-        } else await handle.writeFile(text);
+          await handle.write(text2, 0, "utf8");
+        } else await handle.writeFile(text2);
         await handle.sync();
         await handle.close();
         handle = null;
@@ -17793,14 +17821,7 @@ Operation: ${data.id}
           4
         );
       operation2.completed = true;
-      if (this.active) {
-        if (data.account) this.active.account = data.account;
-        if (data.result?.accessGranted === false) {
-          delete this.active.credential;
-          this.active.authenticated = false;
-          this.state.generation = (this.state.generation ?? 0) + 1;
-        }
-      }
+      if (this.active && data.account) this.active.account = data.account;
       await this.save();
     }
     return data;
@@ -17863,42 +17884,226 @@ async function openBrowser(url2) {
 import { spawn as spawn2 } from "node:child_process";
 import { createRequire as createRequire2 } from "node:module";
 import { randomUUID } from "node:crypto";
-import { cp, writeFile, unlink as unlink2 } from "node:fs/promises";
+import { cp, writeFile as writeFile2, unlink as unlink2 } from "node:fs/promises";
 import { join as join3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 
 // src/release.ts
-import { readFile as readFile3, lstat as lstat2 } from "node:fs/promises";
+import { readFile as readFile3, lstat as lstat2, mkdir as mkdir2, rename as rename2, rm, writeFile } from "node:fs/promises";
 import { join as join2, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createHash as createHash4 } from "node:crypto";
-async function release(requested = VERSION, base = dirname(fileURLToPath(import.meta.url))) {
+import { createHash as createHash4, randomBytes as randomBytes3 } from "node:crypto";
+
+// src/archive.ts
+import { gunzipSync } from "node:zlib";
+var BLOCK = 512;
+var ARCHIVE_LIMIT = 64 * 1024 * 1024;
+function text(header, start, length) {
+  const raw = header.subarray(start, start + length);
+  const end = raw.indexOf(0);
+  return raw.subarray(0, end === -1 ? raw.length : end).toString("latin1");
+}
+function octal(header, start, length, field) {
+  const value = text(header, start, length).trim();
+  if (!/^[0-7]+$/.test(value))
+    fail("release_archive", `Release archive has an unreadable ${field} field.`);
+  const parsed = Number.parseInt(value, 8);
+  if (!Number.isSafeInteger(parsed))
+    fail("release_archive", `Release archive has an out-of-range ${field} field.`);
+  return parsed;
+}
+function checksumMatches(header) {
+  const stored = octal(header, 148, 8, "checksum");
+  let unsigned = 0;
+  let signed = 0;
+  for (let i = 0; i < BLOCK; i++) {
+    const byte = i >= 148 && i < 156 ? 32 : header[i];
+    unsigned += byte;
+    signed += byte > 127 ? byte - 256 : byte;
+  }
+  return stored === unsigned || stored === signed;
+}
+function safePath(raw, directory) {
+  const path = directory ? raw.replace(/\/+$/, "") : raw;
+  if (!path || path.startsWith("/") || path.includes("\\") || path.split("/").some((segment) => segment === "" || segment === "." || segment === ".."))
+    fail("release_archive", "Release archive contains an unsafe path.");
+  return path;
+}
+function readArchive(gzipped, limit = ARCHIVE_LIMIT) {
+  let tar;
+  try {
+    tar = gunzipSync(gzipped, { maxOutputLength: limit });
+  } catch {
+    fail("release_archive", "Release archive is not readable gzip within the size limit.");
+  }
+  if (tar.length % BLOCK !== 0)
+    fail("release_archive", "Release archive is not a whole number of tar blocks.");
+  const entries = [];
+  let total = 0;
+  let offset = 0;
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK);
+    if (header.every((byte) => byte === 0)) {
+      if (!tar.subarray(offset).every((byte) => byte === 0))
+        fail("release_archive", "Release archive continues past its end marker.");
+      return entries;
+    }
+    if (text(header, 257, 6).trim() !== "ustar")
+      fail("release_archive", "Release archive is not in ustar format.");
+    if (!checksumMatches(header))
+      fail("release_archive", "Release archive has a corrupt header.");
+    const type = String.fromCharCode(header[156]);
+    if (type === "L" || type === "K")
+      fail("release_archive", "Release archive uses GNU long-name extensions.");
+    if (type !== "0" && type !== "\0" && type !== "5")
+      fail(
+        "release_archive",
+        "Release archives may contain only regular files and directories."
+      );
+    const directory = type === "5";
+    const prefix = text(header, 345, 155);
+    const name = text(header, 0, 100);
+    const path = safePath(prefix ? `${prefix}/${name}` : name, directory);
+    const size = octal(header, 124, 12, "size");
+    if (directory && size !== 0)
+      fail("release_archive", "Release archive has a directory entry with contents.");
+    total += size;
+    if (total > limit) fail("release_archive", "Release archive exceeds its size limit.");
+    const start = offset + BLOCK;
+    if (start + size > tar.length)
+      fail("release_archive", "Release archive is truncated.");
+    entries.push({
+      path,
+      directory,
+      data: directory ? Buffer.alloc(0) : Buffer.from(tar.subarray(start, start + size))
+    });
+    offset = start + Math.ceil(size / BLOCK) * BLOCK;
+  }
+  fail("release_archive", "Release archive has no end marker.");
+}
+
+// src/release.ts
+var digest = (data) => createHash4("sha256").update(data).digest("hex");
+async function fetchArchive(url2) {
+  let response;
+  try {
+    response = await fetch(url2, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(3e5),
+      headers: { "user-agent": `agw/${VERSION}` }
+    });
+  } catch {
+    fail(
+      "release_download",
+      `Cannot download the gateway release from ${url2}.`,
+      "Check network access, or pass --release-archive with a copy downloaded elsewhere.",
+      3
+    );
+  }
+  if (!response.ok)
+    fail(
+      "release_download",
+      `Downloading the gateway release from ${url2} failed with HTTP ${response.status}.`,
+      "Check network access, or pass --release-archive with a copy downloaded elsewhere.",
+      3
+    );
+  const body = Buffer.from(await response.arrayBuffer());
+  if (body.length > ARCHIVE_LIMIT)
+    fail("release_download", "The downloaded gateway release exceeds its size limit.", void 0, 3);
+  return body;
+}
+async function extract(archive, directory) {
+  await mkdir2(directory, { recursive: true, mode: 448 });
+  for (const entry of readArchive(archive)) {
+    const path = join2(directory, entry.path);
+    if (entry.directory) {
+      await mkdir2(path, { recursive: true, mode: 448 });
+      continue;
+    }
+    await mkdir2(dirname(path), { recursive: true, mode: 448 });
+    await writeFile(path, entry.data, { mode: 384, flag: "wx" });
+  }
+}
+async function cachedRelease(version2, integrity, source) {
+  const root = source.cache ?? join2(cacheDirectory(), "releases");
+  const directory = join2(root, version2);
+  const cached2 = await readFile3(join2(directory, "manifest.json")).catch(() => null);
+  if (cached2 && digest(cached2) === integrity.manifest) return directory;
+  const supplied = source.archive ?? process.env["AGW_RELEASE_ARCHIVE"] ?? void 0;
+  let archive;
+  if (supplied) {
+    archive = await readFile3(supplied).catch(
+      () => fail(
+        "release_unavailable",
+        `Cannot read the gateway release archive at ${supplied}.`,
+        "Supply the gateway-<version>.tar.gz asset published with this CLI release.",
+        4
+      )
+    );
+  } else {
+    archive = await (source.download ?? fetchArchive)(integrity.url);
+  }
+  if (digest(archive) !== integrity.sha256)
+    fail(
+      "release_integrity",
+      "The gateway release archive does not match the digest built into this CLI.",
+      "Nothing was extracted. Obtain the archive published with this CLI version.",
+      4
+    );
+  await protectedDirectory(root);
+  const staging = join2(root, `.${version2}-${randomBytes3(8).toString("hex")}`);
+  try {
+    await extract(archive, staging);
+    const manifest2 = await readFile3(join2(staging, "manifest.json")).catch(() => null);
+    if (!manifest2 || digest(manifest2) !== integrity.manifest)
+      fail(
+        "release_integrity",
+        "The gateway release archive does not contain the expected manifest.",
+        "Nothing was installed. Obtain the archive published with this CLI version.",
+        4
+      );
+    await rm(directory, { recursive: true, force: true });
+    await rename2(staging, directory);
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+  return directory;
+}
+async function release(requested = VERSION, base = dirname(fileURLToPath(import.meta.url)), source = {}) {
   if (requested !== VERSION)
     fail(
       "unsupported_release",
-      `This CLI bundles gateway ${VERSION} only.`,
+      `This CLI deploys gateway ${VERSION} only.`,
       `Install @maxceem/agw@${requested} to use its matching release.`
     );
   const [major, minor] = process.versions.node.split(".").map(Number);
   if (major === void 0 || minor === void 0 || major < 22 || major === 22 && minor < 19)
     fail("unsupported_runtime", "Node.js 22.19.0 or newer is required.");
-  const directory = join2(base, "release", requested);
+  const integrity = source.integrity === void 0 ? RELEASE : source.integrity;
+  const packaged = join2(base, "release", requested);
+  const local = await lstat2(packaged).catch(() => null);
+  let directory;
+  if (local?.isDirectory()) directory = packaged;
+  else if (integrity) directory = await cachedRelease(requested, integrity, source);
+  else
+    fail(
+      "release_missing",
+      "This CLI build does not know where to obtain its deployable release.",
+      "Install a published release; repository contributors must run the CLI release build.",
+      4
+    );
   let serialized;
-  let integrity;
   try {
     serialized = await readFile3(join2(directory, "manifest.json"), "utf8");
-    integrity = JSON.parse(
-      await readFile3(join2(base, "release-integrity.json"), "utf8")
-    );
   } catch {
     fail(
       "release_missing",
-      "The CLI package does not contain its deployable release.",
-      "Install a packaged release; repository contributors must run the CLI release build.",
+      "The deployable release is missing its manifest.",
+      "Install a published release; repository contributors must run the CLI release build.",
       4
     );
   }
-  if (createHash4("sha256").update(serialized).digest("hex") !== integrity.sha256)
+  if (integrity && digest(serialized) !== integrity.manifest)
     fail("release_integrity", "Release manifest integrity check failed.");
   const manifest2 = JSON.parse(serialized);
   if (manifest2.format !== 1 || manifest2.version !== requested || manifest2.wrangler !== WRANGLER_VERSION || manifest2.schema !== 1)
@@ -17911,7 +18116,7 @@ async function release(requested = VERSION, base = dirname(fileURLToPath(import.
       fail("release_integrity", "Release includes an unsafe path.");
     const file2 = join2(directory, path);
     const info = await lstat2(file2);
-    if (!info.isFile() || info.isSymbolicLink() || createHash4("sha256").update(await readFile3(file2)).digest("hex") !== hash2)
+    if (!info.isFile() || info.isSymbolicLink() || digest(await readFile3(file2)) !== hash2)
       fail("release_integrity", "Release asset integrity check failed.");
   }
   return {
@@ -17927,7 +18132,7 @@ async function release(requested = VERSION, base = dirname(fileURLToPath(import.
 var require2 = createRequire2(import.meta.url);
 var OUTPUT_TAIL = 2e3;
 function wranglerFailure(args, code, output, redact = []) {
-  const tail = redact.filter((value) => value.length >= 8).reduce((text, value) => text.split(value).join("[redacted]"), output).trim().slice(-OUTPUT_TAIL);
+  const tail = redact.filter((value) => value.length >= 8).reduce((text2, value) => text2.split(value).join("[redacted]"), output).trim().slice(-OUTPUT_TAIL);
   return new CliError(
     "wrangler_failed",
     `wrangler ${args[0] ?? ""} failed${code === null ? "" : ` (exit ${code})`}.`,
@@ -18114,7 +18319,7 @@ async function configFile(ctx, journal, artifact) {
     } : {}
   };
   const path = join3(directory, "wrangler.json");
-  await writeFile(path, JSON.stringify(config2, null, 2), { mode: 384 });
+  await writeFile2(path, JSON.stringify(config2, null, 2), { mode: 384 });
   return { path, directory, config: config2 };
 }
 async function verifyDeployment(ctx, url2, id) {
@@ -18334,7 +18539,9 @@ async function matchExisting(ctx, cf, flags) {
   return journal;
 }
 async function deploymentCommand(ctx, command, flags, cf = new Cloudflare(), loadRelease = release) {
-  const artifact = await loadRelease(flags.version);
+  const artifact = await loadRelease(flags.version, void 0, {
+    archive: flags["release-archive"]
+  });
   await cf.authenticate(flags);
   if (command !== "deployment setup") {
     const journal2 = await matchExisting(ctx, cf, flags);
@@ -18500,7 +18707,7 @@ async function deploymentCommand(ctx, command, flags, cf = new Cloudflare(), loa
       SECRET_VAULT_LOCAL_KEK_V1: await ctx.store.vaultKey(journal.id)
     };
     const secretPath = join3(file2.directory, "secrets.json");
-    await writeFile(secretPath, JSON.stringify(secrets), {
+    await writeFile2(secretPath, JSON.stringify(secrets), {
       mode: 384
     });
     try {
@@ -18616,10 +18823,10 @@ function* strings(value) {
 }
 function reported(value, sent) {
   if (typeof value !== "string") return "";
-  let text = value.replace(new RegExp("\\p{C}", "gu"), " ").replace(/\s+/g, " ").trim();
+  let text2 = value.replace(new RegExp("\\p{C}", "gu"), " ").replace(/\s+/g, " ").trim();
   for (const secret3 of strings(sent))
-    if (secret3.length >= 8) text = text.split(secret3).join("[redacted]");
-  return text.length > MESSAGE_LIMIT ? text.slice(0, MESSAGE_LIMIT) + "\u2026" : text;
+    if (secret3.length >= 8) text2 = text2.split(secret3).join("[redacted]");
+  return text2.length > MESSAGE_LIMIT ? text2.slice(0, MESSAGE_LIMIT) + "\u2026" : text2;
 }
 var RECOVERABLE_RESOURCE_CODES = ["resource_receipt_expired", "resource_key_unavailable"];
 var RECOVERABLE_RESOURCE_FIELDS = ["appId", "keyId", "providerId", "providerGatewayId"];
@@ -18814,16 +19021,16 @@ async function main(argv = process.argv.slice(2), {
       };
       const rendered = ctx.onboarding ? { ...result, ...ctx.onboarding } : result;
       const output = { schemaVersion: 1, ok: true, context, result: rendered };
-      const text = json2 ? JSON.stringify(output) + "\n" : humanResult(parsed.command, rendered, context);
+      const text2 = json2 ? JSON.stringify(output) + "\n" : humanResult(parsed.command, rendered, context);
       if (stdout instanceof Writable) {
         await new Promise(
           (resolve3, reject2) => stdout.write(
-            text,
+            text2,
             (error51) => error51 ? reject2(error51) : resolve3()
           )
         );
       } else {
-        stdout.write(text);
+        stdout.write(text2);
       }
       await ctx.acknowledgeOutput();
       return 0;