faces-cli 1.7.16 → 1.8.1

package/dist/commands/style/delete.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../base.js';
+export default class StyleDelete extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+    private confirm;
+}

package/dist/commands/style/delete.js

@@ -0,0 +1,73 @@
+import { Args, Flags } from '@oclif/core';
+import { createInterface } from 'node:readline';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { STYLE_FACES_PATH } from '../../style.js';
+/**
+ * The API takes a scope: `map` clears the captured style, `all` clears it and
+ * destroys the uploaded material with it. This CLI only ever sends `map`.
+ *
+ * Nothing that removes a style should be able to take source text with it. A
+ * user reaching for "delete the style" is not asking to lose the writing it was
+ * learned from, and the two are one keystroke apart on the same command. Source
+ * text is deleted through the commands that own it — compile:doc:delete and
+ * compile:thread:delete — where that is the whole point of the call rather than
+ * a side effect of a flag value.
+ */
+const SCOPE = 'map';
+export default class StyleDelete extends BaseCommand {
+    static description = "Delete a face's captured style. The material it was learned from is kept, so the style can be " +
+        'captured again without re-uploading. This never deletes documents or threads: remove those with ' +
+        'compile:doc:delete or compile:thread:delete.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice',
+        '<%= config.bin %> <%= command.id %> alice --yes',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        yes: Flags.boolean({ description: 'Skip confirmation', default: false }),
+    };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(StyleDelete);
+        const client = this.makeClient(flags);
+        if (!flags.yes) {
+            const what = `'${args.alias}' will forget its captured style. Its documents, threads and uploaded material are kept.`;
+            if (this.jsonEnabled())
+                this.error(`${what}\nRe-run with --yes to confirm.`);
+            const ok = await this.confirm(`${what}\nDelete the style?`);
+            if (!ok)
+                this.error('Aborted. Nothing was deleted.');
+        }
+        let data;
+        try {
+            data = await client.delete(`${STYLE_FACES_PATH}/${encodeURIComponent(args.alias)}?scope=${SCOPE}`);
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 404)
+                    this.error(`No face named '${args.alias}'. It does not exist, or is not yours.`);
+                if (err.statusCode === 409)
+                    this.error(`Error (409): ${err.message}\nThe face may be locked. Unlock it first.`);
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        this.log(`'${args.alias}' has forgotten its style. Its source material is untouched.`);
+        this.log(`Capture it again with: faces style:make ${args.alias} --all`);
+        return data;
+    }
+    confirm(message) {
+        return new Promise((resolve) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(`${message} [y/N] `, (answer) => {
+                rl.close();
+                resolve(answer.toLowerCase() === 'y');
+            });
+        });
+    }
+}

package/dist/commands/style/make.d.ts

@@ -0,0 +1,45 @@
+import { BaseCommand } from '../../base.js';
+export default class StyleMake extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        source: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'allow-paid': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        compile: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'best-of': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+    private load;
+    /**
+     * Turn the flags into the wire's source list.
+     *
+     * The API wants {id, medium, source_type} per source and deliberately refuses
+     * to guess the medium. The listing already knows all three for most sources,
+     * so a user only has to supply what genuinely cannot be derived.
+     */
+    private select;
+    /**
+     * Refuse a build that would bill without being asked to.
+     *
+     * The analyst model runs the whole build, so it is the most expensive call in
+     * the product. Models on the free tier run on the user's own linked ChatGPT
+     * subscription; anything else bills every time. Reaching for a paid model to
+     * work around an expired link turns a fixable login into a permanent cost,
+     * which is why this is a refusal and not a warning.
+     */
+    private checkBilling;
+    /** Translate a pre-flight refusal into the decision the user has to make. */
+    private reportStartFailure;
+    private awaitJob;
+}

package/dist/commands/style/make.js

@@ -0,0 +1,271 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { codexEligible } from '../../routing.js';
+import { BUILDS_PATH, DEFAULT_STYLE_MODEL, formatBuildReport, jobFailureMessage, listSelectable, parseSourceArg, pollStyleJob, publicJob, } from '../../style.js';
+export default class StyleMake extends BaseCommand {
+    static description = 'Capture how a face writes, from its own material, and install it. This is style, not knowledge: ' +
+        'compile teaches a face what it knows, style teaches it how it sounds. Name the sources to learn ' +
+        'from with --source, or take everything ready with --all.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --all',
+        '<%= config.bin %> <%= command.id %> alice --source 1a2b3c4d --source 5e6f7a8b',
+        '<%= config.bin %> <%= command.id %> alice --source 1a2b3c4d:essay',
+        '<%= config.bin %> <%= command.id %> alice --all --medium essay --no-wait',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        source: Flags.string({
+            description: 'A document or thread to learn from, by id (repeatable). Append :<medium> to declare what it ' +
+                'is, e.g. --source 1a2b3c4d:essay, when the source does not already say.',
+            multiple: true,
+        }),
+        all: Flags.boolean({
+            description: 'Use every source on the face that is ready. Anything skipped is listed.',
+            default: false,
+        }),
+        medium: Flags.string({
+            description: 'Medium for any selected source that does not declare one. Each medium is analysed on its own, ' +
+                'so an essay never teaches a rule about email.',
+        }),
+        model: Flags.string({ description: `Analyst model (default: ${DEFAULT_STYLE_MODEL})` }),
+        'allow-paid': Flags.boolean({
+            description: 'Permit a build that bills. Without this a build is free or it does not run. Needed for any ' +
+                'model outside the free tier, and to allow the paid route when a free quota is exhausted.',
+            default: false,
+        }),
+        compile: Flags.boolean({
+            description: 'Compile any named source that is not compiled yet, before capturing style. On by default. ' +
+                '--no-compile captures style from what is already compiled and never bills for compilation.',
+            default: true,
+            allowNo: true,
+        }),
+        'best-of': Flags.integer({ description: 'Generate N candidates and keep the best (1-5, default 1)' }),
+        'no-wait': Flags.boolean({ description: 'Start the build and return the job id without polling.', default: false }),
+        timeout: Flags.integer({ description: 'How long to wait, in seconds (default: 3600)', default: 3600 }),
+    };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(StyleMake);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        if (!flags.all && (!flags.source || flags.source.length === 0)) {
+            this.error('Name what to learn from: --source <id> (repeatable), or --all for everything ready.\n' +
+                `See what is available with: faces face:sources ${args.alias}`);
+        }
+        if (flags.all && flags.source?.length) {
+            this.error('Pass either --all or --source, not both.');
+        }
+        const available = await this.load(client, args.alias);
+        const { sources, skipped } = this.select(available, flags, args.alias);
+        const model = flags.model ?? DEFAULT_STYLE_MODEL;
+        await this.checkBilling(client, model, flags['allow-paid']);
+        const payload = {
+            self_face: args.alias,
+            model,
+            sources,
+            compile: flags.compile,
+        };
+        if (flags['allow-paid'])
+            payload.oauth_only = false;
+        if (flags['best-of'] !== undefined)
+            payload.best_of_n = flags['best-of'];
+        if (!json && skipped.length > 0) {
+            for (const line of skipped)
+                process.stderr.write(`skipped: ${line}\n`);
+        }
+        if (!json) {
+            process.stderr.write(`Capturing style for '${args.alias}' from ${sources.length} source(s) using ${model}.\n`);
+        }
+        let started;
+        try {
+            started = (await client.post(BUILDS_PATH, { body: payload }));
+        }
+        catch (err) {
+            this.reportStartFailure(err);
+        }
+        const jobId = String(started.job_id ?? '');
+        if (!jobId)
+            this.error('The server accepted the build but returned no job id.');
+        if (flags['no-wait']) {
+            if (json)
+                return { ...started, sources, skipped };
+            this.log(`Build started: ${jobId}`);
+            this.log(`Read it with: faces style:status ${jobId}`);
+            return started;
+        }
+        const final = await this.awaitJob(client, jobId, flags.timeout, json);
+        if (final.status === 'failed')
+            this.error(`Build failed: ${jobFailureMessage(final.error)}`);
+        if (json)
+            return { ...publicJob(final), sources, skipped };
+        for (const line of formatBuildReport(final))
+            this.log(line);
+        this.log('');
+        this.log(`'${args.alias}' now writes in its own style. Try it: faces chat:chat ${args.alias} -m "..."`);
+        this.log(`Go back to the previous style: faces style:revert ${args.alias} --yes`);
+        return final;
+    }
+    async load(client, alias) {
+        try {
+            return await listSelectable(client, alias);
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 404)
+                    this.error(`No face named '${alias}'. It does not exist, or is not yours.`);
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Turn the flags into the wire's source list.
+     *
+     * The API wants {id, medium, source_type} per source and deliberately refuses
+     * to guess the medium. The listing already knows all three for most sources,
+     * so a user only has to supply what genuinely cannot be derived.
+     */
+    select(available, flags, alias) {
+        const byId = new Map(available.map((s) => [s.id, s]));
+        const skipped = [];
+        let chosen;
+        if (flags.all) {
+            if (available.length === 0) {
+                this.error(`'${alias}' has no sources to learn from. Add some with faces compile:doc or faces style:upload.`);
+            }
+            chosen = [];
+            for (const s of available) {
+                // Imported material and documents go in whether or not they are
+                // compiled: compiling them is part of the build, which is what
+                // --compile is for, and a corpus is never compiled at upload time.
+                //
+                // A live thread is the exception. It compiles as its messages arrive
+                // and is billed per message, so sweeping an unfinished one would charge
+                // for turns the user did not send. Those wait to be named.
+                if (s.isCorpus || s.synced) {
+                    if (!flags.compile && !s.synced) {
+                        skipped.push(`${s.label} (${s.id}) is not compiled, and --no-compile means it would teach nothing.`);
+                        continue;
+                    }
+                    chosen.push({ s });
+                }
+                else {
+                    skipped.push(`${s.label} (${s.id}) is a thread that is still compiling. Name it with --source once it is done.`);
+                }
+            }
+            if (chosen.length === 0) {
+                this.error(`Nothing on '${alias}' is ready to learn from.\n` +
+                    (flags.compile
+                        ? 'Add material with faces style:upload or faces compile:doc, then try again.'
+                        : '--no-compile only uses sources that are already compiled, and none are. Drop it to compile them as part of this build.'));
+            }
+        }
+        else {
+            chosen = [];
+            const missing = [];
+            for (const raw of flags.source ?? []) {
+                const { id, medium } = parseSourceArg(raw);
+                const s = byId.get(id);
+                if (s)
+                    chosen.push({ s, declared: medium });
+                else
+                    missing.push(id);
+            }
+            if (missing.length > 0) {
+                this.error(`Not a source on '${alias}': ${missing.join(', ')}\n` +
+                    `List what is there with: faces face:sources ${alias}`);
+            }
+        }
+        const undeclared = [];
+        const sources = [];
+        for (const { s, declared } of chosen) {
+            const medium = declared ?? flags.medium ?? s.medium;
+            if (!medium) {
+                undeclared.push(s);
+                continue;
+            }
+            sources.push({ id: s.id, medium, source_type: s.sourceType });
+        }
+        if (undeclared.length > 0) {
+            const list = undeclared
+                .map((s) => `  ${s.id}  ${s.label}${s.sourceType === 'room' ? '  (thread)' : ''}`)
+                .join('\n');
+            const first = undeclared[0];
+            const ways = [
+                '  --medium email                 applies to every source that does not say',
+                `  --source ${first.id}:email   applies to just this one`,
+            ];
+            // Only a document can record a medium on itself; a thread has no such field.
+            if (first.sourceType === 'document') {
+                ways.push(`  faces compile:doc:edit ${first.id} --medium email   records it permanently`);
+            }
+            this.error(`These sources do not say what sort of writing they are, and a style build will not guess:\n${list}\n\n` +
+                `Declare it, using the real medium rather than the example:\n${ways.join('\n')}\n\n` +
+                'A wrong declaration is worse than a missing one: a mislabelled source teaches the wrong voice ' +
+                'for that medium, and nothing afterwards says it happened.');
+        }
+        return { sources, skipped };
+    }
+    /**
+     * Refuse a build that would bill without being asked to.
+     *
+     * The analyst model runs the whole build, so it is the most expensive call in
+     * the product. Models on the free tier run on the user's own linked ChatGPT
+     * subscription; anything else bills every time. Reaching for a paid model to
+     * work around an expired link turns a fixable login into a permanent cost,
+     * which is why this is a refusal and not a warning.
+     */
+    async checkBilling(client, model, allowPaid) {
+        if (allowPaid)
+            return;
+        const eligible = await codexEligible(client, model);
+        if (eligible === false) {
+            this.error(`'${model}' is not on the free tier, so this build would bill you.\n` +
+                `Use ${DEFAULT_STYLE_MODEL}, which runs on your linked ChatGPT account at no cost, ` +
+                'or re-run with --allow-paid if you meant to pay.\n' +
+                'If you are here because a build failed on authentication, reconnect instead: faces auth:connect openai');
+        }
+    }
+    /** Translate a pre-flight refusal into the decision the user has to make. */
+    reportStartFailure(err) {
+        if (!(err instanceof FacesAPIError))
+            throw err;
+        // Every one of these lands before the job exists, so nothing has started.
+        const hint = {
+            402: 'Add credit with: faces billing:topup',
+            403: 'That source belongs to another account.',
+            404: 'Check the id against: faces face:sources <alias>',
+            409: 'A source is compiling right now, or the face is locked. Wait for it to finish, or unlock the face.',
+            422: 'A named thread has messages that are not compiled yet. Compile it first, or pass --no-compile.',
+        };
+        const extra = hint[err.statusCode];
+        this.error(`Error (${err.statusCode}): ${err.message}${extra ? `\n${extra}` : ''}\nNothing was started.`);
+    }
+    async awaitJob(client, jobId, timeout, json) {
+        let last = '';
+        try {
+            return await pollStyleJob(client, BUILDS_PATH, jobId, {
+                timeoutMs: timeout * 1000,
+                onPoll: (d) => {
+                    if (json)
+                        return;
+                    const p = d.progress;
+                    const stage = p?.stage ?? String(d.status ?? '');
+                    const key = `${stage}:${p?.done ?? ''}/${p?.total ?? ''}`;
+                    if (key === last)
+                        return;
+                    last = key;
+                    process.stderr.write(`  ${stage}${p?.total ? ` ${p.done ?? 0}/${p.total}` : ''}\n`);
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            this.error(err instanceof Error ? err.message : String(err));
+        }
+    }
+}

package/dist/commands/style/revert.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base.js';
+export default class StyleRevert extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/style/revert.js

@@ -0,0 +1,65 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { VERSIONS_PATH } from '../../style.js';
+export default class StyleRevert extends BaseCommand {
+    static description = 'Go back to the style a face had before the last style:make. It steps backwards through the kept ' +
+        'versions and there is no step forward, so the way to undo a revert is to capture the style again. ' +
+        'It changes how the face writes immediately, so it asks first.';
+    static examples = ['<%= config.bin %> <%= command.id %> alice --yes'];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        yes: Flags.boolean({ description: 'Skip confirmation', default: false }),
+    };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(StyleRevert);
+        const client = this.makeClient(flags);
+        // This writes to a live face the moment it is called. Requiring --yes is
+        // not ceremony: the endpoint takes a single field and gives no dry run, so
+        // an exploratory call is indistinguishable from a real one.
+        if (!flags.yes) {
+            this.error(`This changes how '${args.alias}' writes, straight away. Re-run with --yes to confirm.\n` +
+                `See what it would go back to: faces style:versions ${args.alias}`);
+        }
+        let data;
+        try {
+            data = (await client.post(`${VERSIONS_PATH}/revert`, { body: { self_face: args.alias } }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 404)
+                    this.error(`No face named '${args.alias}'. It does not exist, or is not yours.`);
+                if (err.statusCode === 409)
+                    this.error(`Error (409): ${err.message}\nThe face may be locked. Unlock it first.`);
+                // Reverting past the oldest kept version fails this way rather than
+                // with a clean refusal (faces-backend-shared#590).
+                if (err.statusCode === 500) {
+                    this.error(`Error (500): ${err.message}\n` +
+                        `'${args.alias}' may already be on the oldest style that is still kept, in which case there ` +
+                        'is nothing further back to go to. Check with: faces style:versions ' +
+                        args.alias);
+                }
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        const from = data.from_version;
+        const to = data.to_version;
+        if (from !== undefined && to !== undefined) {
+            this.log(`'${args.alias}' moved from version ${from} back to version ${to}.`);
+        }
+        else {
+            this.log(`'${args.alias}' reverted.`);
+        }
+        // Not "run it again to undo": another revert steps back again, it does not
+        // return. Verified against production.
+        this.log(`There is no step forward. To undo this, capture the style again: faces style:make ${args.alias} --all`);
+        this.log(`List versions: faces style:versions ${args.alias}`);
+        return data;
+    }
+}

package/dist/commands/style/status.d.ts

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../../base.js';
+export default class StyleStatus extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        face: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        job_id: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+    private list;
+}

package/dist/commands/style/status.js

@@ -0,0 +1,102 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { BUILDS_PATH, EXIT_NO_SUCH_FACE, formatBuildReport, jobFailureMessage, faceExists, pollStyleJob, publicJob } from '../../style.js';
+export default class StyleStatus extends BaseCommand {
+    static description = 'Read a style build. Give a job id for one build, or --face to list a face\'s recent builds. ' +
+        'Listing is how you find a job id you no longer have.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> 7a8b9c0d',
+        '<%= config.bin %> <%= command.id %> --face alice',
+        '<%= config.bin %> <%= command.id %> 7a8b9c0d --wait',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        face: Flags.string({ description: 'List recent builds for this face instead of reading one job' }),
+        limit: Flags.integer({ description: 'How many builds to list with --face (default: 10)', default: 10 }),
+        wait: Flags.boolean({ description: 'Block until the job finishes', default: false }),
+        timeout: Flags.integer({ description: 'How long to wait with --wait, in seconds (default: 3600)', default: 3600 }),
+    };
+    static args = {
+        job_id: Args.string({ description: 'Build job id', required: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(StyleStatus);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        if (!args.job_id && !flags.face) {
+            this.error('Give a job id, or --face <alias> to list a face\'s builds.');
+        }
+        if (args.job_id && flags.face) {
+            this.error('Pass either a job id or --face, not both.');
+        }
+        if (flags.face)
+            return this.list(client, flags.face, flags.limit, json);
+        let data;
+        try {
+            data = flags.wait
+                ? await pollStyleJob(client, BUILDS_PATH, args.job_id, { timeoutMs: flags.timeout * 1000 })
+                : (await client.get(`${BUILDS_PATH}/${encodeURIComponent(args.job_id)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 404)
+                    this.error(`No build job '${args.job_id}'. List a face's builds with --face <alias>.`);
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        if (json)
+            return publicJob(data);
+        for (const line of formatBuildReport(data))
+            this.log(line);
+        if (data.status === 'failed')
+            this.log(`\nerror:      ${jobFailureMessage(data.error)}`);
+        return data;
+    }
+    async list(client, face, limit, json) {
+        let data;
+        try {
+            data = (await client.get(`${BUILDS_PATH}?self_face=${encodeURIComponent(face)}&limit=${limit}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 404)
+                    this.error(`No face named '${face}'. It does not exist, or is not yours.`);
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        const jobs = data.jobs ?? [];
+        // An empty list comes back for an unknown face too. "No builds yet" and
+        // "no such face" are opposite answers, so they must not share an output.
+        if (jobs.length === 0 && !(await faceExists(client, face))) {
+            this.error(`No face named '${face}'. It does not exist, or is not yours.`, { exit: EXIT_NO_SUCH_FACE });
+        }
+        if (json)
+            return { ...data, jobs: jobs.map((j) => publicJob(j)) };
+        if (jobs.length === 0) {
+            this.log(`'${face}' has no style builds yet. Capture one with: faces style:make ${face} --all`);
+            return data;
+        }
+        const rows = jobs.map((j) => ({
+            job: String(j.job_id ?? '-'),
+            status: String(j.status ?? '-'),
+            when: String(j.created_at ?? '').slice(0, 19).replace('T', ' ') || '-',
+            model: String(j.report?.model ?? j.model ?? '-'),
+        }));
+        const cols = [
+            ['JOB', (r) => r.job],
+            ['STATUS', (r) => r.status],
+            ['STARTED', (r) => r.when],
+        ];
+        const w = cols.map(([h, g]) => Math.max(h.length, ...rows.map((r) => g(r).length)));
+        const line = (c) => c.map((x, i) => x.padEnd(w[i])).join('  ').trimEnd();
+        this.log(line(cols.map(([h]) => h)));
+        for (const r of rows)
+            this.log(line(cols.map(([, g]) => g(r))));
+        this.log('');
+        this.log(`${rows.length} build(s) shown, newest first. Raise the cap with --limit.`);
+        return data;
+    }
+}

package/dist/commands/style/upload.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../base.js';
+export default class StyleUpload extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        type: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'messages-per-room': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        strict: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        file: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}