runcloud 0.1.14 → 0.1.16

package/dist/api.js

@@ -172,12 +172,26 @@ function headline(err) {
         if (err.status === 403)
             return err.detail ? `Forbidden: ${err.detail}` : 'Forbidden.';
         if (err.status === 404) {
+            const snapshotRestoreMatch = err.path?.match(/^\/run-cloud\/snapshots\/([^/]+)\/restore$/);
+            if (snapshotRestoreMatch) {
+                const id = decodeURIComponent(snapshotRestoreMatch[1]);
+                if (/^sb(?:x)?_/.test(id)) {
+                    return `Snapshot ID not found: ${id}. \`sandbox restore\` expects a snapshot ID; to restart this sandbox, run \`runcloud sandbox resume ${id}\`.`;
+                }
+                return `Snapshot ID not found: ${id}.`;
+            }
             const sandboxMatch = err.path?.match(/^\/run-cloud\/sandboxes\/([^/]+)/);
             if (sandboxMatch) {
                 return `Sandbox ID not found: ${decodeURIComponent(sandboxMatch[1])}.`;
             }
-            if (!err.detail || /^not found$/i.test(err.detail.trim()))
-                return 'Resource not found.';
+            if (err.path?.startsWith('/run-cloud/images')) {
+                return 'Image not found — check the reference, and that it has been registered.';
+            }
+            if (!err.detail || /^not found$/i.test(err.detail.trim())) {
+                return err.path
+                    ? "This version of the CLI asked for something the server doesn't have."
+                    : 'Resource not found.';
+            }
             return err.detail;
         }
         if (err.status === 409)
@@ -190,5 +204,6 @@ function headline(err) {
 }
 export function friendlyApiError(err) {
     const message = headline(err);
-    return err instanceof ApiError ? message : `${message}${detailSuffix(err)}`;
+    const debug = process.env.RUNCLOUD_DEBUG === '1' || process.env.NEWLY_DEBUG === '1';
+    return !debug || err instanceof ApiError ? message : `${message}${detailSuffix(err)}`;
 }

package/dist/commands/boxAccess.js

@@ -20,7 +20,7 @@ async function resolveBox(client, reference) {
         item.name === reference ||
         item.hostname === reference);
     if (!box) {
-        throw new Error(`No exposed sandbox matches ${reference} — publish a hostname first: runcloud sandbox expose <id>`);
+        throw new Error(`No exposed sandbox matches ${reference}. Publish it first with \`runcloud sandbox expose ${reference} --name <name>\`, or use \`runcloud sandbox shell ${reference}\` without SSH.`);
     }
     return box;
 }

package/dist/commands/image.js

@@ -0,0 +1,145 @@
+import { InvalidArgumentError, Option } from 'commander';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+import { formatAge, formatState, printJson, renderDetails, renderTable, shortDigest, StatusLine, style, } from '../terminal.js';
+const POLL_INTERVAL_MS = 3_000;
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 1_200;
+function runCloudApi() {
+    const credentials = requireCredentials();
+    return new ApiClient(credentials.apiUrl, credentials.token);
+}
+function print(value, opts) {
+    if (opts.json) {
+        printJson(value);
+        return;
+    }
+    console.log(renderImage(value));
+}
+function renderImage(row, title) {
+    const heading = title ??
+        (row.state === 'ready'
+            ? '✓ Image ready'
+            : row.state === 'failed'
+                ? '✗ Image build failed'
+                : '◐ Image build started');
+    const footer = row.state === 'building'
+        ? `${style.dim('Follow:')}  runcloud image list`
+        : undefined;
+    return renderDetails(heading, [
+        { label: 'Reference', value: row.ref ?? row.name },
+        { label: 'State', value: formatState(row.state) },
+        { label: 'Digest', value: shortDigest(row.digest) },
+        { label: 'Created', value: formatAge(row.createdAt) },
+        { label: 'Error', value: row.error },
+    ], footer);
+}
+function renderImageList(rows) {
+    if (rows.length === 0) {
+        return `${style.bold('Images')}\n\nNo images registered.\n\n${style.dim('Register one:')}  runcloud image create --ref python:3.12-slim`;
+    }
+    return renderTable(`Images (${rows.length})`, [
+        { key: 'ref', label: 'REFERENCE', maxWidth: 44 },
+        { key: 'state', label: 'STATE', maxWidth: 12 },
+        { key: 'digest', label: 'DIGEST' },
+        { key: 'age', label: 'AGE' },
+    ], rows.map((row) => ({
+        ref: row.ref ?? row.name,
+        state: formatState(row.state),
+        digest: shortDigest(row.digest) ?? '—',
+        age: formatAge(row.createdAt) ?? '—',
+    })));
+}
+async function run(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+function withOutput(cmd) {
+    return cmd.option('--json', 'output JSON', false);
+}
+function parseTimeoutSeconds(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new InvalidArgumentError('--timeout must be a positive number of seconds');
+    }
+    return n;
+}
+const TERMINAL_STATES = new Set(['ready', 'failed']);
+export async function pollImageRegistration(api, ref, opts = {}) {
+    const intervalMs = opts.intervalMs ?? POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_SECONDS * 1000;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const data = await api.get('/run-cloud/images');
+        const items = (data?.items ?? []);
+        const row = items.find((item) => item.ref === ref || item.name === ref);
+        if (row)
+            opts.onState?.(row.state);
+        if (row && TERMINAL_STATES.has(row.state))
+            return row;
+        if (Date.now() > deadline) {
+            throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for image ${ref} to become ready`);
+        }
+        await new Promise((done) => setTimeout(done, intervalMs));
+    }
+}
+export function registerImage(program) {
+    const image = program
+        .command('image')
+        .description('Register and manage the OCI images run.cloud sandboxes boot from');
+    withOutput(image
+        .command('create')
+        .description('Register (build-once) an OCI image ref for run.cloud sandboxes')
+        .requiredOption('--ref <ref>', 'OCI image ref to register, e.g. python:3.12-slim')
+        .option('--no-wait', 'return after scheduling instead of waiting for the image build')
+        .option('--timeout <seconds>', 'max time to wait in seconds', parseTimeoutSeconds, DEFAULT_WAIT_TIMEOUT_SECONDS)
+        .addOption(new Option('--wait').hideHelp())).action((opts) => run(async () => {
+        const api = runCloudApi();
+        const created = await api.post('/run-cloud/images', { ref: opts.ref });
+        if (!opts.wait || created?.state === 'ready') {
+            print(created, opts);
+            return;
+        }
+        const status = opts.json ? undefined : new StatusLine();
+        status?.update(`Building ${opts.ref}`);
+        const finalRow = await pollImageRegistration(api, opts.ref, {
+            timeoutMs: opts.timeout * 1000,
+            onState: (state) => status?.update(state === 'building' ? `Building ${opts.ref}` : `${opts.ref} is ${state}`),
+        });
+        if (finalRow.state === 'failed') {
+            status?.fail(`Image build failed`);
+            throw new Error(finalRow.error
+                ? `image ${opts.ref} failed to build: ${finalRow.error}`
+                : `image ${opts.ref} failed to build`);
+        }
+        status?.clear();
+        print(finalRow, opts);
+    }));
+    withOutput(image.command('list').description('List images your organization has registered')).action((opts) => run(async () => {
+        const data = await runCloudApi().get('/run-cloud/images');
+        const rows = (data?.items ?? []);
+        if (opts.json)
+            printJson(rows);
+        else
+            console.log(renderImageList(rows));
+    }));
+    withOutput(image
+        .command('refresh')
+        .description("Move a tag's pin to its current upstream digest")
+        .argument('<ref>', 'OCI image ref to refresh')).action((ref, opts) => run(async () => {
+        const refreshed = await runCloudApi().post('/run-cloud/images/refresh', { ref });
+        if (opts.json)
+            printJson(refreshed);
+        else {
+            console.log(renderDetails('✓ Image refreshed', [
+                { label: 'Reference', value: refreshed?.ref ?? ref },
+                { label: 'Previous', value: shortDigest(refreshed?.old_digest) },
+                { label: 'Digest', value: shortDigest(refreshed?.new_digest ?? refreshed?.digest) },
+            ]));
+        }
+    }));
+}

package/dist/commands/sandbox.js

@@ -1,21 +1,27 @@
-import { InvalidArgumentError } from 'commander';
+import { Help, InvalidArgumentError } from 'commander';
 import { execFileSync } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { ApiClient, ApiError, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
 import { runSandboxShell } from '../shellSession.js';
+import { printJson, StatusLine, style } from '../terminal.js';
 import { noteDeprecated, registerAccessCommands } from './boxAccess.js';
+import { renderSandbox, renderSandboxList, } from './sandboxOutput.js';
 const MAX_SANDBOX_DISK_GIB = 2048;
 const DEFAULT_BOX_CPU_CORES = 2;
 const DEFAULT_BOX_MEMORY_MIB = 24 * 1024;
+const SANDBOX_POLL_INTERVAL_MS = 1_000;
+const SANDBOX_WAIT_TIMEOUT_MS = 20 * 60 * 1_000;
+const READY_STATES = new Set(['running']);
+const FAILED_STATES = new Set(['interrupted', 'stopped', 'destroyed']);
 function runCloudApi() {
     const credentials = requireCredentials();
     return new ApiClient(credentials.apiUrl, credentials.token);
 }
 function print(value, opts) {
     if (opts.json) {
-        console.log(JSON.stringify(value, null, 2));
+        printJson(value);
         return;
     }
     if (Array.isArray(value)) {
@@ -25,6 +31,53 @@ function print(value, opts) {
     }
     console.log(formatRecord(value));
 }
+function sandboxStatusMessage(state) {
+    if (state === 'building_image')
+        return 'Building image';
+    if (state === 'pending')
+        return 'Waiting for capacity';
+    if (state === 'starting')
+        return 'Starting sandbox';
+    if (state === 'archived')
+        return 'Restoring sandbox';
+    return `Sandbox is ${state.replaceAll('_', ' ')}`;
+}
+export async function pollSandboxReady(api, id, opts = {}) {
+    const intervalMs = opts.intervalMs ?? SANDBOX_POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? SANDBOX_WAIT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const record = (await api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`));
+        const state = record.state ?? 'unknown';
+        opts.onState?.(state);
+        if (READY_STATES.has(state))
+            return record;
+        if (FAILED_STATES.has(state)) {
+            throw new Error(`sandbox ${id} entered ${state.replaceAll('_', ' ')} state`);
+        }
+        if (Date.now() > deadline) {
+            throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for sandbox ${id} to start`);
+        }
+        await new Promise((done) => setTimeout(done, intervalMs));
+    }
+}
+export async function prepareSandboxShell(api, id, status = new StatusLine()) {
+    let record = (await api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`));
+    if (record.state === 'paused' || record.state === 'archived') {
+        status.update(`Resuming ${id}`);
+        record = (await api.post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/resume`));
+        if (record.state !== 'running') {
+            record = await pollSandboxReady(api, id, {
+                onState: (state) => status.update(sandboxStatusMessage(state)),
+            });
+        }
+        status.succeed(`Resumed ${id}`);
+    }
+    if (record.state !== 'running') {
+        status.clear();
+        throw new Error(`sandbox ${id} is ${String(record.state).replaceAll('_', ' ')}; wait until it is running`);
+    }
+}
 function formatRecord(value) {
     if (!value || typeof value !== 'object')
         return String(value);
@@ -107,6 +160,16 @@ function attachHostname(api, sandboxId, name, port) {
 }
 export function registerSandbox(program) {
     const sandbox = program.command('sandbox').description('Spawn and control microVM sandboxes');
+    const defaultHelp = new Help();
+    sandbox.configureHelp({
+        subcommandTerm: (command) => {
+            const term = defaultHelp.subcommandTerm(command);
+            const aliases = command.aliases();
+            if (aliases.length < 2)
+                return term;
+            return term.replace(`${command.name()}|${aliases[0]}`, `${command.name()}|${aliases.join('|')}`);
+        },
+    });
     withOutput(sandbox
         .command('create')
         .description('Spawn a microVM sandbox')
@@ -119,7 +182,8 @@ export function registerSandbox(program) {
         .option('--disk <gb>', 'root disk capacity in GiB', parseDiskGb)
         .option('--idle-pause <seconds>', 'pause after inactivity; 0 keeps it running', parseIdlePauseSeconds)
         .option('--persistent', 'never pause when idle (same as --idle-pause 0)', false)
-        .option('--expose <port>', 'publish a guest port at <name>-box.run.cloud; implies --persistent', parsePort)).action((opts) => run(async () => {
+        .option('--expose <port>', 'publish a guest port at <name>-box.run.cloud; implies --persistent', parsePort)
+        .option('--no-wait', 'return before the sandbox finishes building and starting')).action((opts) => run(async () => {
         const exposed = opts.expose !== undefined;
         if (exposed && !opts.name) {
             throw new Error('--expose needs --name <name>, the hostname prefix for <name>-box.run.cloud');
@@ -149,29 +213,58 @@ export function registerSandbox(program) {
         else if (opts.idlePause !== undefined)
             body.idlePauseSeconds = opts.idlePause;
         const api = runCloudApi();
-        const created = await api.post('/run-cloud/sandboxes', body);
+        let created = (await api.post('/run-cloud/sandboxes', body));
+        if (typeof created.id !== 'string') {
+            throw new Error('sandbox create response did not include an id');
+        }
+        if (!opts.json && opts.wait && created.state && !READY_STATES.has(created.state)) {
+            const status = new StatusLine();
+            status.update(sandboxStatusMessage(created.state));
+            try {
+                created = await pollSandboxReady(api, created.id, {
+                    onState: (state) => status.update(sandboxStatusMessage(state)),
+                });
+                status.clear();
+            }
+            catch (err) {
+                status.fail('Sandbox failed to start');
+                throw err;
+            }
+        }
         if (!exposed) {
-            print(created, opts);
+            if (opts.json)
+                printJson(created);
+            else
+                console.log(renderSandbox(created, 'created'));
             return;
         }
-        if (typeof created?.id !== 'string')
-            throw new Error('sandbox create response did not include an id');
         const box = await attachHostname(api, created.id, opts.name, opts.expose);
-        print({ ...created, box }, opts);
+        const exposedRecord = { ...created, box };
+        if (opts.json)
+            printJson(exposedRecord);
+        else
+            console.log(renderSandbox(exposedRecord, 'created'));
     }));
     withOutput(sandbox.command('list').description('List sandboxes').option('--state <state>', 'filter by state')).action((opts) => run(async () => {
         const qs = opts.state ? `?state=${encodeURIComponent(opts.state)}` : '';
         const api = runCloudApi();
         const [data, boxes] = await Promise.all([
             api.get(`/run-cloud/sandboxes${qs}`),
-            api.get('/run-cloud/boxes'),
+            api.get('/run-cloud/boxes').catch((err) => {
+                if (err instanceof ApiError && err.status === 404)
+                    return { items: [] };
+                throw err;
+            }),
         ]);
         const bySandbox = new Map((boxes?.items ?? []).map((box) => [box.sandboxId, box]));
         const items = (data?.items ?? []).map((item) => {
             const box = bySandbox.get(item.id);
             return box ? { ...item, hostname: box.hostname, exposedPort: box.port } : item;
         });
-        print(items, opts);
+        if (opts.json)
+            printJson(items);
+        else
+            console.log(renderSandboxList(items));
     }));
     withOutput(sandbox
         .command('get')
@@ -182,7 +275,11 @@ export function registerSandbox(program) {
             api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`),
             findBoxForSandbox(api, id),
         ]);
-        print(box ? { ...record, box } : record, opts);
+        const sandboxRecord = (box ? { ...record, box } : record);
+        if (opts.json)
+            printJson(sandboxRecord);
+        else
+            console.log(renderSandbox(sandboxRecord));
     }));
     withOutput(sandbox
         .command('expose')
@@ -240,16 +337,44 @@ export function registerSandbox(program) {
     }));
     sandbox
         .command('shell')
-        .description('Open an interactive shell in a running sandbox')
+        .description('Open an interactive shell (resumes paused sandboxes)')
         .argument('<id>', 'sandbox id')
         .action((id) => run(async () => {
         const credentials = requireCredentials();
+        const api = new ApiClient(credentials.apiUrl, credentials.token);
+        await prepareSandboxShell(api, id);
         process.exitCode = await runSandboxShell({
             apiUrl: credentials.apiUrl,
             token: credentials.token,
             sandboxId: id,
         });
     }));
+    for (const lifecycle of [
+        {
+            name: 'pause',
+            alias: 'stop',
+            description: 'Pause a sandbox so it can be resumed later',
+            pastTense: 'Paused',
+        },
+        {
+            name: 'resume',
+            alias: 'start',
+            description: 'Resume a paused sandbox',
+            pastTense: 'Resumed',
+        },
+    ]) {
+        withOutput(sandbox
+            .command(lifecycle.name)
+            .alias(lifecycle.alias)
+            .description(lifecycle.description)
+            .argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+            const record = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/${lifecycle.name}`);
+            if (opts.json)
+                printJson(record);
+            else
+                console.log(`${style.green('✓')} ${lifecycle.pastTense} ${id}`);
+        }));
+    }
     withOutput(sandbox
         .command('logs')
         .description('Show recent sandbox logs (one-shot journalctl tail; streaming is a follow-up)')
@@ -337,7 +462,8 @@ export function registerSandbox(program) {
     }));
     withOutput(sandbox
         .command('rm')
-        .description('Destroy a sandbox, along with its public hostname when exposed')
+        .aliases(['kill', 'terminate'])
+        .description('Permanently destroy a sandbox and its public hostname when exposed')
         .argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
         const api = runCloudApi();
         try {
@@ -352,7 +478,7 @@ export function registerSandbox(program) {
             await api.delete(`/run-cloud/boxes/${encodeURIComponent(box.id)}`);
         }
         if (!opts.json)
-            console.log(`destroyed ${id}`);
+            console.log(`${style.green('✓')} Destroyed ${id}`);
     }));
     const snapshot = sandbox.command('snapshot').description('Capture and manage sandbox snapshots');
     withOutput(snapshot
@@ -392,7 +518,11 @@ export function registerSandbox(program) {
             body.disk = opts.disk;
         if (opts.region)
             body.region = opts.region;
-        print(await runCloudApi().post(`/run-cloud/snapshots/${encodeURIComponent(snapshotId)}/restore`, body), opts);
+        const restored = await runCloudApi().post(`/run-cloud/snapshots/${encodeURIComponent(snapshotId)}/restore`, body);
+        if (opts.json)
+            printJson(restored);
+        else
+            console.log(renderSandbox(restored, 'restored'));
     }));
     registerAccessCommands(sandbox);
     const box = program

package/dist/commands/sandboxOutput.js

@@ -0,0 +1,70 @@
+import { formatAge, formatCpu, formatMib, formatSeconds, formatState, renderDetails, renderTable, shortDigest, style, } from '../terminal.js';
+function resources(record) {
+    const memory = formatMib(record.mem_mb);
+    const disk = formatMib(record.disk_mb);
+    return [
+        formatCpu(record.milli_cpu),
+        memory ? `${memory} memory` : undefined,
+        disk ? `${disk} disk` : undefined,
+    ]
+        .filter(Boolean)
+        .join(' · ') || undefined;
+}
+function hostname(record) {
+    const host = record.hostname ?? record.box?.hostname;
+    const port = record.exposedPort ?? record.box?.port;
+    return host && port ? `${host}:${port}` : host;
+}
+function title(record, verb) {
+    if (verb === 'details')
+        return 'Sandbox';
+    if (record.state === 'running')
+        return `✓ Sandbox ${verb === 'restored' ? 'restored' : 'ready'}`;
+    if (record.state === 'building_image')
+        return '◐ Sandbox is building its image';
+    if (record.state === 'paused' || record.state === 'archived')
+        return '○ Sandbox paused';
+    return verb === 'restored' ? 'Sandbox restored' : 'Sandbox created';
+}
+export function renderSandbox(record, verb = 'details') {
+    const next = verb === 'details'
+        ? undefined
+        : record.state === 'running'
+            ? `${style.dim('Next:')}  runcloud sandbox shell ${record.id}`
+            : `${style.dim('Follow:')}  runcloud sandbox get ${record.id}`;
+    return renderDetails(title(record, verb), [
+        { label: 'ID', value: record.id },
+        { label: 'Name', value: record.name },
+        { label: 'State', value: formatState(record.state) },
+        { label: 'Image', value: record.image },
+        { label: 'Resources', value: resources(record) },
+        { label: 'Idle pause', value: formatSeconds(record.idle_pause_seconds) },
+        { label: 'Timeout', value: formatSeconds(record.timeout_seconds) },
+        { label: 'Hostname', value: hostname(record) },
+        { label: 'Image digest', value: shortDigest(record.image_digest) },
+        { label: 'Created', value: formatAge(record.created_at) },
+        { label: 'Last active', value: verb === 'details' ? formatAge(record.last_active_at) : undefined },
+    ], next);
+}
+export function renderSandboxList(records) {
+    if (records.length === 0) {
+        return `${style.bold('Sandboxes')}\n\nNo sandboxes found.\n\n${style.dim('Create one:')}  runcloud sandbox create`;
+    }
+    return renderTable(`Sandboxes (${records.length})`, [
+        { key: 'id', label: 'ID', maxWidth: 24 },
+        { key: 'name', label: 'NAME / HOSTNAME', maxWidth: 20 },
+        { key: 'state', label: 'STATE', maxWidth: 14 },
+        { key: 'image', label: 'IMAGE', maxWidth: 20 },
+        { key: 'resources', label: 'CPU / MEMORY', maxWidth: 18 },
+        { key: 'age', label: 'AGE' },
+    ], records.map((record) => ({
+        id: record.id,
+        name: hostname(record) ?? record.name ?? '—',
+        state: formatState(record.state),
+        image: record.image ?? '—',
+        resources: [formatCpu(record.milli_cpu)?.replace(' CPU', ''), formatMib(record.mem_mb)]
+            .filter(Boolean)
+            .join(' / ') || '—',
+        age: formatAge(record.created_at) ?? '—',
+    })));
+}

package/dist/run-cloud.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { registerImage } from './commands/image.js';
 import { registerLogin } from './commands/login.js';
 import { registerRunCloud } from './commands/run-cloud.js';
 import { registerSandbox } from './commands/sandbox.js';
@@ -10,4 +11,5 @@ const program = new Command('runcloud')
 registerLogin(program);
 registerRunCloud(program);
 registerSandbox(program);
+registerImage(program);
 await program.parseAsync(process.argv);

package/dist/terminal.js

@@ -0,0 +1,158 @@
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+function supportsColor(stream) {
+    return stream.isTTY === true && process.env.NO_COLOR === undefined;
+}
+function paint(code, value, stream = process.stdout) {
+    return supportsColor(stream) ? `\u001b[${code}m${value}\u001b[0m` : value;
+}
+export const style = {
+    bold: (value, stream) => paint(1, value, stream),
+    dim: (value, stream) => paint(2, value, stream),
+    red: (value, stream) => paint(31, value, stream),
+    green: (value, stream) => paint(32, value, stream),
+    yellow: (value, stream) => paint(33, value, stream),
+    blue: (value, stream) => paint(34, value, stream),
+    cyan: (value, stream) => paint(36, value, stream),
+};
+function visibleLength(value) {
+    return value.replace(ANSI_PATTERN, '').length;
+}
+function truncate(value, maxWidth) {
+    if (!maxWidth || visibleLength(value) <= maxWidth)
+        return value;
+    if (maxWidth <= 1)
+        return '…';
+    return `${value.slice(0, maxWidth - 1)}…`;
+}
+function pad(value, width) {
+    return `${value}${' '.repeat(Math.max(0, width - visibleLength(value)))}`;
+}
+export function renderTable(title, columns, rows) {
+    if (rows.length === 0)
+        return title;
+    const cells = rows.map((row) => Object.fromEntries(columns.map((column) => [
+        column.key,
+        truncate(row[column.key] === undefined || row[column.key] === null ? '—' : String(row[column.key]), column.maxWidth),
+    ])));
+    const widths = Object.fromEntries(columns.map((column) => [
+        column.key,
+        Math.max(visibleLength(column.label), ...cells.map((row) => visibleLength(row[column.key]))),
+    ]));
+    const line = (row) => columns
+        .map((column, index) => {
+        const value = row[column.key];
+        return index === columns.length - 1 ? value : pad(value, widths[column.key]);
+    })
+        .join('  ')
+        .trimEnd();
+    const header = Object.fromEntries(columns.map((column) => [column.key, style.dim(column.label)]));
+    return `${style.bold(title)}\n\n${line(header)}\n${cells.map((row) => line(row)).join('\n')}`;
+}
+export function renderDetails(title, fields, footer) {
+    const visibleFields = fields.filter(({ value }) => value !== undefined && value !== null && value !== '');
+    const labelWidth = Math.max(...visibleFields.map(({ label }) => label.length), 0);
+    const lines = visibleFields.map(({ label, value }) => `  ${style.dim(pad(label, labelWidth))}  ${String(value)}`);
+    return [style.bold(title), ...lines, footer ? `\n${footer}` : undefined]
+        .filter((value) => value !== undefined)
+        .join('\n');
+}
+export function formatState(state) {
+    const value = typeof state === 'string' && state ? state : 'unknown';
+    if (value === 'running' || value === 'ready')
+        return style.green(value);
+    if (['building', 'building_image', 'pending', 'starting', 'destroying'].includes(value)) {
+        return style.yellow(value.replaceAll('_', ' '));
+    }
+    if (value === 'paused' || value === 'archived' || value === 'stopped') {
+        return style.blue(value);
+    }
+    if (value === 'failed' || value === 'interrupted' || value === 'destroyed') {
+        return style.red(value);
+    }
+    return value.replaceAll('_', ' ');
+}
+function rounded(value, fractionDigits = 1) {
+    return Number.isInteger(value) ? String(value) : value.toFixed(fractionDigits).replace(/\.0$/, '');
+}
+export function formatCpu(milliCpu) {
+    if (typeof milliCpu !== 'number' || !Number.isFinite(milliCpu))
+        return undefined;
+    return `${rounded(milliCpu / 1000, 3)} CPU`;
+}
+export function formatMib(mebibytes) {
+    if (typeof mebibytes !== 'number' || !Number.isFinite(mebibytes))
+        return undefined;
+    if (mebibytes >= 1024)
+        return `${rounded(mebibytes / 1024)} GiB`;
+    return `${rounded(mebibytes)} MiB`;
+}
+export function formatSeconds(seconds) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds))
+        return undefined;
+    if (seconds === 0)
+        return 'never';
+    if (seconds < 60)
+        return `${rounded(seconds)}s`;
+    if (seconds < 3600)
+        return `${rounded(seconds / 60)}m`;
+    if (seconds < 86_400)
+        return `${rounded(seconds / 3600)}h`;
+    return `${rounded(seconds / 86_400)}d`;
+}
+export function formatAge(value, now = Date.now()) {
+    if (typeof value !== 'string')
+        return undefined;
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return value;
+    const seconds = Math.max(0, Math.floor((now - timestamp) / 1000));
+    if (seconds < 5)
+        return 'just now';
+    return `${formatSeconds(seconds)} ago`;
+}
+export function shortDigest(value) {
+    if (typeof value !== 'string' || !value)
+        return undefined;
+    const digest = value.startsWith('sha256:') ? value.slice(7) : value;
+    return digest.slice(0, 12);
+}
+export function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+export class StatusLine {
+    lastMessage;
+    frame = 0;
+    update(message) {
+        if (process.stderr.isTTY) {
+            const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+            const prefix = style.cyan(frames[this.frame++ % frames.length], process.stderr);
+            process.stderr.write(`\r\u001b[2K${prefix} ${message}`);
+            this.lastMessage = message;
+            return;
+        }
+        if (message !== this.lastMessage) {
+            process.stderr.write(`→ ${message}\n`);
+            this.lastMessage = message;
+        }
+    }
+    succeed(message) {
+        this.finish(`${style.green('✓', process.stderr)} ${message}`);
+    }
+    fail(message) {
+        this.finish(`${style.red('✗', process.stderr)} ${message}`);
+    }
+    clear() {
+        if (process.stderr.isTTY && this.lastMessage)
+            process.stderr.write('\r\u001b[2K');
+        this.lastMessage = undefined;
+    }
+    finish(message) {
+        if (process.stderr.isTTY && this.lastMessage) {
+            process.stderr.write(`\r\u001b[2K${message}\n`);
+        }
+        else {
+            process.stderr.write(`${message}\n`);
+        }
+        this.lastMessage = undefined;
+    }
+}

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.14';
+export const CLI_VERSION = '0.1.16';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [