faces-cli 1.7.9 → 1.7.14

package/dist/commands/face/neighbors.js

@@ -12,8 +12,8 @@ export default class FaceNeighbors extends BaseCommand {
             max: 20,
         }),
         component: Flags.string({
-            description: 'Centroid component to rank on (beta, delta, epsilon are the principal components of a face; face is their composite)',
-            options: ['face', 'beta', 'delta', 'epsilon'],
+            description: 'What to rank on: `face` for overall similarity, or a component position such as 1. ' +
+                'Which positions are comparable varies; the API names them if you pick a wrong one.',
             default: 'face',
         }),
         direction: Flags.string({
@@ -33,19 +33,35 @@ export default class FaceNeighbors extends BaseCommand {
             component: flags.component,
             direction: flags.direction,
         };
+        // Positions are open-ended (they follow the component-counts order, which can
+        // grow), so validate the shape only and let the API say which are comparable
+        // — it knows, and the answer differs per face.
+        if (flags.component !== 'face' && !/^\d+$/.test(flags.component)) {
+            this.error(`--component must be 'face' or a component position such as 1 (got '${flags.component}').`);
+        }
         let data;
         try {
             data = await client.get(`/v1/faces/${args.face_id}/neighbors`, { params });
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                // A face with nothing at that position is an empty answer, not a failure:
+                // it mirrors the null at the same index in face:diff. Say so plainly and
+                // exit clean, so a caller can tell "nothing here" from "something broke".
+                if (err.statusCode === 422 && /has no (data for component position|centroid)/.test(err.message)) {
+                    if (!this.jsonEnabled())
+                        this.log(err.message);
+                    return { face: args.face_id, component: flags.component, direction: flags.direction, neighbors: [], reason: err.message };
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
         if (!this.jsonEnabled()) {
             const res = data;
             const label = res.direction === 'nearest' ? 'Nearest' : 'Most dissimilar';
-            this.log(`${label} neighbors to ${res.face} (by ${res.component}):`);
+            const by = res.component === 'face' ? 'overall similarity' : `component ${res.component}`;
+            this.log(`${label} neighbors to ${res.face} (by ${by}):`);
             this.log('');
             if (res.neighbors.length === 0) {
                 this.log('  (none)');

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

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base.js';
+export default class FacePublish extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/face/publish.js

@@ -0,0 +1,41 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FacePublish extends BaseCommand {
+    static description = 'Publish a face so EVERY account can chat with it. This is a global override: while it is on, ' +
+        'everyone can reach the face regardless of who it is shared with. You still pay only to compile it; ' +
+        'whoever chats pays for their own inference.';
+    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(FacePublish);
+        const client = this.makeClient(flags);
+        if (!flags.yes && !this.jsonEnabled()) {
+            this.error(`This makes '${args.alias}' chattable by every account on the platform. Re-run with --yes to confirm.`);
+        }
+        let data;
+        try {
+            data = (await client.patch(`/v1/faces/${encodeURIComponent(args.alias)}/publish`, {
+                body: { published: true },
+            }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        this.log(`'${args.alias}' is published.`);
+        if (data.handle)
+            this.log(`Anyone can chat it as: ${data.handle}@<model>`);
+        this.log(`Unpublish with: faces face:unpublish ${args.alias}`);
+        return data;
+    }
+}

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

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceShare extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        list: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        add: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        with: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        none: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+    private readList;
+    private report;
+}

package/dist/commands/face/share.js

@@ -0,0 +1,106 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FaceShare extends BaseCommand {
+    static description = 'Share a face so named accounts can chat with it. Sharing grants chat and nothing else: no reading its ' +
+        'documents, no compiling, no re-sharing, and never its profile addendum. --add keeps the current list; ' +
+        '--with replaces it.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --list',
+        '<%= config.bin %> <%= command.id %> alice --add dana',
+        '<%= config.bin %> <%= command.id %> alice --with dana --with sam@example.com',
+        '<%= config.bin %> <%= command.id %> alice --none --yes',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        list: Flags.boolean({ description: 'Show who the face is shared with, and change nothing', default: false }),
+        add: Flags.string({
+            description: 'Add an account, keeping everyone already on the list — username or email (repeatable)',
+            multiple: true,
+            exclusive: ['with', 'none'],
+        }),
+        with: Flags.string({
+            description: 'Set the list to exactly these accounts, dropping anyone else (repeatable)',
+            multiple: true,
+            exclusive: ['add', 'none'],
+        }),
+        none: Flags.boolean({ description: 'Revoke everyone', default: false, exclusive: ['add', 'with'] }),
+        yes: Flags.boolean({ description: 'Skip the confirmation shown when someone would lose access', default: false }),
+    };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FaceShare);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        const current = await this.readList(client, args.alias);
+        if (flags.list) {
+            if (!json)
+                this.report(args.alias, current);
+            return { alias: args.alias, shared_with: current };
+        }
+        if (!flags.add && !flags.with && !flags.none) {
+            this.error('Provide --list, --add <account>, --with <account> (replaces), or --none.');
+        }
+        // The endpoint replaces rather than appends, so every form sends a full list.
+        // --add exists because "add one person" is the common intent and expressing it
+        // as a replace is the easiest way to revoke everyone else by accident.
+        let next;
+        if (flags.none)
+            next = [];
+        else if (flags.add)
+            next = [...new Set([...current, ...flags.add])];
+        else
+            next = [...new Set(flags.with)];
+        // Compare case-insensitively: stored values are canonical usernames, and a
+        // caller may well retype one with different capitalisation.
+        const lower = new Set(next.map((u) => u.toLowerCase()));
+        const removed = current.filter((u) => !lower.has(u.toLowerCase()));
+        if (removed.length > 0 && !flags.yes && !json) {
+            this.error(`This removes ${removed.length} account(s) from '${args.alias}': ${removed.join(', ')}.\n` +
+                'Revocation is immediate. Re-run with --yes, or use --add to keep them.');
+        }
+        let data;
+        try {
+            data = (await client.patch(`/v1/faces/${encodeURIComponent(args.alias)}/share`, {
+                body: { shared_with: next },
+            }));
+        }
+        catch (err) {
+            // Unknown accounts are rejected atomically, so the previous list survives
+            // and the caller can fix the name and re-run.
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (json)
+            return data;
+        if (removed.length > 0)
+            this.log(`Revoked: ${removed.join(', ')}`);
+        this.report(args.alias, data.shared_with ?? [], data.handle);
+        return data;
+    }
+    async readList(client, alias) {
+        try {
+            const face = (await client.get(`/v1/faces/${encodeURIComponent(alias)}`));
+            return face.shared_with ?? [];
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+    }
+    report(alias, users, handle) {
+        if (users.length === 0) {
+            this.log(`'${alias}' is not shared with anyone.`);
+            return;
+        }
+        this.log(`'${alias}' is shared with ${users.length} account(s):`);
+        for (const u of users)
+            this.log(`  ${u}`);
+        if (handle)
+            this.log(`\nThey chat with it as: ${handle}@<model>`);
+    }
+}

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

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceUnpublish extends BaseCommand {
+    static description: 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/face/unpublish.js

@@ -0,0 +1,30 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FaceUnpublish extends BaseCommand {
+    static description = 'Stop publishing a face. Anyone it is individually shared with keeps their access — publishing is an ' +
+        'override on top of sharing, not a replacement for it.';
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        alias: Args.string({ description: 'Face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FaceUnpublish);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.patch(`/v1/faces/${encodeURIComponent(args.alias)}/publish`, {
+                body: { published: false },
+            }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        this.log(`'${args.alias}' is no longer published.`);
+        return data;
+    }
+}

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

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceUnshare extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        from: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/face/unshare.js

@@ -0,0 +1,67 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FaceUnshare extends BaseCommand {
+    static description = 'Revoke access to a shared face. Takes effect immediately — there is no grace period.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --from dana --yes',
+        '<%= config.bin %> <%= command.id %> alice --all --yes',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        from: Flags.string({ description: 'Account to revoke (repeatable)', multiple: true, exclusive: ['all'] }),
+        all: Flags.boolean({ description: 'Revoke everyone', default: false, exclusive: ['from'] }),
+        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(FaceUnshare);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        if (!flags.from && !flags.all)
+            this.error('Provide --from <account> (repeatable) or --all.');
+        let current;
+        try {
+            const face = (await client.get(`/v1/faces/${encodeURIComponent(args.alias)}`));
+            current = face.shared_with ?? [];
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (current.length === 0) {
+            if (!json)
+                this.log(`'${args.alias}' is not shared with anyone.`);
+            return { alias: args.alias, shared_with: [] };
+        }
+        const drop = new Set((flags.from ?? []).map((u) => u.toLowerCase()));
+        const next = flags.all ? [] : current.filter((u) => !drop.has(u.toLowerCase()));
+        const removed = current.filter((u) => !next.includes(u));
+        if (removed.length === 0) {
+            // The list stores canonical usernames, so an email that granted access will
+            // not match here. Say that rather than reporting a bare "not found".
+            this.error(`None of those accounts are on '${args.alias}'. Currently shared with: ${current.join(', ')}.\n` +
+                'The list stores usernames, so revoke by username even if you shared by email.');
+        }
+        if (!flags.yes && !json) {
+            this.error(`This revokes ${removed.join(', ')} from '${args.alias}', immediately. Re-run with --yes.`);
+        }
+        let data;
+        try {
+            data = await client.patch(`/v1/faces/${encodeURIComponent(args.alias)}/share`, { body: { shared_with: next } });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (json)
+            return data;
+        this.log(`Revoked: ${removed.join(', ')}`);
+        this.log(next.length > 0 ? `Still shared with: ${next.join(', ')}` : `'${args.alias}' is no longer shared with anyone.`);
+        return data;
+    }
+}

package/dist/poll.d.ts

@@ -9,12 +9,7 @@ export interface PollProgress {
     prepare_status: string | null;
     chunks_total: number | null;
     chunks_completed: number | null;
-    current_counts: {
-        epsilon: number;
-        beta: number;
-        delta: number;
-        alpha: number;
-    } | null;
+    current_counts: number[] | null;
 }
 export interface PollOptions {
     intervalMs?: number;

package/dist/utils.d.ts

@@ -28,3 +28,37 @@ export declare function renameFaceFields(face: Record<string, unknown>): Record<
  *   - OpenAI Chat Completions: { choices: [{delta: {content}}] }
  */
 export declare function extractStreamDelta(parsed: Record<string, unknown>): string;
+/**
+ * OpenAI's Responses API rejects an output cap below this. Checked client-side
+ * because the round trip tells the user nothing they could not be told sooner.
+ */
+export declare const MIN_MAX_OUTPUT_TOKENS = 16;
+/**
+ * True when a provider 400 is the `max_tokens` → `max_completion_tokens` rename
+ * that newer OpenAI models require.
+ *
+ * The backend forwards the provider's rejection verbatim rather than rewriting
+ * the parameter, so the client is what has to adapt. Matched on the message
+ * because the set of models that require it grows, and a model list here would
+ * be stale the day a new one ships.
+ */
+export declare function isMaxTokensRenameError(message: string): boolean;
+/**
+ * Shared help text for `--medium`. It declares what the artefact IS, not how it
+ * should sound — the persona decides that. Values are not validated here:
+ * synonyms fold server-side, the set grows, and compile's own 422 names the
+ * valid ones better than a stale local list could.
+ */
+export declare const MEDIUM_FLAG_DESCRIPTION: string;
+/**
+ * Warn when the server dropped request parameters before forwarding.
+ *
+ * The OAuth/Codex route strips params Codex rejects (`max_output_tokens`,
+ * `temperature`), so the same flag is honoured on the paid path and ignored on
+ * the free one — a difference the caller cannot see and did not choose. The
+ * server announces it in `x-faces-dropped-params`; without that header a client
+ * could only guess, since which route ran is decided per request.
+ */
+export declare function warnDroppedParams(headers: Record<string, string>, flagFor: Record<string, string>): void;
+/** Maps the server's parameter names back to the flags a user actually typed. */
+export declare const CHAT_PARAM_FLAGS: Record<string, string>;

package/dist/utils.js

@@ -71,3 +71,60 @@ export function extractStreamDelta(parsed) {
     const choices = parsed.choices;
     return String(choices?.[0]?.delta?.content ?? '');
 }
+/**
+ * OpenAI's Responses API rejects an output cap below this. Checked client-side
+ * because the round trip tells the user nothing they could not be told sooner.
+ */
+export const MIN_MAX_OUTPUT_TOKENS = 16;
+/**
+ * True when a provider 400 is the `max_tokens` → `max_completion_tokens` rename
+ * that newer OpenAI models require.
+ *
+ * The backend forwards the provider's rejection verbatim rather than rewriting
+ * the parameter, so the client is what has to adapt. Matched on the message
+ * because the set of models that require it grows, and a model list here would
+ * be stale the day a new one ships.
+ */
+export function isMaxTokensRenameError(message) {
+    return /max_completion_tokens/.test(message) && /max_tokens/.test(message);
+}
+/**
+ * Shared help text for `--medium`. It declares what the artefact IS, not how it
+ * should sound — the persona decides that. Values are not validated here:
+ * synonyms fold server-side, the set grows, and compile's own 422 names the
+ * valid ones better than a stale local list could.
+ */
+export const MEDIUM_FLAG_DESCRIPTION = 'What sort of writing this is — e.g. email, text message, social post, essay, academic paper, ' +
+    'blog post, legal document, thread reply, conversation (covers speech: transcripts, interviews, ' +
+    'calls). Common synonyms fold automatically. Omit it if you do not know: a wrong declaration is ' +
+    'worse than none, because a declaration is trusted and an absence is not.';
+/**
+ * Warn when the server dropped request parameters before forwarding.
+ *
+ * The OAuth/Codex route strips params Codex rejects (`max_output_tokens`,
+ * `temperature`), so the same flag is honoured on the paid path and ignored on
+ * the free one — a difference the caller cannot see and did not choose. The
+ * server announces it in `x-faces-dropped-params`; without that header a client
+ * could only guess, since which route ran is decided per request.
+ */
+export function warnDroppedParams(headers, flagFor) {
+    const raw = headers['x-faces-dropped-params'];
+    if (!raw)
+        return;
+    const flags = raw
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean)
+        .map((p) => flagFor[p] ?? `--${p.replaceAll('_', '-')}`);
+    if (flags.length === 0)
+        return;
+    process.stderr.write(`Note: ${flags.join(' and ')} had no effect — this request ran on your linked ChatGPT account, ` +
+        'which does not accept them. Use --no-oauth-only to run on the paid API instead.\n');
+}
+/** Maps the server's parameter names back to the flags a user actually typed. */
+export const CHAT_PARAM_FLAGS = {
+    max_output_tokens: '--max-tokens',
+    max_tokens: '--max-tokens',
+    max_completion_tokens: '--max-tokens',
+    temperature: '--temperature',
+};