faces-cli 1.7.14 → 1.8.0

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

package/dist/commands/style/upload.js

@@ -0,0 +1,81 @@
+import { Args, Flags } from '@oclif/core';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class StyleUpload extends BaseCommand {
+    static description = 'Load a corpus of a person\'s own writing (a mail export, a message archive) as source material for ' +
+        'style capture. This only stores the material: nothing is compiled and nothing is billed. Capture ' +
+        'the style afterwards with style:make.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice ./mail.jsonl',
+        '<%= config.bin %> <%= command.id %> alice ./thread.json --type thread_json',
+        '<%= config.bin %> <%= command.id %> alice ./mail.jsonl --messages-per-room 100 --strict',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        type: Flags.string({
+            description: 'email_jsonl: one message per line, split across several rooms. thread_json: a JSON array that ' +
+                'becomes a single room.',
+            options: ['email_jsonl', 'thread_json'],
+            default: 'email_jsonl',
+        }),
+        'messages-per-room': Flags.integer({
+            description: 'How many messages per room when the type is email_jsonl (1-1000, default: 50)',
+            default: 50,
+        }),
+        strict: Flags.boolean({
+            description: 'Reject the whole upload if any message is invalid. By default invalid messages are skipped and ' +
+                'reported, because a corpus is statistical and a few bad lines are not worth losing the rest.',
+            default: false,
+        }),
+    };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+        file: Args.string({ description: 'Corpus file', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(StyleUpload);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        if (!fs.existsSync(args.file))
+            this.error(`File not found: ${args.file}`);
+        const form = new FormData();
+        form.append('file', new Blob([fs.readFileSync(args.file)], { type: 'application/json' }), path.basename(args.file));
+        const params = new URLSearchParams({ type: flags.type });
+        if (flags.type === 'email_jsonl')
+            params.set('emails_per_thread', String(flags['messages-per-room']));
+        if (flags.strict)
+            params.set('strict', 'true');
+        let data;
+        try {
+            data = (await client.postForm(`/v1/faces/${encodeURIComponent(args.alias)}/upload?${params}`, form));
+        }
+        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 === 422 && flags.strict) {
+                    this.error(`Error (422): ${err.message}\nDrop --strict to skip invalid messages instead of refusing the upload.`);
+                }
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        if (json)
+            return data;
+        const roomIds = data.room_ids ?? [];
+        const skipped = data.skipped;
+        this.log(`face:     ${data.alias ?? args.alias}`);
+        this.log(`messages: ${data.message_count ?? '?'}`);
+        this.log(`rooms:    ${data.room_count ?? roomIds.length}`);
+        // Never let a partial upload read as a complete one.
+        if (skipped?.length) {
+            this.log(`skipped:  ${skipped.length} message(s) failed validation and were not stored.`);
+            this.log('          Re-run with --strict to refuse the whole upload instead.');
+        }
+        this.log('');
+        this.log(`Capture the style: faces style:make ${args.alias} --all`);
+        return data;
+    }
+}

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

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class StyleVersions extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        '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/versions.js

@@ -0,0 +1,77 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { EXIT_NO_SUCH_FACE, VERSIONS_PATH, faceExists } from '../../style.js';
+export default class StyleVersions extends BaseCommand {
+    static description = 'List the styles captured for a face, and which one it is writing in now. Each style:make keeps ' +
+        'the previous one, so this is what style:revert has to go back to.';
+    static examples = ['<%= config.bin %> <%= command.id %> alice', '<%= config.bin %> <%= command.id %> alice --json'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(StyleVersions);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.get(`${VERSIONS_PATH}/${encodeURIComponent(args.alias)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError && err.statusCode === 404) {
+                // The 404 covers both "no style" and "no face". Only one is an error.
+                if (await faceExists(client, args.alias)) {
+                    if (this.jsonEnabled())
+                        return { self_face: args.alias, versions: [] };
+                    this.log(`'${args.alias}' exists and has no captured style yet.`);
+                    this.log(`Capture one with: faces style:make ${args.alias} --all`);
+                    return { self_face: args.alias, versions: [] };
+                }
+                this.error(`No face named '${args.alias}'. It does not exist, or is not yours.`, { exit: EXIT_NO_SUCH_FACE });
+            }
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        const versions = data.versions ?? [];
+        if (this.jsonEnabled())
+            return data;
+        if (versions.length === 0) {
+            this.log(`'${args.alias}' has no captured style. Capture one with: faces style:make ${args.alias} --all`);
+            return data;
+        }
+        const rows = versions.map((v) => ({
+            version: String(v.version ?? '-'),
+            active: v.active ? 'yes' : '-',
+            model: v.model?.trim() || '-',
+            created: String(v.created_at ?? '').slice(0, 19).replace('T', ' ') || '-',
+        }));
+        const cols = [
+            ['VERSION', (r) => r.version],
+            ['ACTIVE', (r) => r.active],
+            ['MODEL', (r) => r.model],
+            ['CAPTURED', (r) => r.created],
+        ];
+        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))));
+        // More than one row can come back marked active (faces-backend-shared#589).
+        // Saying "you are writing in version N" would be a guess, so when the data
+        // is ambiguous the command says so instead of picking one.
+        const active = versions.filter((v) => v.active);
+        this.log('');
+        if (active.length === 1) {
+            this.log(`Writing in version ${active[0].version} now. ${versions.length} version(s) kept.`);
+        }
+        else if (active.length === 0) {
+            this.log(`${versions.length} version(s) kept. None is marked active.`);
+        }
+        else {
+            this.log(`${versions.length} version(s) kept, and ${active.length} are marked active, so which one is in ` +
+                'use cannot be read from this list. Reported upstream.');
+        }
+        return data;
+    }
+}

package/dist/routing.d.ts

@@ -26,3 +26,12 @@ export declare function isCompositeFormula(modelArg: string): boolean;
  * default model from the local catalog, falling back to GET /v1/faces/{alias}.
  */
 export declare function resolveEndpoint(client: FacesClient, modelArg: string): Promise<RouteInfo>;
+/**
+ * Whether a model runs on the user's own linked ChatGPT subscription, and so
+ * costs them nothing, or always bills.
+ *
+ * Returns undefined when the catalog cannot say — an unknown model, or a cache
+ * written before this field was read. Undefined must not be treated as "bills":
+ * refusing to run because we are out of date is worse than running.
+ */
+export declare function codexEligible(client: FacesClient, llm: string): Promise<boolean | undefined>;

package/dist/routing.js

@@ -131,3 +131,23 @@ export async function resolveEndpoint(client, modelArg) {
         return { endpoint: hit.endpoint, llm, freeWhenConnected: hit.freeWhenConnected };
     return { endpoint: fallbackEndpoint(llm), llm, freeWhenConnected: false };
 }
+/**
+ * Whether a model runs on the user's own linked ChatGPT subscription, and so
+ * costs them nothing, or always bills.
+ *
+ * Returns undefined when the catalog cannot say — an unknown model, or a cache
+ * written before this field was read. Undefined must not be treated as "bills":
+ * refusing to run because we are out of date is worse than running.
+ */
+export async function codexEligible(client, llm) {
+    const hits = (await getModels(client)).filter((m) => m.id === llm);
+    if (hits.length === 0)
+        return undefined;
+    // The catalog lists paid and OAuth twins under one id; eligible on either
+    // means the free route exists.
+    if (hits.some((m) => m.codex_eligible === true))
+        return true;
+    if (hits.every((m) => m.codex_eligible === false))
+        return false;
+    return undefined;
+}

package/dist/style.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared helpers for the `style` command family.
+ *
+ * "Style" is what the CLI calls the API's voiceprint: the writing manner
+ * captured from a person's own material and installed on their face. It is a
+ * separate act from `compile`, which captures what a face knows. One family
+ * answers "what does it know", the other "how does it write".
+ *
+ * The API names a source by a triple — id, medium, source_type. Users should
+ * only ever have to give an id, so everything here exists to turn one into the
+ * other from what the list endpoints already report.
+ */
+import { FacesClient } from './client.js';
+export declare const BUILDS_PATH = "/v1/voiceprint/builds";
+export declare const VERSIONS_PATH = "/v1/voiceprint/versions";
+export declare const STYLE_FACES_PATH = "/v1/voiceprint/faces";
+/**
+ * Analyst model used when the caller does not choose one.
+ *
+ * Not the server default, deliberately. The server still defaults to an older
+ * model (faces-backend-shared#574) and the build is the most expensive call in
+ * the product, so the CLI names the current recommendation rather than
+ * inheriting a stale one.
+ */
+export declare const DEFAULT_STYLE_MODEL = "gpt-5.6-terra";
+/**
+ * Medium assumed for a room that does not declare one.
+ *
+ * Corpus rooms carry `corpus_kind`. Ordinary threads do not, because they are
+ * live conversations rather than an imported corpus — so a thread with no
+ * declared medium is a conversation, which is the one case where the medium
+ * follows from the source type rather than from a guess about content.
+ */
+export declare const ROOM_DEFAULT_MEDIUM = "conversation";
+/** Exit code for "no such face", so a caller can tell it from a face with no style. */
+export declare const EXIT_NO_SUCH_FACE = 4;
+/**
+ * Whether a face exists at all.
+ *
+ * The voiceprint routes cannot answer this. `GET /voiceprint/versions/{alias}`
+ * returns the same 404 for a face that has no style as for a face that does not
+ * exist, and `GET /voiceprint/builds?self_face=` returns an empty list for
+ * both. Those are opposite answers, so the face route is asked directly rather
+ * than reporting one as the other.
+ */
+export declare function faceExists(client: FacesClient, alias: string): Promise<boolean>;
+/** A source the CLI can name in a build request. */
+export interface Selectable {
+    id: string;
+    sourceType: 'room' | 'document';
+    /** Resolved from the listing. Undefined means the caller has to declare it. */
+    medium?: string;
+    label: string;
+    synced: boolean;
+    /**
+     * True for imported corpus material. Distinguishes it from a live thread,
+     * which is the one source type a build may not compile for free.
+     */
+    isCorpus: boolean;
+    /** Present once this source has been printed. */
+    printedAt?: string;
+    printedMedium?: string;
+}
+/** What goes on the wire. `medium`, not `kind` — renamed 2026-08-27, no alias. */
+export interface SourceRef {
+    id: string;
+    medium: string;
+    source_type: 'room' | 'document';
+}
+/**
+ * Every source on a face that a build could name.
+ *
+ * `include_uploads` matters: imported corpus rooms are excluded by default, and
+ * they are the main thing a style build is made from.
+ */
+export declare function listSelectable(client: FacesClient, alias: string): Promise<Selectable[]>;
+/**
+ * Parse one `--source` value: `<id>` or `<id>:<medium>`.
+ *
+ * Ids are UUIDs, so the first colon separates cleanly and a medium containing
+ * spaces ("academic paper") survives intact.
+ */
+export declare function parseSourceArg(raw: string): {
+    id: string;
+    medium?: string;
+};
+/**
+ * Poll a voiceprint job until it stops.
+ *
+ * Returns the terminal payload including a failed one — whether a failure is an
+ * error is the caller's decision, not this function's.
+ */
+export declare function pollStyleJob(client: FacesClient, basePath: string, jobId: string, opts?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    onPoll?: (d: Record<string, unknown>) => void;
+}): Promise<Record<string, unknown>>;
+/** Failure text, with the one hint that is actionable rather than descriptive. */
+export declare function jobFailureMessage(error: unknown): string;
+/**
+ * A job payload safe to hand onward, with its report reduced to public fields.
+ *
+ * Applied to --json too. A machine consumer reading our output is as much a way
+ * for an internal key to escape as a terminal is.
+ */
+export declare function publicJob(data: Record<string, unknown>): Record<string, unknown>;
+/** Human-readable build summary. Never dumps the report. */
+export declare function formatBuildReport(data: Record<string, unknown>): string[];