faces-cli 1.7.8 → 1.7.9

package/dist/commands/compile/doc/index.d.ts

@@ -1,10 +1,11 @@
 import { BaseCommand } from '../../../base.js';
 export default class CompileDoc extends BaseCommand {
     static description: string;
+    static examples: string[];
     static flags: {
         label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         content: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        file: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         perspective: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
@@ -16,4 +17,10 @@ export default class CompileDoc extends BaseCommand {
         face_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
+    /**
+     * `documents` is always present and always in input order. For a single
+     * source the compiled/started body is also spread at the top level, so
+     * callers that already read `.document_id` keep working.
+     */
+    private shape;
 }

package/dist/commands/compile/doc/index.js

@@ -1,21 +1,28 @@
 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';
 import { pollCompileProgress } from '../../../poll.js';
 export default class CompileDoc extends BaseCommand {
-    static description = 'Compile a document into a face (create → make in one step)';
+    static description = 'Compile one or more documents into a face (create → make in one step). ' +
+        'Repeat --file to submit several documents in a single command; each file becomes its own ' +
+        'document rather than being concatenated.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --file notes.txt',
+        '<%= config.bin %> <%= command.id %> alice --file a.txt --file b.txt --file c.txt --no-wait --json',
+    ];
     static flags = {
         ...BaseCommand.baseFlags,
-        label: Flags.string({ description: 'Document label/title' }),
-        content: Flags.string({ description: 'Inline text content' }),
-        file: Flags.string({ description: 'Read content from file' }),
+        label: Flags.string({ description: 'Document label/title (single document only; with several files each is labelled by its filename)' }),
+        content: Flags.string({ description: 'Inline text content', exclusive: ['file'] }),
+        file: Flags.string({ description: 'Read content from file (repeatable — each file becomes its own document)', multiple: true }),
         perspective: Flags.string({
             description: 'Perspective',
             options: ['first-person', 'third-person'],
             default: 'first-person',
         }),
-        timeout: Flags.integer({ description: 'Compile timeout in seconds (default: 600)', default: 600 }),
+        timeout: Flags.integer({ description: 'Compile timeout in seconds, per document (default: 600)', default: 600 }),
         'no-wait': Flags.boolean({
             description: 'Create and trigger compilation, then return immediately without polling.',
             default: false,
@@ -28,79 +35,181 @@ export default class CompileDoc extends BaseCommand {
         const { args, flags } = await this.parse(CompileDoc);
         const client = this.makeClient(flags);
         const json = this.jsonEnabled();
-        // Resolve content
-        let content = flags.content;
-        if (flags.file) {
-            if (!fs.existsSync(flags.file))
-                this.error(`File not found: ${flags.file}`);
-            content = fs.readFileSync(flags.file, 'utf8');
-        }
-        if (!content)
+        const files = flags.file ?? [];
+        if (files.length === 0 && !flags.content)
             this.error('Provide --content or --file.');
-        // Step 1: Create document
-        if (!json)
-            process.stderr.write('Creating document... ');
-        let doc;
-        try {
-            const payload = { alias: args.face_id, content };
-            if (flags.label)
-                payload.label = flags.label;
-            if (flags.perspective)
-                payload.perspective = flags.perspective;
-            doc = await client.post('/v1/compile/documents', { body: payload });
-        }
-        catch (err) {
-            if (err instanceof FacesAPIError)
-                this.error(`Error (${err.statusCode}): ${err.message}`);
-            throw err;
+        if (flags.label && files.length > 1) {
+            this.error('--label applies to a single document. With several --file flags each document is labelled by its filename.');
         }
-        const docId = (doc.document_id ?? doc.id);
-        if (!json)
-            process.stderr.write(`done (${docId})\n`);
-        // Step 2: Make (prepare + sync in one call, returns 202)
-        let makeResponse;
-        try {
-            makeResponse = await client.post(`/v1/compile/documents/${docId}/make`);
+        // Read every source up front, keeping failures in place rather than
+        // collecting them separately — results must come back in input order so a
+        // caller can line them up against what it passed. A file that cannot be
+        // used is a per-file failure, not a reason to abandon the files that are
+        // fine: a whole-call failure leaves the caller unable to tell which file
+        // was at fault.
+        const sources = files.map((file) => {
+            try {
+                return { name: file, content: readTextFile(file) };
+            }
+            catch (err) {
+                return { name: file, readError: err instanceof Error ? err.message : String(err) };
+            }
+        });
+        if (flags.content)
+            sources.push({ name: '(--content)', content: flags.content });
+        const results = [];
+        const multi = files.length > 1;
+        const started = [];
+        for (const source of sources) {
+            if (source.readError !== undefined) {
+                results.push({ file: source.name, error: source.readError });
+                continue;
+            }
+            try {
+                const payload = { alias: args.face_id, content: source.content };
+                if (flags.label)
+                    payload.label = flags.label;
+                else if (multi)
+                    payload.label = path.basename(source.name);
+                if (flags.perspective)
+                    payload.perspective = flags.perspective;
+                if (!json)
+                    process.stderr.write(`Creating document${multi ? ` (${source.name})` : ''}... `);
+                const doc = (await client.post('/v1/compile/documents', { body: payload }));
+                const docId = String(doc.document_id ?? doc.id ?? '');
+                if (!docId)
+                    throw new Error('Server did not return a document_id');
+                if (!json)
+                    process.stderr.write(`done (${docId})\n`);
+                const makeResponse = (await client.post(`/v1/compile/documents/${docId}/make`));
+                const chunksTotal = makeResponse.chunks_total;
+                started.push({ source, docId, chunksTotal });
+                results.push({ file: source.name, document_id: docId, chunks_total: chunksTotal });
+            }
+            catch (err) {
+                if (!json)
+                    process.stderr.write('failed\n');
+                const message = err instanceof FacesAPIError ? `Error (${err.statusCode}): ${err.message}` : err instanceof Error ? err.message : String(err);
+                results.push({ file: source.name, error: message });
+            }
         }
-        catch (err) {
-            if (err instanceof FacesAPIError)
-                this.error(`Error (${err.statusCode}): ${err.message}`);
-            throw err;
+        if (started.length === 0) {
+            // Nothing was accepted — report every reason, then fail.
+            for (const r of results)
+                if (r.error)
+                    process.stderr.write(`${r.file}: ${r.error}\n`);
+            this.error(results.length === 1 ? 'Document was not accepted.' : 'No documents were accepted.');
         }
-        const chunksTotal = makeResponse.chunks_total;
+        if (!json)
+            for (const r of results)
+                if (r.error)
+                    process.stderr.write(`${r.file}: ${r.error}\n`);
         if (flags['no-wait']) {
             if (!json) {
-                process.stderr.write(`Compilation started in background${chunksTotal ? ` (${chunksTotal} chunks)` : ''}.\n`);
-                process.stderr.write(`Poll with: faces compile:doc:get ${docId} --json\n`);
+                for (const s of started) {
+                    process.stderr.write(`Compilation started in background${s.chunksTotal ? ` (${s.chunksTotal} chunks)` : ''}: ${s.docId}\n`);
+                }
+                process.stderr.write(`Poll with: faces compile:doc:get <id> --json\n`);
             }
-            return makeResponse;
+            return this.shape(results);
         }
-        if (!json)
-            process.stderr.write(`Compiling${chunksTotal ? ` (${chunksTotal} chunks)` : ''}:\n`);
-        // Step 3: Poll until synced
-        let result;
-        try {
-            result = await pollCompileProgress(client, docId, {
-                timeoutMs: flags.timeout * 1000,
-                onProgress: (p) => {
-                    if (!json) {
+        for (const s of started) {
+            if (!json)
+                process.stderr.write(`Compiling ${multi ? `${s.source.name} ` : ''}${s.chunksTotal ? `(${s.chunksTotal} chunks)` : ''}:\n`);
+            try {
+                const result = (await pollCompileProgress(client, s.docId, {
+                    timeoutMs: flags.timeout * 1000,
+                    onProgress: (p) => {
+                        if (json)
+                            return;
                         const c = p.current_counts;
                         const counts = c ? `ε=${c.epsilon} β=${c.beta} δ=${c.delta} α=${c.alpha}` : '';
                         const phase = p.prepare_status === 'syncing' ? ' (syncing)' : '';
                         process.stderr.write(`  [${p.chunks_completed ?? '?'}/${p.chunks_total ?? '?'}] ${counts}${phase}\n`);
-                    }
-                },
-            });
-        }
-        catch (err) {
-            if (err instanceof Error)
-                this.error(err.message);
-            throw err;
+                    },
+                }));
+                const hit = results.find((r) => r.document_id === s.docId);
+                if (hit)
+                    hit.compiled = result;
+            }
+            catch (err) {
+                const hit = results.find((r) => r.document_id === s.docId);
+                if (hit)
+                    hit.error = err instanceof Error ? err.message : String(err);
+                if (!json)
+                    process.stderr.write(`${s.source.name}: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
         }
         if (!json)
             process.stderr.write('Done.\n');
-        if (json)
-            this.log(JSON.stringify(result, null, 2));
-        return result;
+        return this.shape(results);
+    }
+    /**
+     * `documents` is always present and always in input order. For a single
+     * source the compiled/started body is also spread at the top level, so
+     * callers that already read `.document_id` keep working.
+     */
+    shape(results) {
+        const documents = results.map((r) => {
+            const out = { file: r.file };
+            if (r.document_id)
+                out.document_id = r.document_id;
+            if (r.chunks_total !== undefined)
+                out.chunks_total = r.chunks_total;
+            if (r.error)
+                out.error = r.error;
+            return out;
+        });
+        const body = { documents };
+        if (results.length === 1) {
+            const only = results[0];
+            Object.assign(body, only.compiled ?? {}, only.document_id ? { document_id: only.document_id } : {});
+            if (only.chunks_total !== undefined && body.chunks_total === undefined)
+                body.chunks_total = only.chunks_total;
+            body.documents = documents;
+        }
+        return body;
     }
 }
+/** Extensions the compile-documents endpoint takes as inline text. */
+const BINARY_HINTS = {
+    '.pdf': 'PDF is supported, but not by this command — use: faces compile:upload <alias> --file <path> --kind document',
+    '.docx': 'Word documents are not supported. Convert it to text first (e.g. `textutil -convert txt file.docx` on macOS).',
+    '.doc': 'Word documents are not supported. Convert it to text first.',
+    '.pages': 'Pages documents are not supported. Export it as text or PDF first.',
+    '.rtf': 'RTF is not supported. Convert it to plain text first (e.g. `textutil -convert txt file.rtf`).',
+    '.key': 'Keynote files are not supported. Export the text first.',
+    '.pptx': 'PowerPoint files are not supported. Export the text first.',
+    '.xlsx': 'Excel files are not supported. Export as .csv first.',
+    '.zip': 'Archives are not supported. Extract it and pass the text files.',
+    '.epub': 'EPUB is not supported. Convert it to text first.',
+};
+/**
+ * Read a file as text, refusing binary before it reaches the API.
+ *
+ * `compile:doc` posts its content as a text field, so a binary file used to
+ * travel all the way to the server and come back as a 500 ("A string literal
+ * cannot contain NUL (0x00) characters") that named neither the file nor the
+ * cause. The NUL scan is the general check — the extension table only makes the
+ * message more useful for formats people actually try.
+ */
+function readTextFile(file) {
+    if (!fs.existsSync(file))
+        throw new Error(`File not found: ${file}`);
+    const stat = fs.statSync(file);
+    if (stat.isDirectory())
+        throw new Error(`Not a file: ${file}`);
+    // Extension first, and independent of the byte scan: a small PDF can contain
+    // no NUL at all and would otherwise be posted as mojibake. A known format
+    // always gets the answer for that format.
+    const hint = BINARY_HINTS[path.extname(file).toLowerCase()];
+    if (hint)
+        throw new Error(hint);
+    const buf = fs.readFileSync(file);
+    if (buf.includes(0))
+        throw new Error('Looks like a binary file, not text. Convert it to text first.');
+    const content = buf.toString('utf8');
+    if (content.trim() === '')
+        throw new Error('File is empty.');
+    return content;
+}