faces-cli 1.7.4 → 1.7.6

package/dist/base.js

@@ -47,6 +47,12 @@ export class BaseCommand extends Command {
         }
         else if (data !== null && typeof data === 'object') {
             for (const [k, v] of Object.entries(data)) {
+                // read_only: only surface when set; render as a bare marker, never "read_only: false"
+                if (k === 'read_only') {
+                    if (v)
+                        this.log(`${prefix}read only`);
+                    continue;
+                }
                 if (v !== null && typeof v === 'object') {
                     this.log(`${prefix}${k}:`);
                     this.printHuman(v, indent + 1);

package/dist/commands/face/get.js

@@ -39,6 +39,8 @@ export default class FaceGet extends BaseCommand {
             this.log(`name:      ${f.name}`);
             this.log(`owned_by:  ${f.owned_by}`);
             this.log(`created:   ${new Date(f.created * 1000).toISOString().slice(0, 10)}`);
+            if (f.read_only)
+                this.log('read only');
             if (f.formula) {
                 this.log(`formula:   ${f.formula}`);
                 this.log(`type:      composite`);

package/dist/commands/face/list.js

@@ -102,6 +102,8 @@ export default class FaceList extends BaseCommand {
                     }
                     if (f.published)
                         suffix += '  [public · requires @model]';
+                    if (f.read_only)
+                        suffix += '  [read only]';
                     this.log(`${handle(f).padEnd(handleWidth)}  ${f.name.padEnd(nameWidth)}${suffix}`);
                 }
             }

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

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceLock 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: {
+        face_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/face/lock.js

@@ -0,0 +1,34 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FaceLock extends BaseCommand {
+    static description = 'Lock a face (read-only). A locked face still reads and chats normally, but it — and everything it owns (documents, threads, voiceprint) — cannot be changed until unlocked.';
+    static examples = ['<%= config.bin %> <%= command.id %> socrates'];
+    static flags = {
+        ...BaseCommand.baseFlags,
+    };
+    static args = {
+        face_id: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FaceLock);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = await client.patch(`/v1/faces/${args.face_id}/lock`, { body: { read_only: true } });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (!this.jsonEnabled()) {
+            const res = data;
+            this.log(`Locked '${res.alias ?? args.face_id}' — read only.`);
+            const affected = res.affected ?? [];
+            if (affected.length > 0)
+                this.log(`Affected: ${affected.join(', ')}`);
+        }
+        return data;
+    }
+}

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

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceUnlock 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: {
+        face_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/face/unlock.js

@@ -0,0 +1,34 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FaceUnlock extends BaseCommand {
+    static description = 'Unlock a face (make it writable again). Thaws the face and everything it owns (documents, threads, voiceprint).';
+    static examples = ['<%= config.bin %> <%= command.id %> socrates'];
+    static flags = {
+        ...BaseCommand.baseFlags,
+    };
+    static args = {
+        face_id: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FaceUnlock);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = await client.patch(`/v1/faces/${args.face_id}/lock`, { body: { read_only: false } });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (!this.jsonEnabled()) {
+            const res = data;
+            this.log(`Unlocked '${res.alias ?? args.face_id}' — writable.`);
+            const affected = res.affected ?? [];
+            if (affected.length > 0)
+                this.log(`Affected: ${affected.join(', ')}`);
+        }
+        return data;
+    }
+}

package/dist/commands/voiceprint/build-status.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintBuildStatus 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: {
+        job_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/build-status.js

@@ -0,0 +1,46 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { jobFailureMessage } from '../../voiceprint.js';
+import { printBuildReport } from './build.js';
+export default class VoiceprintBuildStatus extends BaseCommand {
+    static description = 'Get the status/result of a voiceprint build job (from voiceprint:build without --wait)';
+    static examples = ['<%= config.bin %> <%= command.id %> 4e13bf03-fbc1-4ad0-92ae-16984e2f9a1d'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        job_id: Args.string({ description: 'Build job id', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintBuildStatus);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.get(`/v1/voiceprint/builds/${encodeURIComponent(args.job_id)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        const status = String(data.status ?? 'unknown');
+        if (status === 'failed') {
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: failed`);
+            this.log(`error:  ${jobFailureMessage(data.error)}`);
+        }
+        else if (status === 'done') {
+            printBuildReport(this, args.job_id, data);
+        }
+        else {
+            const p = data.progress;
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: ${status}`);
+            if (p?.stage)
+                this.log(`stage:  ${p.stage}${p.total ? ` ${p.done}/${p.total}` : ''}`);
+            this.log(`(still running — poll again with: faces voiceprint:build-status ${args.job_id})`);
+        }
+        return data;
+    }
+}

package/dist/commands/voiceprint/build.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintBuild extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'holdout-count': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'min-valid': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: 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: {
+        self_alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}
+/** Shared build-report formatter (used by voiceprint:build --wait and voiceprint:build-status). */
+export declare function printBuildReport(cmd: {
+    log: (m: string) => void;
+}, jobId: string, data: Record<string, unknown>): void;

package/dist/commands/voiceprint/build.js

@@ -0,0 +1,109 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { pollVoiceprintJob, jobFailureMessage } from '../../voiceprint.js';
+export default class VoiceprintBuild extends BaseCommand {
+    static description = "Build a self face's voice map from its uploaded corpus. Auto-creates the hidden <self>-voiceprint face and installs the map. Async — use --wait to block.";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --wait',
+        '<%= config.bin %> <%= command.id %> alice --holdout-count 120 --oauth-only --wait',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        model: Flags.string({ description: 'Model that forges the voice map (default: gpt-5.4)' }),
+        'holdout-count': Flags.integer({ description: 'Stratified scoring holdout size (default: 120)' }),
+        'min-valid': Flags.integer({ description: 'Corpus floor below which no holdout is split — train on all (default: 550)' }),
+        'oauth-only': Flags.boolean({ description: 'Only run on a free (OAuth) route; never fall back to billed inference', default: false }),
+        wait: Flags.boolean({ description: 'Block and poll until the build finishes (default: print the job_id and return)', default: false }),
+    };
+    static args = {
+        self_alias: Args.string({ description: 'Self face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintBuild);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        const payload = { self_face: args.self_alias };
+        if (flags.model)
+            payload.model = flags.model;
+        if (flags['holdout-count'] !== undefined)
+            payload.holdout_count = flags['holdout-count'];
+        if (flags['min-valid'] !== undefined)
+            payload.min_valid = flags['min-valid'];
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
+        let started;
+        try {
+            started = (await client.post('/v1/voiceprint/builds', { body: payload }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        const jobId = String(started.job_id ?? '');
+        if (!jobId)
+            this.error('Server did not return a job_id');
+        if (!flags.wait) {
+            if (!json) {
+                this.log(`Build started: ${jobId}`);
+                this.log(`Poll with: faces voiceprint:build-status ${jobId}`);
+            }
+            return started;
+        }
+        if (!json)
+            process.stderr.write(`Building voice map for ${args.self_alias} (job ${jobId})...\n`);
+        let final;
+        let lastStage = '';
+        try {
+            final = await pollVoiceprintJob(client, '/v1/voiceprint/builds', jobId, {
+                timeoutMs: 3_600_000, // a large corpus fans lenses over many chunks — can take a while
+                onPoll: (data) => {
+                    if (json)
+                        return;
+                    const p = data.progress;
+                    const key = p ? `${p.stage}:${p.done}/${p.total}` : String(data.status);
+                    if (key !== lastStage) {
+                        lastStage = key;
+                        process.stderr.write(`  ${p?.stage ?? data.status}${p?.total ? ` ${p.done}/${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));
+        }
+        if (final.status === 'failed')
+            this.error(`Build failed: ${jobFailureMessage(final.error)}`);
+        if (json)
+            return final;
+        printBuildReport(this, jobId, final);
+        return final;
+    }
+}
+/** Shared build-report formatter (used by voiceprint:build --wait and voiceprint:build-status). */
+export function printBuildReport(cmd, jobId, data) {
+    const report = (data.report ?? {});
+    cmd.log(`job:                ${jobId}`);
+    cmd.log(`status:             ${data.status}`);
+    if (data.voiceprint_face_id)
+        cmd.log(`voiceprint_face_id: ${data.voiceprint_face_id}`);
+    if (data.version_id)
+        cmd.log(`version_id:         ${data.version_id}`);
+    if (report.voice_map_chars !== undefined)
+        cmd.log(`voice_map_chars:    ${report.voice_map_chars}`);
+    const baseline = report.baseline;
+    if (baseline) {
+        if (baseline.skipped) {
+            cmd.log(`baseline:           skipped (${baseline.skipped})`);
+        }
+        else {
+            cmd.log(`baseline VCI:       ${baseline.VCI ?? 'n/a'}`);
+            cmd.log(`baseline VFI:       ${baseline.VFI ?? 'n/a'}`);
+            if (baseline.delta_ratio !== undefined)
+                cmd.log(`baseline delta:     ${baseline.delta_ratio}`);
+        }
+    }
+}

package/dist/commands/voiceprint/get.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintGet 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: {
+        job_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/get.js

@@ -0,0 +1,47 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class VoiceprintGet extends BaseCommand {
+    static description = 'Get the status/result of a voiceprint scoring job started with voiceprint:score --no-wait';
+    static examples = ['<%= config.bin %> <%= command.id %> 4e13bf03-fbc1-4ad0-92ae-16984e2f9a1d'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        job_id: Args.string({ description: 'Scoring job id (from voiceprint:score --no-wait)', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintGet);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.get(`/v1/voiceprint/score/${encodeURIComponent(args.job_id)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        const status = String(data.status ?? 'unknown');
+        this.log(`job:    ${args.job_id}`);
+        this.log(`status: ${status}`);
+        const progress = data.progress;
+        if (progress && typeof progress.pairs_done === 'number') {
+            this.log(`pairs:  ${progress.pairs_done}/${progress.pairs_total ?? '?'}`);
+        }
+        if (status === 'done') {
+            const report = (data.report ?? {});
+            this.log(`VCI:     ${report.VCI ?? 'n/a'}   (voice closeness — 100 = writes indistinguishably from the person)`);
+            this.log(`VFI:     ${report.VFI ?? 'n/a'}   (voice fidelity — how much of their voice is captured vs a generic baseline)`);
+            if (report.n_pairs !== undefined)
+                this.log(`n_pairs: ${report.n_pairs}`);
+        }
+        else if (status === 'failed') {
+            this.log(`error:  ${data.error ?? 'unknown error'}`);
+        }
+        else {
+            this.log(`(still running — poll again with: faces voiceprint:get ${args.job_id})`);
+        }
+        return data;
+    }
+}

package/dist/commands/voiceprint/refine-status.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintRefineStatus 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: {
+        job_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/refine-status.js

@@ -0,0 +1,43 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { jobFailureMessage } from '../../voiceprint.js';
+import { printRefineReport } from './refine.js';
+export default class VoiceprintRefineStatus extends BaseCommand {
+    static description = 'Get the status/result of a voiceprint refine job (from voiceprint:refine without --wait)';
+    static examples = ['<%= config.bin %> <%= command.id %> 4e13bf03-fbc1-4ad0-92ae-16984e2f9a1d'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        job_id: Args.string({ description: 'Refine job id', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintRefineStatus);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.get(`/v1/voiceprint/refines/${encodeURIComponent(args.job_id)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        const status = String(data.status ?? 'unknown');
+        if (status === 'failed') {
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: failed`);
+            this.log(`error:  ${jobFailureMessage(data.error)}`);
+        }
+        else if (status === 'done') {
+            printRefineReport(this, args.job_id, (data.report ?? {}));
+        }
+        else {
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: ${status}`);
+            this.log(`(still running — poll again with: faces voiceprint:refine-status ${args.job_id})`);
+        }
+        return data;
+    }
+}

package/dist/commands/voiceprint/refine.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintRefine extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        temperature: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'n-samples': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: 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: {
+        self_alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}
+/** Shared refine-report formatter (used by voiceprint:refine --wait and voiceprint:refine-status). */
+export declare function printRefineReport(cmd: {
+    log: (m: string) => void;
+}, jobId: string, report: Record<string, unknown>): void;

package/dist/commands/voiceprint/refine.js

@@ -0,0 +1,88 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { pollVoiceprintJob, jobFailureMessage } from '../../voiceprint.js';
+export default class VoiceprintRefine extends BaseCommand {
+    static description = "Tune the active version's post-processing recipe and promote it only if it beats the current one. Requires an existing build with a holdout ≥ 20. Undo with voiceprint:revert.";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --wait',
+        '<%= config.bin %> <%= command.id %> alice --temperature 0.4 --n-samples 6 --wait',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        model: Flags.string({ description: "Model used to forge candidate drafts (default: the active version's build model)" }),
+        temperature: Flags.string({ description: 'Sampling temperature for candidate drafts (default: 0.4)' }),
+        'n-samples': Flags.integer({ description: 'Drafts forged per holdout pair (default: 6)' }),
+        'oauth-only': Flags.boolean({ description: 'Only run on a free (OAuth) route; never fall back to billed inference', default: false }),
+        wait: Flags.boolean({ description: 'Block and poll until refine finishes (default: print the job_id and return)', default: false }),
+    };
+    static args = {
+        self_alias: Args.string({ description: 'Self face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintRefine);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        const payload = { self_face: args.self_alias };
+        if (flags.model)
+            payload.model = flags.model;
+        if (flags.temperature !== undefined)
+            payload.temperature = Number.parseFloat(flags.temperature);
+        if (flags['n-samples'] !== undefined)
+            payload.n_samples = flags['n-samples'];
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
+        let started;
+        try {
+            started = (await client.post('/v1/voiceprint/refines', { body: payload }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        const jobId = String(started.job_id ?? '');
+        if (!jobId)
+            this.error('Server did not return a job_id');
+        if (!flags.wait) {
+            if (!json) {
+                this.log(`Refine started: ${jobId}`);
+                this.log(`Poll with: faces voiceprint:refine-status ${jobId}`);
+            }
+            return started;
+        }
+        if (!json)
+            process.stderr.write(`Refining ${args.self_alias}'s recipe (job ${jobId})...\n`);
+        let final;
+        try {
+            final = await pollVoiceprintJob(client, '/v1/voiceprint/refines', jobId, { timeoutMs: 3_600_000 });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            this.error(err instanceof Error ? err.message : String(err));
+        }
+        if (final.status === 'failed')
+            this.error(`Refine failed: ${jobFailureMessage(final.error)}`);
+        if (json)
+            return final;
+        printRefineReport(this, jobId, (final.report ?? {}));
+        return final;
+    }
+}
+/** Shared refine-report formatter (used by voiceprint:refine --wait and voiceprint:refine-status). */
+export function printRefineReport(cmd, jobId, report) {
+    const decision = String(report.decision ?? 'unknown');
+    const baseline = (report.baseline ?? {});
+    cmd.log(`job:      ${jobId}`);
+    cmd.log(`decision: ${decision}${decision === 'promote' ? ' (a better recipe was promoted to a new active version)' : decision === 'keep' ? ' (nothing beat the current recipe; unchanged)' : ''}`);
+    if (baseline.VCI !== undefined || baseline.VFI !== undefined) {
+        cmd.log(`baseline: VCI ${baseline.VCI ?? 'n/a'} / VFI ${baseline.VFI ?? 'n/a'}`);
+    }
+    if (report.version_id)
+        cmd.log(`version:  ${report.version_id}`);
+    if (Array.isArray(report.promoted_recipe))
+        cmd.log(`recipe:   ${JSON.stringify(report.promoted_recipe)}`);
+    if (decision === 'promote')
+        cmd.log(`\nUndo with: faces voiceprint:revert <self_alias>`);
+}

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

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintRevert 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: {
+        self_alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/revert.js

@@ -0,0 +1,36 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class VoiceprintRevert extends BaseCommand {
+    static description = "Revert a self face's voice map to its prior version (one-deep undo; re-running toggles back). Only changes which stored recipe/baseline is active — the map text is frozen.";
+    static examples = ['<%= config.bin %> <%= command.id %> alice'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        self_alias: Args.string({ description: 'Self face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintRevert);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.post('/v1/voiceprint/versions/revert', { body: { self_face: args.self_alias } }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 409)
+                    this.error(`Nothing to revert to — ${args.self_alias} has only one voice-map version.`);
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        this.log(`self_face:    ${data.self_face ?? args.self_alias}`);
+        this.log(`from_version: ${data.from_version ?? '?'}`);
+        this.log(`to_version:   ${data.to_version ?? '?'}`);
+        this.log(`VCI/VFI:      ${data.baseline_vci ?? 'n/a'} / ${data.baseline_vfi ?? 'n/a'}`);
+        if (data.recipe !== undefined)
+            this.log(`recipe:       ${JSON.stringify(data.recipe)}`);
+        return data;
+    }
+}

package/dist/commands/voiceprint/score-status.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintScoreStatus 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: {
+        job_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}