@xano/cli 1.0.6-beta.6 → 1.0.6-beta.8

package/dist/utils/hatch-client.js

@@ -0,0 +1,163 @@
+/* eslint-disable n/no-unsupported-features/node-builtins, no-undef -- fetch/Response/Headers and the RequestInit type are stable on the Node 20.12 floor this package targets; the rule's support data is stale, and src/base-command.ts hits the same false positives */
+import { isTerminalOutcome } from './hatch-contract.js';
+/** Where `xano hatch` talks to when nothing else says otherwise. */
+export const DEFAULT_HATCH_URL = 'https://hatch.mesh0.ai';
+/** The env var that points the command at a local API or a staging droplet. */
+export const HATCH_URL_ENV_VAR = 'XANO_HATCH_URL';
+/**
+ * Resolve the Hatch origin: `--api` flag > `XANO_HATCH_URL` > the default.
+ *
+ * Trailing slashes are stripped here rather than at each call site, so no
+ * request ever ends up asking for `//api/sessions`.
+ */
+export function resolveHatchUrl(source) {
+    const chosen = source.flag?.trim() || source.env?.trim() || DEFAULT_HATCH_URL;
+    return chosen.replace(/\/+$/, '');
+}
+/**
+ * Session-create answered without a `Set-Cookie`. Named because every later
+ * call would otherwise 404 or 403 with no hint of the real cause.
+ */
+export class HatchSessionCookieError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HatchSessionCookieError';
+    }
+}
+/**
+ * Derive how a build ended from its snapshot, in the same shape a `terminal`
+ * activity carries — so the command's stream path and its snapshot backstop
+ * agree on what "done" looks like. Undefined while the build is in flight.
+ */
+export function outcomeFromSnapshot(snapshot) {
+    if (!isTerminalOutcome(snapshot.state))
+        return undefined;
+    return {
+        ...(snapshot.failureMessage === undefined ? {} : { message: snapshot.failureMessage }),
+        outcome: snapshot.state,
+        ...(snapshot.siteUrl === undefined ? {} : { siteUrl: snapshot.siteUrl }),
+    };
+}
+export class HatchClient {
+    baseUrl;
+    fetchImpl;
+    /** The `name=value` pair captured from session-create. */
+    sessionCookie;
+    userAgent;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.userAgent = `xano-cli/${options.version}`;
+    }
+    /**
+     * Mint an anonymous session, asking for a watch link.
+     *
+     * `watchUrl` is optional on purpose: a Hatch deployed before the `?watch=1`
+     * affordance answers without one, and the command degrades to watching
+     * without a link rather than failing.
+     */
+    async createSession() {
+        const response = await this.request(`${this.baseUrl}/api/sessions?watch=1`, { method: 'POST' });
+        if (!response.ok) {
+            throw new Error(await describeFailure(response, 'failed to start a Hatch session'));
+        }
+        const cookie = extractSessionCookie(response);
+        if (!cookie) {
+            throw new HatchSessionCookieError('failed to start a Hatch session: the server returned no session cookie, so the build could not be claimed');
+        }
+        this.sessionCookie = cookie;
+        return (await parseJson(response, 'failed to start a Hatch session'));
+    }
+    /** `GET /api/sessions/:id` — the backstop when the stream says nothing. */
+    async getSnapshot(sessionId) {
+        const response = await this.request(`${this.baseUrl}/api/sessions/${encodeURIComponent(sessionId)}`, {
+            headers: { accept: 'application/json' },
+            method: 'GET',
+        });
+        if (!response.ok) {
+            throw new Error(await describeFailure(response, 'failed to read the Hatch session'));
+        }
+        return (await parseJson(response, 'failed to read the Hatch session'));
+    }
+    /**
+     * Open the session's SSE stream, returning the raw `Response` for a reader
+     * to frame.
+     *
+     * `lastEventId` goes in the `Last-Event-ID` **header**. Hatch's frontend also
+     * appends `?from=<n>`, but the server reads only the header — sending the
+     * query parameter alone silently replays the whole build on every reconnect.
+     */
+    async openStream(sessionId, lastEventId) {
+        const headers = { accept: 'text/event-stream' };
+        if (lastEventId !== undefined) {
+            headers['Last-Event-ID'] = String(lastEventId);
+        }
+        const response = await this.request(`${this.baseUrl}/events/sessions/${encodeURIComponent(sessionId)}`, {
+            headers,
+            method: 'GET',
+        });
+        if (!response.ok) {
+            throw new Error(await describeFailure(response, 'failed to open the Hatch build stream'));
+        }
+        return response;
+    }
+    /** `POST /api/sessions/:id/prompt` — the server answers 202. */
+    async submitPrompt(sessionId, prompt) {
+        const response = await this.request(`${this.baseUrl}/api/sessions/${encodeURIComponent(sessionId)}/prompt`, {
+            body: JSON.stringify({ prompt }),
+            headers: { accept: 'application/json', 'content-type': 'application/json' },
+            method: 'POST',
+        });
+        if (!response.ok) {
+            throw new Error(await describeFailure(response, 'failed to submit the prompt'));
+        }
+    }
+    /** Every request carries the User-Agent, and the cookie once we hold one. */
+    async request(url, init) {
+        const headers = {
+            'User-Agent': this.userAgent,
+            ...init.headers,
+        };
+        if (this.sessionCookie) {
+            headers.Cookie = this.sessionCookie;
+        }
+        try {
+            return await this.fetchImpl(url, { ...init, headers });
+        }
+        catch (error) {
+            throw new Error(`failed to reach Hatch at ${url}: ${error.message}`);
+        }
+    }
+}
+/**
+ * Unwrap Hatch's `{code, message}` error envelope. A non-JSON body (a proxy's
+ * HTML error page, say) still has to read as something, so it is appended
+ * under the status line rather than swallowed.
+ */
+async function describeFailure(response, context) {
+    const body = await response.text().catch(() => '');
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed?.message)
+            return `${context}: ${parsed.message}`;
+    }
+    catch {
+        // Not JSON — fall through to the status-plus-body form below.
+    }
+    return body ? `${context} (${response.status})\n${body}` : `${context} (${response.status})`;
+}
+/** Read a `Set-Cookie`, keeping only the `name=value` pair. */
+function extractSessionCookie(response) {
+    const raw = response.headers.getSetCookie?.()[0] ?? response.headers.get('set-cookie');
+    const pair = raw?.split(';')[0]?.trim();
+    return pair || undefined;
+}
+async function parseJson(response, context) {
+    const body = await response.text();
+    try {
+        return JSON.parse(body);
+    }
+    catch (error) {
+        throw new Error(`${context}: the server returned a non-JSON response (${error.message})`);
+    }
+}

package/dist/utils/hatch-contract.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A hand-written copy of the subset of Hatch's contract this CLI reads.
+ *
+ * Hatch's own `shared/contracts.ts` is an unpublished workspace file in a
+ * different repository; this package is released independently and cannot
+ * import it. Only what `xano hatch` consumes is copied here.
+ *
+ * It is a permissive superset on purpose: an activity `kind` or a phase this
+ * CLI has never heard of must degrade to "ignored", never to a throw, so a
+ * newer Hatch keeps working against an older CLI.
+ */
+export declare const BUILD_PHASES: readonly ["queued", "scaffolding", "backend", "frontend", "deploying", "done"];
+export type BuildPhase = (typeof BUILD_PHASES)[number];
+/** Phase copy, mirroring Hatch's `frontend/src/lib/labels.ts`. */
+export declare const PHASE_LABELS: Record<BuildPhase, string>;
+/** Falls back to the raw value so an unknown phase renders as itself. */
+export declare function phaseLabel(phase: string): string;
+/** The states a build can end in. Everything else is in-flight. */
+export declare const TERMINAL_OUTCOMES: readonly ["succeeded", "failed", "expired", "rejected"];
+export type TerminalOutcome = (typeof TERMINAL_OUTCOMES)[number];
+export type SessionState = 'building' | 'deploying' | 'draft' | 'provisioning' | 'queued' | TerminalOutcome;
+export declare function isTerminalOutcome(state: string): state is TerminalOutcome;
+export declare const ACTIVITY_KINDS: readonly ["phase", "narration", "artifact", "log", "heartbeat", "terminal"];
+export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
+export interface ActivityBase {
+    /** Epoch milliseconds, server-assigned. */
+    at: number;
+    kind: string;
+    /** Monotonic per-session sequence; doubles as the SSE `Last-Event-ID`. */
+    seq: number;
+}
+export interface PhaseActivity extends ActivityBase {
+    kind: 'phase';
+    phase: BuildPhase;
+}
+export interface NarrationActivity extends ActivityBase {
+    kind: 'narration';
+    message: string;
+}
+export interface ArtifactActivity extends ActivityBase {
+    action: 'created' | 'deleted' | 'failed' | 'modified';
+    kind: 'artifact';
+    path: string;
+}
+export interface LogActivity extends ActivityBase {
+    kind: 'log';
+    line: string;
+    role?: 'input' | 'output';
+    stream: 'stderr' | 'stdout';
+}
+export interface HeartbeatActivity extends ActivityBase {
+    elapsedInPhaseMs: number;
+    filesWritten: number;
+    kind: 'heartbeat';
+    lastAction: string;
+    phase: BuildPhase;
+}
+export interface TerminalActivity extends ActivityBase {
+    kind: 'terminal';
+    /** User-facing prose on any non-success outcome. */
+    message?: string;
+    outcome: TerminalOutcome;
+    /** Present only when `outcome === 'succeeded'`. */
+    siteUrl?: string;
+}
+export type KnownActivity = ArtifactActivity | HeartbeatActivity | LogActivity | NarrationActivity | PhaseActivity | TerminalActivity;
+/** An activity off the wire: known kinds are typed, anything else is inert. */
+export type Activity = ActivityBase | KnownActivity;
+export declare function isKnownActivity(activity: Activity): activity is KnownActivity;
+/** How a build ended — the one shape both the stream and the snapshot yield. */
+export interface BuildOutcome {
+    message?: string;
+    outcome: TerminalOutcome;
+    siteUrl?: string;
+}
+/** `POST /api/sessions` */
+export interface CreateSessionResponse {
+    sessionId: string;
+    state: SessionState;
+    /** Absolute, server-built, and present only when `?watch=1` was asked for. */
+    watchUrl?: string;
+}
+/** `GET /api/sessions/:id` */
+export interface SessionSnapshot {
+    createdAt: number;
+    failureMessage?: string;
+    phase: BuildPhase;
+    prompt: string;
+    sessionId: string;
+    siteUrl?: string;
+    state: SessionState;
+}

package/dist/utils/hatch-contract.js

@@ -0,0 +1,34 @@
+/**
+ * A hand-written copy of the subset of Hatch's contract this CLI reads.
+ *
+ * Hatch's own `shared/contracts.ts` is an unpublished workspace file in a
+ * different repository; this package is released independently and cannot
+ * import it. Only what `xano hatch` consumes is copied here.
+ *
+ * It is a permissive superset on purpose: an activity `kind` or a phase this
+ * CLI has never heard of must degrade to "ignored", never to a throw, so a
+ * newer Hatch keeps working against an older CLI.
+ */
+export const BUILD_PHASES = ['queued', 'scaffolding', 'backend', 'frontend', 'deploying', 'done'];
+/** Phase copy, mirroring Hatch's `frontend/src/lib/labels.ts`. */
+export const PHASE_LABELS = {
+    backend: 'Backend',
+    deploying: 'Deploying',
+    done: 'Done',
+    frontend: 'Frontend',
+    queued: 'Waiting',
+    scaffolding: 'Setting up',
+};
+/** Falls back to the raw value so an unknown phase renders as itself. */
+export function phaseLabel(phase) {
+    return PHASE_LABELS[phase] ?? phase;
+}
+/** The states a build can end in. Everything else is in-flight. */
+export const TERMINAL_OUTCOMES = ['succeeded', 'failed', 'expired', 'rejected'];
+export function isTerminalOutcome(state) {
+    return TERMINAL_OUTCOMES.includes(state);
+}
+export const ACTIVITY_KINDS = ['phase', 'narration', 'artifact', 'log', 'heartbeat', 'terminal'];
+export function isKnownActivity(activity) {
+    return ACTIVITY_KINDS.includes(activity.kind);
+}

package/dist/utils/hatch-render.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Turning a Hatch activity stream into what the terminal shows.
+ *
+ * Everything here is a pure function of `(state, activity)`, so the whole of
+ * `xano hatch`'s output can be tested with no socket, no TTY, and no clock.
+ *
+ * The fold emits two different things and the caller decides which to print:
+ *
+ * - `lines` — things that belong in the transcript no matter what (a completed
+ *   phase, the final block, a `--verbose` log line).
+ * - `status` — the current "what is happening right now" label.
+ *
+ * When the command is animating, `status` is the spinner label and only `lines`
+ * are printed. When it is not — a non-TTY, `--verbose`, a redirect to a file —
+ * there is no spinner to carry the status, so a *changed* status has to be
+ * printed as a plain line; otherwise a piped build shows one line per phase and
+ * nothing at all for the six minutes in between. {@link renderLines} is the one
+ * place that difference lives; the fold itself is identical in both modes.
+ */
+import type { Activity, BuildOutcome, TerminalOutcome } from './hatch-contract.js';
+/**
+ * The status before any activity arrives. Not empty on purpose: the gap between
+ * submitting a prompt and the first `phase` event is not short — the agent pool
+ * is small and a build behind a full one waits — and an empty terminal in that
+ * window reads as a crash.
+ */
+export declare const QUEUED_STATUS = "Queued";
+/** The one outcome the user can act on immediately, and the only one not about their prompt. */
+export declare const POOL_FULL_SENTENCE = "Hatch had no free build slot \u2014 try again shortly.";
+export interface RenderOptions {
+    /** Whether `log` activities are part of the transcript. */
+    verbose?: boolean;
+    /** Printed by the terminal blocks so a user always has somewhere to look. */
+    watchUrl?: string;
+}
+/** How a build ended, plus the process exit code that ending implies. */
+export interface RenderDone {
+    exitCode: number;
+    outcome: BuildOutcome;
+}
+export interface RenderState {
+    /** Artifacts seen so far. Counted, never printed inline. */
+    artifactCount: number;
+    /** Set once a `terminal` activity has been folded in; the fold stops there. */
+    done?: RenderDone;
+    /** Time in the current phase, per the last heartbeat. Decorates the status only. */
+    elapsedMs?: number;
+    /** Highest `seq` folded in, so a replayed prefix cannot double-count. */
+    lastSeq: number;
+    /** The raw phase value, kept so the next `phase` can flush it as completed. */
+    phase?: string;
+    /** The status without its elapsed decoration — this is what gets printed. */
+    statusText: string;
+}
+export interface RenderResult {
+    /** Present only on the activity that ended the build. */
+    done?: RenderDone;
+    /** Lines to print in either mode. */
+    lines: string[];
+    /** The state to fold the next activity into. */
+    state: RenderState;
+    /** The spinner label: {@link RenderState.statusText} plus any elapsed time. */
+    status: string;
+    /**
+     * Whether the status changed in a way worth printing. A heartbeat refreshing
+     * the elapsed time does not count — it would otherwise put a line in every
+     * piped build every few seconds.
+     */
+    statusChanged: boolean;
+    /** The undecorated status, which is what non-animated mode prints. */
+    statusText: string;
+}
+export declare function initialRenderState(): RenderState;
+/** 0 on success; 1 on every other ending. */
+export declare function exitCodeFor(outcome: TerminalOutcome): number;
+/** `1m 05s`, or `42s` under a minute. Only ever decorates a spinner label. */
+export declare function formatElapsed(ms: number): string;
+/**
+ * Printed before the stream opens, so a user who never sees another byte still
+ * has the link. Degrades to a link-free sentence against a Hatch deployed
+ * before `?watch=1` existed, rather than printing `undefined`.
+ */
+export declare function openingBlock(watchUrl?: string): string[];
+/**
+ * The success block. The URL sits alone on an indented line so it survives a
+ * copy-paste and a `| tail -1`.
+ *
+ * `siteUrl` is promised on success and the client still must not crash without
+ * it, so the watch link stands in.
+ */
+export declare function successBlock(outcome: BuildOutcome, watchUrl?: string): string[];
+/**
+ * The failure block, shared by `failed`, `expired`, and `rejected`. The
+ * difference between "the agent could not do it" and "it ran out of time" is on
+ * the page the watch link opens; pointing there beats paraphrasing it.
+ */
+export declare function failureBlock(outcome: BuildOutcome, watchUrl?: string): string[];
+/** The terminal block for any outcome. */
+export declare function terminalBlock(outcome: BuildOutcome, watchUrl?: string): string[];
+/**
+ * What the caller actually prints.
+ *
+ * Animated: only `lines` — `status` is on the spinner. Not animated: `lines`
+ * first, then the changed status as its own line, so a completed phase is
+ * reported before the one that replaced it.
+ */
+export declare function renderLines(result: RenderResult, options: {
+    animate: boolean;
+}): string[];
+/**
+ * A dropped connection is otherwise invisible — the elapsed counter is driven
+ * by server heartbeats, so during a backoff it simply freezes, which on a
+ * fifteen-minute command is indistinguishable from a hang.
+ *
+ * The attempt number is part of the status so each attempt reads as a change,
+ * and so non-animated mode prints once per attempt rather than once per drop.
+ */
+export declare function reduceReconnecting(state: RenderState, attempt: number): RenderResult;
+/**
+ * The fold. One activity in, the next state plus whatever it should print out.
+ *
+ * An unrecognized `kind` is ignored rather than thrown on: Hatch may add
+ * activity kinds, and an older CLI has to keep working against a newer server.
+ * A `seq` at or below the highest already folded in is ignored too — the caller
+ * drops replayed events by id, but a duplicate reaching here must not
+ * double-count an artifact or re-flush a phase.
+ */
+export declare function reduceActivity(state: RenderState, activity: Activity, options?: RenderOptions): RenderResult;

package/dist/utils/hatch-render.js

@@ -0,0 +1,183 @@
+/**
+ * Turning a Hatch activity stream into what the terminal shows.
+ *
+ * Everything here is a pure function of `(state, activity)`, so the whole of
+ * `xano hatch`'s output can be tested with no socket, no TTY, and no clock.
+ *
+ * The fold emits two different things and the caller decides which to print:
+ *
+ * - `lines` — things that belong in the transcript no matter what (a completed
+ *   phase, the final block, a `--verbose` log line).
+ * - `status` — the current "what is happening right now" label.
+ *
+ * When the command is animating, `status` is the spinner label and only `lines`
+ * are printed. When it is not — a non-TTY, `--verbose`, a redirect to a file —
+ * there is no spinner to carry the status, so a *changed* status has to be
+ * printed as a plain line; otherwise a piped build shows one line per phase and
+ * nothing at all for the six minutes in between. {@link renderLines} is the one
+ * place that difference lives; the fold itself is identical in both modes.
+ */
+import { isKnownActivity, phaseLabel } from './hatch-contract.js';
+/**
+ * The status before any activity arrives. Not empty on purpose: the gap between
+ * submitting a prompt and the first `phase` event is not short — the agent pool
+ * is small and a build behind a full one waits — and an empty terminal in that
+ * window reads as a crash.
+ */
+export const QUEUED_STATUS = 'Queued';
+/** The one outcome the user can act on immediately, and the only one not about their prompt. */
+export const POOL_FULL_SENTENCE = 'Hatch had no free build slot — try again shortly.';
+/** Fallback prose per outcome, used when the server sent no `message`. */
+const DEFAULT_FAILURE_MESSAGE = {
+    expired: 'The build ran out of time before it finished.',
+    failed: 'The build did not finish.',
+    rejected: 'The build could not be started.',
+};
+export function initialRenderState() {
+    return { artifactCount: 0, lastSeq: 0, statusText: QUEUED_STATUS };
+}
+/** 0 on success; 1 on every other ending. */
+export function exitCodeFor(outcome) {
+    return outcome === 'succeeded' ? 0 : 1;
+}
+/** `1m 05s`, or `42s` under a minute. Only ever decorates a spinner label. */
+export function formatElapsed(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
+    return minutes > 0 ? `${minutes}m ${String(seconds).padStart(2, '0')}s` : `${seconds}s`;
+}
+/**
+ * Printed before the stream opens, so a user who never sees another byte still
+ * has the link. Degrades to a link-free sentence against a Hatch deployed
+ * before `?watch=1` existed, rather than printing `undefined`.
+ */
+export function openingBlock(watchUrl) {
+    if (!watchUrl) {
+        return ['Your idea is being created. No follow-along link is available, so watch here.'];
+    }
+    return ['Your idea is being created, follow along for more details:', `  ${watchUrl}`];
+}
+/**
+ * The success block. The URL sits alone on an indented line so it survives a
+ * copy-paste and a `| tail -1`.
+ *
+ * `siteUrl` is promised on success and the client still must not crash without
+ * it, so the watch link stands in.
+ */
+export function successBlock(outcome, watchUrl) {
+    const url = outcome.siteUrl ?? watchUrl;
+    if (!url)
+        return ['Your project is complete.'];
+    return ['Your project is complete, you can view it at:', `  ${url}`];
+}
+/**
+ * The failure block, shared by `failed`, `expired`, and `rejected`. The
+ * difference between "the agent could not do it" and "it ran out of time" is on
+ * the page the watch link opens; pointing there beats paraphrasing it.
+ */
+export function failureBlock(outcome, watchUrl) {
+    const kind = outcome.outcome === 'succeeded' ? 'failed' : outcome.outcome;
+    const lines = [outcome.message?.trim() || DEFAULT_FAILURE_MESSAGE[kind]];
+    if (outcome.outcome === 'rejected')
+        lines.push(POOL_FULL_SENTENCE);
+    if (watchUrl)
+        lines.push('You can see what happened at:', `  ${watchUrl}`);
+    return lines;
+}
+/** The terminal block for any outcome. */
+export function terminalBlock(outcome, watchUrl) {
+    return outcome.outcome === 'succeeded' ? successBlock(outcome, watchUrl) : failureBlock(outcome, watchUrl);
+}
+/**
+ * What the caller actually prints.
+ *
+ * Animated: only `lines` — `status` is on the spinner. Not animated: `lines`
+ * first, then the changed status as its own line, so a completed phase is
+ * reported before the one that replaced it.
+ */
+export function renderLines(result, options) {
+    if (options.animate || !result.statusChanged)
+        return result.lines;
+    return [...result.lines, result.statusText];
+}
+/**
+ * A dropped connection is otherwise invisible — the elapsed counter is driven
+ * by server heartbeats, so during a backoff it simply freezes, which on a
+ * fifteen-minute command is indistinguishable from a hang.
+ *
+ * The attempt number is part of the status so each attempt reads as a change,
+ * and so non-animated mode prints once per attempt rather than once per drop.
+ */
+export function reduceReconnecting(state, attempt) {
+    return build(state, { elapsedMs: undefined, statusText: `Reconnecting… (attempt ${attempt})` });
+}
+/**
+ * The fold. One activity in, the next state plus whatever it should print out.
+ *
+ * An unrecognized `kind` is ignored rather than thrown on: Hatch may add
+ * activity kinds, and an older CLI has to keep working against a newer server.
+ * A `seq` at or below the highest already folded in is ignored too — the caller
+ * drops replayed events by id, but a duplicate reaching here must not
+ * double-count an artifact or re-flush a phase.
+ */
+export function reduceActivity(state, activity, options = {}) {
+    if (typeof activity.seq === 'number' && activity.seq <= state.lastSeq)
+        return build(state, {});
+    const seen = typeof activity.seq === 'number' ? { lastSeq: activity.seq } : {};
+    if (!isKnownActivity(activity))
+        return build(state, seen);
+    switch (activity.kind) {
+        case 'artifact': {
+            return build(state, { ...seen, artifactCount: state.artifactCount + 1 });
+        }
+        case 'heartbeat': {
+            // Refreshes the elapsed time in the status and nothing else. Notably it
+            // does not advance the phase, even though it carries one.
+            return build(state, { ...seen, elapsedMs: activity.elapsedInPhaseMs });
+        }
+        case 'log': {
+            return build(state, seen, options.verbose ? [activity.line] : []);
+        }
+        case 'narration': {
+            const label = state.phase === undefined ? undefined : phaseLabel(state.phase);
+            return build(state, {
+                ...seen,
+                statusText: label ? `${label} — ${activity.message}` : activity.message,
+            });
+        }
+        case 'phase': {
+            // The previous phase is only complete once another one starts, so this is
+            // where it gets flushed. The first phase has nothing to flush.
+            const previous = state.phase;
+            return build(state, { ...seen, elapsedMs: undefined, phase: activity.phase, statusText: phaseLabel(activity.phase) }, previous !== undefined && previous !== activity.phase ? [`✓ ${phaseLabel(previous)}`] : []);
+        }
+        case 'terminal': {
+            const outcome = {
+                ...(activity.message === undefined ? {} : { message: activity.message }),
+                outcome: activity.outcome,
+                ...(activity.siteUrl === undefined ? {} : { siteUrl: activity.siteUrl }),
+            };
+            const done = { exitCode: exitCodeFor(activity.outcome), outcome };
+            // The status is left alone: the final block says everything, and moving
+            // the status here would put a redundant line in a piped run.
+            return build(state, { ...seen, done, elapsedMs: undefined }, terminalBlock(outcome, options.watchUrl));
+        }
+        default: {
+            return build(state, seen);
+        }
+    }
+}
+/** Assembles a result, deriving `status` and `statusChanged` from the transition. */
+function build(state, changes, lines = []) {
+    const next = { ...state, ...changes };
+    const statusChanged = next.statusText !== state.statusText;
+    return {
+        ...(next.done === undefined ? {} : { done: next.done }),
+        lines,
+        state: next,
+        status: next.elapsedMs === undefined ? next.statusText : `${next.statusText} (${formatElapsed(next.elapsedMs)})`,
+        statusChanged,
+        statusText: next.statusText,
+    };
+}

package/dist/utils/paging.d.ts

@@ -92,25 +92,29 @@ export declare function collectAllPages<T>(fetchPage: (page: number) => Promise<
     onTruncate?: (collected: number) => void;
 }): Promise<T[]>;
 export interface PagingJson<T> {
-    count: number;
+    curPage?: number;
     items: T[];
-    next_page?: number;
-    page?: number;
-    per_page?: number;
-    prev_page?: number;
-    total?: number;
+    itemsTotal?: number;
+    nextPage?: number;
+    perPage?: number;
+    prevPage?: number;
 }
 /**
  * Build the `--output json` payload for a list command.
  *
+ * Field names mirror the Metadata API envelope exactly — `curPage`, `nextPage`,
+ * `prevPage`, `itemsTotal`, `items` — so a script can move between the CLI and
+ * the raw API without a translation layer. `perPage` is the one field the CLI
+ * injects: the API never echoes it back, and it is otherwise invisible when the
+ * user leaves the flag at its default.
+ *
  * Emits only fields the response actually proves, mirroring the footer's
- * honesty rule: `total` appears only when the server sent `itemsTotal`,
- * `next_page` only when the server computed it. `count` is always the number of
- * items in this payload and is the one figure that is unconditionally true.
+ * honesty rule: `itemsTotal` appears only when the server sent it, `nextPage`
+ * only when the server computed it.
  *
- * Without this, a script driving `--output json` sees a bare array and its only
- * available stop condition is `length < per_page` — precisely the page-fullness
- * inference this module refuses to make in the footer.
+ * Without this envelope, a script driving `--output json` sees a bare array and
+ * its only available stop condition is `length < perPage` — precisely the
+ * page-fullness inference this module refuses to make in the footer.
  */
 export declare function buildPagingJson<T>(list: NormalizedList<T>, options: {
     page?: number;