@juuno-sdk/cli 4.0.2 → 4.2.0

package/README.md

@@ -118,8 +118,74 @@ npx juuno-cli deploy
 
 # Specify build directory
 npx juuno-cli deploy --build-dir ./build
+
+# Let the backend check the build, and deploy nothing
+npx juuno-cli deploy --dry-run
+```
+
+`--dry-run` sends the same upload with `dry_run=1`. The backend runs every
+check of a real deploy, including the rules for a config schema, and writes
+nothing, so you find a problem before the release is immutable. The CLI prints
+"Dry run passed", or the backend's error message unchanged and exits non-zero.
+
+A deploy and a dry run print each `required` config key that the release adds,
+with the default that goes into your existing scenes, for example:
+
+```text
+   Adds `meta.styles.spotsTextColor` (required, default `#011841`).
+```
+
+A release with a config schema is not served until the backend has filled the
+existing scenes, so the deploy waits until the release is live. If the fill
+fails, the previous release stays live and the CLI exits non-zero. Releases are
+immutable, so the next deploy needs a higher version.
+
+Build with source maps on. An error thrown in your app is reported as a position
+in the minified bundle, and a map beside that bundle is what turns it back into
+a line of your own source, for you and for Juuno support. The deploy uploads
+whatever the build directory holds, maps included, and warns when it finds none.
+
+### Deploying an App Backend
+
+An **app backend** is a Cloudflare Workers-for-Platforms tenant script that owns
+one app's data and logic. Deploying goes through Juuno's platform rather than
+straight to Cloudflare — that is what provisions the app's KV and D1 stores,
+fills their ids, and triggers the tenant's own migrations. A raw
+`wrangler deploy --dispatch-namespace` silently skips all of it.
+
+Run it from the worker directory:
+
+```bash
+cd cloudflare-workers/app-google-reviews
+
+# Deploy to stage
+npx juuno-cli deploy-backend --profile stage
+
+# See what would be sent, without deploying
+npx juuno-cli deploy-backend --profile stage --print-metadata
 ```
 
+The environment is not chosen here. Each API instance is pinned to exactly one
+dispatch namespace and reports which environment that is, so the profile you
+deploy with determines the target; the CLI uses that answer to select the
+matching env in `wrangler.jsonc`. The bindings that get built and the namespace
+that receives them therefore always agree, with nothing to keep in sync. A
+worker with no matching env fails with the envs it does declare.
+
+Bundling shells out to the worker's own pinned `wrangler`, so the version in its
+`devDependencies` is the one that runs.
+
+Observability is on for every deploy: the platform fills `enabled: true` when
+the upload does not say otherwise, so the tenant's logs reach the Superadmin
+Logs tab without any `wrangler.jsonc` setting. The worker's `observability`
+block is still forwarded as written, for a sampling rate or an explicit
+`"enabled": false`.
+
+**The backend must already be registered** in Superadmin, on the Backend tab of
+the app it serves. Registration is what attaches it to an app and mints its
+platform secret; deploying an unregistered script is refused before anything
+uploads.
+
 ### List Apps
 
 View all your deployed apps.
@@ -305,6 +371,7 @@ juuno-cli deploy [options]
 
 Options:
   --build-dir <dir> Build directory to deploy (default: ./dist)
+  --dry-run         Let the backend check the build, and deploy nothing
   --profile <name>  Use credentials from the given profile
   --token <token>   Override with specific token (for CI/CD)
   --email <email>   Login with email instead of using saved credentials

package/bin/cli-router.js

@@ -22,6 +22,54 @@ export function parseAuthOptions(args) {
   };
 }
 
+/** Every flag `deploy-backend` accepts, its own and the shared auth ones. */
+const DEPLOY_BACKEND_FLAGS = [
+  '--dir',
+  '--print-metadata',
+  '--email',
+  '--password',
+  '--token',
+  '--profile',
+  '--api-url',
+];
+
+/**
+ * What is wrong with a `deploy-backend` line, or null if nothing is.
+ *
+ * Strict where the other commands are lenient, and deliberately so: this one
+ * uploads to a real dispatch namespace, and it takes no `--env` because the
+ * environment comes from the profile's API. Ignoring an unknown argument would
+ * turn `--env stage` into a silent deploy of stage code wherever the active
+ * profile points, and a `--dir` with no path would deploy whichever worker the
+ * shell happens to be standing in.
+ *
+ * @param {string[]} args - Command arguments, including the command itself
+ * @returns {string|null} The problem, or null if the line is usable
+ */
+export function checkDeployBackendArgs(args) {
+  const unknown = args.filter(
+    (arg) => arg.startsWith('--') && !DEPLOY_BACKEND_FLAGS.includes(arg),
+  );
+
+  if (unknown.length > 0) {
+    return `Unknown argument: ${unknown.join(', ')}`;
+  }
+
+  const dirIndex = args.indexOf('--dir');
+
+  if (dirIndex !== -1) {
+    const dir = args[dirIndex + 1];
+
+    // Nothing after it, or the next flag — which it would otherwise swallow as
+    // its value.
+    if (dir === undefined || dir.startsWith('--')) {
+      return '--dir requires a path.';
+    }
+  }
+
+  return null;
+}
+
 /**
  * Per-command dispatch table. adding a command is one entry.
  */
@@ -53,9 +101,31 @@ const COMMANDS = {
     await deployApp({
       buildDir,
       skipIfDeployed: args.includes('--skip-if-deployed'),
+      dryRun: args.includes('--dry-run'),
       ...parseAuthOptions(args),
     });
   },
+  'deploy-backend': async (args, importPrefix) => {
+    const problem = checkDeployBackendArgs(args);
+    if (problem) {
+      console.error(`❌ ${problem}`);
+      console.error(
+        '   Usage: juuno-cli deploy-backend [--dir <path>] [--print-metadata]',
+      );
+      process.exit(1);
+    }
+
+    const { deployBackend } = await import(
+      `${importPrefix}deploy-backend/index.js`
+    );
+    const dirIndex = args.indexOf('--dir');
+    await deployBackend({
+      dir: dirIndex !== -1 ? args[dirIndex + 1] : undefined,
+      printMetadata: args.includes('--print-metadata'),
+      ...parseAuthOptions(args),
+    });
+  },
+
   list: async (args, importPrefix) => {
     const { listApps } = await import(`${importPrefix}list/index.js`);
     await listApps(parseAuthOptions(args));
@@ -72,6 +142,27 @@ const COMMANDS = {
   },
 };
 
+/**
+ * The code the process should exit with.
+ *
+ * `process.exitCode` is how a command reports a failure it must not throw for —
+ * deploy-backend writes the server's own account of a deploy that may already
+ * have landed, rather than throwing and having it wrapped as a refusal. An
+ * explicit code passed to `process.exit()` overrides that, so handing it the
+ * handler's 0 turned a failed deploy into a green CI run.
+ *
+ * @param {number} commandExitCode - What runCommand() returned
+ * @param {number|string|undefined} reportedExitCode - process.exitCode, as the command left it
+ * @returns {number} The code to exit with
+ */
+export function resolveExitCode(commandExitCode, reportedExitCode) {
+  if (commandExitCode !== 0) {
+    return commandExitCode;
+  }
+
+  return Number(reportedExitCode ?? 0);
+}
+
 /**
  * Execute a CLI command with the given import prefix.
  *

package/bin/cli.js

@@ -9,8 +9,8 @@
  */
 
 import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { runCommand } from './cli-router.js';
+import { dirname } from 'path';
+import { resolveExitCode, runCommand } from './cli-router.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -31,6 +31,7 @@ Commands:
   logout            Remove stored credentials
   whoami            Show authentication status
   deploy            Deploy your app to Juuno
+  deploy-backend    Deploy an app backend (Workers-for-Platforms tenant script)
   list              List your deployed apps
   info <app-id>     Show detailed information about an app
   help              Show this help message
@@ -60,8 +61,23 @@ Deploy Options:
   --build-dir <dir>        Build directory to deploy (default: ./dist)
   --skip-if-deployed       Exit 0 with a notice when the manifest version is not
                            above the deployed one, instead of erroring. For CI.
+  --dry-run                Send the build for the backend to check, and deploy
+                           nothing. Exits non-zero when the backend refuses it.
 
-Authentication Options (for deploy, list, info):
+Deploy Backend Options:
+  --dir <path>             Worker directory (default: current directory)
+  --print-metadata         Print the resolved script + metadata, then stop
+
+  The backend must already be registered in Superadmin, on the Backend tab of
+  the app it serves — that is what attaches it to an app and mints its platform
+  secret. Deploying an unregistered script is refused before anything uploads.
+
+  The API associated with the active profile reports which environment it
+  deploys to; eg prod|stage - this selects the matching environment in
+  wrangler.jsonc, so the bindings that get built and the namespace that
+  receives them always agree.
+
+Authentication Options (for deploy, deploy-backend, list, info):
   By default, these commands use the token saved by 'juuno-cli login'.
   You can override with:
   --profile <name>     Use credentials from a named profile
@@ -100,6 +116,10 @@ Examples:
   juuno-cli deploy
   juuno-cli deploy --build-dir ./dist
 
+  # Deploy an app backend from its worker directory
+  cd cloudflare-workers/app-google-reviews
+  juuno-cli deploy-backend --profile stage
+
   # List apps (uses saved credentials)
   juuno-cli list
 
@@ -115,11 +135,14 @@ if (
   command === 'logout' ||
   command === 'whoami' ||
   command === 'deploy' ||
+  command === 'deploy-backend' ||
   command === 'list' ||
   command === 'info'
 ) {
   const exitCode = await runCommand(command, args, '../dist/cli/src/');
-  process.exit(exitCode);
+
+  // Not process.exit(exitCode) — see resolveExitCode().
+  process.exit(resolveExitCode(exitCode, process.exitCode));
 }
 
 // `dev` is not unknown, it moved: the simulator is its own package so CI

package/dist/cli/src/deploy/index.js

@@ -1,10 +1,11 @@
-import { readFileSync, existsSync, readdirSync, statSync, realpathSync, } from 'fs';
+import { readFileSync, existsSync, readdirSync, realpathSync } from 'fs';
 import { isAbsolute, join, relative } from 'path';
+import { setTimeout as sleep } from 'timers/promises';
 import JSZip from 'jszip';
 import semver from 'semver';
 import { getAuthToken, getApiUrl } from '../auth/index.js';
 import { getErrorMessage } from '../utils/error.js';
-import { wrapError } from '../utils/api.js';
+import { assertSuccessEnvelope, fetchAuthorisedJson, HttpError, wrapError, } from '../utils/api.js';
 import { isRecord } from '../utils/is-record.js';
 /**
  * Fetches the currently deployed version of an app.
@@ -79,6 +80,82 @@ export function checkTranslations(declared, bundled) {
     }
     return null;
 }
+/**
+ * Every JavaScript bundle the upload will carry, and the ones with a map
+ * beside them.
+ *
+ * A map is looked for at `<bundle>.map`, which is where every bundler writes
+ * one and the only place a reader of a stack trace looks for it. A map named
+ * something else, or inlined into the bundle as a data URL, is not found by
+ * this and is not found by the tooling either.
+ *
+ * Each file is classified from the same directory entry and the same
+ * containment rule `createZipBundle` applies below, so the two agree on what
+ * ships. A path resolving outside the build directory is dropped on upload,
+ * and a directory is walked into rather than uploaded, so neither can stand in
+ * for a map the CDN will never serve.
+ */
+export function listBundles(buildDir) {
+    const bundles = [];
+    const maps = new Set();
+    const resolvedBuildDir = realpathSync(buildDir);
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = join(dir, entry.name);
+            const resolved = safeResolveWithinBase(fullPath, resolvedBuildDir);
+            if (resolved === 'unresolvable' || resolved === 'escapes') {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                walk(fullPath);
+                continue;
+            }
+            const file = relative(resolvedBuildDir, fullPath);
+            if (entry.name.endsWith('.map')) {
+                maps.add(file);
+                continue;
+            }
+            // `.mjs` as well as `.js`: a third-party build picks its own extension
+            // for an ES module, and an all-`.mjs` build would otherwise count no
+            // bundles and say nothing about itself.
+            if (/\.m?js$/.test(entry.name)) {
+                bundles.push(file);
+            }
+        }
+    }
+    walk(resolvedBuildDir);
+    return {
+        bundles,
+        mapped: bundles.filter((bundle) => maps.has(`${bundle}.map`)),
+    };
+}
+/**
+ * Say that this build ships nothing that can turn a crash back into a line of
+ * source, or null when at least one bundle has a map.
+ *
+ * Only a build with no maps at all is worth saying anything about. A build that
+ * has them on still emits the occasional generated chunk with no original
+ * source and so no map, and a warning that fires on a correctly configured app
+ * is one nobody reads.
+ *
+ * A warning rather than an error, because a build with no maps is a valid
+ * deploy. It is just one nobody can debug.
+ */
+export function describeMissingSourceMaps(bundles, mapped) {
+    if (bundles.length === 0 || mapped.length > 0) {
+        return null;
+    }
+    const noun = bundles.length === 1 ? 'bundle' : 'bundles';
+    return (`No source maps in this build (${bundles.length} JavaScript ${noun}, ` +
+        'none with a .map beside it).\n' +
+        '   An error thrown in your app is reported as a position in the minified\n' +
+        '   bundle. Without a map beside it that position names no file and no\n' +
+        '   line, for you or for Juuno support.\n' +
+        '   Turn on source maps in your bundler (`build.sourcemap: true` in Vite)\n' +
+        '   and deploy again. They upload with the rest of the build directory.');
+}
+/** How long the CLI waits between two reads of a filling release's status. */
+const RELEASE_POLL_MS = 2000;
 /**
  * Resolve a real path under a base directory. Returns 'unresolvable' when
  * realpathSync throws (broken symlink, missing target), 'escapes' when the
@@ -142,7 +219,7 @@ async function createZipBundle(buildDir) {
 /**
  * Uploads the app bundle to the developer API.
  */
-async function uploadBundle(token, zipBuffer, apiUrl) {
+async function uploadBundle(token, zipBuffer, apiUrl, dryRun) {
     const uploadUrl = `${apiUrl}/api/v1/developer/apps/upload`;
     const formData = new FormData();
     // @types/node 26 makes Buffer generic over ArrayBufferLike, which BlobPart
@@ -152,6 +229,9 @@ async function uploadBundle(token, zipBuffer, apiUrl) {
         type: 'application/zip',
     });
     formData.append('app_bundle', blob, 'app.zip');
+    if (dryRun) {
+        formData.append('dry_run', '1');
+    }
     try {
         const response = await fetch(uploadUrl, {
             method: 'POST',
@@ -162,19 +242,101 @@ async function uploadBundle(token, zipBuffer, apiUrl) {
             body: formData,
         });
         if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Upload failed: ${response.status} ${response.statusText}\n${errorText}`);
+            throw new Error(await describeRefusal(response));
         }
         const data = (await response.json());
         if (!data.success) {
-            throw new Error(`Upload failed: ${data.message || 'Unknown error'}`);
+            throw new Error(data.message || 'Unknown error');
         }
         return data;
     }
     catch (error) {
-        throw wrapError('Upload failed', error);
+        throw wrapError(dryRun ? 'Dry run failed' : 'Upload failed', error);
     }
 }
+/**
+ * The message of a refused upload. The backend answers a failed check as
+ * `{ error }`, and Laravel answers a request it refuses as `{ message }`. That
+ * message tells the author what to fix, so it is shown unchanged rather than
+ * inside the HTTP status and the raw body.
+ */
+async function describeRefusal(response) {
+    const body = await response.text();
+    let parsed = null;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        // A body that is not JSON, such as a proxy's error page, is shown below
+        // with its status.
+    }
+    if (isRecord(parsed)) {
+        if (typeof parsed.error === 'string') {
+            return parsed.error;
+        }
+        if (typeof parsed.message === 'string') {
+            return parsed.message;
+        }
+    }
+    return `${response.status} ${response.statusText}\n${body}`;
+}
+/**
+ * Read the status of one release, or null when the backend has no such
+ * release.
+ */
+async function fetchReleaseStatus(token, apiUrl, manifest) {
+    const url = `${apiUrl}/api/v1/developer/apps/${encodeURIComponent(manifest.id)}` +
+        `/releases/${encodeURIComponent(manifest.version)}`;
+    try {
+        const envelope = await fetchAuthorisedJson(url, token);
+        return assertSuccessEnvelope(envelope).status;
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Wait until a filling release is live. The upload answers `filling` for each
+ * release with a config schema, and the release is served only when the fill
+ * of the existing scenes is done, so the deploy is not done before that.
+ *
+ * Throws when the fill failed, when the release is gone, when the status
+ * cannot be read, and on a status that is not part of a deploy's end. Each one
+ * exits non-zero, so CI does not report a release that no screen gets.
+ */
+async function waitUntilLive(token, apiUrl, manifest, uploadStatus) {
+    let status = uploadStatus;
+    while (status === 'filling') {
+        await sleep(RELEASE_POLL_MS);
+        try {
+            status = await fetchReleaseStatus(token, apiUrl, manifest);
+        }
+        catch (error) {
+            throw new Error(`Could not read the status of version ${manifest.version}: ` +
+                `${getErrorMessage(error)}\n   The fill can still finish. Run ` +
+                `\`juuno-cli info ${manifest.id}\` with the --profile or --api-url ` +
+                'of this deploy to see the version that is served.');
+        }
+    }
+    if (status === 'live') {
+        return;
+    }
+    if (status === 'failed') {
+        throw new Error(`The fill of existing scenes failed, so version ${manifest.version} ` +
+            'is not served and the previous release stays live.\n   Releases ' +
+            `are immutable: the next deploy needs a version above ${manifest.version}.`);
+    }
+    if (status === null) {
+        throw new Error(`Version ${manifest.version} is not on the backend. The upload ` +
+            'failed before the fill, and the backend deleted the release.\n   ' +
+            'Deploy again with the same version.');
+    }
+    throw new Error(`Version ${manifest.version} is \`${status}\`, which is not a state ` +
+        'that a deploy waits in.');
+}
 /**
  * Read and validate the manifest.json from a build directory. Throws with
  * actionable messages when the build is missing, the manifest is missing,
@@ -277,26 +439,42 @@ function printVersionDelta(deployedVersion, manifest) {
     }
     console.log('');
 }
-function printDeploySuccess(result) {
-    console.log('✅ Deployment successful!');
-    console.log('');
-    if (result.data) {
-        console.log('📋 App Details:');
-        console.log(`   ID: ${result.data.id}`);
-        console.log(`   Name: ${result.data.name}`);
-        console.log(`   Version: ${result.data.version}`);
-        console.log('');
+/**
+ * Print each `required` key that the release adds, with its default, as the
+ * backend reports it.
+ */
+function printFillReport(fill) {
+    if (fill.keys.length === 0) {
+        return;
     }
-    if (result.message) {
-        console.log(`💡 ${result.message}`);
-        console.log('');
+    for (const key of fill.keys) {
+        // A string default shows without JSON quotes, as the author wrote it.
+        const value = typeof key.default === 'string'
+            ? key.default
+            : JSON.stringify(key.default);
+        console.log(`   Adds \`${key.path}\` (required, default \`${value}\`).`);
     }
+    console.log('');
+}
+/**
+ * Print the release from the manifest. The upload answers the app as it is
+ * served, which is still the previous release while the new one fills.
+ */
+function printDeploySuccess(manifest) {
+    console.log('✅ Deployment successful!');
+    console.log('');
+    console.log('📋 App Details:');
+    console.log(`   ID: ${manifest.id}`);
+    console.log(`   Name: ${manifest.name}`);
+    console.log(`   Version: ${manifest.version}`);
+    console.log('');
 }
 /**
  * Deploys an external app to the Juuno platform.
  */
 export async function deployApp(options) {
-    console.log('📦 Juuno CLI - Deploy');
+    const { dryRun } = options;
+    console.log(`📦 Juuno CLI - Deploy${dryRun ? ' (dry run)' : ''}`);
     console.log('');
     try {
         const manifest = loadAndValidateManifest(options.buildDir);
@@ -304,6 +482,12 @@ export async function deployApp(options) {
         console.log(`   Version: ${manifest.version}`);
         console.log(`   ID: ${manifest.id}`);
         console.log('');
+        const { bundles, mapped } = listBundles(options.buildDir);
+        const sourceMapWarning = describeMissingSourceMaps(bundles, mapped);
+        if (sourceMapWarning) {
+            console.warn(`⚠️  ${sourceMapWarning}`);
+            console.log('');
+        }
         const apiUrl = getApiUrl(options);
         console.log('🔑 Authenticating...');
         const token = await getAuthToken(options);
@@ -319,11 +503,34 @@ export async function deployApp(options) {
         const zipBuffer = await createZipBundle(options.buildDir);
         console.log(`   ✓ Bundle created (${(zipBuffer.length / 1024).toFixed(1)} KB)`);
         console.log('');
-        console.log('☁️  Uploading to Juuno...');
-        const result = await uploadBundle(token, zipBuffer, apiUrl);
-        console.log('   ✓ Upload complete');
+        console.log(dryRun ? '🧪 Sending for a dry run...' : '☁️  Uploading to Juuno...');
+        const result = await uploadBundle(token, zipBuffer, apiUrl, dryRun);
+        console.log(dryRun ? '   ✓ Checked' : '   ✓ Upload complete');
         console.log('');
-        printDeploySuccess(result);
+        if (dryRun) {
+            // A backend from before the dry run ignores `dry_run` and deploys, and
+            // answers without a fill report.
+            if (result.fill === undefined) {
+                throw new Error(`The API at ${apiUrl} does not support a dry run, so it deployed ` +
+                    `version ${manifest.version}.`);
+            }
+            printFillReport(result.fill);
+            console.log('✅ Dry run passed. Nothing was deployed.');
+            console.log('');
+            return;
+        }
+        if (result.fill !== undefined) {
+            printFillReport(result.fill);
+        }
+        // A backend from before the fill sends no status. Its release is live
+        // when it answers.
+        if (result.status !== undefined && result.status !== 'live') {
+            console.log('⏳ Filling existing scenes...');
+            await waitUntilLive(token, apiUrl, manifest, result.status);
+            console.log('   ✓ Live');
+            console.log('');
+        }
+        printDeploySuccess(manifest);
     }
     catch (error) {
         console.error(`❌ ${getErrorMessage(error)}`);

package/dist/cli/src/deploy-backend/context.js

@@ -0,0 +1,62 @@
+/**
+ * Which environment the API deploys to, and into which dispatch namespace.
+ *
+ * The environment is the API's to state, not the caller's. Each instance is
+ * pinned to exactly one dispatch namespace in its own config, so asking removes
+ * the only way a deploy could bundle one environment's bindings and upload them
+ * to another's namespace. There is nothing to keep in sync and nothing to
+ * mistype — which is why this has no `--env` flag and never will.
+ */
+/** One small GET; an instance that has not answered by now is not going to. */
+const CONTEXT_TIMEOUT_MS = 15_000;
+export async function fetchContext(api, token) {
+    const response = await withTimeout(() => fetch(`${api}/api/v1/developer/app-backends/context`, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+        },
+        signal: AbortSignal.timeout(CONTEXT_TIMEOUT_MS),
+    }), `${api} did not answer within ${CONTEXT_TIMEOUT_MS / 1000}s.`);
+    if (!response.ok) {
+        // Names both plausible causes, because the two are indistinguishable from
+        // here: pointed at the wrong instance, or not logged in to the right one.
+        throw new Error(`Could not read the deploy context from ${api} (HTTP ${response.status}). ` +
+            'Check the profile and that you are logged in.');
+    }
+    // A 200 that will not parse is the same misconfiguration a 404 here would be:
+    // an SPA catch-all, a proxy interstitial, or an instance too old to have the
+    // route. Left unguarded it surfaces as `Unexpected token '<'`, which points a
+    // developer at everything except their API url.
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        throw new Error(`${api} did not answer as the deploy context endpoint. ` +
+            'Check the profile’s API url.');
+    }
+    // Refused rather than defaulted. Guessing an environment here is how a stage
+    // bundle reaches a production namespace.
+    if (!body.data?.env) {
+        throw new Error(`${api} did not report which environment it deploys to.`);
+    }
+    return { env: body.data.env, namespace: body.data.namespace };
+}
+/**
+ * Run a fetch and turn its abort into a sentence.
+ *
+ * `AbortSignal.timeout` rejects with `TimeoutError: The operation was aborted`,
+ * which tells a developer nothing about which request gave up or how long it
+ * waited. Everything else propagates untouched.
+ */
+export async function withTimeout(request, message) {
+    try {
+        return await request();
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new Error(message);
+        }
+        throw error;
+    }
+}