@juuno-sdk/cli 4.0.1 → 4.1.0

package/README.md

@@ -120,6 +120,46 @@ npx juuno-cli deploy
 npx juuno-cli deploy --build-dir ./build
 ```
 
+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.
+
+**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.

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.
  */
@@ -56,6 +104,27 @@ const COMMANDS = {
       ...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 +141,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
@@ -61,7 +62,20 @@ Deploy Options:
   --skip-if-deployed       Exit 0 with a notice when the manifest version is not
                            above the deployed one, instead of erroring. For CI.
 
-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 +114,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 +133,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,4 +1,4 @@
-import { readFileSync, existsSync, readdirSync, statSync, realpathSync, } from 'fs';
+import { readFileSync, existsSync, readdirSync, realpathSync } from 'fs';
 import { isAbsolute, join, relative } from 'path';
 import JSZip from 'jszip';
 import semver from 'semver';
@@ -79,6 +79,80 @@ 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.');
+}
 /**
  * Resolve a real path under a base directory. Returns 'unresolvable' when
  * realpathSync throws (broken symlink, missing target), 'escapes' when the
@@ -304,6 +378,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);

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;
+    }
+}

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

@@ -0,0 +1,196 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { getApiUrl, getAuthToken } from '../auth/index.js';
+import { spawnSync } from '../utils/bin.js';
+import { fetchContext, withTimeout } from './context.js';
+import { getErrorMessage } from '../utils/error.js';
+import { describeOutcome, report, } from './outcome.js';
+import { buildMetadata, isModuleFile, moduleContentType, parseWranglerConfig, resolveApiUrl, resolveEnvConfig, scriptName, } from './wrangler-config.js';
+/**
+ * Far longer than the context read: this uploads the whole bundle and the server
+ * then provisions stores and runs the tenant's migrations before answering.
+ */
+const DEPLOY_TIMEOUT_MS = 180_000;
+/**
+ * Main script entry point.
+ */
+export async function deployBackend(options) {
+    try {
+        await run(options);
+    }
+    catch (error) {
+        // Matches the other commands: one line the developer can act on, not a
+        // stack trace. The messages here already name the fix.
+        console.error(`❌ ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+}
+/**
+ * Resolve the plan, print the metadata, and deploy.
+ */
+async function run(options) {
+    const plan = await resolvePlan(options);
+    if (options.printMetadata) {
+        const { script, env, namespace, metadata } = plan;
+        console.log(JSON.stringify({ script, env, namespace, metadata }, null, 2));
+        return;
+    }
+    const target = plan.namespace ? `${plan.env} (${plan.namespace})` : plan.env;
+    console.log(`Deploying '${plan.script}' to ${target} via ${plan.api}`);
+    const outcome = await postDeploy(plan, bundle(plan.workerDir, plan.env));
+    report(outcome);
+}
+/**
+ * Bundle the worker with its own pinned wrangler.
+ *
+ * Shelled out rather than imported so the version in the worker's
+ * devDependencies is the one that runs — a bundler mismatch between the CLI and
+ * the worker would be a genuinely confusing failure — and so the CLI takes no
+ * wrangler dependency of its own.
+ */
+function bundle(workerDir, env) {
+    const outDir = join(workerDir, 'dist');
+    // Emptied first: wrangler writes into --outdir without clearing it, and
+    // everything left there is uploaded as a module. A renamed entry point or a
+    // dropped code-split chunk would otherwise ship alongside the current build
+    // forever — dead weight against the Worker size limit, and a bundle whose
+    // contents depend on what happened to be built in this directory before.
+    rmSync(outDir, { recursive: true, force: true });
+    const bundled = spawnSync('npx', ['wrangler', 'deploy', '--env', env, '--dry-run', '--outdir', outDir], { cwd: workerDir, stdio: 'inherit' });
+    // spawnSync reports rather than throws, so both failures are checked here:
+    // the spawn itself (wrangler missing, PATH wrong) and a non-zero exit.
+    if (bundled.error) {
+        throw new Error(`Could not run wrangler: ${bundled.error.message}`);
+    }
+    if (bundled.status !== 0) {
+        throw new Error(`wrangler exited with code ${bundled.status ?? 'unknown'}.`);
+    }
+    if (!existsSync(outDir)) {
+        throw new Error(`wrangler produced no output at ${outDir}.`);
+    }
+    const modules = collectModules(outDir);
+    if (!modules.length) {
+        throw new Error(`No module files in ${outDir}.`);
+    }
+    return modules;
+}
+/**
+ * Every module in the dry-run output, as parts to upload.
+ *
+ * The walk is recursive because wrangler writes a code-split chunk or an
+ * imported `.wasm` into a subdirectory, and a flat read would leave it out of
+ * the upload entirely — either rejected for a missing module, or accepted and
+ * then throwing `No such module` on the first request.
+ */
+export function collectModules(outDir) {
+    // Separators normalised on the way in: Cloudflare addresses a module by a
+    // posix path, and a nested entry on Windows arrives here as `lib\chunk.js`.
+    const names = readdirSync(outDir, {
+        encoding: 'utf8',
+        recursive: true,
+    }).map((entry) => entry.replaceAll('\\', '/'));
+    return names.filter(isModuleFile).map((name) => ({
+        name,
+        contents: new Uint8Array(readFileSync(join(outDir, name))),
+    }));
+}
+/**
+ * Work out what would be deployed, without deploying it.
+ *
+ * Everything here is a read, so `--print-metadata` can stop straight afterwards
+ * and show exactly what a real run would send.
+ */
+async function resolvePlan(options) {
+    const workerDir = resolve(options.dir ?? process.cwd());
+    const configPath = join(workerDir, 'wrangler.jsonc');
+    if (!existsSync(configPath)) {
+        throw new Error(`No wrangler.jsonc in ${workerDir}. Run this from a worker directory, or pass --dir.`);
+    }
+    // Resolved before the token, not after. On the --email/--password path
+    // getAuthToken() posts the credentials to this url, so a guard that ran
+    // afterwards would refuse a cleartext connection the password had already gone
+    // over. Passed back in so the checked value is the one that gets used.
+    const api = resolveApiUrl(getApiUrl(options));
+    const token = await getAuthToken({ ...options, apiUrl: api });
+    // The profile picks the API; the API states its environment. That single
+    // answer then selects the wrangler env to bundle, so the bindings that get
+    // built and the namespace that receives them can never disagree.
+    const { env, namespace } = await fetchContext(api, token);
+    const config = parseWranglerConfig(readFileSync(configPath, 'utf8'));
+    // Throws naming the envs the file does declare, which is the useful error
+    // when a worker has not been set up for the environment you are pointed at.
+    const resolved = resolveEnvConfig(config, env);
+    return {
+        workerDir,
+        api,
+        token,
+        env,
+        namespace,
+        // The raw config, not the resolved one: naming the script is the one place
+        // wrangler suffixes rather than inherits. See scriptName().
+        script: scriptName(config, env),
+        metadata: buildMetadata(resolved),
+    };
+}
+/**
+ * The multipart upload Cloudflare's Workers API expects, as the platform
+ * forwards it: the script name, the metadata, and one part per module.
+ */
+function buildUploadForm(plan, modules) {
+    const form = new FormData();
+    form.append('script', plan.script);
+    form.append('metadata', JSON.stringify(plan.metadata));
+    for (const module of modules) {
+        form.append(module.name, new Blob([module.contents], { type: moduleContentType(module.name) }), basename(module.name));
+    }
+    return form;
+}
+/**
+ * Read the body, tolerating one that will not parse.
+ *
+ * The status is still meaningful, and every status has an answer without a body.
+ * An abort is not a parse failure, though — that is the deploy running past its
+ * timeout, which has its own answer — so it propagates rather than being flatted
+ * into an empty body and reported as "HTTP 200: no error message".
+ */
+export async function readDeployResponse(response) {
+    try {
+        return (await response.json());
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw error;
+        }
+        return {};
+    }
+}
+/**
+ * Upload the modules and say what happened.
+ *
+ * Returns the outcome rather than a status and a body, because nothing upstream
+ * wants the transport details — the only question is what happened, and
+ * describeOutcome() is what answers it.
+ */
+async function postDeploy(plan, modules) {
+    // One timeout around the request and the body read together. The deploy is
+    // not finished until the server has answered in full, so an abort partway
+    // through the body is the same "may still have landed" situation as an abort
+    // before the headers, and gets the same sentence.
+    const { status, body } = await withTimeout(async () => {
+        const response = await fetch(`${plan.api}/api/v1/developer/app-backends/deploy`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${plan.token}`,
+                Accept: 'application/json',
+            },
+            body: buildUploadForm(plan, modules),
+            signal: AbortSignal.timeout(DEPLOY_TIMEOUT_MS),
+        });
+        return {
+            status: response.status,
+            body: await readDeployResponse(response),
+        };
+    }, `The deploy did not finish within ${DEPLOY_TIMEOUT_MS / 1000}s. It may still ` +
+        "have landed — check the app's Backend tab in Superadmin before retrying.");
+    return describeOutcome(status, body, modules.map((module) => module.name), plan.api);
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Reading a deploy response, and saying what happened.
+ *
+ * Two functions, split so the decision is separable from the printing:
+ * `describeOutcome` is pure and decides, `report` performs. Kept apart from the
+ * command because the distinction they draw is a safety property rather than
+ * presentation — a 404 means the platform refused before anything reached
+ * Cloudflare, so nothing is live and the CLI can fail loudly; any other failure
+ * may have uploaded the script and then failed a later step, so the server's own
+ * message is the only accurate account of what happened and is passed through
+ * untouched.
+ *
+ * Getting that backwards would either hide a live half-deploy behind a tidy
+ * error, or tell a developer to go and register something that already exists.
+ */
+/**
+ * What the response means, given the modules that were sent.
+ *
+ * A body of `{ success: false }` on a 200 counts as a failure — the endpoint
+ * reports step failures in the body, so the HTTP status alone is not the answer.
+ */
+export function describeOutcome(status, body, moduleNames, api) {
+    const failed = status < 200 || status >= 300 || body.success !== true;
+    if (!failed) {
+        const lines = [
+            `\n${body.message ?? 'Deployed.'}`,
+            `  modules: ${moduleNames.join(', ')}`,
+        ];
+        // Only apps with a database report one, so its absence is not a gap.
+        if (body.schema_version != null) {
+            lines.push(`  schema version: ${body.schema_version}`);
+        }
+        return { kind: 'success', lines };
+    }
+    // A 404 alone does not mean "not registered". The deploy endpoint answers one
+    // with its own error envelope; a wrong --api, a proxy, or an instance too old
+    // to have the route answers one with HTML or nothing, which postDeploy turns
+    // into an empty body. Telling that developer to go and register a backend they
+    // already registered sends them looking in the wrong place entirely, so the
+    // envelope is what distinguishes them.
+    if (status === 404) {
+        if (typeof body.error === 'string') {
+            return {
+                kind: 'unregistered',
+                message: `${body.error}\n` +
+                    'Register it in Superadmin, on the Backend tab of the app it serves.',
+            };
+        }
+        return {
+            kind: 'failed',
+            message: `\nDeploy failed (HTTP 404): ${api}/api/v1/developer/app-backends/deploy ` +
+                'did not answer as the deploy endpoint.\nCheck the profile’s API url — ' +
+                'a 404 without an error body usually means the request never reached it.',
+        };
+    }
+    return {
+        kind: 'failed',
+        message: `\nDeploy failed (HTTP ${status}): ${body.error ?? 'no error message'}`,
+        details: body.errors ? JSON.stringify(body.errors, null, 2) : undefined,
+    };
+}
+/**
+ * Turn an outcome into output and an exit code.
+ *
+ * Only `unregistered` throws, and only because nothing was uploaded: the caller
+ * wraps a throw as a one-line `❌ …`, which is the right shape for "this was
+ * refused, here is the fix". A failure that may have half-landed must not be
+ * wrapped, so it is written straight to stderr and the exit code is set by hand.
+ */
+export function report(outcome) {
+    if (outcome.kind === 'unregistered') {
+        throw new Error(outcome.message);
+    }
+    if (outcome.kind === 'failed') {
+        console.error(outcome.message);
+        if (outcome.details) {
+            console.error(outcome.details);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    for (const line of outcome.lines) {
+        console.log(line);
+    }
+}