faces-cli 1.7.14 → 1.8.0

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