faces-cli 1.7.14 → 1.8.0

package/dist/commands/compile/doc/list.d.ts

@@ -2,6 +2,7 @@ import { BaseCommand } from '../../../base.js';
 export default class CompileDocList extends BaseCommand {
     static description: string;
     static flags: {
+        verbose: 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>;

package/dist/commands/compile/doc/list.js

@@ -1,10 +1,12 @@
-import { Args } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../../base.js';
 import { FacesAPIError } from '../../../client.js';
 export default class CompileDocList extends BaseCommand {
-    static description = 'List documents for a face';
+    static description = "List documents for a face. Each document's full text is omitted unless --verbose, so a face with a " +
+        'real corpus stays readable. For a table of every source, documents and threads together, use face:sources.';
     static flags = {
         ...BaseCommand.baseFlags,
+        verbose: Flags.boolean({ description: "Include each document's full text", default: false }),
     };
     static args = {
         face_id: Args.string({ description: 'Face alias', required: true }),
@@ -21,8 +23,21 @@ export default class CompileDocList extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled())
-            this.printHuman(data);
+        // --json is untouched: machine callers may already read `content`, and
+        // dropping a field from structured output would break them silently.
+        if (!this.jsonEnabled()) {
+            const items = Array.isArray(data) ? data : [];
+            const omitted = flags.verbose ? 0 : items.filter((d) => typeof d.content === 'string' && d.content !== '').length;
+            this.printHuman(flags.verbose
+                ? data
+                : items.map((d) => Object.fromEntries(Object.entries(d).filter(([k]) => k !== 'content'))));
+            // Say that something was left out. A list that quietly drops a field
+            // reads as complete, which is how this became a problem in the first place.
+            if (omitted > 0) {
+                this.log('');
+                this.log(`Text omitted for ${omitted} document(s). Pass --verbose to include it.`);
+            }
+        }
         return data;
     }
 }

package/dist/commands/face/sources.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceSources extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        type: import("@oclif/core/interfaces").OptionFlag<string | undefined, 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 fetch;
+    private statusOf;
+    private toRow;
+    private toJson;
+    private render;
+}

package/dist/commands/face/sources.js

@@ -0,0 +1,150 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+/** Exit code for "no such face", so a caller can tell it from an empty face. */
+const EXIT_NO_SUCH_FACE = 4;
+export default class FaceSources extends BaseCommand {
+    static description = 'List every source compiled into a face: documents and threads together, one row each. ' +
+        `Exits ${EXIT_NO_SUCH_FACE} if the face does not exist, which is a different answer from a face that ` +
+        'has no sources. Content is never printed; read a single source with compile:doc:get or compile:thread:get.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice',
+        '<%= config.bin %> <%= command.id %> alice --type thread',
+        '<%= config.bin %> <%= command.id %> alice --json',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        type: Flags.string({ description: 'Show only one kind of source', options: ['doc', 'thread'] }),
+    };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FaceSources);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        const alias = encodeURIComponent(args.alias);
+        const wantDocs = flags.type !== 'thread';
+        const wantThreads = flags.type !== 'doc';
+        // A face that does not exist and a face with nothing in it are opposite
+        // answers. The API distinguishes them with a 404, so this must too — by
+        // message and by exit code, since a script only sees the latter.
+        const docs = wantDocs ? await this.fetch(client, `/v1/compile/documents?alias=${alias}`, args.alias) : [];
+        // include_uploads defaults to excluding upload-created threads. This command
+        // claims to list every source, so it asks for them explicitly.
+        const threads = wantThreads
+            ? await this.fetch(client, `/v1/compile/threads?alias=${alias}&include_uploads=true`, args.alias)
+            : [];
+        const rows = [...docs.map((d) => this.toRow(d, 'doc')), ...threads.map((t) => this.toRow(t, 'thread'))];
+        rows.sort((a, b) => (b.updated || '').localeCompare(a.updated || '') || a.label.localeCompare(b.label));
+        if (json) {
+            return {
+                alias: args.alias,
+                documents: docs.map((d) => this.toJson(d, 'doc')),
+                threads: threads.map((t) => this.toJson(t, 'thread')),
+                totals: {
+                    sources: rows.length,
+                    tokens: rows.reduce((n, r) => n + r.tokens, 0),
+                    not_synced: rows.filter((r) => !r.synced).length,
+                },
+            };
+        }
+        this.render(args.alias, rows, flags.type);
+        return { alias: args.alias, sources: rows.length };
+    }
+    async fetch(client, path, alias) {
+        try {
+            const data = await client.get(path);
+            return (Array.isArray(data) ? data : (data.data ?? []));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 404) {
+                    this.error(`No face named '${alias}'. It does not exist, or is not owned by this account.`, {
+                        exit: EXIT_NO_SUCH_FACE,
+                    });
+                }
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+    }
+    statusOf(s) {
+        if (s.synced)
+            return 'synced';
+        const st = s.prepare_status;
+        const done = s.chunks_completed;
+        const total = s.chunks_total;
+        const progress = done !== null && done !== undefined && total ? ` ${done}/${total}` : '';
+        if (st)
+            return `${st}${progress}`;
+        return 'not compiled';
+    }
+    toRow(s, type) {
+        return {
+            type,
+            id: String(s.document_id ?? s.thread_id ?? ''),
+            label: s.label?.trim() || '(untitled)',
+            tokens: s.token_count ?? 0,
+            status: this.statusOf(s),
+            medium: s.medium?.trim() || '-',
+            updated: (s.updated_at ?? s.created_at ?? '').slice(0, 10) || '-',
+            synced: Boolean(s.synced),
+        };
+    }
+    toJson(s, type) {
+        const out = {
+            type,
+            // A stable id, because anything that later deletes or recompiles a source
+            // needs one — the label is for people and is not unique.
+            id: String(s.document_id ?? s.thread_id ?? ''),
+            label: s.label ?? null,
+            token_count: s.token_count ?? 0,
+            status: this.statusOf(s),
+            synced: Boolean(s.synced),
+            prepare_status: s.prepare_status ?? null,
+            medium: s.medium ?? null,
+            created_at: s.created_at ?? null,
+            updated_at: s.updated_at ?? null,
+            read_only: Boolean(s.read_only),
+        };
+        if (type === 'doc')
+            out.document_id = s.document_id;
+        if (type === 'thread') {
+            out.thread_id = s.thread_id;
+            out.message_count = s.message_count ?? null;
+        }
+        return out;
+    }
+    render(alias, rows, type) {
+        if (rows.length === 0) {
+            const what = type ? `${type} sources` : 'sources';
+            this.log(`'${alias}' exists and has no ${what}.`);
+            return;
+        }
+        const n = (v) => v.toLocaleString('en-US');
+        const cols = [
+            ['TYPE', (r) => r.type],
+            ['LABEL', (r) => r.label],
+            ['TOKENS', (r) => n(r.tokens)],
+            ['STATUS', (r) => r.status],
+            ['MEDIUM', (r) => r.medium],
+            ['UPDATED', (r) => r.updated],
+        ];
+        const widths = cols.map(([h, get]) => Math.max(h.length, ...rows.map((r) => get(r).length)));
+        const line = (cells) => cells.map((c, i) => (cols[i][0] === 'TOKENS' ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join('  ').trimEnd();
+        this.log(line(cols.map(([h]) => h)));
+        for (const r of rows)
+            this.log(line(cols.map(([, get]) => get(r))));
+        // Say what the total counts. Every listed row is included, so the column
+        // adds up to the figure shown; anything not yet compiled is called out
+        // separately rather than quietly left out of the sum.
+        const tokens = rows.reduce((a, r) => a + r.tokens, 0);
+        const pending = rows.filter((r) => !r.synced).length;
+        this.log('');
+        this.log(`${n(tokens)} tokens across all ${rows.length} source(s) listed.`);
+        if (pending > 0) {
+            this.log(`${pending} not yet synced. Their tokens are included in that total.`);
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../../base.js';
+export default class StyleDelete extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        scope: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        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,71 @@
+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';
+/** What each scope destroys, in the words the user needs before choosing. */
+const SCOPES = {
+    map: 'the captured style and everything derived from it. Your uploaded material is kept, so it can be captured again without re-uploading.',
+    all: 'the captured style AND the material it was built from. The uploaded corpus is deleted. This cannot be undone and nothing can rebuild it.',
+};
+export default class StyleDelete extends BaseCommand {
+    static description = 'Delete a face\'s captured style. --scope map forgets the style and keeps the material it came from. ' +
+        '--scope all deletes the uploaded material too, permanently. There is no default because the two ' +
+        'differ by whether your material survives.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --scope map',
+        '<%= config.bin %> <%= command.id %> alice --scope all --yes',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        scope: Flags.string({
+            description: 'map: forget the style, keep the material. all: delete the material with it, permanently.',
+            options: ['map', 'all'],
+            required: true,
+        }),
+        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);
+        const scope = flags.scope;
+        if (!flags.yes) {
+            const what = `This deletes ${SCOPES[scope]}`;
+            if (this.jsonEnabled())
+                this.error(`${what}\nRe-run with --yes to confirm.`);
+            const ok = await this.confirm(`${what}\nDelete for '${args.alias}'?`);
+            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.`);
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        this.log(scope === 'all'
+            ? `Deleted the style and the uploaded material for '${args.alias}'.`
+            : `Deleted the style for '${args.alias}'. The material it came from is still there, so you can capture it again: 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>;
+}