runcloud 0.1.15 → 0.1.17

package/dist/api.js

@@ -21,6 +21,9 @@ function parsedErrorDetail(body) {
     }
     catch {
     }
+    if (/<(?:!doctype|html)\b/i.test(body)) {
+        return 'the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer command';
+    }
     return body;
 }
 export class ApiClient {
@@ -69,6 +72,9 @@ export class ApiClient {
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
     }
+    put(path, body) {
+        return this.request('PUT', path, body);
+    }
     patch(path, body) {
         return this.request('PATCH', path, body);
     }
@@ -172,6 +178,14 @@ 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])}.`;
@@ -196,5 +210,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,10 +20,58 @@ 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;
 }
+async function resolveSandboxId(client, reference) {
+    const response = await client.get('/run-cloud/sandboxes');
+    const sandboxes = (response?.items ?? []);
+    const sandbox = sandboxes.find((item) => item.id === reference || item.name === reference);
+    if (sandbox?.id)
+        return sandbox.id;
+    return (await resolveBox(client, reference)).sandboxId ?? reference;
+}
+async function writeSandboxFile(client, sandboxId, path, content) {
+    const chunkSize = 512 * 1024;
+    const count = Math.max(1, Math.ceil(content.byteLength / chunkSize));
+    for (let index = 0; index < count; index += 1) {
+        const offset = index * chunkSize;
+        const chunk = content.subarray(offset, Math.min(content.byteLength, offset + chunkSize));
+        const response = await client.post(`/run-cloud/sandboxes/${encodeURIComponent(sandboxId)}/fs`, {
+            op: 'write',
+            path,
+            offset,
+            content: chunk.toString('base64'),
+            truncate: index === 0,
+        });
+        if (response?.error)
+            throw new Error(String(response.error));
+    }
+}
+async function readSandboxFile(client, sandboxId, path) {
+    const chunks = [];
+    let offset = 0;
+    for (;;) {
+        const response = await client.post(`/run-cloud/sandboxes/${encodeURIComponent(sandboxId)}/fs`, {
+            op: 'read',
+            path,
+            offset,
+            length: 512 * 1024,
+        });
+        if (response?.error)
+            throw new Error(String(response.error));
+        const chunk = Buffer.from(String(response?.content ?? ''), 'base64');
+        chunks.push(chunk);
+        const next = Number(response?.next_offset ?? offset + chunk.byteLength);
+        if (response?.eof === true || chunk.byteLength === 0)
+            break;
+        if (!Number.isSafeInteger(next) || next <= offset)
+            throw new Error('file read did not advance');
+        offset = next;
+    }
+    return Buffer.concat(chunks);
+}
 function sshHome() {
     const base = process.env.RUN_CLOUD_HOME || join(homedir(), '.run-cloud');
     return join(base, 'ssh');
@@ -174,7 +222,7 @@ export function registerAccessCommands(parent, opts = {}) {
     });
     parent
         .command('cp')
-        .description('Copy files with scp; prefix the remote path with a colon')
+        .description('Copy a file directly; prefix the remote path with a colon')
         .argument('<sandbox>', REFERENCE_HELP)
         .argument('<source>', 'local path or :/remote/path')
         .argument('<destination>', 'local path or :/remote/path')
@@ -185,6 +233,17 @@ export function registerAccessCommands(parent, opts = {}) {
             if (source.startsWith(':') === destination.startsWith(':')) {
                 throw new Error('Exactly one path must be remote (prefix it with :)');
             }
+            if (!cmdOpts.recursive) {
+                const client = api();
+                const sandboxId = await resolveSandboxId(client, reference);
+                if (source.startsWith(':')) {
+                    writeFileSync(destination, await readSandboxFile(client, sandboxId, source.slice(1)));
+                }
+                else {
+                    await writeSandboxFile(client, sandboxId, destination.slice(1), readFileSync(source));
+                }
+                return;
+            }
             const configured = await setupSsh(reference);
             const remote = (path) => path.startsWith(':') ? `${configured.alias}:${path.slice(1)}` : path;
             const args = [

package/dist/commands/image.js

@@ -1,6 +1,7 @@
-import { InvalidArgumentError } from 'commander';
+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() {
@@ -9,23 +10,44 @@ function runCloudApi() {
 }
 function print(value, opts) {
     if (opts.json) {
-        console.log(JSON.stringify(value, null, 2));
+        printJson(value);
         return;
     }
-    if (Array.isArray(value)) {
-        for (const item of value)
-            console.log(formatRecord(item));
-        return;
-    }
-    console.log(formatRecord(value));
+    console.log(renderImage(value));
 }
-function formatRecord(value) {
-    if (!value || typeof value !== 'object')
-        return String(value);
-    return Object.entries(value)
-        .filter(([, v]) => v !== undefined && v !== null)
-        .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
-        .join('\n');
+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 {
@@ -55,6 +77,8 @@ export async function pollImageRegistration(api, ref, opts = {}) {
         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) {
@@ -71,30 +95,51 @@ export function registerImage(program) {
         .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('--wait', 'poll until the image is ready or failed', false)
-        .option('--timeout <seconds>', `max time to wait with --wait, in seconds (default ${DEFAULT_WAIT_TIMEOUT_SECONDS})`, parseTimeoutSeconds, DEFAULT_WAIT_TIMEOUT_SECONDS)).action((opts) => run(async () => {
+        .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) {
+        if (!opts.wait || created?.state === 'ready') {
             print(created, opts);
             return;
         }
-        const finalRow = await pollImageRegistration(api, opts.ref, { timeoutMs: opts.timeout * 1000 });
+        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');
-        print(data?.items ?? [], opts);
+        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 () => {
-        print(await runCloudApi().post('/run-cloud/images/refresh', { ref }), opts);
+        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/run-cloud.js

@@ -6,148 +6,20 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
 import { ApiClient, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
-export const RUN_CLOUD_SKILL = `---
-name: run-cloud-ios-simulator
-description: Use run.cloud SDK and CLI workflows for iOS simulator and Android emulator sessions.
-version: 0.5.1
----
-
-# run.cloud Mobile Sessions
-
-Use this skill when a user asks an agent to create, inspect, smoke test, debug, or release an iOS simulator or Android emulator through run.cloud.
-
-## Requirements
-
-- Read SDK credentials from \`RUN_CLOUD_API_KEY\`. Never print it, commit it, or write it into a skill file. The SDK uses \`RUN_CLOUD_API_URL\` when set and otherwise defaults to \`https://api.run.cloud\`.
-- Authenticate the CLI with either a saved \`runcloud login\` credential or \`RUN_CLOUD_API_KEY\` together with \`RUN_CLOUD_API_URL\`. Do not require both a saved login and an API key.
-- The TypeScript SDK requires Node.js 20 or newer.
-- The account must have run.cloud access, available capacity, and organization credit.
-- App artifacts must match the target platform. iOS sessions need simulator-compatible builds; Android sessions need Android-compatible artifacts such as APKs.
-
-## TypeScript SDK
-
-Prefer \`@run-cloud/sdk\` for applications, CI, and agent code:
-
-\`\`\`bash
-npm install @run-cloud/sdk
-\`\`\`
-
-Use the platform client when the platform is known, and always release metered sessions in \`finally\`:
-
-\`\`\`ts
-import { Client } from "@run-cloud/sdk";
-
-const cloud = new Client();
-const session = await cloud.ios.create({
-  displayName: "Agent smoke",
-  labels: { owner: "agent" },
-  inactivityTimeout: "60s",
-});
-
-try {
-  await cloud.ios.openUrl(session.id, "https://run.cloud");
-  console.log(session.url);
-} finally {
-  await cloud.ios.delete(session.id);
+const RUN_CLOUD_SKILL_FILENAME = 'run-cloud-ios-simulator/SKILL.md';
+function loadRunCloudSkill() {
+    const commandDirectory = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(commandDirectory, '../../skills', RUN_CLOUD_SKILL_FILENAME),
+        resolve(commandDirectory, '../../../.claude/skills', RUN_CLOUD_SKILL_FILENAME),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return readFileSync(candidate, 'utf8');
+    }
+    throw new Error('run.cloud agent skill is missing from the package; reinstall runcloud or use npx skills add newly-app/run-cloud-examples --skill run-cloud-ios-simulator');
 }
-\`\`\`
-
-Use \`cloud.android\` for Android. When the platform is selected at runtime, use \`cloud.simulators\` and pass \`session.platform\` to \`get\`, \`openUrl\`, or \`delete\`.
-
-The implemented SDK surface is:
-
-- \`cloud.account()\`;
-- \`cloud.ios\` and \`cloud.android\`: \`create\`, \`list\`, \`get\`, \`openUrl\`, \`delete\`;
-- \`cloud.simulators\`: the same lifecycle with a runtime \`platform\` option;
-- \`cloud.assets\`: \`upload\`, \`list\`, \`delete\`.
-
-Do not invent screenshot, tap, typing, recording, app lifecycle, sandbox, build, or compatibility-adapter methods. Check the installed package types and https://docs.run.cloud/cli/typescript-sdk before using a method not listed here.
-
-## CLI Workflow
-
-Use the CLI for interactive terminal work. Authenticate with a saved login:
-
-\`\`\`bash
-npm install -g runcloud
-runcloud login
-\`\`\`
-
-Or authenticate non-interactively with both required environment variables:
-
-\`\`\`bash
-export RUN_CLOUD_API_KEY="rc_live_..."
-export RUN_CLOUD_API_URL="https://api.run.cloud"
-\`\`\`
-
-Then inspect the account:
-
-\`\`\`bash
-runcloud account --json
-\`\`\`
-
-Create, inspect, open a URL, and release an iOS session:
-
-\`\`\`bash
-runcloud ios create --install ./build/MyApp.tar.gz --json
-runcloud ios get "$SESSION_ID" --json
-runcloud ios open-url myapp://settings --id "$SESSION_ID"
-runcloud ios delete "$SESSION_ID" --json
-\`\`\`
-
-Use the corresponding \`runcloud android\` commands with an Android artifact for Android emulator sessions.
-
-Download checksum-verified onboarding artifacts when no local build is
-available:
-
-\`\`\`bash
-runcloud sample download ios
-runcloud ios create --install ./run-cloud-sample-ios.app.tar.gz
-
-runcloud sample download android
-runcloud android create --install ./run-cloud-sample-android.apk
-\`\`\`
-
-## Runnable SDK Example
-
-The maintained example checks account state, creates iOS and Android sessions, opens a URL on each, and releases both sessions:
-
-\`\`\`bash
-git clone --depth 1 https://github.com/newly-app/run-cloud-examples.git
-cd run-cloud-examples/sdk-ios-android
-npm install
-npm run demo -- --platform both --open
-\`\`\`
-
-Use \`--platform ios\` or \`--platform android\` for one platform. Use \`--json\` for machine-readable output. The example releases sessions on completion, failure, SIGINT, and SIGTERM unless the user explicitly passes \`--keep\`.
-
-## Bundled CLI Demos
-
-These published demos exercise multi-simulator workflows:
-
-\`\`\`bash
-runcloud demo run eight-device-mosaic --open
-runcloud demo run live-camera-relay --open
-\`\`\`
-
-They use the same CLI authentication choices described above and release every session automatically.
-
-## Embedded Iframes
-
-- Use \`inactivityTimeout: "60s"\` in the SDK, or \`--inactivity-timeout 60s\` in the CLI, when an embed should auto-close after user inactivity.
-- Omit the option or pass \`null\`/\`none\` when the user needs a metered session without idle auto-close.
-- Treat the returned signed session URL as a secret. Do not publish it in logs.
-- Iframes post \`ios-simulator:status\`, \`ios-simulator:auth-error\`, \`ios-simulator:session-ended\`, and \`ios-simulator:session-restart-requested\` messages to the parent window.
-- Verify \`event.source\` before acting on iframe messages.
-- When \`ios-simulator:session-restart-requested\` arrives, create a fresh session; do not reuse the ended iframe URL.
-
-## Rules
-
-- Prefer the SDK for code and \`--json\` CLI output for shell automation.
-- Always release sessions you create unless the user asks to keep them open.
-- If installation fails, verify that the artifact matches the target platform before attempting code changes.
-- Do not assume a local tunnel is installed on the user's machine.
-- Do not expose API keys, CLI tokens, signed simulator URLs, or simulator tokens in logs or screenshots.
-`;
+export const RUN_CLOUD_SKILL = loadRunCloudSkill();
 function client() {
     const creds = requireCredentials();
     return new ApiClient(creds.apiUrl, creds.token);
@@ -332,11 +204,29 @@ export async function runCloudDemo(name = 'eight-device-mosaic', opts = {}, load
 }
 async function pushAsset(path, opts = {}) {
     const { blob, name } = fileBlob(path);
-    const form = new FormData();
-    form.set('file', blob, name);
-    if (opts.name)
-        form.set('name', opts.name);
-    return (await client().uploadForm('/run-cloud/assets', form));
+    const api = client();
+    const prepared = await api.post('/run-cloud/assets/uploads', {
+        filename: name,
+        ...(opts.name ? { name: opts.name } : {}),
+        contentType: blob.type || 'application/octet-stream',
+        byteSize: blob.size,
+    });
+    try {
+        const uploaded = await fetch(prepared.upload.url, {
+            method: 'PUT',
+            headers: prepared.upload.headers,
+            body: blob,
+        });
+        if (!uploaded.ok)
+            throw new Error(`asset storage upload failed with HTTP ${uploaded.status}`);
+    }
+    catch (error) {
+        if (prepared.asset.id) {
+            await api.delete(`/run-cloud/assets/${encodeURIComponent(prepared.asset.id)}`).catch(() => undefined);
+        }
+        throw error;
+    }
+    return prepared.asset;
 }
 async function createSimulatorSession(platform, opts) {
     assertDevHostAllowed(opts.devHost);