@devicecloud.dev/dcd 5.10.0 → 5.11.0-beta.2

package/dist/utils/device-bundle.d.ts

@@ -0,0 +1,22 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+import type { DeviceFlowBundle } from '../types/domain/device-session.types.js';
+/** The API's limit on a bundle (dcd plan 2.5b). */
+export declare const MAX_BUNDLE_BYTES: number;
+/** Every file under `dir`, relative to it, in a stable order. */
+export declare function bundleFiles(dir: string): string[];
+export interface UploadFlowBundleOptions {
+    apiUrl: string;
+    auth: AuthContext;
+    dir: string;
+    log: (message: string) => void;
+}
+/**
+ * Zip a directory of flows and upload it as a flow bundle: ask the API for
+ * upload URLs, PUT the zip to both copies, then register it with its
+ * SHA-256. Encrypted like `dcd cloud`'s flow zips when the org's default
+ * (or DCD_ENCRYPT) says so. Entries are relative to `dir`, so a run's
+ * `flow` is a path inside it, e.g. `login.yaml`.
+ */
+export declare function uploadFlowBundle(opts: UploadFlowBundleOptions): Promise<DeviceFlowBundle & {
+    files: number;
+}>;

package/dist/utils/device-bundle.js

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import { readdirSync } from 'node:fs';
+import * as path from 'node:path';
+import { DeviceGateway } from '../gateways/device-gateway.js';
+import { compressFilesFromRelativePath } from '../methods.js';
+import { detectCiContext } from './ci.js';
+import { CliError, getCliVersion } from './cli.js';
+import { fetchCompatibilityData } from './compatibility.js';
+import { checkKekForEncryption, encryptFlowBuffer, resolveEncryption, resolveKekPublicKey, } from './envelope.js';
+/** The API's limit on a bundle (dcd plan 2.5b). */
+export const MAX_BUNDLE_BYTES = 50 * 1024 * 1024;
+/** Never bundled: version control, dependencies, and other dot-folders. */
+function skipped(relativePath) {
+    return relativePath
+        .split(path.sep)
+        .some((part) => part === 'node_modules' || (part.startsWith('.') && part !== '.'));
+}
+/** Every file under `dir`, relative to it, in a stable order. */
+export function bundleFiles(dir) {
+    return readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => path.relative(dir, path.join(entry.parentPath, entry.name)))
+        .filter((file) => !skipped(file))
+        .sort();
+}
+/** PUT the zip to one signed URL. The URL is the credential. */
+async function put(url, body) {
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        try {
+            const res = await fetch(url, {
+                method: 'PUT',
+                headers: { 'content-type': 'application/zip' },
+                body: new Uint8Array(body),
+            });
+            await res.body?.cancel();
+            if (res.ok)
+                return true;
+            if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
+                return false;
+            }
+        }
+        catch {
+            // A network error: try once more.
+        }
+    }
+    return false;
+}
+/**
+ * Zip a directory of flows and upload it as a flow bundle: ask the API for
+ * upload URLs, PUT the zip to both copies, then register it with its
+ * SHA-256. Encrypted like `dcd cloud`'s flow zips when the org's default
+ * (or DCD_ENCRYPT) says so. Entries are relative to `dir`, so a run's
+ * `flow` is a path inside it, e.g. `login.yaml`.
+ */
+export async function uploadFlowBundle(opts) {
+    const { apiUrl, auth, dir, log } = opts;
+    const files = bundleFiles(dir);
+    if (!files.some((f) => /\.ya?ml$/i.test(f))) {
+        throw new CliError(`No flow files (.yaml) in ${dir}.`);
+    }
+    const zip = await compressFilesFromRelativePath(dir, files, '');
+    let serverDefault;
+    try {
+        const ci = detectCiContext();
+        const compatibility = await fetchCompatibilityData(apiUrl, auth, {
+            cliVersion: getCliVersion(),
+            ciProvider: ci.provider,
+            ciWrapperVersion: ci.wrapperVersion,
+        });
+        serverDefault = compatibility.encryption?.defaultOn;
+    }
+    catch {
+        serverDefault = undefined;
+    }
+    const encryption = await checkKekForEncryption(resolveEncryption({ serverDefault }), apiUrl);
+    if (encryption.notice)
+        log(encryption.notice);
+    const kek = encryption.enabled ? await resolveKekPublicKey(apiUrl) : null;
+    const sealed = kek ? encryptFlowBuffer(zip, kek) : null;
+    const body = sealed ? sealed.ciphertext : zip;
+    if (body.length > MAX_BUNDLE_BYTES) {
+        throw new CliError(`${dir} zips to ${(body.length / 1024 / 1024).toFixed(1)} MB; a bundle can be at most ${MAX_BUNDLE_BYTES / 1024 / 1024} MB.`);
+    }
+    const sha = createHash('sha256').update(body).digest('hex');
+    const urls = await DeviceGateway.bundleUploadUrls(apiUrl, auth, body.length);
+    const [supabase, backblaze] = await Promise.all([
+        urls.upload ? put(urls.upload.signedUrl, body) : Promise.resolve(false),
+        urls.mirror ? put(urls.mirror.signedUrl, body) : Promise.resolve(false),
+    ]);
+    if (!supabase && !backblaze) {
+        throw new Error('The flow bundle could not be uploaded. Please retry.');
+    }
+    const { bundle } = await DeviceGateway.registerBundle(apiUrl, auth, {
+        id: urls.id,
+        sha,
+        bytes: body.length,
+        supabase,
+        backblaze,
+        ...(sealed && { enc: sealed.enc }),
+    });
+    return { ...bundle, files: files.length };
+}

package/dist/utils/device-output.d.ts

@@ -0,0 +1,81 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+import type { DeviceHumanStatus, DeviceSession } from '../types/domain/device-session.types.js';
+import { type Field } from './ui.js';
+/**
+ * Exit codes for `dcd device` (dcd docs/device-v1-plan.md, section 4.2).
+ * Scripts and agents branch on these, so they are a contract.
+ */
+export declare const DEVICE_EXIT: {
+    readonly ok: 0;
+    /** Called wrongly: a bad flag, a bad value, or no session to pick. */
+    readonly usage: 1;
+    /** It ran and failed: a flow or action failed, or the API could not do it. */
+    readonly failed: 2;
+    /** A limit: concurrency, spend cap or rate limit. */
+    readonly limit: 3;
+    /** The session has ended, or there is no such session. */
+    readonly gone: 4;
+};
+export declare function deviceExitCode(error: unknown): number;
+/**
+ * The one object `--json` prints, on success and on failure alike. `session`
+ * is left out by the commands that are not about one session (`list`,
+ * `models`, `stop --all`), so it never reads as "no session".
+ */
+export interface DeviceEnvelope<T> {
+    ok: boolean;
+    session?: DeviceSession | null;
+    data: T | null;
+    error: {
+        code: null | string;
+        message: string;
+    } | null;
+}
+export interface DeviceOutcome<T> {
+    /** The session the command was about; undefined when it is not about one. */
+    session: DeviceSession | null | undefined;
+    data: T;
+    /** Prints the result for a person. Not called under --json. */
+    print(): void;
+    /**
+     * Set when the command ran but did not succeed (a failed launch, a failed
+     * flow). The CLI then exits 2, still printing `data`.
+     */
+    failure?: {
+        code: null | string;
+        message: string;
+    };
+}
+/**
+ * Runs one `dcd device` command and prints its result: one envelope under
+ * --json, readable text otherwise. Errors leave with the matching exit code.
+ * Under --json the error is printed here, as an envelope, so the top-level
+ * handler's `{ status, error }` never appears.
+ */
+export declare function runDeviceCommand<T>(json: boolean, fn: () => Promise<DeviceOutcome<T>>): Promise<void>;
+/**
+ * Progress for a person, on stderr, so stdout carries only the result. Off
+ * under --json. These are plain lines, never a spinner, so they read the same
+ * in a terminal, a CI log or an agent's tool output.
+ */
+export declare function deviceProgress(json: boolean): (message: string) => void;
+/**
+ * The default-session rule: `<id>` may be left out when the org has exactly
+ * one open session. With none, or several, the command is a usage error and
+ * lists what there is to choose from.
+ */
+export declare function resolveSessionId(apiUrl: string, auth: AuthContext, given: string | undefined): Promise<string>;
+export declare function formatSeconds(seconds: number): string;
+/** The rows that describe a session, for {@link ui.fields}. */
+export declare function sessionFields(session: DeviceSession): Field[];
+/** A session as a branch group, with its warnings after it. */
+export declare function printSession(session: DeviceSession): void;
+/**
+ * An API timestamp for a person: how far off it is and the local time, e.g.
+ * "in 12m (14:32)" or "3m ago (14:17)". The text as given when unreadable.
+ */
+export declare function formatWhen(iso: string, now?: number): string;
+/** Where the hand-over stands, in a few words. */
+export declare function humanState(human: DeviceHumanStatus): string;
+/** The rows that describe a request for a person, for {@link ui.fields}. */
+export declare function humanFields(human: DeviceHumanStatus, now?: number): Field[];

package/dist/utils/device-output.js

@@ -0,0 +1,204 @@
+import { DeviceApiError, DeviceGateway } from '../gateways/device-gateway.js';
+import { CliError, logger } from './cli.js';
+import { colors, formatUrl } from './styling.js';
+import { ui } from './ui.js';
+/**
+ * Exit codes for `dcd device` (dcd docs/device-v1-plan.md, section 4.2).
+ * Scripts and agents branch on these, so they are a contract.
+ */
+export const DEVICE_EXIT = {
+    ok: 0,
+    /** Called wrongly: a bad flag, a bad value, or no session to pick. */
+    usage: 1,
+    /** It ran and failed: a flow or action failed, or the API could not do it. */
+    failed: 2,
+    /** A limit: concurrency, spend cap or rate limit. */
+    limit: 3,
+    /** The session has ended, or there is no such session. */
+    gone: 4,
+};
+const LIMIT_CODES = new Set(['LIVE_CONCURRENCY_LIMIT', 'LIVE_RATE_LIMITED', 'LIVE_SPEND_CAP']);
+const GONE_CODES = new Set(['LIVE_NOT_FOUND', 'LIVE_SESSION_ENDED']);
+const USAGE_CODES = new Set([
+    'LIVE_INVALID_ACTION',
+    'LIVE_INVALID_APP',
+    'LIVE_SESSION_REQUIRED',
+]);
+export function deviceExitCode(error) {
+    if (error instanceof DeviceApiError) {
+        if (error.code && GONE_CODES.has(error.code))
+            return DEVICE_EXIT.gone;
+        if (error.code && LIMIT_CODES.has(error.code))
+            return DEVICE_EXIT.limit;
+        if (error.code && USAGE_CODES.has(error.code))
+            return DEVICE_EXIT.usage;
+        if (error.status === 404)
+            return DEVICE_EXIT.gone;
+        if (error.status === 429)
+            return DEVICE_EXIT.limit;
+        if ([400, 401, 403].includes(error.status))
+            return DEVICE_EXIT.usage;
+        return DEVICE_EXIT.failed;
+    }
+    if (error instanceof CliError)
+        return error.exitCode;
+    return DEVICE_EXIT.failed;
+}
+/**
+ * Runs one `dcd device` command and prints its result: one envelope under
+ * --json, readable text otherwise. Errors leave with the matching exit code.
+ * Under --json the error is printed here, as an envelope, so the top-level
+ * handler's `{ status, error }` never appears.
+ */
+export async function runDeviceCommand(json, fn) {
+    let outcome;
+    try {
+        outcome = await fn();
+    }
+    catch (error) {
+        const exitCode = deviceExitCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        if (!json)
+            throw new CliError(message, exitCode);
+        const envelope = {
+            ok: false,
+            session: error instanceof DeviceApiError ? error.session : null,
+            data: null,
+            error: { code: error instanceof DeviceApiError ? error.code : null, message },
+        };
+        logger.json(envelope);
+        logger.fail(message, exitCode);
+    }
+    if (json) {
+        const envelope = {
+            ok: !outcome.failure,
+            ...(outcome.session !== undefined && { session: outcome.session }),
+            data: outcome.data,
+            error: outcome.failure ?? null,
+        };
+        logger.json(envelope);
+    }
+    else {
+        outcome.print();
+    }
+    if (outcome.failure)
+        logger.fail(outcome.failure.message, DEVICE_EXIT.failed);
+}
+/**
+ * Progress for a person, on stderr, so stdout carries only the result. Off
+ * under --json. These are plain lines, never a spinner, so they read the same
+ * in a terminal, a CI log or an agent's tool output.
+ */
+export function deviceProgress(json) {
+    return (message) => {
+        if (!json)
+            process.stderr.write(`${message}\n`);
+    };
+}
+/**
+ * The default-session rule: `<id>` may be left out when the org has exactly
+ * one open session. With none, or several, the command is a usage error and
+ * lists what there is to choose from.
+ */
+export async function resolveSessionId(apiUrl, auth, given) {
+    const id = given?.trim();
+    if (id)
+        return id;
+    const { sessions } = await DeviceGateway.list(apiUrl, auth);
+    if (sessions.length === 1)
+        return sessions[0].id;
+    if (sessions.length === 0) {
+        throw new CliError('No open device session. Start one with `dcd device start --platform ios|android`.', DEVICE_EXIT.usage);
+    }
+    const candidates = sessions
+        .map((s) => `  ${s.id}  ${s.platform}  ${s.state}${s.client_label ? `  ${s.client_label}` : ''}`)
+        .join('\n');
+    throw new CliError(`${sessions.length} device sessions are open. Name one:\n${candidates}`, DEVICE_EXIT.usage);
+}
+export function formatSeconds(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = seconds % 60;
+    return rest ? `${minutes}m ${rest}s` : `${minutes}m`;
+}
+/** The rows that describe a session, for {@link ui.fields}. */
+export function sessionFields(session) {
+    const fields = [
+        ['session', colors.highlight(session.id)],
+        ['state', session.release_reason ? `${session.state} (${session.release_reason})` : session.state],
+        ['platform', session.platform],
+    ];
+    if (session.model)
+        fields.push(['model', session.model]);
+    if (session.client_label)
+        fields.push(['client', session.client_label]);
+    if (session.queue) {
+        const position = session.queue.position === null ? '' : `#${session.queue.position}`;
+        const eta = session.queue.eta_s === null ? '' : `, about ${formatSeconds(session.queue.eta_s)}`;
+        fields.push(['queue', `${position || 'waiting'}${eta} (${session.queue.reason.replaceAll('_', ' ')})`]);
+    }
+    if (session.time_remaining_s !== null) {
+        fields.push(['time left', formatSeconds(session.time_remaining_s)]);
+    }
+    if (session.idle_remaining_s !== null) {
+        fields.push(['idle timeout', `in ${formatSeconds(session.idle_remaining_s)}`]);
+    }
+    if (session.cost_so_far_usd !== null) {
+        fields.push(['cost so far', `$${session.cost_so_far_usd.toFixed(2)}`]);
+    }
+    if (session.last_crash) {
+        fields.push(['last crash', colors.error(`${session.last_crash.summary} (${session.last_crash.at})`)]);
+    }
+    fields.push(['monitor', formatUrl(session.monitor_url)]);
+    return fields;
+}
+/** A session as a branch group, with its warnings after it. */
+export function printSession(session) {
+    logger.log(ui.branch(ui.fields(sessionFields(session))));
+    for (const warning of session.warnings)
+        logger.log(ui.warn(warning));
+}
+/**
+ * An API timestamp for a person: how far off it is and the local time, e.g.
+ * "in 12m (14:32)" or "3m ago (14:17)". The text as given when unreadable.
+ */
+export function formatWhen(iso, now = Date.now()) {
+    const at = Date.parse(iso);
+    if (!Number.isFinite(at))
+        return iso;
+    const clock = new Date(at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    const seconds = Math.round((at - now) / 1000);
+    if (Math.abs(seconds) < 5)
+        return `now (${clock})`;
+    return seconds > 0
+        ? `in ${formatSeconds(seconds)} (${clock})`
+        : `${formatSeconds(-seconds)} ago (${clock})`;
+}
+/** Where the hand-over stands, in a few words. */
+export function humanState(human) {
+    if (human.human_in_control)
+        return 'a person has control';
+    if (human.waiting)
+        return 'waiting for a person';
+    if (human.handed_back)
+        return 'handed back';
+    return 'no help asked for';
+}
+/** The rows that describe a request for a person, for {@link ui.fields}. */
+export function humanFields(human, now = Date.now()) {
+    const fields = [['state', humanState(human)]];
+    if (human.reason)
+        fields.push(['reason', human.reason]);
+    if (human.since)
+        fields.push(['asked', formatWhen(human.since, now)]);
+    if (human.waiting && human.expires_at) {
+        fields.push(['ends', `${formatWhen(human.expires_at, now)} unless they hand it back`]);
+    }
+    if (human.handed_back && human.handed_back_at) {
+        fields.push(['handed back', formatWhen(human.handed_back_at, now)]);
+    }
+    if (human.handed_back)
+        fields.push(['note', human.note ?? colors.dim('none')]);
+    return fields;
+}

package/dist/utils/device-run.d.ts

@@ -0,0 +1,29 @@
+import type { DeviceCommandResult, DeviceFlowResult } from '../types/domain/device-session.types.js';
+/**
+ * What `dcd device run` shows a person: one row per flow and a short summary.
+ *
+ * The API passes on the runner's report as text in `result.output` (a pass)
+ * or `result.error` (a failure). For a directory that report is Maestro's
+ * JSON: `{ success, device_id, total_flows, total_commands_executed,
+ * results: [{ file, success, error, message }], env_vars, message }`. For one
+ * flow it is the same without `results`. Newer APIs also send
+ * `result.flows`, which is used when present. None of the runner's own
+ * fields (device_id, command counts, env_vars) are shown.
+ */
+export interface RunReport {
+    flows: DeviceFlowResult[];
+    /** The runner's one-line summary, e.g. "Some flows failed to execute". */
+    message: null | string;
+}
+/**
+ * The flows a run reported, or null when the result carries no report the
+ * CLI can read (plain text): then the text is shown as it came.
+ */
+export declare function parseRunReport(result: DeviceCommandResult): null | RunReport;
+/** The failure message for a failed run: each failing flow and why. */
+export declare function runFailureMessage(result: DeviceCommandResult, report: null | RunReport): string;
+/**
+ * Print a run's result for a person. `label` names a flow the report does not
+ * (a single flow's report has no file name).
+ */
+export declare function printRunResult(log: (line: string) => void, passed: boolean, result: DeviceCommandResult, label: string): void;

package/dist/utils/device-run.js

@@ -0,0 +1,105 @@
+import { colors } from './styling.js';
+import { ui } from './ui.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function toFlow(raw, file) {
+    const success = raw.success === true;
+    return {
+        file: text(raw.file) ?? file,
+        success,
+        // A failed flow's reason is in `error`; some reports only have `message`.
+        error: text(raw.error) ?? (success ? null : text(raw.message)),
+    };
+}
+/** The runner's JSON report in `body`, or null when it is not one. */
+function parseRunnerJson(body) {
+    if (!body || !body.trimStart().startsWith('{'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (Array.isArray(parsed.results)) {
+        return {
+            flows: parsed.results.filter((r) => isRecord(r)).map((r) => toFlow(r, null)),
+            message: text(parsed.message),
+        };
+    }
+    if (typeof parsed.success !== 'boolean')
+        return null;
+    // One flow: the report is that flow's result.
+    return { flows: [toFlow(parsed, null)], message: text(parsed.message) };
+}
+/**
+ * The flows a run reported, or null when the result carries no report the
+ * CLI can read (plain text): then the text is shown as it came.
+ */
+export function parseRunReport(result) {
+    if (Array.isArray(result.flows)) {
+        return { flows: result.flows.map((f) => toFlow({ ...f }, null)), message: null };
+    }
+    return parseRunnerJson(result.error) ?? parseRunnerJson(result.output);
+}
+/** The failure message for a failed run: each failing flow and why. */
+export function runFailureMessage(result, report) {
+    if (!report)
+        return result.error || 'The flow failed.';
+    const failed = report.flows.filter((f) => !f.success);
+    if (failed.length === 0)
+        return report.message ?? 'The flow failed.';
+    return failed
+        .map((f) => `${f.file ?? 'flow'}: ${f.error ?? 'failed'}`)
+        .join('; ');
+}
+/**
+ * Print a run's result for a person. `label` names a flow the report does not
+ * (a single flow's report has no file name).
+ */
+export function printRunResult(log, passed, result, label) {
+    const report = parseRunReport(result);
+    if (!report || report.flows.length === 0) {
+        log(passed ? ui.success('Flow passed') : `${ui.statusSymbol('FAILED')} Flow failed`);
+        if (report) {
+            if (report.message)
+                log(ui.note(report.message));
+            return;
+        }
+        // Plain text, not a report the CLI can read: show it as it came.
+        if (result.output) {
+            log(ui.section('Output'));
+            log(result.output);
+        }
+        if (result.error) {
+            log(ui.section('Error'));
+            log(colors.error(result.error));
+        }
+        return;
+    }
+    const { flows } = report;
+    const failed = flows.filter((f) => !f.success).length;
+    const total = flows.length;
+    let summary;
+    if (total === 1)
+        summary = passed ? 'Flow passed' : 'Flow failed';
+    else if (failed === 0)
+        summary = `${total} flows passed`;
+    else
+        summary = `${failed} of ${total} flows failed`;
+    log(passed && failed === 0 ? ui.success(summary) : `${ui.statusSymbol('FAILED')} ${summary}`);
+    const rows = flows.map((f) => [
+        f.file ?? label,
+        f.success
+            ? ui.statusWord('PASSED')
+            : `${ui.statusWord('FAILED')}${f.error ? `  ${colors.error(f.error)}` : ''}`,
+    ]);
+    log(ui.branch(ui.fields(rows)));
+}

package/dist/utils/progress.d.ts

@@ -4,9 +4,13 @@ declare class Action {
     private _lastPrinted;
     private interactive;
     start(title: string, initialStatus?: string, _opts?: unknown): void;
+    /** End the action as a success: `✓ message`. */
     stop(message?: string): void;
+    /** End the action as a failure: `✗ message`. */
+    fail(message?: string): void;
     set status(value: string);
     get status(): string;
+    private finish;
     private print;
 }
 export declare const ux: {

package/dist/utils/progress.js

@@ -10,9 +10,20 @@
  * non-interactive environments we skip the spinner entirely and instead print a
  * plain line once per *distinct* status, so CI logs show real progress without
  * the flood.
+ *
+ * Styling: the spinner uses the CLI's own palette (cyan braille frames) rather
+ * than clack's magenta default, and no `│` guide bar, since the rest of the CLI
+ * is a `⏺`/`⎿` tree rather than a clack session. The final line is written by
+ * us, not clack, so it carries the same `✓` / `✗` symbols as every other
+ * command (see STYLE_GUIDE.md).
  */
 import * as p from '@clack/prompts';
 import { isCI } from './ci.js';
+import { colors, symbols } from './styling.js';
+// Braille dots where the terminal can draw them, plain ASCII otherwise.
+const FRAMES = p.unicode
+    ? ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+    : ['-', '\\', '|', '/'];
 class Action {
     current = null;
     _status = '';
@@ -23,37 +34,30 @@ class Action {
     }
     start(title, initialStatus, _opts) {
         this._status = initialStatus ?? '';
-        const line = initialStatus ? `${title} — ${initialStatus}` : title;
+        const line = initialStatus ? `${title} ${colors.dim('·')} ${initialStatus}` : title;
         if (!this.interactive()) {
             this.current = null;
             this.print(line);
             return;
         }
         if (this.current) {
-            this.current.stop();
+            this.current.clear();
         }
-        this.current = p.spinner();
+        this.current = p.spinner({
+            delay: 80,
+            frames: FRAMES,
+            styleFrame: colors.highlight,
+            withGuide: false,
+        });
         this.current.start(line);
     }
+    /** End the action as a success: `✓ message`. */
     stop(message) {
-        if (!this.interactive()) {
-            if (message)
-                this.print(message);
-            this.current = null;
-            this._status = '';
-            this._lastPrinted = '';
-            return;
-        }
-        if (!this.current) {
-            if (message) {
-                // eslint-disable-next-line no-console
-                console.log(message);
-            }
-            return;
-        }
-        this.current.stop(message ?? '');
-        this.current = null;
-        this._status = '';
+        this.finish(symbols.success, message);
+    }
+    /** End the action as a failure: `✗ message`. */
+    fail(message) {
+        this.finish(symbols.error, message);
     }
     set status(value) {
         this._status = value;
@@ -70,6 +74,26 @@ class Action {
     get status() {
         return this._status;
     }
+    // Erase the spinner (if one is live) and print the final line ourselves, so
+    // the symbol matches the rest of the CLI instead of clack's `◇`.
+    finish(symbol, message) {
+        const line = message ? `${symbol} ${message}` : '';
+        if (!this.interactive()) {
+            if (line)
+                this.print(line);
+            this.current = null;
+            this._status = '';
+            this._lastPrinted = '';
+            return;
+        }
+        this.current?.clear();
+        this.current = null;
+        this._status = '';
+        if (line) {
+            // eslint-disable-next-line no-console
+            console.log(line);
+        }
+    }
     // Emit a line only when it differs from the previous one, so repeated polls
     // with no state change stay quiet.
     print(line) {

package/package.json

@@ -68,7 +68,7 @@
     "test:unit": "node scripts/test-runner.mjs --unit",
     "typecheck": "tsc --noEmit -p tsconfig.test.json"
   },
-  "version": "5.10.0",
+  "version": "5.11.0-beta.2",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },
@@ -109,7 +109,7 @@
       "ws@>=8.0.0 <8.21.0": "8.21.0",
       "esbuild@<0.28.1": ">=0.28.1",
       "qs@<6.16.0": "6.16.0",
-      "fast-uri@>=3.0.0 <3.1.8": "3.1.8",
+      "fast-uri@>=3.0.0 <3.1.9": "3.1.9",
       "hono@>=4.0.0 <4.13.11": "4.13.11",
       "source-map-js@<1.2.2": "1.2.2",
       "micromatch>picomatch": "^2.3.2",