faces-cli 1.5.14 → 1.5.15

package/dist/commands/catalog/backup.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../base.js';
+export default class CatalogBackup 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>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/catalog/backup.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { flattenBasicFacts } from '../../utils.js';
+export default class CatalogBackup extends BaseCommand {
+    static description = 'Snapshot all faces and source material for migration';
+    static flags = {
+        ...BaseCommand.baseFlags,
+    };
+    async run() {
+        const { flags } = await this.parse(CatalogBackup);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        // Fetch all faces
+        let faces;
+        try {
+            const resp = await client.get('/v1/faces');
+            faces = (resp.data ?? resp);
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (!json)
+            process.stderr.write(`Found ${faces.length} face(s)\n`);
+        const backupFaces = [];
+        for (const face of faces) {
+            const alias = face.alias;
+            if (!json)
+                process.stderr.write(`  ${alias}: `);
+            const entry = {
+                alias,
+                name: face.name,
+                basic_facts: face.basic_facts ? flattenBasicFacts(face.basic_facts) : null,
+                default_model: face.default_model ?? null,
+                default_tools: face.default_tools ?? [],
+                formula: face.formula ?? null,
+                documents: [],
+                threads: [],
+            };
+            // Fetch documents
+            try {
+                const docs = await client.get('/v1/compile/documents', { params: { alias } });
+                for (const doc of docs) {
+                    entry.documents.push({
+                        label: doc.label ?? null,
+                        content: doc.content,
+                        perspective: doc.perspective ?? null,
+                    });
+                }
+            }
+            catch {
+                // face may have no documents
+            }
+            // Fetch threads
+            try {
+                const threads = await client.get('/v1/compile/threads', { params: { alias } });
+                for (const thread of threads) {
+                    const threadId = thread.thread_id;
+                    try {
+                        const full = await client.get(`/v1/compile/threads/${threadId}`);
+                        const messages = full.messages ?? [];
+                        entry.threads.push({
+                            label: thread.label ?? null,
+                            messages,
+                        });
+                    }
+                    catch {
+                        // skip threads we can't fetch
+                    }
+                }
+            }
+            catch {
+                // face may have no threads
+            }
+            if (!json)
+                process.stderr.write(`${entry.documents.length} doc(s), ${entry.threads.length} thread(s)\n`);
+            backupFaces.push(entry);
+        }
+        const backup = {
+            version: 1,
+            created_at: new Date().toISOString(),
+            faces: backupFaces,
+        };
+        const backupDir = path.join(os.homedir(), '.faces', 'backups');
+        fs.mkdirSync(backupDir, { recursive: true });
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const filePath = path.join(backupDir, `${timestamp}.json`);
+        fs.writeFileSync(filePath, JSON.stringify(backup, null, 2));
+        const totalDocs = backupFaces.reduce((n, f) => n + f.documents.length, 0);
+        const totalThreads = backupFaces.reduce((n, f) => n + f.threads.length, 0);
+        if (!json) {
+            this.log(`\nBackup saved: ${filePath}`);
+            this.log(`  ${backupFaces.length} face(s), ${totalDocs} document(s), ${totalThreads} thread(s)`);
+        }
+        return { path: filePath, faces: backupFaces.length, documents: totalDocs, threads: totalThreads };
+    }
+}

package/dist/commands/catalog/restore.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../base.js';
+export default class CatalogRestore extends BaseCommand {
+    static description: string;
+    static flags: {
+        compile: 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: {
+        file: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+    private createFace;
+    private findLatestBackup;
+}

package/dist/commands/catalog/restore.js

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { CatalogService } from '../../catalog.js';
+export default class CatalogRestore extends BaseCommand {
+    static description = 'Restore faces and source material from a backup snapshot';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        compile: Flags.boolean({ description: 'Run compile:all after restoring', default: false }),
+    };
+    static args = {
+        file: Args.string({ description: 'Backup file path (default: most recent in ~/.faces/backups/)' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(CatalogRestore);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        const filePath = args.file ?? this.findLatestBackup();
+        if (!fs.existsSync(filePath))
+            this.error(`Backup file not found: ${filePath}`);
+        const backup = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (backup.version !== 1)
+            this.error(`Unsupported backup version: ${backup.version}`);
+        if (!json) {
+            this.log(`Restoring from: ${filePath}`);
+            this.log(`  Created: ${backup.created_at}`);
+            this.log(`  Faces: ${backup.faces.length}\n`);
+        }
+        const catalog = new CatalogService();
+        let facesCreated = 0;
+        let facesSkipped = 0;
+        let docsUploaded = 0;
+        let threadsUploaded = 0;
+        for (const face of backup.faces) {
+            if (!json)
+                process.stderr.write(`${face.alias}: `);
+            // Create face
+            const created = await this.createFace(client, face, json);
+            if (!created) {
+                facesSkipped++;
+                if (!json)
+                    process.stderr.write('exists, skipping\n');
+                continue;
+            }
+            facesCreated++;
+            // Write to local catalog
+            try {
+                catalog.writeFace({ alias: face.alias, name: face.name, basic_facts: face.basic_facts });
+            }
+            catch { /* non-fatal */ }
+            // Upload documents
+            for (const doc of face.documents) {
+                try {
+                    const payload = { alias: face.alias, content: doc.content };
+                    if (doc.label)
+                        payload.label = doc.label;
+                    if (doc.perspective)
+                        payload.perspective = doc.perspective;
+                    await client.post('/v1/compile/documents', { body: payload });
+                    docsUploaded++;
+                }
+                catch (err) {
+                    const msg = err instanceof FacesAPIError ? `${err.statusCode}: ${err.message}` : String(err);
+                    if (!json)
+                        process.stderr.write(`\n    warn: doc upload failed: ${msg}\n    `);
+                }
+            }
+            // Upload threads — create thread then PATCH messages in bulk
+            for (const thread of face.threads) {
+                try {
+                    const createPayload = { alias: face.alias };
+                    if (thread.label)
+                        createPayload.label = thread.label;
+                    const created = await client.post('/v1/compile/threads', { body: createPayload });
+                    const threadId = created.thread_id;
+                    // Overwrite the auto-generated messages with the backup messages
+                    if (thread.messages.length > 0) {
+                        await client.patch(`/v1/compile/threads/${threadId}/messages`, {
+                            body: { messages: thread.messages },
+                        });
+                    }
+                    threadsUploaded++;
+                }
+                catch (err) {
+                    const msg = err instanceof FacesAPIError ? `${err.statusCode}: ${err.message}` : String(err);
+                    if (!json)
+                        process.stderr.write(`\n    warn: thread upload failed: ${msg}\n    `);
+                }
+            }
+            if (!json)
+                process.stderr.write(`${face.documents.length} doc(s), ${face.threads.length} thread(s)\n`);
+        }
+        if (!json) {
+            this.log(`\nRestore complete:`);
+            this.log(`  Faces created: ${facesCreated}, skipped: ${facesSkipped}`);
+            this.log(`  Documents uploaded: ${docsUploaded}`);
+            this.log(`  Threads uploaded: ${threadsUploaded}`);
+        }
+        if (flags.compile) {
+            if (!json)
+                this.log('\nRunning compile:all...\n');
+            await this.config.runCommand('compile:all', json ? ['--json'] : []);
+        }
+        return { faces_created: facesCreated, faces_skipped: facesSkipped, documents: docsUploaded, threads: threadsUploaded };
+    }
+    async createFace(client, face, _json) {
+        const payload = { name: face.name, alias: face.alias };
+        if (face.formula) {
+            payload.formula = face.formula;
+            if (face.default_model)
+                payload.default_model = face.default_model;
+        }
+        else {
+            if (face.basic_facts && Object.keys(face.basic_facts).length > 0)
+                payload.basic_facts = face.basic_facts;
+            if (face.default_tools && face.default_tools.length > 0)
+                payload.default_tools = face.default_tools;
+            if (face.default_model)
+                payload.default_model = face.default_model;
+        }
+        try {
+            await client.post('/v1/faces', { body: payload });
+            return true;
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError && err.statusCode === 400) {
+                // likely "already have a face with alias"
+                return false;
+            }
+            throw err;
+        }
+    }
+    findLatestBackup() {
+        const backupDir = path.join(os.homedir(), '.faces', 'backups');
+        if (!fs.existsSync(backupDir))
+            this.error('No backups found in ~/.faces/backups/');
+        const files = fs.readdirSync(backupDir)
+            .filter(f => f.endsWith('.json'))
+            .sort();
+        if (files.length === 0)
+            this.error('No backups found in ~/.faces/backups/');
+        return path.join(backupDir, files[files.length - 1]);
+    }
+}

package/dist/commands/compile/all.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base.js';
+export default class CompileAll extends BaseCommand {
+    static description: string;
+    static flags: {
+        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>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/compile/all.js

@@ -0,0 +1,116 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { pollCompileProgress } from '../../poll.js';
+export default class CompileAll extends BaseCommand {
+    static description = 'Compile all uncompiled documents and threads across all faces';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        timeout: Flags.integer({ description: 'Per-item compile timeout in seconds (default: 600)', default: 600 }),
+    };
+    async run() {
+        const { flags } = await this.parse(CompileAll);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        // Fetch all faces
+        let faces;
+        try {
+            const resp = await client.get('/v1/faces');
+            faces = (resp.data ?? resp);
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        // Collect uncompiled items
+        const items = [];
+        for (const face of faces) {
+            const alias = face.alias;
+            if (face.formula)
+                continue; // composite faces have no source material
+            // Check documents
+            try {
+                const docs = await client.get('/v1/compile/documents', { params: { alias } });
+                for (const doc of docs) {
+                    const status = doc.prepare_status;
+                    if (status !== 'synced' && status !== 'ready') {
+                        items.push({
+                            type: 'document',
+                            id: doc.document_id,
+                            alias,
+                            label: doc.label ?? null,
+                        });
+                    }
+                }
+            }
+            catch { /* no docs */ }
+            // Check threads
+            try {
+                const threads = await client.get('/v1/compile/threads', { params: { alias } });
+                for (const thread of threads) {
+                    const status = thread.prepare_status;
+                    if (status !== 'synced' && status !== 'ready') {
+                        items.push({
+                            type: 'thread',
+                            id: thread.thread_id,
+                            alias,
+                            label: thread.label ?? null,
+                        });
+                    }
+                }
+            }
+            catch { /* no threads */ }
+        }
+        if (items.length === 0) {
+            if (!json)
+                this.log('Nothing to compile — all documents and threads are up to date.');
+            return { compiled: 0, failed: 0, items: [] };
+        }
+        if (!json)
+            this.log(`Found ${items.length} item(s) to compile\n`);
+        let compiled = 0;
+        let failed = 0;
+        const results = [];
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            const tag = `[${i + 1}/${items.length}]`;
+            const name = item.label ?? item.id.slice(0, 8);
+            if (!json)
+                process.stderr.write(`${tag} ${item.type} "${name}" (${item.alias})... `);
+            const makeEndpoint = item.type === 'document'
+                ? `/v1/compile/documents/${item.id}/make`
+                : `/v1/compile/threads/${item.id}/make`;
+            const pollEndpoint = item.type === 'document'
+                ? `/v1/compile/documents/${item.id}`
+                : `/v1/compile/threads/${item.id}`;
+            try {
+                await client.post(makeEndpoint);
+                await pollCompileProgress(client, item.id, {
+                    timeoutMs: flags.timeout * 1000,
+                    endpoint: pollEndpoint,
+                    onProgress: (p) => {
+                        if (!json) {
+                            process.stderr.write(`[${p.chunks_completed ?? '?'}/${p.chunks_total ?? '?'}] `);
+                        }
+                    },
+                });
+                compiled++;
+                results.push({ ...item, status: 'compiled' });
+                if (!json)
+                    process.stderr.write('done\n');
+            }
+            catch (err) {
+                failed++;
+                const msg = err instanceof FacesAPIError ? `${err.statusCode}: ${err.message}` : err instanceof Error ? err.message : String(err);
+                results.push({ ...item, status: `failed: ${msg}` });
+                if (!json)
+                    process.stderr.write(`failed: ${msg}\n`);
+            }
+        }
+        if (!json) {
+            this.log(`\nCompile complete: ${compiled} succeeded, ${failed} failed`);
+        }
+        return { compiled, failed, items: results };
+    }
+}