faces-cli 1.7.7 → 1.7.8

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

@@ -2,6 +2,8 @@ import { BaseCommand } from '../../../base.js';
 export default class CompileDocPause extends BaseCommand {
     static description: string;
     static flags: {
+        'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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>;
@@ -10,4 +12,5 @@ export default class CompileDocPause extends BaseCommand {
         doc_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
+    private report;
 }

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

@@ -1,10 +1,17 @@
-import { Args } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../../base.js';
 import { FacesAPIError } from '../../../client.js';
+import { pollUntilPaused } from '../../../poll.js';
 export default class CompileDocPause extends BaseCommand {
-    static description = 'Pause a running document compilation (preserves progress, resume with make)';
+    static description = 'Ask a running document compilation to stop (preserves progress, resume with make). ' +
+        'The compile stops at the next chunk boundary; this waits for it unless --no-wait.';
     static flags = {
         ...BaseCommand.baseFlags,
+        'no-wait': Flags.boolean({
+            description: 'Return as soon as the pause is accepted, without waiting for the compile to stop.',
+            default: false,
+        }),
+        timeout: Flags.integer({ description: 'Seconds to wait for the compile to stop (default: 60)', default: 60 }),
     };
     static args = {
         doc_id: Args.string({ description: 'Document ID', required: true }),
@@ -12,6 +19,7 @@ export default class CompileDocPause extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(CompileDocPause);
         const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
         let data;
         try {
             data = await client.post(`/v1/compile/documents/${args.doc_id}/pause`);
@@ -21,9 +29,48 @@ export default class CompileDocPause extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled()) {
-            this.log(`Paused. Resume with: faces compile:doc:make ${args.doc_id}`);
+        // POST /pause only acknowledges the request — it answers "pausing", not
+        // "paused". Reporting it as stopped here would be a guess, and before the
+        // backend fix it was usually a wrong one. prepare_status is the authority.
+        if (flags['no-wait']) {
+            if (!json) {
+                process.stderr.write(`Pausing. Poll with: faces compile:doc:get ${args.doc_id} --json\n`);
+            }
+            return data;
+        }
+        if (!json)
+            process.stderr.write('Pausing');
+        const status = await pollUntilPaused(client, args.doc_id, {
+            timeoutMs: flags.timeout * 1000,
+            onTick: () => {
+                if (!json && process.stderr.isTTY)
+                    process.stderr.write('.');
+            },
+        });
+        if (!json)
+            process.stderr.write('\n');
+        if (!json)
+            this.log(this.report(status, args.doc_id, flags.timeout));
+        return { ...data, prepare_status: status ?? null };
+    }
+    report(status, id, timeout) {
+        switch (status) {
+            case 'paused': {
+                return `Paused. Resume with: faces compile:doc:make ${id}`;
+            }
+            case 'synced':
+            case 'ready': {
+                return 'Compile finished before the pause took effect — nothing to resume.';
+            }
+            case 'failed': {
+                return 'Compile failed before the pause took effect.';
+            }
+            case null: {
+                return 'Stopped — the compile is no longer running.';
+            }
+            default: {
+                return `Still stopping after ${timeout}s. Poll with: faces compile:doc:get ${id} --json`;
+            }
         }
-        return data;
     }
 }

package/dist/commands/compile/thread/pause.d.ts

@@ -2,6 +2,8 @@ import { BaseCommand } from '../../../base.js';
 export default class CompileThreadPause extends BaseCommand {
     static description: string;
     static flags: {
+        'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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>;
@@ -10,4 +12,5 @@ export default class CompileThreadPause extends BaseCommand {
         thread_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
+    private report;
 }

package/dist/commands/compile/thread/pause.js

@@ -1,10 +1,17 @@
-import { Args } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../../base.js';
 import { FacesAPIError } from '../../../client.js';
+import { pollUntilPaused } from '../../../poll.js';
 export default class CompileThreadPause extends BaseCommand {
-    static description = 'Pause a running thread compilation (preserves progress, resume with make)';
+    static description = 'Ask a running thread compilation to stop (preserves progress, resume with make). ' +
+        'The compile stops at the next chunk boundary; this waits for it unless --no-wait.';
     static flags = {
         ...BaseCommand.baseFlags,
+        'no-wait': Flags.boolean({
+            description: 'Return as soon as the pause is accepted, without waiting for the compile to stop.',
+            default: false,
+        }),
+        timeout: Flags.integer({ description: 'Seconds to wait for the compile to stop (default: 60)', default: 60 }),
     };
     static args = {
         thread_id: Args.string({ description: 'Thread ID', required: true }),
@@ -12,6 +19,7 @@ export default class CompileThreadPause extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(CompileThreadPause);
         const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
         let data;
         try {
             data = await client.post(`/v1/compile/threads/${args.thread_id}/pause`);
@@ -21,9 +29,49 @@ export default class CompileThreadPause extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled()) {
-            this.log(`Paused. Resume with: faces compile:thread:make ${args.thread_id}`);
+        // POST /pause only acknowledges the request — it answers "pausing", not
+        // "paused". Reporting it as stopped here would be a guess, and before the
+        // backend fix it was usually a wrong one. prepare_status is the authority.
+        if (flags['no-wait']) {
+            if (!json) {
+                process.stderr.write(`Pausing. Poll with: faces compile:thread:get ${args.thread_id} --json\n`);
+            }
+            return data;
+        }
+        if (!json)
+            process.stderr.write('Pausing');
+        const status = await pollUntilPaused(client, args.thread_id, {
+            endpoint: `/v1/compile/threads/${args.thread_id}`,
+            timeoutMs: flags.timeout * 1000,
+            onTick: () => {
+                if (!json && process.stderr.isTTY)
+                    process.stderr.write('.');
+            },
+        });
+        if (!json)
+            process.stderr.write('\n');
+        if (!json)
+            this.log(this.report(status, args.thread_id, flags.timeout));
+        return { ...data, prepare_status: status ?? null };
+    }
+    report(status, id, timeout) {
+        switch (status) {
+            case 'paused': {
+                return `Paused. Resume with: faces compile:thread:make ${id}`;
+            }
+            case 'synced':
+            case 'ready': {
+                return 'Compile finished before the pause took effect — nothing to resume.';
+            }
+            case 'failed': {
+                return 'Compile failed before the pause took effect.';
+            }
+            case null: {
+                return 'Stopped — the compile is no longer running.';
+            }
+            default: {
+                return `Still stopping after ${timeout}s. Poll with: faces compile:thread:get ${id} --json`;
+            }
         }
-        return data;
     }
 }

package/dist/poll.d.ts

@@ -30,3 +30,24 @@ export interface PollOptions {
  * Throws on timeout or failure.
  */
 export declare function pollCompileProgress(client: FacesClient, id: string, opts?: PollOptions): Promise<unknown>;
+export interface PausePollOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    onTick?: () => void;
+    /** Override the GET endpoint path. Defaults to /v1/compile/documents/{id}. */
+    endpoint?: string;
+}
+/**
+ * Wait for a pause request to actually land.
+ *
+ * POST /pause only acknowledges the request — it returns `status: "pausing"` and
+ * the compile stops at the next chunk boundary, usually within a few seconds.
+ * `prepare_status` on the document is the authority on whether it has stopped.
+ *
+ * Returns that final status: `paused` when the pause landed, `synced`/`ready`
+ * when the compile finished before it could (a normal race, not an error),
+ * `failed` if it died, or null when nothing was running. Returns undefined if
+ * the timeout expires while it is still stopping — the pause was accepted
+ * either way, so callers should report rather than fail.
+ */
+export declare function pollUntilPaused(client: FacesClient, id: string, opts?: PausePollOptions): Promise<string | null | undefined>;

package/dist/poll.js

@@ -39,3 +39,37 @@ export async function pollCompileProgress(client, id, opts = {}) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Statuses that mean the compile is no longer running. `paused` is the outcome a
+ * pause is waiting for; the rest mean it stopped for some other reason first.
+ */
+const PAUSE_TERMINAL = new Set(['paused', 'synced', 'ready', 'failed']);
+/**
+ * Wait for a pause request to actually land.
+ *
+ * POST /pause only acknowledges the request — it returns `status: "pausing"` and
+ * the compile stops at the next chunk boundary, usually within a few seconds.
+ * `prepare_status` on the document is the authority on whether it has stopped.
+ *
+ * Returns that final status: `paused` when the pause landed, `synced`/`ready`
+ * when the compile finished before it could (a normal race, not an error),
+ * `failed` if it died, or null when nothing was running. Returns undefined if
+ * the timeout expires while it is still stopping — the pause was accepted
+ * either way, so callers should report rather than fail.
+ */
+export async function pollUntilPaused(client, id, opts = {}) {
+    const interval = opts.intervalMs ?? 1000;
+    const timeout = opts.timeoutMs ?? 60_000;
+    const endpoint = opts.endpoint ?? `/v1/compile/documents/${id}`;
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+        await sleep(interval);
+        opts.onTick?.();
+        // status_only trims the body to the progress fields — this is a poll loop.
+        const data = await client.get(`${endpoint}?status_only=true`);
+        const status = data.prepare_status ?? null;
+        if (status === null || PAUSE_TERMINAL.has(status))
+            return status;
+    }
+    return undefined;
+}