@newly/cli 0.1.1 → 0.1.2

package/dist/commands/build.js

@@ -1,12 +1,250 @@
+import { existsSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { ApiClient, ApiError } from '../api.js';
+import { createSnapshot } from '../archive.js';
+import { readProjectLink, requireCredentials, resolveProject, writeProjectLink } from '../config.js';
 export function buildPlaceholderMessage(platform) {
     return (`In-house ${platform} builds are coming in an upcoming release.\n` +
         'Set up iOS signing first with `newly creds apple` (check readiness with `newly creds apple status`).');
 }
+function makeClient() {
+    const creds = requireCredentials();
+    return {
+        client: new ApiClient(creds.apiUrl, creds.token),
+    };
+}
+function assertDirectory(path, label) {
+    if (!existsSync(path))
+        throw new Error(`${label} does not exist: ${path}`);
+    if (!statSync(path).isDirectory())
+        throw new Error(`${label} is not a directory: ${path}`);
+}
+function archiveKib(size) {
+    return size < 1024 ? '<1' : Math.round(size / 1024).toString();
+}
+async function ensureRemoteSourceProject(client, sourceDir, explicitProject, log) {
+    if (explicitProject)
+        return explicitProject;
+    const linked = readProjectLink(sourceDir);
+    if (linked?.projectId)
+        return linked.projectId;
+    const name = basename(resolve(sourceDir)) || 'iOS simulator build';
+    log('No Newly project link found; creating a build-only project for this local source...');
+    const created = (await client.post('/newly_backend/create_project', {
+        name,
+        provision: false,
+    }));
+    const projectId = typeof created.project_id === 'string' ? created.project_id : '';
+    if (!projectId)
+        throw new Error('Backend did not return project_id for build-only project.');
+    writeProjectLink(sourceDir, {
+        projectId,
+        pulledSha: null,
+        pulledAt: new Date().toISOString(),
+    });
+    log(`Linked local source to Newly project ${projectId} for remote simulator builds.`);
+    return projectId;
+}
+function parseSseData(frame) {
+    const out = [];
+    for (const part of frame.split(/\n\n+/)) {
+        const data = part
+            .split(/\n/)
+            .filter((line) => line.startsWith('data:'))
+            .map((line) => line.slice(5).trimStart())
+            .join('\n');
+        if (!data)
+            continue;
+        try {
+            out.push(JSON.parse(data));
+        }
+        catch {
+        }
+    }
+    return out;
+}
+async function waitForBuild(client, buildId, log) {
+    let status = 'queued';
+    const answeredPrompts = new Set();
+    for await (const chunk of client.stream(`/builds/${buildId}/stream`)) {
+        for (const event of parseSseData(chunk)) {
+            const promptId = typeof event.id === 'string' ? event.id : '';
+            if (promptId === 'jenkins-fallback-choice' && !answeredPrompts.has(promptId)) {
+                answeredPrompts.add(promptId);
+                if (typeof event.message === 'string')
+                    log(event.message);
+                log('Default build system failed; leaving this remote simulator build failed.');
+                await client.post(`/builds/${buildId}/respond`, {
+                    promptId,
+                    value: 'keep_failed',
+                });
+                status = 'failed';
+                continue;
+            }
+            if (Array.isArray(event.new_logs)) {
+                for (const line of event.new_logs)
+                    log(String(line));
+            }
+            if (typeof event.message === 'string')
+                log(event.message);
+            if (typeof event.status === 'string')
+                status = event.status;
+        }
+    }
+    return status;
+}
+function serveSimPrepareUrl(session) {
+    if (typeof session.base_url !== 'string' || typeof session.install_url !== 'string')
+        return null;
+    const installUrl = new URL(session.install_url);
+    const prepareUrl = new URL(`${session.base_url.replace(/\/+$/, '')}/api/integration/prepare`);
+    const device = installUrl.searchParams.get('device');
+    if (device)
+        prepareUrl.searchParams.set('device', device);
+    prepareUrl.searchParams.set('async', '1');
+    return prepareUrl.toString();
+}
+async function prepareServeSimBuildFromCli(session, launchUrl) {
+    if (typeof session.token !== 'string') {
+        throw new Error('Backend returned a serve-sim session without a token.');
+    }
+    const prepareUrl = serveSimPrepareUrl(session);
+    if (!prepareUrl) {
+        throw new Error('Backend returned a serve-sim session without a prepare target.');
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 20_000);
+    try {
+        const res = await fetch(prepareUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${session.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                artifactUrl: typeof session.artifact_url === 'string' ? session.artifact_url : undefined,
+                launchUrl,
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`serve-sim prepare failed: HTTP ${res.status}${body ? ` ${body}` : ''}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof DOMException && error.name === 'AbortError') {
+            throw new Error('serve-sim prepare timed out after 20000ms');
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function runIosSimulatorBuild(client, projectId, opts = {}, log = console.log) {
+    let build;
+    const metroUrl = opts.metroUrl?.trim() || null;
+    if (opts.remoteSource) {
+        const sourceDir = opts.sourcePath ?? '.';
+        assertDirectory(sourceDir, 'iOS build source directory');
+        projectId = await ensureRemoteSourceProject(client, sourceDir, projectId, log);
+        log('Packaging iOS source...');
+        const archive = await createSnapshot(sourceDir);
+        log(`Uploading source snapshot (${archiveKib(archive.length)} KiB) for remote iOS simulator build...`);
+        const form = new FormData();
+        form.set('request', JSON.stringify({
+            project_id: projectId,
+            platform: 'ios',
+            mode: 'automatic',
+            build_profile: 'development-simulator',
+        }));
+        form.set('source', new Blob([new Uint8Array(archive)], { type: 'application/gzip' }), 'source.tar.gz');
+        build = (await client.uploadForm('/builds/source-upload', form));
+    }
+    else {
+        projectId = resolveProject(process.cwd(), projectId);
+        build = (await client.post('/builds', {
+            projectId,
+            platform: 'ios',
+            mode: 'automatic',
+            buildProfile: 'development-simulator',
+        }));
+    }
+    log(`Build ${build.id} queued (${build.status})`);
+    if (opts.wait) {
+        const status = await waitForBuild(client, build.id, log);
+        log(`Build ${build.id} ${status}`);
+        if (status !== 'completed')
+            throw new Error(`iOS simulator build ${status}`);
+    }
+    if (opts.loadToSimulator) {
+        const load = (provider) => {
+            const params = new URLSearchParams();
+            if (provider)
+                params.set('provider', provider);
+            if (provider === 'serve-sim' && metroUrl)
+                params.set('expo_url', metroUrl);
+            const qs = params.size ? `?${params.toString()}` : '';
+            return client.post(`/builds/${build.id}/load-to-simulator${qs}`, {});
+        };
+        let loaded;
+        try {
+            loaded = await load(opts.provider);
+        }
+        catch (e) {
+            if (opts.provider === 'serve-sim' && e instanceof ApiError && (e.status === 503 || e.status === 500)) {
+                log('Cloud iOS simulator unavailable; falling back to Appetize...');
+                loaded = await load();
+            }
+            else {
+                throw e;
+            }
+        }
+        if (typeof loaded.appetize_public_key === 'string') {
+            log(`Appetize iOS key: ${loaded.appetize_public_key}`);
+        }
+        else if (loaded.serve_sim && typeof loaded.serve_sim === 'object') {
+            const session = loaded.serve_sim;
+            await prepareServeSimBuildFromCli(session, metroUrl);
+            const url = typeof session.url === 'string' ? session.url : session.base_url;
+            log(`Cloud simulator prepared on ${typeof url === 'string' ? url : 'ready'}`);
+        }
+        else {
+            log('Simulator load requested.');
+        }
+    }
+}
 export function registerBuild(program) {
     program
         .command('build [platform]')
-        .description('Build the mobile app (coming soon)')
-        .action((platform = 'ios') => {
-        console.log(buildPlaceholderMessage(platform));
+        .description('Build the mobile app')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .option('--source-path <path>', 'local source directory to upload for --remote-source', '.')
+        .option('--simulator', 'build an iOS simulator artifact', false)
+        .option('--remote-source', 'upload local source files and build in Newly cloud', false)
+        .option('--wait', 'stream logs until the build finishes', false)
+        .option('--load-to-simulator', 'load a completed simulator build into a cloud simulator', false)
+        .option('--provider <provider>', 'simulator provider for --load-to-simulator (serve-sim or appetize)')
+        .option('--metro-url <url>', 'reachable Metro bundle URL for remote simulator source builds')
+        .action(async (platform = 'ios', opts) => {
+        try {
+            if (platform !== 'ios' || !opts.simulator) {
+                console.log(buildPlaceholderMessage(platform));
+                return;
+            }
+            if (opts.provider && !opts.loadToSimulator) {
+                throw new Error('--provider requires --load-to-simulator.');
+            }
+            const { client } = makeClient();
+            const projectId = opts.remoteSource
+                ? opts.project || readProjectLink(opts.sourcePath ?? '.')?.projectId
+                : resolveProject(process.cwd(), opts.project);
+            await runIosSimulatorBuild(client, projectId, opts);
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            process.exitCode = 1;
+        }
     });
 }

package/dist/commands/login.js

@@ -1,7 +1,7 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { clearCredentials, saveCredentials } from '../config.js';
+import { clearCredentials, credentialsDisplayPath, saveCredentials } from '../config.js';
 const DEFAULT_APP_URL = process.env.NEWLY_APP_URL ?? 'https://newly.app';
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 export async function startCallbackServer(state, appOrigin, timeoutMs) {
@@ -152,7 +152,7 @@ export function registerLogin(program) {
                     appUrl: opts.appUrl,
                     expiresAt: Math.floor(Date.now() / 1000) + payload.expiresIn,
                 });
-                console.log('Logged in. Credentials saved to ~/.newly/credentials');
+                console.log(`Logged in. Credentials saved to ${credentialsDisplayPath()}`);
             }
             finally {
                 close();

package/dist/commands/run-cloud.js

@@ -0,0 +1,272 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+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.
+`;
+function client() {
+    const creds = requireCredentials();
+    return new ApiClient(creds.apiUrl, creds.token);
+}
+function print(value, opts = {}) {
+    if (opts.json) {
+        console.log(JSON.stringify(value, null, 2));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            console.log(formatRecord(item));
+        return;
+    }
+    console.log(formatRecord(value));
+}
+function formatRecord(value) {
+    if (!value || typeof value !== 'object')
+        return String(value);
+    const record = value;
+    return Object.entries(record)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
+        .join('\n');
+}
+function parseLabels(labels) {
+    const out = {};
+    for (const raw of labels ?? []) {
+        const idx = raw.indexOf('=');
+        if (idx <= 0)
+            throw new Error(`Invalid --label ${raw}; expected key=value`);
+        out[raw.slice(0, idx)] = raw.slice(idx + 1);
+    }
+    return out;
+}
+function fileBlob(path) {
+    const resolved = resolve(path);
+    if (!existsSync(resolved))
+        throw new Error(`File does not exist: ${path}`);
+    if (!statSync(resolved).isFile())
+        throw new Error(`Not a file: ${path}`);
+    const data = readFileSync(resolved);
+    return {
+        blob: new Blob([new Uint8Array(data)], { type: 'application/octet-stream' }),
+        name: basename(resolved),
+    };
+}
+function skillBase(agent, scope) {
+    if (scope === 'project') {
+        if (agent === 'claude')
+            return join(process.cwd(), '.claude', 'skills');
+        if (agent === 'codex')
+            return join(process.cwd(), '.codex', 'skills');
+        if (agent === 'cursor')
+            return join(process.cwd(), '.agents', 'skills');
+    }
+    if (agent === 'claude')
+        return join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'skills');
+    if (agent === 'codex')
+        return join(process.env.CODEX_HOME ?? join(homedir(), '.codex'), 'skills');
+    if (agent === 'cursor')
+        return join(homedir(), '.agents', 'skills');
+    throw new Error(`Unsupported agent: ${agent}`);
+}
+function installSkill(opts) {
+    const agents = opts.agents?.length ? opts.agents : ['claude', 'codex', 'cursor'];
+    const scope = opts.scope ?? 'project';
+    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.`);
+            rmSync(target, { recursive: true, force: true });
+        }
+        mkdirSync(target, { recursive: true });
+        writeFileSync(join(target, 'SKILL.md'), RUN_CLOUD_SKILL);
+        results.push({ agent, path: target, status: 'installed' });
+    }
+    return results;
+}
+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) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+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
+        .command('create')
+        .description('Create a remote iOS simulator session')
+        .option('--model <iphone|ipad>', 'simulator model', 'iphone')
+        .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-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('--rm', 'release the session when this command exits', false)
+        .option('--json', 'output JSON', false)
+        .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);
+    }));
+    ios
+        .command('list')
+        .description('List active iOS simulator 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);
+    }));
+    ios
+        .command('get')
+        .description('Show an iOS simulator session')
+        .argument('<id>')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().get(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+    }));
+    ios
+        .command('delete')
+        .description('Release an iOS simulator session')
+        .argument('<id>')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().delete(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+    }));
+    ios
+        .command('open-url')
+        .description('Open a URL or deep link in an iOS simulator 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);
+    }));
+    const asset = program
+        .command('asset')
+        .alias('assets')
+        .description('Upload, list, inspect, and delete run.cloud assets');
+    asset
+        .command('push')
+        .description('Upload an app asset for simulator installation')
+        .argument('<file>')
+        .option('-n, --name <name>', 'asset name')
+        .option('--json', 'output JSON', false)
+        .action((file, opts) => action(async () => {
+        print(await pushAsset(file, opts), opts);
+    }));
+    asset
+        .command('list')
+        .description('List uploaded assets')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        print(await client().get('/run-cloud/assets'), opts);
+    }));
+    asset
+        .command('pull')
+        .description('Download an asset')
+        .argument('<id>')
+        .option('-o, --output <path>', 'output path')
+        .action((id, opts) => action(async () => {
+        const body = await client().getBinary(`/run-cloud/assets/${encodeURIComponent(id)}/download`);
+        const output = opts.output ?? id;
+        writeFileSync(output, body);
+        console.log(output);
+    }));
+    asset
+        .command('delete')
+        .description('Delete an uploaded asset')
+        .argument('<id>')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().delete(`/run-cloud/assets/${encodeURIComponent(id)}`), opts);
+    }));
+    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')
+        .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);
+    }));
+}

package/dist/config.js

@@ -1,23 +1,49 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
-function newlyHome() {
+import { basename, join } from 'node:path';
+function credentialsHome() {
+    if (process.env.RUN_CLOUD_HOME)
+        return process.env.RUN_CLOUD_HOME;
+    if (process.env.NEWLY_HOME)
+        return process.env.NEWLY_HOME;
+    const invoked = basename(process.argv[1] ?? '');
+    if (invoked === 'runcloud' || invoked === 'run-cloud.js')
+        return join(homedir(), '.run-cloud');
     return process.env.NEWLY_HOME ?? join(homedir(), '.newly');
 }
 function credentialsPath() {
-    return join(newlyHome(), 'credentials');
+    return join(credentialsHome(), 'credentials');
+}
+export function credentialsDisplayPath() {
+    const path = credentialsPath();
+    const home = homedir();
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+function loginCommandName() {
+    const invoked = basename(process.argv[1] ?? '');
+    return invoked === 'runcloud' || invoked === 'run-cloud.js' ? 'runcloud login' : 'newly login';
 }
 export function normalizeApiUrl(url) {
     const trimmed = url.replace(/\/+$/, '');
     return trimmed.endsWith('/api') ? trimmed : `${trimmed}/api`;
 }
 export function saveCredentials(creds) {
-    mkdirSync(newlyHome(), { recursive: true, mode: 0o700 });
+    mkdirSync(credentialsHome(), { recursive: true, mode: 0o700 });
     const normalized = { ...creds, apiUrl: normalizeApiUrl(creds.apiUrl) };
     writeFileSync(credentialsPath(), JSON.stringify(normalized, null, 2) + '\n', { mode: 0o600 });
     chmodSync(credentialsPath(), 0o600);
 }
 export function loadCredentials() {
+    const envToken = process.env.NEWLY_API_TOKEN ?? process.env.NEWLY_CLI_TOKEN;
+    const envApiUrl = process.env.NEWLY_API_URL ?? process.env.NEWLY_API_HOST ?? process.env.NEXT_PUBLIC_API_HOST;
+    if (envToken?.trim() && envApiUrl?.trim()) {
+        return {
+            token: envToken.trim(),
+            apiUrl: normalizeApiUrl(envApiUrl.trim()),
+            appUrl: process.env.NEWLY_APP_URL ?? 'https://newly.dev',
+            expiresAt: Number.MAX_SAFE_INTEGER,
+        };
+    }
     if (!existsSync(credentialsPath()))
         return null;
     try {
@@ -36,7 +62,7 @@ export function clearCredentials() {
 export function requireCredentials() {
     const creds = loadCredentials();
     if (!creds) {
-        throw new Error('Not logged in (or session expired). Run: newly login');
+        throw new Error(`Not logged in (or session expired). Run: ${loginCommandName()}`);
     }
     return creds;
 }

package/dist/diagnose.js

@@ -0,0 +1,159 @@
+const DEFAULT_URLS = {
+    dev: {
+        apiOps: 'https://cp-api-ops-dev.newly.app',
+        worker: 'https://cp-worker-dev.newly.app',
+    },
+    prod: {
+        apiOps: 'https://cp-api-ops-prod.newly.app',
+        worker: 'https://cp-worker-prod.newly.app',
+    },
+};
+function stripSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+export function resolveTargets(env) {
+    if (env !== 'dev' && env !== 'prod') {
+        throw new Error(`--env must be dev or prod (got "${env}")`);
+    }
+    const upper = env.toUpperCase();
+    const apiOps = process.env[`DIAGNOSE_CP_API_OPS_URL_${upper}`] ??
+        process.env.DIAGNOSE_CP_API_OPS_URL ??
+        DEFAULT_URLS[env].apiOps;
+    const worker = process.env[`DIAGNOSE_CP_WORKER_URL_${upper}`] ??
+        process.env.DIAGNOSE_CP_WORKER_URL ??
+        DEFAULT_URLS[env].worker;
+    return [
+        { service: 'cp-api', url: stripSlash(apiOps) },
+        { service: 'cp-worker', url: stripSlash(worker) },
+    ];
+}
+function extractAuthorization(headers) {
+    if (headers instanceof Headers) {
+        return headers.get('authorization') ?? undefined;
+    }
+    const h = headers;
+    return h?.Authorization ?? h?.authorization;
+}
+export async function resolveOpsAuthHeader(env = process.env) {
+    const audience = env.DIAGNOSE_OIDC_AUDIENCE ?? 'newly-diagnose-ops';
+    try {
+        const { GoogleAuth } = await import('google-auth-library');
+        const auth = new GoogleAuth();
+        const client = await auth.getIdTokenClient(audience);
+        const authz = extractAuthorization(await client.getRequestHeaders());
+        if (authz) {
+            return authz;
+        }
+    }
+    catch {
+    }
+    const token = env.DIAGNOSE_OPS_TOKEN;
+    if (token) {
+        return `Bearer ${token}`;
+    }
+    throw new Error('No ops credential available. Run `gcloud auth application-default login` (ADC/OIDC), ' +
+        'or export DIAGNOSE_OPS_TOKEN with the break-glass ops token.');
+}
+function truncate(value, max = 200) {
+    const trimmed = value.trim();
+    return trimmed.length > max ? `${trimmed.slice(0, max)}...` : trimmed;
+}
+export async function fetchDiagnose(target, authHeader) {
+    try {
+        const res = await fetch(`${target.url}/diagnose`, { headers: { Authorization: authHeader } });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            return {
+                service: target.service,
+                error: `HTTP ${res.status}${body ? `: ${truncate(body)}` : ''}`,
+            };
+        }
+        return (await res.json());
+    }
+    catch (e) {
+        return { service: target.service, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function isDoc(result) {
+    return !('error' in result);
+}
+export function rollupVerdict(services) {
+    const names = Object.keys(services);
+    const down = names.filter((name) => !isDoc(services[name]));
+    if (down.length) {
+        return `DOWN - unreachable: ${down.join(', ')}`;
+    }
+    const degraded = [];
+    for (const name of names) {
+        const doc = services[name];
+        const bad = Object.entries(doc.health)
+            .filter(([, probe]) => !probe.ok)
+            .map(([probeName]) => probeName);
+        if (bad.length) {
+            degraded.push(`${name} (${bad.join(', ')})`);
+        }
+    }
+    if (degraded.length) {
+        return `DEGRADED - ${degraded.join('; ')}`;
+    }
+    return `OK - ${names.length} service(s) healthy`;
+}
+export async function fanoutDiagnose(env) {
+    const targets = resolveTargets(env);
+    const authHeader = await resolveOpsAuthHeader();
+    const results = await Promise.all(targets.map((target) => fetchDiagnose(target, authHeader)));
+    const services = {};
+    results.forEach((result, index) => {
+        services[targets[index].service] = result;
+    });
+    return { rollup: rollupVerdict(services), services };
+}
+export function renderRollup(result, session) {
+    const lines = [result.rollup];
+    if (session) {
+        lines.push(`session: ${session}`);
+    }
+    lines.push('');
+    for (const [name, service] of Object.entries(result.services)) {
+        if (!isDoc(service)) {
+            lines.push(`${name}: UNREACHABLE - ${service.error}`);
+            continue;
+        }
+        const sha = service.deploy.git_sha ?? '(sha unknown)';
+        const revision = service.deploy.revision ?? '(revision unknown)';
+        lines.push(`${name}: ${sha} @ ${revision} [env=${service.env}]`);
+        const badProbes = Object.entries(service.health)
+            .filter(([, probe]) => !probe.ok)
+            .map(([probeName, probe]) => `${probeName}${probe.detail ? ` (${probe.detail})` : ''}`);
+        lines.push(`  health: ${badProbes.length ? `DEGRADED - ${badProbes.join(', ')}` : 'all ok'}`);
+        for (const verdict of service.diagnosis) {
+            lines.push(`  - ${verdict}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function registerDiagnose(program) {
+    program
+        .command('diagnose')
+        .description('Fan out /diagnose across control-plane services and roll up a verdict (dev/ops only)')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--session <id>', 'annotate the rollup with a session id you are investigating')
+        .option('--json', 'emit the merged JSON document instead of the human rollup')
+        .action(async (opts) => {
+        try {
+            if (opts.env !== 'dev' && opts.env !== 'prod') {
+                throw new Error('--env must be dev or prod');
+            }
+            const result = await fanoutDiagnose(opts.env);
+            if (opts.json) {
+                console.log(JSON.stringify({ session: opts.session ?? null, ...result }, null, 2));
+                return;
+            }
+            console.log(renderRollup(result, opts.session));
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { registerEmail } from './commands/email.js';
 import { registerWebsite } from './commands/website.js';
 import { registerDomains } from './commands/domains.js';
 import { registerDns } from './commands/dns.js';
+import { registerDiagnose } from './diagnose.js';
 const program = new Command('newly')
     .description('Develop, provision, and deploy Newly backends')
     .version('0.1.0');
@@ -33,4 +34,5 @@ registerEmail(program);
 registerWebsite(program);
 registerDomains(program);
 registerDns(program);
+registerDiagnose(program);
 await program.parseAsync(process.argv);

package/dist/run-cloud.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerLogin } from './commands/login.js';
+import { registerRunCloud } from './commands/run-cloud.js';
+const program = new Command('runcloud')
+    .description('Create and control remote iOS simulator sessions')
+    .version('0.1.0');
+registerLogin(program);
+registerRunCloud(program);
+await program.parseAsync(process.argv);

package/package.json

@@ -1,15 +1,24 @@
 {
   "name": "@newly/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Develop, provision, and deploy Newly backends from your terminal",
   "license": "UNLICENSED",
   "type": "module",
-  "bin": { "newly": "dist/index.js", "newly-dev": "dist/newly-dev.js" },
-  "files": ["dist"],
-  "engines": { "node": ">=20" },
+  "bin": {
+    "newly": "dist/index.js",
+    "newly-dev": "dist/newly-dev.js",
+    "runcloud": "dist/run-cloud.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc",
+    "build:run-cloud": "tsc && node dist/run-cloud.js --help >/dev/null",
     "dev": "tsx src/index.ts",
     "lint": "eslint src",
     "test": "vitest run",
@@ -17,6 +26,7 @@
   },
   "dependencies": {
     "commander": "^12.1.0",
+    "google-auth-library": "^9.15.0",
     "tar": "^7.4.3"
   },
   "devDependencies": {