@newly/cli 0.1.2 → 0.1.27

package/dist/commands/run-cloud.js

@@ -1,47 +1,45 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { Option } from 'commander';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
 import { ApiClient, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
-const RUN_CLOUD_SKILL = `---
-name: run-cloud-ios-simulator
-description: Build, install, and inspect iOS apps with run.cloud remote simulator sessions.
-version: 0.1.0
----
-
-# run.cloud iOS Simulator
-
-Use this skill when a user asks an agent to run, inspect, smoke test, or debug an iOS app in a remote simulator through run.cloud.
-
-## Requirements
-
-- The user must be authenticated with \`runcloud login\`.
-- The account must have run.cloud access and a positive run.cloud balance.
-- App artifacts should be simulator-compatible builds. Device App Store IPAs may fail to install on iOS Simulator.
-
-## Workflow
-
-1. Check access with \`runcloud account --json\`.
-2. Create a simulator with \`runcloud ios create --install ./build/MyApp.tar.gz --json\`.
-3. Save the returned session id and URL.
-4. Use \`runcloud ios open-url <url> --id <session-id>\` when a URL or deep link must be opened.
-5. Release the session with \`runcloud ios delete <session-id>\`.
-
-## Embedded Iframes
-
-- Use \`runcloud ios create --inactivity-timeout 60s --json\` when the embed should auto-close after user inactivity.
-- Omit \`--inactivity-timeout\` or pass \`none\` when the user needs a metered session without idle auto-close.
-- Iframes post \`ios-simulator:status\`, \`ios-simulator:auth-error\`, \`ios-simulator:session-ended\`, and \`ios-simulator:session-restart-requested\` to the parent window. Verify \`event.source\` before acting.
-- If \`ios-simulator:session-restart-requested\` arrives, create a fresh run.cloud session; do not reuse the ended iframe URL.
-
-## Rules
-
-- Prefer \`--json\` for parsed output.
-- Always release sessions you create unless the user asks to keep them open.
-- If installation fails, verify that the artifact is a simulator build before attempting code changes.
-- Do not assume a local tunnel is installed on the user's machine.
-- Do not expose iOS simulator tokens in logs or screenshots.
-`;
+export const RUN_CLOUD_SKILL_NAMES = [
+    'run-cloud',
+    'run-cloud-ios-simulator',
+    'run-cloud-sandboxes',
+];
+const RUN_CLOUD_SKILL_FILE_NAMES = ['SKILL.md', 'agents/openai.yaml'];
+function loadRunCloudSkillFiles(skillName) {
+    const embedded = globalThis.__RUN_CLOUD_EMBEDDED_SKILLS__?.[skillName];
+    if (embedded)
+        return embedded;
+    const commandDirectory = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(commandDirectory, '../../skills', skillName),
+        resolve(commandDirectory, '../../../.claude/skills', skillName),
+    ];
+    for (const candidate of candidates) {
+        if (RUN_CLOUD_SKILL_FILE_NAMES.every((filename) => existsSync(join(candidate, filename)))) {
+            return Object.fromEntries(RUN_CLOUD_SKILL_FILE_NAMES.map((filename) => [
+                filename,
+                readFileSync(join(candidate, filename), 'utf8'),
+            ]));
+        }
+    }
+    throw new Error(`run.cloud agent skill ${skillName} is missing from the package; reinstall runcloud or use npx skills add newly-app/run-cloud-examples`);
+}
+const RUN_CLOUD_SKILL_FILES = Object.fromEntries(RUN_CLOUD_SKILL_NAMES.map((skillName) => [
+    skillName,
+    loadRunCloudSkillFiles(skillName),
+]));
+export const RUN_CLOUD_SKILLS = Object.fromEntries(RUN_CLOUD_SKILL_NAMES.map((skillName) => [
+    skillName,
+    RUN_CLOUD_SKILL_FILES[skillName]['SKILL.md'],
+]));
+export const RUN_CLOUD_SKILL = RUN_CLOUD_SKILLS['run-cloud-ios-simulator'];
 function client() {
     const creds = requireCredentials();
     return new ApiClient(creds.apiUrl, creds.token);
@@ -106,117 +104,329 @@ function skillBase(agent, scope) {
         return join(homedir(), '.agents', 'skills');
     throw new Error(`Unsupported agent: ${agent}`);
 }
-function installSkill(opts) {
+function installSkills(opts) {
     const agents = opts.agents?.length ? opts.agents : ['claude', 'codex', 'cursor'];
     const scope = opts.scope ?? 'project';
+    const targets = agents.flatMap((agent) => RUN_CLOUD_SKILL_NAMES.map((skill) => ({
+        agent,
+        skill,
+        path: join(skillBase(agent, scope), skill),
+    })));
+    if (!opts.force) {
+        const existing = targets.find((target) => existsSync(target.path));
+        if (existing) {
+            throw new Error(`${existing.path} already exists. Pass --force to overwrite.`);
+        }
+    }
     const results = [];
-    for (const agent of agents) {
-        const target = join(skillBase(agent, scope), 'run-cloud-ios-simulator');
-        if (existsSync(target)) {
-            if (!opts.force)
-                throw new Error(`${target} already exists. Pass --force to overwrite.`);
+    for (const { agent, skill, path: target } of targets) {
+        if (existsSync(target))
             rmSync(target, { recursive: true, force: true });
+        for (const filename of RUN_CLOUD_SKILL_FILE_NAMES) {
+            const destination = join(target, filename);
+            mkdirSync(dirname(destination), { recursive: true });
+            writeFileSync(destination, RUN_CLOUD_SKILL_FILES[skill][filename]);
         }
-        mkdirSync(target, { recursive: true });
-        writeFileSync(join(target, 'SKILL.md'), RUN_CLOUD_SKILL);
-        results.push({ agent, path: target, status: 'installed' });
+        results.push({ agent, skill, path: target, status: 'installed' });
     }
     return results;
 }
+const RUN_CLOUD_DEMOS = [
+    'eight-device-mosaic',
+    'live-camera-relay',
+];
+export const RUN_CLOUD_SAMPLES = {
+    ios: {
+        filename: 'run-cloud-sample-ios.app.tar.gz',
+        url: 'https://run.cloud/downloads/run-cloud-sample-ios.app.tar.gz',
+        sha256: '09c437b1f299d41f79a8453611d99b8b1e4a3f5198dd871f4dad183362f944b3',
+        byteSize: 19_516,
+    },
+    android: {
+        filename: 'run-cloud-sample-android.apk',
+        url: 'https://run.cloud/downloads/run-cloud-sample-android.apk',
+        sha256: '892d4441a24757fc88852d29abe87d42d14f04921cbe89802e369dad6e46edba',
+        byteSize: 6_521_225,
+    },
+};
+function samplePlatform(value) {
+    if (value === 'ios' || value === 'android')
+        return value;
+    throw new Error(`Unknown sample platform: ${value}. Choose ios or android.`);
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export async function downloadRunCloudSample(rawPlatform, opts = {}, fetchSample = fetch, samples = RUN_CLOUD_SAMPLES) {
+    const platform = samplePlatform(rawPlatform);
+    const sample = samples[platform];
+    const target = resolve(opts.output ?? sample.filename);
+    if (existsSync(target) && !opts.force) {
+        throw new Error(`${target} already exists. Pass --force to overwrite it.`);
+    }
+    const response = await fetchSample(sample.url);
+    if (!response.ok) {
+        throw new Error(`Could not download the ${platform} sample: HTTP ${response.status}`);
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    const sha256 = createHash('sha256').update(body).digest('hex');
+    if (body.byteLength !== sample.byteSize || sha256 !== sample.sha256) {
+        throw new Error(`The ${platform} sample failed its checksum verification.`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, body);
+    return {
+        platform,
+        path: target,
+        url: sample.url,
+        sha256,
+        byteSize: body.byteLength,
+        next: `runcloud ${platform} create --install ${shellQuote(target)}`,
+    };
+}
+function experimentalWebRtcEnabled() {
+    return ['1', 'true', 'yes', 'on'].includes((process.env.RUN_CLOUD_EXPERIMENTAL_WEBRTC ?? '').trim().toLowerCase());
+}
+function assertDevHostAllowed(devHost) {
+    if (devHost && process.env.RUN_CLOUD_DEV_FEATURES !== '1') {
+        throw new Error('--dev-host is dev-only; set RUN_CLOUD_DEV_FEATURES=1 to use it');
+    }
+}
+function requestedCodec(codec) {
+    const value = codec?.trim().toLowerCase() || 'auto';
+    if (value === 'webrtc' && !experimentalWebRtcEnabled()) {
+        throw new Error('--codec webrtc is experimental; set RUN_CLOUD_EXPERIMENTAL_WEBRTC=1 to use it');
+    }
+    return value;
+}
+function demoDirectory(name) {
+    if (!RUN_CLOUD_DEMOS.some((demoName) => demoName === name)) {
+        throw new Error(`Unknown demo: ${name}. Available demos: ${RUN_CLOUD_DEMOS.join(', ')}`);
+    }
+    const source = resolve(dirname(fileURLToPath(import.meta.url)), '../../examples', name);
+    if (!existsSync(source))
+        throw new Error(`The ${name} demo is missing from this runcloud package.`);
+    return source;
+}
+export function initRunCloudDemo(name = 'eight-device-mosaic', directory, opts = {}) {
+    const source = demoDirectory(name);
+    const target = resolve(directory ?? `run-cloud-${name}`);
+    if (existsSync(target)) {
+        if (!opts.force)
+            throw new Error(`${target} already exists. Pass --force to overwrite it.`);
+        rmSync(target, { recursive: true, force: true });
+    }
+    cpSync(source, target, { recursive: true });
+    return { example: name, path: target, status: 'created' };
+}
+export async function runCloudDemo(name = 'eight-device-mosaic', opts = {}, loadDemo = async (url) => (await import(url))) {
+    if (name === 'eight-device-mosaic' && opts.duration) {
+        throw new Error('The eight-device mosaic uses a fixed 10-minute lease and does not accept --duration.');
+    }
+    const args = [];
+    if (opts.duration)
+        args.push('--duration', opts.duration);
+    if (opts.open)
+        args.push('--open');
+    const source = join(demoDirectory(name), 'demo.mjs');
+    const demo = await loadDemo(pathToFileURL(source).href);
+    await demo.runDemo(args);
+}
 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));
-}
-async function action(fn) {
+    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 {
-        await fn();
+        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 (err) {
-        console.error(friendlyApiError(err));
-        process.exitCode = 1;
+    catch (error) {
+        if (prepared.asset.id) {
+            await api.delete(`/run-cloud/assets/${encodeURIComponent(prepared.asset.id)}`).catch(() => undefined);
+        }
+        throw error;
     }
+    return prepared.asset;
 }
-export function registerRunCloud(program) {
-    program
-        .command('account')
-        .description('Show run.cloud entitlement and metered balance')
-        .option('--json', 'output JSON', false)
-        .action((opts) => action(async () => {
-        print(await client().get('/run-cloud/account'), opts);
-    }));
-    const ios = program.command('ios').description('Create, list, inspect, and delete iOS simulator sessions');
-    ios
+async function createSimulatorSession(platform, opts) {
+    assertDevHostAllowed(opts.devHost);
+    const uploadedAssets = [];
+    for (const file of opts.install ?? [])
+        uploadedAssets.push(await pushAsset(file));
+    const installAssets = [
+        ...(opts.installAsset ?? []),
+        ...uploadedAssets
+            .map((asset) => asset.id)
+            .filter((id) => typeof id === 'string' && id.length > 0),
+    ];
+    return await client().post(`/run-cloud/${platform}`, {
+        model: opts.model,
+        region: opts.region,
+        displayName: opts.displayName,
+        labels: parseLabels(opts.label),
+        installAssets,
+        inactivityTimeout: opts.inactivityTimeout,
+        hardTimeout: opts.hardTimeout,
+        autoDelete: opts.rm,
+        codec: requestedCodec(opts.codec),
+        ...(opts.devHost ? { devHost: opts.devHost } : {}),
+    });
+}
+function registerSimulatorCommands(program, platform) {
+    const label = platform === 'android' ? 'Android emulator' : 'iOS simulator';
+    const article = platform === 'android' ? 'an' : 'an';
+    const simulator = program.command(platform).description(`Create, list, inspect, and delete ${label} sessions`);
+    simulator
         .command('create')
-        .description('Create a remote iOS simulator session')
-        .option('--model <iphone|ipad>', 'simulator model', 'iphone')
+        .description(`Create a remote ${label} session`)
+        .option('--model <model>', platform === 'ios' ? 'simulator model' : 'emulator model', platform === 'ios' ? 'iphone' : 'pixel')
         .option('--region <region>', 'fleet region')
         .option('--display-name <name>', 'human-readable name')
         .option('--label <key=value>', 'label to attach to the session', (v, p) => [...p, v], [])
-        .option('--install <file>', 'local .ipa, .zip, .tar.gz, or simulator .app archive to upload and install', (v, p) => [...p, v], [])
+        .option('--install <file>', 'local app artifact to upload and install', (v, p) => [...p, v], [])
         .option('--install-asset <name-or-id>', 'previously uploaded asset to install', (v, p) => [...p, v], [])
         .option('--inactivity-timeout <duration>', 'auto-close idle timeout, e.g. 60s, 3m, or none')
         .option('--hard-timeout <duration>', 'maximum lifetime, e.g. 10m or 1h')
+        .option('--codec <auto|mjpeg|webrtc>', 'force the simulator viewer stream codec', 'auto')
         .option('--rm', 'release the session when this command exits', false)
         .option('--json', 'output JSON', false)
+        .addOption(new Option('--dev-host <host>', 'dev-only: target a specific simulator fleet host').hideHelp())
         .action((opts) => action(async () => {
-        const uploadedAssets = [];
-        for (const file of opts.install ?? [])
-            uploadedAssets.push(await pushAsset(file));
-        const installAssets = [
-            ...(opts.installAsset ?? []),
-            ...uploadedAssets
-                .map((asset) => asset.id)
-                .filter((id) => typeof id === 'string' && id.length > 0),
-        ];
-        const session = await client().post('/run-cloud/ios', {
-            model: opts.model,
-            region: opts.region,
-            displayName: opts.displayName,
-            labels: parseLabels(opts.label),
-            installAssets,
-            inactivityTimeout: opts.inactivityTimeout,
-            hardTimeout: opts.hardTimeout,
-            autoDelete: opts.rm,
-        });
-        print(session, opts);
+        print(await createSimulatorSession(platform, opts), opts);
     }));
-    ios
+    simulator
         .command('list')
-        .description('List active iOS simulator sessions')
+        .description(`List active ${label} sessions`)
         .option('--all', 'include released sessions', false)
         .option('--json', 'output JSON', false)
         .action((opts) => action(async () => {
         const qs = opts.all ? '?all=1' : '';
-        print(await client().get(`/run-cloud/ios${qs}`), opts);
+        print(await client().get(`/run-cloud/${platform}${qs}`), opts);
     }));
-    ios
+    simulator
         .command('get')
-        .description('Show an iOS simulator session')
+        .description(`Show ${article} ${label} session`)
         .argument('<id>')
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
-        print(await client().get(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+        print(await client().get(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
     }));
-    ios
+    simulator
         .command('delete')
-        .description('Release an iOS simulator session')
+        .description(`Release ${article} ${label} session`)
         .argument('<id>')
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
-        print(await client().delete(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+        print(await client().delete(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
     }));
-    ios
+    simulator
         .command('open-url')
-        .description('Open a URL or deep link in an iOS simulator session')
+        .description(`Open a URL or deep link in ${article} ${label} session`)
         .argument('<url>')
         .requiredOption('--id <id>', 'session id')
         .option('--json', 'output JSON', false)
         .action((url, opts) => action(async () => {
-        print(await client().post(`/run-cloud/ios/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+        print(await client().post(`/run-cloud/${platform}/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+    }));
+    return simulator;
+}
+async function action(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+export function registerRunCloud(program) {
+    const sample = program
+        .command('sample')
+        .alias('samples')
+        .description('Download installable onboarding sample apps');
+    sample
+        .command('download')
+        .description('Download a checksum-verified iOS or Android sample app')
+        .argument('<ios|android>', 'sample platform')
+        .option('-o, --output <path>', 'output file')
+        .option('--force', 'overwrite an existing output file', false)
+        .option('--json', 'output JSON', false)
+        .action((platform, opts) => action(async () => {
+        print(await downloadRunCloudSample(platform, opts), opts);
+    }));
+    const demo = program.command('demo').description('Create and run run.cloud demo projects');
+    demo
+        .command('init')
+        .description('Scaffold a standalone demo project')
+        .argument('[name]', 'demo to create', 'eight-device-mosaic')
+        .argument('[directory]', 'output directory')
+        .option('--force', 'overwrite an existing output directory', false)
+        .option('--json', 'output JSON', false)
+        .action((name, directory, opts) => action(async () => {
+        print(initRunCloudDemo(name, directory, opts), opts);
+    }));
+    demo
+        .command('run')
+        .description('Run a bundled demo without scaffolding a project')
+        .argument('[name]', 'demo to run', 'eight-device-mosaic')
+        .option('--duration <seconds>', 'duration for live-camera-relay')
+        .option('--open', 'open the demo viewer or live sessions in the browser', false)
+        .action((name, opts) => action(async () => {
+        await runCloudDemo(name, opts);
+    }));
+    program
+        .command('account')
+        .description('Show run.cloud account and organization access')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        print(await client().get('/run-cloud/account'), opts);
+    }));
+    const ios = registerSimulatorCommands(program, 'ios');
+    registerSimulatorCommands(program, 'android');
+    ios
+        .command('tunnel')
+        .description('Connect a local service to a remote iOS simulator session')
+        .argument('<id>')
+        .requiredOption('--local-port <port>', 'local service port, for example Metro on 8081')
+        .option('--service <name>', 'service name shown in status', 'metro')
+        .option('--local-host <host>', 'loopback service host', '127.0.0.1')
+        .option('--sidecar-url <url>', 'Newly sidecar URL', 'http://127.0.0.1:4500')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        const localPort = Number(opts.localPort);
+        if (!Number.isInteger(localPort) || localPort < 1 || localPort > 65535)
+            throw new Error('--local-port must be a valid TCP port');
+        const allocation = await client().post(`/sessions/${encodeURIComponent(id)}/tunnel`, {
+            localService: opts.service, localHost: opts.localHost, localPort,
+        });
+        if (!allocation.tunnel)
+            throw new Error('Control plane did not return tunnel credentials');
+        const sidecarResponse = await fetch(`${opts.sidecarUrl.replace(/\/$/, '')}/run-cloud/tunnel`, {
+            method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(allocation.tunnel),
+        });
+        const status = await sidecarResponse.json();
+        if (!sidecarResponse.ok)
+            throw new Error(`Local tunnel failed: ${status.error ?? sidecarResponse.statusText}`);
+        print(status, opts);
+    }));
+    ios
+        .command('tunnel-status')
+        .description('Show the local tunnel sidecar status')
+        .option('--sidecar-url <url>', 'Newly sidecar URL', 'http://127.0.0.1:4500')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        const response = await fetch(`${opts.sidecarUrl.replace(/\/$/, '')}/run-cloud/tunnel`);
+        print(await response.json(), opts);
     }));
     const asset = program
         .command('asset')
@@ -260,13 +470,13 @@ export function registerRunCloud(program) {
     const skills = program.command('skills').description('Install run.cloud skills for AI coding agents');
     skills
         .command('install')
-        .description('Install the run.cloud iOS simulator skill')
+        .description('Install the run.cloud router, mobile-session, and sandbox skills')
         .option('--agents <agent>', 'agent to install for: claude, codex, cursor', (v, p) => [...p, v], [])
         .option('--scope <project|global>', 'install scope', 'project')
         .option('--force', 'overwrite existing skill', false)
         .option('--json', 'output JSON', false)
         .action((opts) => action(async () => {
         const scope = opts.scope === 'global' ? 'global' : 'project';
-        print(installSkill({ ...opts, scope }), opts);
+        print(installSkills({ ...opts, scope }), opts);
     }));
 }