@faable/faable 4.6.0 → 4.7.0

package/dist/commands/auth/users/list.js

@@ -1,10 +1,39 @@
 import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
 import { log } from '../../../log.js';
-import { list_options, fetch_page, from_paginator, print_json, table_lines, print, more_hint } from '../../../lib/listing.js';
+import { list_options, print_json, print, fetch_page, from_paginator, table_lines, more_hint } from '../../../lib/listing.js';
 import { tenant_options } from '../options.js';
-import { compose_query } from '../query.js';
+import { compose_query, term, range_term } from '../query.js';
 import { truncate, yes_no, when } from '../render.js';
+import { CliError } from '../../../lib/errors.js';
 
+// A Faable Auth older than ?count= / ?sort= / the date ranges answers 400
+// "Unknown query parameter": say what is missing instead of passing that on.
+const unsupported = (feature) => (e) => {
+    const res = e?.response;
+    const message = String(res?.data?.message ?? e?.message ?? '');
+    if (res?.status === 400 &&
+        /Unknown query parameter|Unknown field|last_login_|created_(since|until)|sort/.test(message)) {
+        throw new CliError('usage', `This Faable Auth does not support ${feature ?? 'that filter'} yet (${message}).`, { status: 400, cause: e });
+    }
+    throw e;
+};
+const USER_SORTS = [
+    '-last_login',
+    'last_login',
+    '-logins_count',
+    'logins_count',
+    '-createdAt',
+    'createdAt'
+];
+// The FaableQL filter of a users listing, from its flags.
+const users_query = (args, now) => compose_query([
+    args.suspended !== undefined && `suspended:${args.suspended}`,
+    term('email', args.email?.toLowerCase()),
+    range_term('last_login_since', 'last-login-since', args.lastLoginSince, now),
+    range_term('last_login_until', 'last-login-until', args.lastLoginUntil, now),
+    range_term('created_since', 'created-since', args.createdSince, now),
+    range_term('created_until', 'created-until', args.createdUntil, now)
+], args.query);
 const users_list = {
     command: 'list',
     describe: 'List and filter users',
@@ -20,14 +49,69 @@ const users_list = {
         .option('suspended', {
         type: 'boolean',
         description: 'Only suspended users (shorthand for query suspended:true)'
+    })
+        .option('email', {
+        type: 'string',
+        description: 'Exact email'
+    })
+        .option('sort', {
+        type: 'string',
+        choices: USER_SORTS,
+        description: 'Order: -last_login (most recent login first), last_login (longest absent first), -logins_count, -createdAt (default). Sorting by last_login leaves out users who never logged in'
+    })
+        .option('last-login-since', {
+        type: 'string',
+        description: 'Logged in at or after: 30m, 24h, 7d ago, unix-millis or YYYY-MM-DD'
+    })
+        .option('last-login-until', {
+        type: 'string',
+        description: 'Last login at or before (same formats)'
+    })
+        .option('created-since', {
+        type: 'string',
+        description: 'Signed up at or after (same formats)'
+    })
+        .option('created-until', {
+        type: 'string',
+        description: 'Signed up at or before (same formats)'
+    })
+        .option('count', {
+        type: 'boolean',
+        description: 'Only count the users matching the filters ({"total": N}), across every page'
     })
         .example('$0 auth users list --suspended', 'List suspended users')
+        .example('$0 auth users list --sort -last_login --limit 20', 'The 20 most recent logins')
+        .example('$0 auth users list --last-login-since 24h --count', 'How many users logged in in the last 24 hours')
         .example('$0 auth users list --query email_verified:false --limit 50', 'First 50 unverified users')
         .showHelpOnFail(false),
     handler: withAuthHints(async (args) => {
         const api = await requireAuthAdmin(args);
-        const query = compose_query([args.suspended !== undefined && `suspended:${args.suspended}`], args.query);
-        const page = await fetch_page(from_paginator(api.userList({ query, q: args.q })), args);
+        const query = users_query(args);
+        if (args.count) {
+            // One row is enough: the server counts the whole filter (`?count=true`).
+            const res = await api.fetcher
+                .get('/user', {
+                params: {
+                    pageSize: '1',
+                    count: 'true',
+                    ...(query ? { query } : {}),
+                    ...(args.q ? { q: args.q } : {})
+                }
+            })
+                .catch(unsupported('count'));
+            if (typeof res?.total !== 'number') {
+                throw new Error('This Faable Auth does not count users yet (no `total` in the answer).');
+            }
+            if (args.json)
+                return print_json({ total: res.total, query: query ?? null });
+            print(String(res.total));
+            return;
+        }
+        const page = await fetch_page(p => from_paginator(api.userList({
+            query,
+            q: args.q,
+            ...(args.sort ? { sort: args.sort } : {})
+        }))(p).catch(unsupported(args.sort ? 'sort' : undefined)), args);
         if (args.json)
             return print_json(page);
         if (page.data.length === 0) {
@@ -52,4 +136,4 @@ const users_list = {
     })
 };
 
-export { users_list };
+export { USER_SORTS, users_list, users_query };

package/dist/commands/auth/users/password_setup.js

@@ -0,0 +1,54 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { confirm } from '../../../lib/interactive.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { json_option, print_json } from '../../../lib/listing.js';
+import { resolve_user_ref } from './resolve.js';
+
+// Sends the user a link (or a code) to set — or reset — their password. The
+// way to "invite" a user created by hand, or to unblock one who forgot it.
+const users_password_setup = {
+    command: 'password-setup <user>',
+    describe: 'Send a user the email (or code) to set or reset their password',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('user', {
+        type: 'string',
+        demandOption: true,
+        description: 'User id (user_…) or email'
+    })
+        .option('channel', {
+        type: 'string',
+        choices: ['email', 'sms', 'whatsapp'],
+        description: "How to deliver it (default: the tenant's)"
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        // An email is resolved first (a read), so the prompt names one user; an
+        // id is confirmed before any request.
+        const early = args.user.includes('@') ? await requireAuthAdmin(args) : undefined;
+        const user_id = early ? await resolve_user_ref(early, args.user) : args.user;
+        const go = await confirm({
+            message: `Send ${args.user} a password setup ${args.channel ?? 'message'}?`,
+            yes: args.yes
+        });
+        if (!go) {
+            log.info('Cancelled.');
+            return;
+        }
+        const api = early ?? (await requireAuthAdmin(args));
+        const res = await api.userPasswordSetup(await resolve_user_ref(api, user_id), {
+            ...(args.channel ? { channel: args.channel } : {})
+        });
+        if (args.json)
+            return print_json({ user_id, ...res });
+        log.info(`📨 Sent to ${args.user} (${res.channel ?? 'email'}).`);
+    })
+};
+
+export { users_password_setup };

package/dist/commands/auth/users/reinstate.js

@@ -3,6 +3,7 @@ import { log } from '../../../log.js';
 import { tenant_options } from '../options.js';
 import { json_option, print_json } from '../../../lib/listing.js';
 import { wants_stdin, read_stdin, parse_user_ids } from './ids.js';
+import { resolve_user_refs } from './resolve.js';
 import { confirm } from '../../../lib/interactive.js';
 
 const users_reinstate = {
@@ -12,7 +13,7 @@ const users_reinstate = {
         .positional('user_ids', {
         type: 'string',
         array: true,
-        description: 'User ids (user_…); omit them to read ids from stdin'
+        description: 'User ids (user_…) or emails (exactly one user each); omit them to read ids from stdin'
     })
         .option('yes', {
         alias: 'y',
@@ -28,7 +29,11 @@ const users_reinstate = {
         const stdin = wants_stdin(argv_ids, !!process.stdin.isTTY)
             ? await read_stdin()
             : null;
-        const ids = parse_user_ids(argv_ids, stdin);
+        const refs = parse_user_ids(argv_ids, stdin);
+        // Emails become ids BEFORE the prompt, so what is confirmed is what runs.
+        const has_email = refs.some(r => r.includes('@'));
+        const early = has_email ? await requireAuthAdmin(args) : undefined;
+        const ids = early ? await resolve_user_refs(early, refs) : refs;
         const preview = ids.slice(0, 5).join(', ') + (ids.length > 5 ? ', …' : '');
         const go = await confirm({
             message: `Reinstate ${ids.length} user(s) (${preview})?`,
@@ -38,7 +43,7 @@ const users_reinstate = {
             log.info('Cancelled.');
             return;
         }
-        const api = await requireAuthAdmin(args);
+        const api = early ?? (await requireAuthAdmin(args));
         const results = [];
         for (const id of ids) {
             try {

package/dist/commands/auth/users/resolve.js

@@ -0,0 +1,36 @@
+import { CliError } from '../../../lib/errors.js';
+
+// A user given as an id (`user_…`) or as an email. An email is looked up with
+// an exact `?email=` (stored lowercase) and must match ONE user: a write by
+// email never acts on a partial or ambiguous match.
+const resolve_user_ref = async (api, ref) => {
+    const value = ref.trim();
+    if (/^user_[0-9a-f]{24}$/.test(value))
+        return value;
+    if (!value.includes('@')) {
+        throw new CliError('usage', `"${ref}" is neither a user id (user_…) nor an email.`);
+    }
+    const email = value.toLowerCase();
+    const page = await api
+        .userList({ email, pageSize: '2' })
+        .pass({ pageSize: '2' });
+    const matches = (page.results ?? []);
+    const exact = matches.filter(u => u.email?.toLowerCase() === email);
+    if (exact.length === 0) {
+        throw new CliError('not_found', `No user with email ${email} in this tenant.`);
+    }
+    if (exact.length > 1) {
+        throw new CliError('usage', `${exact.length} users have email ${email} (${exact
+            .map(u => u.id)
+            .join(', ')}): pass the user id.`);
+    }
+    return exact[0].id;
+};
+const resolve_user_refs = async (api, refs) => {
+    const out = [];
+    for (const ref of refs)
+        out.push(await resolve_user_ref(api, ref));
+    return out;
+};
+
+export { resolve_user_ref, resolve_user_refs };

package/dist/commands/auth/users/suspend.js

@@ -3,6 +3,7 @@ import { log } from '../../../log.js';
 import { tenant_options } from '../options.js';
 import { json_option, print_json } from '../../../lib/listing.js';
 import { wants_stdin, read_stdin, parse_user_ids } from './ids.js';
+import { resolve_user_refs } from './resolve.js';
 import { confirm } from '../../../lib/interactive.js';
 
 const users_suspend = {
@@ -12,7 +13,7 @@ const users_suspend = {
         .positional('user_ids', {
         type: 'string',
         array: true,
-        description: 'User ids (user_…); omit them to read ids from stdin'
+        description: 'User ids (user_…) or emails (exactly one user each); omit them to read ids from stdin'
     })
         .option('reason', {
         alias: 'r',
@@ -34,7 +35,11 @@ const users_suspend = {
         const stdin = wants_stdin(argv_ids, !!process.stdin.isTTY)
             ? await read_stdin()
             : null;
-        const ids = parse_user_ids(argv_ids, stdin);
+        const refs = parse_user_ids(argv_ids, stdin);
+        // Emails become ids BEFORE the prompt, so what is confirmed is what runs.
+        const has_email = refs.some(r => r.includes('@'));
+        const early = has_email ? await requireAuthAdmin(args) : undefined;
+        const ids = early ? await resolve_user_refs(early, refs) : refs;
         const preview = ids.slice(0, 5).join(', ') + (ids.length > 5 ? ', …' : '');
         const go = await confirm({
             message: `Suspend ${ids.length} user(s) (${preview})?`,
@@ -44,7 +49,7 @@ const users_suspend = {
             log.info('Cancelled.');
             return;
         }
-        const api = await requireAuthAdmin(args);
+        const api = early ?? (await requireAuthAdmin(args));
         const results = [];
         for (const id of ids) {
             try {

package/dist/commands/deploy/apps/create.js

@@ -3,6 +3,7 @@ import { requireProject } from '../../../api/project.js';
 import { CliError } from '../../../lib/errors.js';
 import { print_json, json_option } from '../../../lib/listing.js';
 import { log } from '../../../log.js';
+import { wait_for_deployment, app_url } from '../wait.js';
 
 // "owner/repo" from any of the ways people paste a GitHub repository.
 const parse_repo = (input) => {
@@ -55,6 +56,16 @@ const apps_create = {
         type: 'boolean',
         default: true,
         description: 'Start the first deploy (--no-deploy to only link)'
+    })
+        .option('wait', {
+        type: 'boolean',
+        default: false,
+        description: 'Wait until the deploy is live or fails, and print the URL (or why it failed)'
+    })
+        .option('timeout', {
+        type: 'number',
+        default: 900,
+        description: 'With --wait: give up waiting after this many seconds (the build goes on)'
     })
         .check(({ repo, name }) => {
         if (!repo && !name) {
@@ -123,8 +134,30 @@ const apps_create = {
                 log.warn(`⚠️ The app is ready but the first deploy did not start: ${e.message}`);
             }
         }
-        if (args.json)
-            return print_json({ app: linked, first_deploy });
+        let waited;
+        if (args.wait &&
+            first_deploy &&
+            'deployment_id' in first_deploy &&
+            first_deploy.deployment_id) {
+            waited = await wait_for_deployment(api, first_deploy.deployment_id, {
+                timeout_s: args.timeout ?? 900,
+                app_url: app_url(linked.url)
+            });
+            if (!args.json) {
+                log.info(waited.ok
+                    ? `✅ Live: ${waited.url}`
+                    : waited.done
+                        ? `❌ ${waited.phase}${waited.fault_owner ? ` (${waited.fault_owner})` : ''}: ${waited.reason ?? ''}`
+                        : `⏳ Still ${waited.phase} after ${args.timeout}s`);
+            }
+        }
+        if (args.json) {
+            return print_json({
+                app: linked,
+                first_deploy,
+                ...(waited ? { result: waited } : {})
+            });
+        }
         log.info(`🌍 https://${linked.url}  ·  follow it with: faable deploy status -a ${app.id}`);
     }
 };

package/dist/commands/deploy/github/index.js

@@ -0,0 +1,10 @@
+import { github_repos } from './repos.js';
+
+const github = {
+    command: 'github',
+    describe: 'The GitHub repositories Faable can deploy',
+    builder: yargs => yargs.command(github_repos).demandCommand(1).showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { github };

package/dist/commands/deploy/github/repos.js

@@ -0,0 +1,70 @@
+import { requireApi } from '../../../api/context.js';
+import { print_json, print, json_option } from '../../../lib/listing.js';
+import { log } from '../../../log.js';
+
+// Where a user installs the Faable GitHub App — the one step of "deploy this
+// repository" that needs a browser (github.com), so it is handed over, never
+// automated.
+const GITHUB_INSTALL_URL = 'https://github.com/apps/faable-deploy/installations/new';
+const github_repos_listing = async (api, opts) => {
+    const installations = await api.listGithubInstallations();
+    const repositories = [];
+    for (const i of installations) {
+        const repos = await api.listGithubRepos(i.installation_id, {
+            ...(opts.q ? { q: opts.q } : {}),
+            limit: opts.limit ?? 30
+        });
+        for (const r of repos) {
+            repositories.push({
+                full_name: r.full_name,
+                default_branch: r.default_branch,
+                private: r.private,
+                installation: i.account_login
+            });
+        }
+    }
+    return {
+        installations: installations.map(i => ({
+            installation_id: i.installation_id,
+            account: i.account_login,
+            account_type: i.account_type
+        })),
+        repositories,
+        install_url: GITHUB_INSTALL_URL
+    };
+};
+const github_repos = {
+    command: 'repos',
+    describe: 'GitHub repositories Faable can deploy (where the Faable GitHub App is installed)',
+    builder: yargs => json_option(yargs)
+        .option('q', {
+        type: 'string',
+        description: 'Filter by name'
+    })
+        .option('limit', {
+        alias: 'n',
+        type: 'number',
+        default: 30,
+        description: 'Repositories per GitHub account (max 100)'
+    })
+        .showHelpOnFail(false),
+    handler: async (args) => {
+        const { api } = await requireApi();
+        const listing = await github_repos_listing(api, {
+            q: args.q,
+            limit: Math.min(args.limit ?? 30, 100)
+        });
+        if (args.json)
+            return print_json(listing);
+        if (listing.installations.length === 0) {
+            log.info(`The Faable GitHub App is not installed on any account yet. Install it: ${GITHUB_INSTALL_URL}`);
+            return;
+        }
+        for (const r of listing.repositories) {
+            print(`${r.full_name}${r.private ? ' (private)' : ''}  ·  ${r.default_branch}`);
+        }
+        log.info(`A repository that is not listed: give the Faable GitHub App access to it at ${GITHUB_INSTALL_URL}`);
+    }
+};
+
+export { GITHUB_INSTALL_URL, github_repos, github_repos_listing };

package/dist/commands/deploy/index.js

@@ -1,3 +1,4 @@
+import { github } from './github/index.js';
 import { link } from '../link/index.js';
 import { apps, apps_list_legacy } from './apps/index.js';
 import { domains } from './domains/index.js';
@@ -36,6 +37,7 @@ const deploy = {
     builder: yargs => capture_deploy_help(yargs
         .command(launch)
         .command(apps)
+        .command(github)
         .command(secrets)
         .command(domains)
         .command(waf)

package/dist/commands/deploy/inspect/inspect.js

@@ -54,8 +54,25 @@ const inspect = {
                 return null;
             });
         }
+        // Whose failure it is, from the api's attribution (absent on older apis
+        // and on deployments that did not fail).
+        const phase = deployment.status?.phase;
+        const fault = phase === 'BUILD_ERROR' || phase === 'ERROR'
+            ? await ctx.api.getDeploymentFault(deployment_id).catch(() => null)
+            : null;
         if (args.json) {
-            process.stdout.write(JSON.stringify({ ...deployment, artifact }, null, 2) + '\n');
+            process.stdout.write(JSON.stringify({
+                ...deployment,
+                artifact,
+                ...(fault
+                    ? {
+                        fault: {
+                            owner: fault.fault_owner,
+                            error_code: fault.error_code
+                        }
+                    }
+                    : {})
+            }, null, 2) + '\n');
             return;
         }
         for (const line of deployment_detail({ app, deployment, artifact })) {

package/dist/commands/deploy/inspect/trigger.js

@@ -2,6 +2,7 @@ import { requireApi } from '../../../api/context.js';
 import { print_json, json_option } from '../../../lib/listing.js';
 import { log } from '../../../log.js';
 import { resolve_app_id } from '../resolve_app_id.js';
+import { wait_for_deployment, app_url } from '../wait.js';
 
 const trigger = {
     command: 'trigger',
@@ -11,6 +12,16 @@ const trigger = {
         alias: 'a',
         type: 'string',
         description: 'App id, name or slug (defaults to the linked app)'
+    })
+        .option('wait', {
+        type: 'boolean',
+        default: false,
+        description: 'Wait until the deploy is live or fails, and print the URL (or why it failed)'
+    })
+        .option('timeout', {
+        type: 'number',
+        default: 900,
+        description: 'With --wait: give up waiting after this many seconds (the build goes on)'
     })
         .example('$0 deploy trigger', 'Deploy the repo HEAD without uploading anything from this machine')
         .showHelpOnFail(false),
@@ -21,6 +32,23 @@ const trigger = {
         // Takes the exact same path a git push would (same-commit dedupe
         // included) — the API answers with an actionable refusal otherwise.
         const result = await ctx.api.deployNow(app_id, app.team);
+        if (args.wait && result.deployment_id) {
+            if (!args.json) {
+                log.info(`⏳ Building ${result.commit.slice(0, 7)} (${result.branch}) as ${result.deployment_id}…`);
+            }
+            const waited = await wait_for_deployment(ctx.api, result.deployment_id, {
+                timeout_s: args.timeout ?? 900,
+                app_url: app_url(app.url)
+            });
+            if (args.json)
+                return print_json({ app_id, ...result, ...waited });
+            log.info(waited.ok
+                ? `✅ Live: ${waited.url}`
+                : waited.done
+                    ? `❌ ${waited.phase}${waited.fault_owner ? ` (${waited.fault_owner})` : ''}: ${waited.reason ?? ''}`
+                    : `⏳ Still ${waited.phase} after ${args.timeout}s — follow it with: faable deploy status -a ${app.id}`);
+            return;
+        }
         if (args.json)
             return print_json({ app_id, ...result });
         log.info(`🚀 Building ${result.commit.slice(0, 7)} (${result.branch}) of ${app.name} server-side${result.deployment_id ? ` as ${result.deployment_id}` : ''}.`);

package/dist/commands/deploy/launch.js

@@ -2,7 +2,9 @@ import { requireApi } from '../../api/context.js';
 import { Configuration } from '../../lib/Configuration.js';
 import { CliError } from '../../lib/errors.js';
 import { is_non_interactive, confirm } from '../../lib/interactive.js';
+import { print_json } from '../../lib/listing.js';
 import { log } from '../../log.js';
+import { requireProject } from '../../api/project.js';
 import { git_context } from './git_context.js';
 import { show_deploy_help } from './help.js';
 import { propose_release } from './release_version.js';
@@ -39,6 +41,16 @@ const launch = {
         default: false,
         description: 'Skip the confirmation prompt (only asked in interactive terminals — CI is unaffected)'
     })
+        .option('create', {
+        type: 'string',
+        description: 'No app yet: create one with this name in the active project (or --project) and deploy the directory to it'
+    })
+        .option('json', {
+        type: 'boolean',
+        default: false,
+        description: 'Print the outcome as JSON on stdout: app, deployment, phase and the URL once live'
+    })
+        .conflicts('create', 'app')
         .example('$0 deploy', 'Deploy the app linked to the current directory')
         .example('$0 deploy --app app_a1b2c3', 'Deploy another app (monorepo: several apps, one repo)')
         .showHelpOnFail(false),
@@ -47,7 +59,7 @@ const launch = {
         // working directory, and the go-ahead is explicit (see lib/interactive).
         if (is_non_interactive()) {
             const missing = [
-                !args.app && '--app',
+                !args.app && !args.create && '--app (or --create <name>)',
                 !args.workdir && '--workdir',
                 !args.yes && '--yes'
             ].filter(Boolean);
@@ -64,7 +76,16 @@ const launch = {
         const ctx = await requireApi(args.app?.startsWith('app_') ? args.app : undefined);
         const { api } = ctx;
         const config = Configuration.instance().deployConfig();
-        const app_id = await find_app_id(args.app, ctx.appId, api, workdir);
+        // --create: a directory with no app yet (the agent's «deploy this folder
+        // and give me the URL»). The app is new, so nothing existing is touched.
+        let created_id;
+        if (args.create) {
+            const { id: project } = await requireProject(api);
+            const created = await api.createApp(project, { name: args.create });
+            created_id = created.id;
+            log.info(`📦 Created ${created.name} (${created.id})`);
+        }
+        const app_id = created_id ?? (await find_app_id(args.app, ctx.appId, api, workdir));
         // Nothing to deploy from here. `faable deploy` is the entry point to the
         // whole product, so an unlinked directory is a perfectly normal way to
         // arrive: list what deploy can do (like `faable auth` does) instead of
@@ -176,6 +197,45 @@ const launch = {
                 log.debug(`Polling app status failed, retrying...`);
             }
         }
+        if (args.json) {
+            const outcome = promoted
+                ? 'live'
+                : superseded
+                    ? 'superseded'
+                    : failure
+                        ? 'failed'
+                        : 'timeout';
+            const fault = failure
+                ? await api.getDeploymentFault(deployment.id).catch(() => null)
+                : null;
+            const result = {
+                app_id: app.id,
+                app_name: app.name,
+                ...(created_id ? { created: true } : {}),
+                deployment_id: deployment.id,
+                outcome,
+                url: `https://${app.url}`,
+                ...(failure
+                    ? {
+                        phase: failure.phase,
+                        reason: failure.reason,
+                        ...(fault
+                            ? { fault_owner: fault.fault_owner, error_code: fault.error_code }
+                            : {})
+                    }
+                    : {}),
+                dashboard_url
+            };
+            if (failure) {
+                // A failed deploy still exits red (CI depends on it); the outcome
+                // travels in the error so a program reads it without parsing prose.
+                const err = new CliError('usage', `Deployment ${deployment.id} failed (${failure.phase})${fault?.fault_owner ? ` — ${fault.fault_owner}'s side` : ''}: ${failure.reason ?? 'no reason recorded'}`, { action: JSON.stringify(result) });
+                // The api's own code when it classified the failure.
+                err.code = fault?.error_code ?? 'deploy_failed';
+                throw err;
+            }
+            return print_json(result);
+        }
         if (promoted) {
             log.info(`🌍 Deployment promoted and live, visit: https://${app.url}`);
         }