native-sim 0.1.0

package/src/commands/down.js

@@ -0,0 +1,48 @@
+import * as gh from '../lib/gh.js';
+import { loadSession, clearSession } from '../lib/session.js';
+import { info, ok, warn, dim } from '../lib/ui.js';
+
+const WORKFLOW = 'native-sim.yml';
+
+export async function down(cwd, flags) {
+  gh.requireAuth();
+
+  // The session file only ever remembers the most recent `up`, so --all is the
+  // only way to catch sessions started before this one.
+  if (flags.all) {
+    const runs = gh.inFlightRuns(cwd, WORKFLOW);
+    if (runs.length === 0) {
+      info('no native-sim runs in flight');
+      clearSession(cwd);
+      return;
+    }
+    for (const run of runs) {
+      if (gh.cancelRun(cwd, run.databaseId)) ok(`cancelled ${run.databaseId} ${dim(run.displayTitle ?? '')}`);
+      else warn(`could not cancel ${run.databaseId} — ${run.url}`);
+    }
+    clearSession(cwd);
+    return;
+  }
+
+  const session = loadSession(cwd);
+  if (!session) {
+    info(`no native-sim session recorded ${dim('(try: native-sim down --all)')}`);
+    return;
+  }
+
+  const run = gh.getRun(cwd, session.runId);
+  if (run?.status === 'completed') {
+    info(`run already finished (${run.conclusion})`);
+  } else if (gh.cancelRun(cwd, session.runId)) {
+    ok(`cancelled run ${session.runId} — the stream and the runner shut down together`);
+  } else {
+    warn(`could not cancel run ${session.runId}; cancel it at ${session.url}`);
+  }
+
+  const others = gh.inFlightRuns(cwd, WORKFLOW).filter((r) => r.databaseId !== session.runId);
+  if (others.length) {
+    warn(`${others.length} other native-sim run(s) still in flight — ${dim('native-sim down --all')}`);
+  }
+
+  clearSession(cwd);
+}

package/src/commands/init.js

@@ -0,0 +1,64 @@
+import { mkdirSync, writeFileSync, existsSync, readFileSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertExpoProject } from '../lib/project.js';
+import { GITIGNORE } from '../lib/git.js';
+import { ok, info, warn, dim } from '../lib/ui.js';
+
+const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
+
+export const WORKFLOW_PATH = '.github/workflows/native-sim.yml';
+
+/**
+ * Templates carry a version stamp so an out-of-date file (which must be
+ * refreshed, or the CLI will dispatch inputs the deployed workflow does not
+ * declare) can be told apart from one the user deliberately customised.
+ */
+const VERSION_RE = /native-sim-template-version:\s*(\d+)/;
+const versionOf = (text) => Number(text.match(VERSION_RE)?.[1] ?? 0);
+export const GATE_PATH = '.github/native-sim/gate.cjs';
+
+/** Writes the workflow + gate into the project. Returns true if anything changed. */
+export function scaffold(cwd, { force = false } = {}) {
+  let changed = false;
+
+  for (const [rel, src] of [[WORKFLOW_PATH, 'native-sim.yml'], [GATE_PATH, 'gate.cjs']]) {
+    const dest = join(cwd, rel);
+    const template = readFileSync(join(TEMPLATES, src), 'utf8');
+    if (existsSync(dest) && !force) {
+      const existing = readFileSync(dest, 'utf8');
+      if (existing === template) continue;
+
+      const [have, want] = [versionOf(existing), versionOf(template)];
+      if (have >= want) {
+        warn(`${rel} differs from the bundled template ${dim('(native-sim init --force to overwrite)')}`);
+        continue;
+      }
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, template);
+      ok(`updated ${rel} ${dim(`(template v${have} → v${want})`)}`);
+      changed = true;
+      continue;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, template);
+    ok(`wrote ${rel}`);
+    changed = true;
+  }
+
+  const gitignore = join(cwd, '.gitignore');
+  if (!existsSync(gitignore)) {
+    writeFileSync(gitignore, GITIGNORE);
+    ok('wrote .gitignore');
+    changed = true;
+  }
+
+  return changed;
+}
+
+export async function init(cwd, flags) {
+  assertExpoProject(cwd);
+  const changed = scaffold(cwd, { force: flags.force });
+  if (!changed) info('already initialized — nothing to do');
+  console.log(`\nNext: ${dim('native-sim up')}`);
+}

package/src/commands/r2.js

@@ -0,0 +1,62 @@
+import { createInterface } from 'node:readline';
+import * as r2 from '../lib/r2.js';
+import { ok, info, warn, step, bold, dim, cyan } from '../lib/ui.js';
+
+/** Reads a line; when `hidden`, suppresses echo so secrets stay off the screen. */
+function prompt(question, { hidden = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    if (hidden) {
+      rl._writeToOutput = (chunk) => {
+        if (chunk.includes(question)) rl.output.write(question);
+      };
+    }
+    rl.question(question, (answer) => {
+      rl.close();
+      if (hidden) process.stdout.write('\n');
+      resolve(answer.trim());
+    });
+  });
+}
+
+export async function r2Setup(cwd, flags) {
+  if (flags.status) {
+    const config = r2.loadConfig();
+    const set = (v) => (v ? cyan('set') : dim('unset'));
+    console.log(`\n  ${bold('config')}   ${r2.configPath()}`);
+    console.log(`  account   ${config.accountId ?? dim('unset')}`);
+    console.log(`  bucket    ${config.bucket ?? dim('unset')}`);
+    console.log(`  key id    ${set(config.accessKeyId)}`);
+    console.log(`  secret    ${set(config.secretAccessKey)}`);
+    if (config.accountId && config.bucket && config.accessKeyId && config.secretAccessKey) {
+      console.log(`  reachable ${r2.bucketExists(config) ? cyan('yes') : dim('no')}`);
+    }
+    console.log('');
+    return;
+  }
+
+  step('Configure R2');
+  console.log(dim('  Create an R2 API token with Object Read & Write at:'));
+  console.log(dim('  https://dash.cloudflare.com -> R2 -> Manage API Tokens'));
+  console.log('');
+
+  const accountId = await prompt('  Cloudflare account ID: ');
+  const bucket = (await prompt('  Bucket name [native-sim-builds]: ')) || 'native-sim-builds';
+  const accessKeyId = await prompt('  R2 access key ID: ');
+  const secretAccessKey = await prompt('  R2 secret access key: ', { hidden: true });
+
+  const config = { accountId, bucket, accessKeyId, secretAccessKey };
+  r2.assertConfigured(config);
+
+  if (r2.bucketExists(config)) {
+    info(`bucket ${bold(bucket)} already exists`);
+  } else {
+    r2.createBucket(config);
+    ok(`created bucket ${bold(bucket)}`);
+  }
+
+  const path = r2.saveConfig(config);
+  ok(`saved ${path} ${dim('(0600)')}`);
+  warn('keep this file private -- it holds your R2 secret');
+  console.log(`\nNext: ${dim('native-sim upload ./MyApp.app')}`);
+}

package/src/commands/status.js

@@ -0,0 +1,30 @@
+import * as gh from '../lib/gh.js';
+import { loadSession } from '../lib/session.js';
+import { info, ok, warn, dim, bold, cyan, green, red } from '../lib/ui.js';
+
+export async function status(cwd) {
+  const session = loadSession(cwd);
+  if (!session) {
+    info('no native-sim session recorded for this project');
+    return;
+  }
+
+  const run = gh.getRun(cwd, session.runId);
+  const commitStatus = gh.readStatus(cwd, session.repo, session.sha, session.context);
+  const age = Math.round((Date.now() - session.startedAt) / 60000);
+
+  console.log('');
+  console.log(`  ${bold('session')}  ${session.session} ${dim(`· started ${age}m ago`)}`);
+  console.log(`  ${bold('repo')}     ${session.repo}`);
+  console.log(`  ${bold('run')}      ${cyan(session.url)}`);
+  console.log(`  ${bold('state')}    ${run ? `${run.status}${run.conclusion ? ` / ${run.conclusion}` : ''}` : dim('unknown')}`);
+
+  if (commitStatus?.state === 'success' && commitStatus.target_url) {
+    console.log(`  ${bold('stream')}   ${green('●')} ${commitStatus.target_url}`);
+  } else if (commitStatus) {
+    console.log(`  ${bold('stream')}   ${red('○')} ${commitStatus.description ?? commitStatus.state}`);
+  } else {
+    console.log(`  ${bold('stream')}   ${dim('not published yet')}`);
+  }
+  console.log('');
+}

package/src/commands/turn.js

@@ -0,0 +1,83 @@
+import { createInterface } from 'node:readline';
+import * as gh from '../lib/gh.js';
+import { ok, info, warn, step, bold, dim, cyan } from '../lib/ui.js';
+
+function prompt(question, { hidden = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    if (hidden) {
+      rl._writeToOutput = (chunk) => {
+        if (chunk.includes(question)) rl.output.write(question);
+      };
+    }
+    rl.question(question, (answer) => {
+      rl.close();
+      if (hidden) process.stdout.write('\n');
+      resolve(answer.trim());
+    });
+  });
+}
+
+const KEYS = [
+  'NATIVE_SIM_TURN_KEY_ID',
+  'NATIVE_SIM_TURN_KEY_TOKEN',
+  'NATIVE_SIM_TURN_URL',
+  'NATIVE_SIM_TURN_USERNAME',
+  'NATIVE_SIM_TURN_CREDENTIAL',
+  'NATIVE_SIM_STUN_URL',
+];
+
+/**
+ * TURN config lives in repo secrets, never workflow inputs: dispatch inputs are
+ * visible to anyone who can read the repo, and on a public repo that is everyone.
+ *
+ * With a Cloudflare Realtime key the runner mints a short-lived credential per
+ * session, so nothing long-lived is stored and a leak expires by itself.
+ */
+export async function turn(cwd, flags) {
+  gh.requireAuth();
+  const repo = gh.nameWithOwner(cwd);
+  if (!repo) throw new Error('no GitHub remote here — run native-sim up first');
+
+  if (flags.status) {
+    const names = gh.listSecrets(cwd);
+    console.log(`\n  ${bold(repo)}`);
+    for (const k of KEYS) console.log(`  ${names.includes(k) ? cyan('set  ') : dim('unset')} ${k}`);
+    console.log('');
+    return;
+  }
+
+  step(`Configure TURN for ${bold(repo)}`);
+  console.log(dim('  A cloudflared quick tunnel carries no UDP, so WebRTC needs TURN.'));
+  console.log(dim('  STUN alone cannot traverse it.'));
+  console.log('');
+  console.log('  Cloudflare Realtime (recommended — credentials are minted per session):');
+  console.log(dim('    dash.cloudflare.com -> Realtime -> TURN Keys -> Create'));
+  console.log(dim('    then paste the Key ID and its API token below'));
+  console.log('');
+  console.log(dim('  Leave the Key ID blank to enter a static TURN URL instead.'));
+  console.log('');
+
+  const keyId = await prompt('  Realtime TURN Key ID (blank for static): ');
+
+  if (keyId) {
+    const token = await prompt('  TURN Key API token: ', { hidden: true });
+    if (!token) throw new Error('a TURN key API token is required');
+    gh.setSecret(cwd, 'NATIVE_SIM_TURN_KEY_ID', keyId);
+    gh.setSecret(cwd, 'NATIVE_SIM_TURN_KEY_TOKEN', token);
+    ok(`stored Realtime TURN key on ${repo}`);
+    info('the runner mints a 2h credential per session; nothing long-lived is kept');
+  } else {
+    const url = await prompt('  TURN URL (turn:host:3478): ');
+    if (!url) throw new Error('a TURN URL is required');
+    const username = await prompt('  TURN username: ');
+    const credential = await prompt('  TURN credential: ', { hidden: true });
+    gh.setSecret(cwd, 'NATIVE_SIM_TURN_URL', url);
+    if (username) gh.setSecret(cwd, 'NATIVE_SIM_TURN_USERNAME', username);
+    if (credential) gh.setSecret(cwd, 'NATIVE_SIM_TURN_CREDENTIAL', credential);
+    ok(`stored static TURN credentials on ${repo}`);
+    warn('static credentials do not expire — prefer a Realtime key');
+  }
+
+  console.log(`\nNext: ${dim('native-sim up --transport webrtc --public')}`);
+}

package/src/commands/up.js

@@ -0,0 +1,288 @@
+import { randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as git from '../lib/git.js';
+import * as gh from '../lib/gh.js';
+import { sh, sleep, open as openUrl } from '../lib/proc.js';
+import { assertExpoProject, defaultRepoName } from '../lib/project.js';
+import { scaffold, WORKFLOW_PATH } from './init.js';
+import { saveSession } from '../lib/session.js';
+import * as r2 from '../lib/r2.js';
+import * as ghrelease from '../lib/ghrelease.js';
+import { info, ok, warn, step, spinner, bold, dim, cyan, green } from '../lib/ui.js';
+
+const WORKFLOW = 'native-sim.yml';
+
+export async function up(cwd, flags) {
+  const appFile = flags['app-file'];
+  const appRelease = flags['app-release'];
+  const mode = flags.app || appFile || appRelease ? 'app' : (flags.mode ?? 'build');
+
+  // R2 uploads happen before any git work, so a bad config fails fast rather
+  // than after a push and a dispatch. A GitHub-hosted upload cannot: it needs
+  // the repo to exist, so it runs further down, once `repo` is known.
+  let appUrl = flags.app ?? '';
+  let appReleaseAsset = appRelease && appRelease !== true ? appRelease : '';
+  if (appFile && flags.r2) {
+    const config = r2.loadConfig();
+    r2.assertConfigured(config);
+    step(`Uploading ${bold(appFile)} to R2`);
+    const uploaded = r2.upload(config, appFile, { expiresIn: 7200 });
+    appUrl = uploaded.url;
+    ok(`uploaded ${(uploaded.bytes / 1048576).toFixed(1)} MB ${dim('(presigned 2h)')}`);
+  }
+
+  // In app mode nothing is compiled from this checkout, so the directory does
+  // not have to be an Expo project — the repo only carries the workflow.
+  if (mode !== 'app') assertExpoProject(cwd);
+  gh.requireAuth();
+
+  step('Preparing repository');
+
+  if (!git.isRepo(cwd)) {
+    git.init(cwd);
+    ok('git init');
+  }
+
+  const branch = git.currentBranch(cwd);
+  const message = flags.message ?? `native-sim: ${new Date().toISOString()}`;
+
+  // Commit and push the app *before* scaffolding the workflow. GitHub does not
+  // scan the first push to a brand-new empty repo for workflow files, so a
+  // workflow shipped in that push is never registered with Actions.
+  if (git.isDirty(cwd) || !git.hasCommits(cwd)) {
+    git.commitAll(cwd, message);
+    ok(`committed on ${bold(branch)}`);
+  } else {
+    info(`working tree clean on ${bold(branch)}`);
+  }
+
+  let repo = gh.nameWithOwner(cwd);
+  if (!repo) {
+    const name = flags.repo ?? defaultRepoName(cwd);
+    const isPublic = Boolean(flags.public);
+    step(`Creating ${isPublic ? 'public' : 'private'} repo ${bold(name)}`);
+    if (!isPublic) {
+      warn(`private repos bill macOS minutes at ${bold('10×')} — use ${dim('--public')} for unlimited free minutes`);
+    }
+    repo = gh.createRepo(cwd, name, { isPublic, branch });
+    ok(`created ${repo}`);
+  } else {
+    git.push(cwd, branch);
+    ok(`pushed to ${repo}`);
+    if (!gh.isPublicRepo(cwd)) {
+      warn(`${repo} is private — macOS minutes bill at ${bold('10×')} against your quota`);
+    }
+  }
+
+  // Second push. This one GitHub does scan for workflow files.
+  if (scaffold(cwd) || git.isDirty(cwd)) {
+    git.commitAll(cwd, 'native-sim: add simulator streaming workflow');
+    git.push(cwd, branch);
+    ok('pushed native-sim workflow');
+  }
+
+  // Now that the repo exists, a local build can be hosted on its own release.
+  // The runner fetches it with the job's own token — no third-party account,
+  // and nothing publicly downloadable when the release stays a draft.
+  if (appFile && !flags.r2) {
+    step(`Uploading ${bold(appFile)} to ${bold(repo)}`);
+    const uploaded = ghrelease.upload(cwd, repo, appFile);
+    appReleaseAsset = uploaded.asset;
+    ok(`uploaded ${(uploaded.bytes / 1048576).toFixed(1)} MB ${dim(`as ${uploaded.asset}`)}`);
+    if (ghrelease.isPubliclyReadable(cwd, repo)) {
+      warn('published release on a public repo — the build is downloadable by anyone');
+    }
+  }
+
+  await assertWorkflowIsDispatchable(cwd, repo, branch);
+  await ensureRegistered(cwd, repo, branch);
+
+  const sha = git.headSha(cwd);
+  const session = randomBytes(4).toString('hex');
+  const gateToken = randomBytes(24).toString('base64url');
+  const context = `native-sim/${session}`;
+
+  step('Dispatching build');
+  await gh.dispatch(cwd, WORKFLOW, branch, {
+    session,
+    gate_token: gateToken,
+    minutes: String(flags.minutes ?? 30),
+    device: flags.device ?? 'iPhone 17 Pro',
+    mode,
+    app_url: appUrl,
+    app_release_asset: appReleaseAsset,
+    export_app: flags.export ? 'true' : 'false',
+    agent_device: flags.agent ? 'true' : 'false',
+    agent_device_version: agentDeviceVersion(),
+    transport: flags.transport ?? 'http',
+    codec: flags.codec ?? 'mjpeg',
+    max_dimension: String(flags['max-dimension'] ?? 900),
+    video_fps: String(flags.fps ?? 30),
+    video_quality: String(flags.quality ?? 0.7),
+    scheme: flags.scheme ?? '',
+    cache: flags.cache === false ? 'false' : 'true',
+    runner: flags.runner ?? 'macos-26',
+  });
+
+  const run = await waitForRun(cwd, session);
+  ok(`run ${cyan(run.url)}`);
+  saveSession(cwd, { session, runId: run.databaseId, sha, repo, context, url: run.url });
+
+  const base = await waitForStream(cwd, { repo, sha, context, runId: run.databaseId });
+  // The runner publishes only the bare tunnel URL; the key never leaves this machine.
+  const url = `${base.replace(/\/$/, '')}/?k=${gateToken}`;
+
+  console.log('');
+  console.log(`  ${green('●')} ${bold('Simulator is live')}`);
+  console.log(`  ${url}`);
+  console.log('');
+  console.log(dim(`  Anyone with that link can drive the simulator.`));
+  console.log(dim(`  Stop it early with: native-sim down`));
+  console.log('');
+
+  if (flags.agent) printAgentConnect(base, gateToken);
+
+  if (flags.export) await exportArtifact(cwd, repo, run.databaseId, session, flags.out ?? process.cwd());
+  if (flags.open !== false) openUrl(url);
+  return url;
+}
+
+/**
+ * The proxied daemon and the local client should be the same build, so the
+ * runner installs whatever this machine already has rather than a floating
+ * latest. Falls back to the workflow's own default when agent-device is absent
+ * locally — the session still works, you just install the client afterwards.
+ */
+function agentDeviceVersion() {
+  const r = sh('agent-device', ['--version']);
+  const version = r.ok ? r.out.trim().split(/\s+/).pop() : '';
+  return /^\d+\.\d+\.\d+/.test(version) ? version : '0.20.1';
+}
+
+/**
+ * The agent-device proxy rides the same tunnel and the same token as the
+ * stream, so the connect line is derivable locally — nothing extra has to be
+ * published from the runner.
+ */
+function printAgentConnect(base, gateToken) {
+  const daemon = `${base.replace(/\/$/, '')}/agent-device`;
+  console.log(`  ${bold('Drive it from an agent')} ${dim('(agent-device)')}`);
+  console.log('');
+  console.log(cyan(`  agent-device connect proxy \\`));
+  console.log(cyan(`    --daemon-base-url ${daemon} \\`));
+  console.log(cyan(`    --daemon-auth-token ${gateToken}`));
+  console.log('');
+  console.log(dim(`  Then: agent-device devices --platform ios`));
+  console.log(dim(`        agent-device open <app-id> --platform ios`));
+  console.log(dim(`        agent-device snapshot -i`));
+  console.log(dim(`  Release it with: agent-device close && agent-device disconnect`));
+  console.log('');
+}
+
+/** Waits for the build to upload the .app archive, then fetches it. */
+async function exportArtifact(cwd, repo, runId, session, dir) {
+  const name = `native-sim-app-${session}`;
+  const spin = spinner('waiting for the app archive (built after the stream comes up)');
+  try {
+    await gh.waitForArtifact(cwd, repo, runId, name);
+  } finally {
+    spin.stop();
+  }
+  gh.downloadArtifact(cwd, runId, name, dir);
+  ok(`exported app archive to ${bold(dir)}`);
+}
+
+/**
+ * `workflow_dispatch` reads the workflow definition from the default branch, so
+ * a workflow that only exists on a feature branch silently isn't dispatchable.
+ */
+async function assertWorkflowIsDispatchable(cwd, repo, branch) {
+  const meta = gh.api(`repos/${repo}`);
+  const defaultBranch = meta?.default_branch ?? 'main';
+  if (branch === defaultBranch) return;
+
+  const onDefault = gh.api(`repos/${repo}/contents/${WORKFLOW_PATH}?ref=${defaultBranch}`);
+  if (onDefault) return;
+
+  throw new Error(
+    `${WORKFLOW_PATH} is not on the default branch (${defaultBranch}).\n` +
+      `GitHub only exposes workflow_dispatch for workflows present there.\n` +
+      `Merge ${branch} into ${defaultBranch}, or run native-sim from ${defaultBranch}.`,
+  );
+}
+
+/**
+ * Actions must register the workflow before it can be dispatched. If polling
+ * times out, nudge GitHub by making the workflow file part of a fresh push.
+ */
+async function ensureRegistered(cwd, repo, branch) {
+  const spin = spinner('waiting for GitHub to register the workflow');
+  try {
+    if (await gh.waitForWorkflowRegistration(cwd, repo, WORKFLOW_PATH, { timeoutMs: 120000 })) return;
+
+    spin.update('nudging GitHub to rescan the workflow');
+    const file = join(cwd, WORKFLOW_PATH);
+    const body = readFileSync(file, 'utf8').replace(/\n# native-sim-revision:.*\n$/, '\n');
+    writeFileSync(file, `${body}# native-sim-revision: ${Date.now()}\n`);
+    git.commitAll(cwd, 'native-sim: refresh workflow registration');
+    git.push(cwd, branch);
+
+    if (await gh.waitForWorkflowRegistration(cwd, repo, WORKFLOW_PATH, { timeoutMs: 120000 })) return;
+  } finally {
+    spin.stop();
+  }
+  throw new Error(
+    `GitHub never registered ${WORKFLOW_PATH}.\n` +
+      `Check that Actions is enabled: https://github.com/${repo}/settings/actions`,
+  );
+}
+
+async function waitForRun(cwd, session) {
+  const spin = spinner('waiting for GitHub to queue the run');
+  for (let i = 0; i < 40; i++) {
+    const run = gh.findRun(cwd, WORKFLOW, session);
+    if (run) {
+      spin.stop();
+      return run;
+    }
+    await sleep(3000);
+  }
+  spin.stop();
+  throw new Error('GitHub never queued the run. Check: gh run list --workflow native-sim.yml');
+}
+
+/** Poll the commit status the runner writes once the tunnel is up. */
+async function waitForStream(cwd, { repo, sha, context, runId }) {
+  const spin = spinner('starting runner');
+  const deadline = Date.now() + 45 * 60 * 1000;
+
+  try {
+    while (Date.now() < deadline) {
+      const status = gh.readStatus(cwd, repo, sha, context);
+      if (status?.state === 'success' && status.target_url) return status.target_url;
+
+      const run = gh.getRun(cwd, runId);
+      if (run?.status === 'completed') {
+        throw new Error(
+          `Run finished (${run.conclusion}) without publishing a stream URL.\n` +
+            `Logs: gh run view ${runId} --log-failed`,
+        );
+      }
+      spin.update(describe(run));
+      await sleep(5000);
+    }
+  } finally {
+    spin.stop();
+  }
+  throw new Error('Timed out after 45 minutes waiting for the stream URL.');
+}
+
+function describe(run) {
+  const job = run?.jobs?.[0];
+  if (!job) return 'waiting for a macOS runner';
+  const active = job.steps?.find((s) => s.status === 'in_progress');
+  const done = job.steps?.filter((s) => s.status === 'completed').length ?? 0;
+  const total = job.steps?.length ?? 0;
+  return active ? `${active.name} ${dim(`(${done}/${total})`)}` : `${job.status.replace('_', ' ')}`;
+}

package/src/commands/upload.js

@@ -0,0 +1,60 @@
+import * as r2 from '../lib/r2.js';
+import * as ghrelease from '../lib/ghrelease.js';
+import * as gh from '../lib/gh.js';
+import { ok, info, warn, step, bold, dim, cyan } from '../lib/ui.js';
+
+const mb = (bytes) => `${(bytes / 1048576).toFixed(1)} MB`;
+
+export async function upload(cwd, flags) {
+  const file = flags._positional?.[0];
+  if (!file) throw new Error('usage: native-sim upload <path to .app, .tar.gz or .zip>');
+
+  if (flags.r2) return uploadToR2(cwd, file, flags);
+  return uploadToGitHub(cwd, file);
+}
+
+/**
+ * Default host. The runner's own GITHUB_TOKEN is already scoped to this repo,
+ * so an asset here needs no third-party account and no presigned URL that can
+ * expire mid-session — and on a private repo it is private for free.
+ */
+function uploadToGitHub(cwd, file) {
+  gh.requireAuth();
+  const repo = gh.nameWithOwner(cwd);
+  if (!repo) {
+    throw new Error(
+      'No GitHub repo here yet. Run this from the project you stream, or create one first:\n' +
+        '  gh repo create --source . --private',
+    );
+  }
+
+  step(`Uploading ${bold(file)} to ${bold(repo)}`);
+  const result = ghrelease.upload(cwd, repo, file);
+
+  ok(`uploaded ${mb(result.bytes)} as ${dim(result.asset)}`);
+  if (ghrelease.isPubliclyReadable(cwd, repo)) {
+    warn('this release is published on a public repo — the build is downloadable by anyone');
+  } else {
+    info('draft release on this repo — only people who can read the repo can fetch it');
+  }
+  console.log('');
+  console.log(dim(`  run it:  native-sim up --app-release ${result.asset}`));
+  console.log('');
+  return result;
+}
+
+function uploadToR2(cwd, file, flags) {
+  const config = r2.loadConfig();
+  r2.assertConfigured(config);
+
+  step(`Uploading ${bold(file)} to R2`);
+  const expiresIn = Number(flags.expires ?? 3600);
+  const result = r2.upload(config, file, { expiresIn });
+
+  ok(`uploaded ${mb(result.bytes)} as ${dim(result.key)}`);
+  console.log('');
+  console.log(`  ${cyan(result.url)}`);
+  console.log('');
+  info(`presigned for ${Math.round(expiresIn / 60)} min -- fetch a fresh one per session`);
+  return result;
+}