faces-cli 1.7.16 → 1.8.0

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[];

package/dist/style.js

@@ -0,0 +1,258 @@
+/**
+ * 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 { FacesAPIError } from './client.js';
+export const BUILDS_PATH = '/v1/voiceprint/builds';
+export const VERSIONS_PATH = '/v1/voiceprint/versions';
+export 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 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 const ROOM_DEFAULT_MEDIUM = 'conversation';
+/**
+ * What an import reports when it could not tell what the material is.
+ *
+ * Not a medium, and must not be sent as one — the build rejects it. It means
+ * the same as no answer, except that it came from imported material, where
+ * assuming a conversation would be a guess about content rather than a fact
+ * about the source type.
+ */
+const UNIDENTIFIED_CORPUS = 'unknown';
+/** Exit code for "no such face", so a caller can tell it from a face with no style. */
+export 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 async function faceExists(client, alias) {
+    try {
+        await client.get(`/v1/faces/${encodeURIComponent(alias)}`);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof FacesAPIError && err.statusCode === 404)
+            return false;
+        // Anything else (network, auth, 5xx) is not evidence of absence.
+        throw err;
+    }
+}
+/**
+ * The medium a source already declares, or undefined when the caller has to.
+ *
+ * A live thread is the one case where the medium follows from the source type
+ * rather than from a guess: it is a conversation because that is what a thread
+ * is. Imported material is not — a corpus the importer could not classify could
+ * be anything, and calling it a conversation would teach the wrong voice for a
+ * medium with nothing afterwards to signal it happened.
+ */
+function mediumOf(r, sourceType) {
+    if (sourceType === 'document')
+        return r.medium?.trim() || undefined;
+    const kind = r.corpus_kind?.trim();
+    if (!kind)
+        return ROOM_DEFAULT_MEDIUM;
+    return kind === UNIDENTIFIED_CORPUS ? undefined : kind;
+}
+function rowToSelectable(r, sourceType) {
+    const stamp = r.voiceprint ?? undefined;
+    return {
+        id: String(r.document_id ?? r.thread_id ?? ''),
+        sourceType,
+        // A document declares its own medium. A room declares one only when it came
+        // from a corpus import; anything else is a live conversation.
+        medium: mediumOf(r, sourceType),
+        label: r.label?.trim() || '(untitled)',
+        synced: Boolean(r.synced),
+        isCorpus: sourceType === 'document' || Boolean(r.corpus_kind?.trim()),
+        // The stamp was renamed alongside the request field, but stored stamps kept
+        // the old key (faces-backend-shared#589), so both are read.
+        printedMedium: stamp?.medium ?? stamp?.kind,
+        printedAt: stamp?.printed_at,
+    };
+}
+function rowsOf(data) {
+    if (Array.isArray(data))
+        return data;
+    const obj = (data ?? {});
+    for (const key of ['documents', 'threads', 'data', 'items']) {
+        if (Array.isArray(obj[key]))
+            return obj[key];
+    }
+    return [];
+}
+/**
+ * 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 async function listSelectable(client, alias) {
+    const a = encodeURIComponent(alias);
+    const [docs, threads] = await Promise.all([
+        client.get(`/v1/compile/documents?alias=${a}`),
+        client.get(`/v1/compile/threads?alias=${a}&include_uploads=true`),
+    ]);
+    const out = [
+        ...rowsOf(docs).map((r) => rowToSelectable(r, 'document')),
+        ...rowsOf(threads).map((r) => rowToSelectable(r, 'room')),
+    ];
+    return out.filter((s) => s.id);
+}
+/**
+ * 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 function parseSourceArg(raw) {
+    const at = raw.indexOf(':');
+    if (at === -1)
+        return { id: raw.trim() };
+    return { id: raw.slice(0, at).trim(), medium: raw.slice(at + 1).trim() || undefined };
+}
+/**
+ * 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 async function pollStyleJob(client, basePath, jobId, opts = {}) {
+    const interval = opts.intervalMs ?? 3000;
+    const timeout = opts.timeoutMs ?? 3_600_000;
+    const start = Date.now();
+    const endpoint = `${basePath}/${encodeURIComponent(jobId)}`;
+    while (true) {
+        if (Date.now() - start > timeout) {
+            throw new Error(`Timed out after ${Math.round(timeout / 1000)}s. The build may still finish; read it later with: faces style:status ${jobId}`);
+        }
+        await new Promise((r) => setTimeout(r, interval));
+        let data;
+        try {
+            data = (await client.get(endpoint));
+        }
+        catch (err) {
+            // A 5xx mid-poll is transient. Anything else is real and propagates.
+            if (err instanceof FacesAPIError && err.statusCode >= 500)
+                continue;
+            throw err;
+        }
+        opts.onPoll?.(data);
+        const status = String(data.status ?? '');
+        if (status === 'done' || status === 'failed')
+            return data;
+    }
+}
+/** Failure text, with the one hint that is actionable rather than descriptive. */
+export function jobFailureMessage(error) {
+    const e = typeof error === 'string' && error ? error : 'unknown error';
+    if (e.toUpperCase().startsWith('CHATGPT_AUTH')) {
+        return (`${e}\n` +
+            'The ChatGPT link has expired. Reconnect it with: faces auth:connect openai\n' +
+            'Your uploaded material is preserved, so re-running costs nothing extra. Do not switch to a ' +
+            'paid model to get around this: it turns a login problem into a bill.');
+    }
+    return e;
+}
+/**
+ * Fields printed from a build report, and the only ones.
+ *
+ * A whitelist rather than a filter, because the report carries internal
+ * analysis keys that must not reach a user's screen and this package ships its
+ * compiled source to npm. Naming the unwanted keys in order to strip them would
+ * publish them; naming only the wanted ones cannot.
+ */
+const REPORT_FIELDS = [
+    ['sources_printed', 'sources printed'],
+    ['corpus_rooms', 'corpus rooms'],
+    ['voice_map_chars', 'voice map size'],
+    ['best_of_n', 'best of n'],
+];
+/**
+ * Report keys that may leave this CLI, in --json as much as on screen.
+ *
+ * The report also carries internal analysis keys. Those are excluded by being
+ * absent from this list rather than by being named and removed: this package
+ * publishes its compiled source to npm, so naming them in order to strip them
+ * would publish them.
+ */
+const REPORT_PUBLIC_KEYS = new Set([
+    'sources_printed',
+    'corpus_rooms',
+    'voice_map_chars',
+    'best_of_n',
+    'components',
+    'analyze',
+    'intake',
+    'baseline',
+    'holdout',
+    'scoring_enabled',
+    'source_compile',
+    'voicemap_compile',
+    'tuning',
+    'reused_lenses',
+]);
+/**
+ * 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 function publicJob(data) {
+    const report = data.report;
+    if (!report || typeof report !== 'object')
+        return data;
+    const clean = {};
+    for (const [k, v] of Object.entries(report)) {
+        if (REPORT_PUBLIC_KEYS.has(k))
+            clean[k] = v;
+    }
+    return { ...data, report: clean };
+}
+/** Human-readable build summary. Never dumps the report. */
+export function formatBuildReport(data) {
+    const report = (data.report ?? {});
+    const pairs = [
+        ['job', data.job_id ?? '-'],
+        ['status', data.status ?? '-'],
+    ];
+    if (data.version_id)
+        pairs.push(['version', data.version_id]);
+    for (const [key, label] of REPORT_FIELDS) {
+        const v = report[key];
+        if (v !== undefined && v !== null)
+            pairs.push([label, v]);
+    }
+    const analyze = report.analyze;
+    if (analyze?.chunks !== undefined)
+        pairs.push(['chunks', analyze.chunks]);
+    const width = Math.max(...pairs.map(([label]) => label.length)) + 2;
+    return pairs.map(([label, v]) => `${(label + ':').padEnd(width)}${v}`);
+}