runcloud 0.1.2 → 0.1.4

package/dist/config.js

@@ -1,13 +1,16 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
+function isRunCloud() {
+    const invoked = basename(process.argv[1] ?? '');
+    return invoked === 'runcloud' || invoked === 'run-cloud.js';
+}
 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')
+    if (isRunCloud())
         return join(homedir(), '.run-cloud');
     return process.env.NEWLY_HOME ?? join(homedir(), '.newly');
 }
@@ -20,12 +23,10 @@ export function credentialsDisplayPath() {
     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';
+    return isRunCloud() ? 'runcloud login' : 'newly login';
 }
 export function normalizeApiUrl(url) {
-    const trimmed = url.replace(/\/+$/, '');
-    return trimmed.endsWith('/api') ? trimmed : `${trimmed}/api`;
+    return url.replace(/\/+$/, '');
 }
 export function saveCredentials(creds) {
     mkdirSync(credentialsHome(), { recursive: true, mode: 0o700 });
@@ -34,13 +35,19 @@ export function saveCredentials(creds) {
     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;
+    const envToken = isRunCloud()
+        ? process.env.RUN_CLOUD_API_TOKEN ?? process.env.RUN_CLOUD_API_KEY
+        : process.env.NEWLY_API_TOKEN ?? process.env.NEWLY_CLI_TOKEN;
+    const envApiUrl = isRunCloud()
+        ? process.env.RUN_CLOUD_API_URL
+        : process.env.NEWLY_API_URL;
     if (envToken?.trim() && envApiUrl?.trim()) {
         return {
             token: envToken.trim(),
             apiUrl: normalizeApiUrl(envApiUrl.trim()),
-            appUrl: process.env.NEWLY_APP_URL ?? 'https://newly.dev',
+            appUrl: isRunCloud()
+                ? process.env.RUN_CLOUD_APP_URL ?? 'https://run.cloud'
+                : process.env.NEWLY_APP_URL ?? 'https://newly.app',
             expiresAt: Number.MAX_SAFE_INTEGER,
         };
     }
@@ -56,6 +63,40 @@ export function loadCredentials() {
         return null;
     }
 }
+function environmentSelectionPath(dir) {
+    return join(dir, '.newly', 'environment.json');
+}
+export function writeEnvironmentSelection(dir, selection) {
+    const selectionDir = join(dir, '.newly');
+    mkdirSync(selectionDir, { recursive: true });
+    const gitignorePath = join(selectionDir, '.gitignore');
+    if (!existsSync(gitignorePath))
+        writeFileSync(gitignorePath, '*\n');
+    writeFileSync(environmentSelectionPath(dir), JSON.stringify(selection, null, 2) + '\n');
+}
+export function readEnvironmentSelection(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(environmentSelectionPath(dir), 'utf8'));
+        if (!parsed.id || !parsed.name || !parsed.projectId)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearEnvironmentSelection(dir) {
+    rmSync(environmentSelectionPath(dir), { force: true });
+}
+export function requireEnvironmentSelection(dir, projectId) {
+    const selection = readEnvironmentSelection(dir);
+    if (!selection)
+        throw new Error('No environment selected. Run `newly env use <name>` first.');
+    if (selection.projectId !== projectId) {
+        throw new Error('The selected environment belongs to a different linked project. Run `newly env clear`.');
+    }
+    return selection;
+}
 export function clearCredentials() {
     rmSync(credentialsPath(), { force: true });
 }

package/dist/environmentShell.js

@@ -0,0 +1,70 @@
+import WebSocket from 'ws';
+export async function runEnvironmentDatabaseShell(input) {
+    const stdin = input.stdin ?? process.stdin;
+    const stdout = input.stdout ?? process.stdout;
+    const stderr = input.stderr ?? process.stderr;
+    const url = new URL(`/environment-databases/${encodeURIComponent(input.databaseId)}/shell`, input.apiUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    const createWebSocket = input.createWebSocket ?? ((address, options) => new WebSocket(address, options));
+    const socket = createWebSocket(url.toString(), {
+        headers: { Authorization: `Bearer ${input.token}` },
+    });
+    const ttyInput = stdin;
+    const ttyOutput = stdout;
+    const wasRaw = ttyInput.isRaw;
+    let exitCode = 1;
+    const sendResize = () => {
+        if (socket.readyState === WebSocket.OPEN && ttyOutput.rows && ttyOutput.columns) {
+            socket.send(JSON.stringify({ stream: 'resize', rows: ttyOutput.rows, cols: ttyOutput.columns }));
+        }
+    };
+    const onInput = (data) => {
+        if (socket.readyState === WebSocket.OPEN) {
+            socket.send(JSON.stringify({ stream: 'stdin', data: Buffer.from(data).toString('base64') }));
+        }
+    };
+    const restore = () => {
+        stdin.off('data', onInput);
+        ttyOutput.off?.('resize', sendResize);
+        if (ttyInput.isTTY && typeof ttyInput.setRawMode === 'function')
+            ttyInput.setRawMode(Boolean(wasRaw));
+        stdin.pause();
+    };
+    return await new Promise((resolve, reject) => {
+        socket.once('open', () => {
+            if (ttyInput.isTTY && typeof ttyInput.setRawMode === 'function')
+                ttyInput.setRawMode(true);
+            stdin.resume();
+            stdin.on('data', onInput);
+            ttyOutput.on?.('resize', sendResize);
+            sendResize();
+        });
+        socket.on('message', (raw) => {
+            try {
+                const frame = JSON.parse(raw.toString());
+                if ((frame.stream === 'stdout' || frame.stream === 'stderr') && typeof frame.data === 'string') {
+                    const target = frame.stream === 'stderr' ? stderr : stdout;
+                    target.write(Buffer.from(frame.data, 'base64'));
+                }
+                else if (frame.stream === 'exit' && typeof frame.exit_code === 'number') {
+                    exitCode = frame.exit_code;
+                }
+            }
+            catch {
+            }
+        });
+        socket.once('error', (error) => {
+            restore();
+            reject(error);
+        });
+        socket.once('close', (code, reason) => {
+            restore();
+            if (code >= 4400) {
+                reject(new Error(reason.toString() || `Database shell rejected (${code})`));
+            }
+            else {
+                resolve(exitCode);
+            }
+        });
+    });
+}

package/dist/index.js

@@ -16,6 +16,8 @@ import { registerWebsite } from './commands/website.js';
 import { registerDomains } from './commands/domains.js';
 import { registerDns } from './commands/dns.js';
 import { registerDiagnose } from './diagnose.js';
+import { registerDesktop } from './commands/desktop.js';
+import { registerEnvironment } from './commands/environment.js';
 const program = new Command('newly')
     .description('Develop, provision, and deploy Newly backends')
     .version('0.1.0');
@@ -35,4 +37,6 @@ registerWebsite(program);
 registerDomains(program);
 registerDns(program);
 registerDiagnose(program);
+registerDesktop(program);
+registerEnvironment(program);
 await program.parseAsync(process.argv);

package/dist/run-cloud.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { registerLogin } from './commands/login.js';
 import { registerRunCloud } from './commands/run-cloud.js';
+import { registerSandbox } from './commands/sandbox.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command('runcloud')
-    .description('Create and control remote iOS simulator sessions')
-    .version('0.1.0');
+    .description('Create and control remote mobile simulators and microVM sandboxes')
+    .version(version);
 registerLogin(program);
 registerRunCloud(program);
+registerSandbox(program);
 await program.parseAsync(process.argv);

package/dist/services-manifest.js

@@ -2,7 +2,6 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 export const DEFAULT_BACKEND_SERVICES = [
     { name: 'api', path: 'api-service', type: 'worker', schema: 'api', secrets: 'api', public: true },
-    { name: 'auth', path: 'auth-service', type: 'worker', schema: 'auth', secrets: 'auth', public: true },
 ];
 const SERVICE_NAME = /^[a-z][a-z0-9-]{0,31}$/;
 export function readBackendServices(dir) {
@@ -33,9 +32,39 @@ export function readBackendServices(dir) {
             schema: entry.schema === undefined ? undefined : entry.schema === null ? null : String(entry.schema),
             secrets: entry.secrets === undefined ? undefined : String(entry.secrets),
             public: entry.public === undefined ? true : Boolean(entry.public),
+            bindings: parseBindings(name, entry.bindings),
         };
     });
 }
+function parseBindings(serviceName, value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Service ${serviceName} bindings must be an object`);
+    }
+    const bindings = {};
+    for (const [bindingName, raw] of Object.entries(value)) {
+        if (!/^[A-Z][A-Z0-9_]{0,127}$/.test(bindingName)) {
+            throw new Error(`Invalid binding name for service ${serviceName}: ${bindingName}`);
+        }
+        if (bindingName.startsWith('NEWLY_')) {
+            throw new Error(`Service ${serviceName} cannot override reserved binding ${bindingName}`);
+        }
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error(`Binding ${bindingName} for service ${serviceName} must be an object`);
+        }
+        const entries = Object.entries(raw);
+        if (entries.length !== 1 || !['database', 'secret', 'storage'].includes(entries[0][0])) {
+            throw new Error(`Binding ${bindingName} for service ${serviceName} must declare exactly one database, secret, or storage`);
+        }
+        const [kind, logicalName] = entries[0];
+        if (typeof logicalName !== 'string' || logicalName.length === 0) {
+            throw new Error(`Binding ${bindingName} for service ${serviceName} has an invalid logical name`);
+        }
+        bindings[bindingName] = { [kind]: logicalName };
+    }
+    return bindings;
+}
 export function parseServiceFilter(value) {
     if (!value)
         return [];

package/examples/eight-device-mosaic/README.md

@@ -0,0 +1,30 @@
+# Eight-device mosaic
+
+Start eight run.cloud iOS simulator sessions, send each simulator to one tile
+of a synchronized animated canvas, and embed the signed sessions in a local
+4-by-2 mosaic viewer. The demo has one fixed ten-minute lease and releases every
+session when that lease ends. The same server-side cap protects against an
+interrupted local process.
+
+## Requirements
+
+- Node.js 20 or newer
+- `runcloud` 0.1.3 or newer: `npm install -g runcloud`
+- A simulator account authenticated either with `runcloud login` or with both
+  `RUN_CLOUD_API_KEY` and `RUN_CLOUD_API_URL`
+- run.cloud simulator access, capacity, and enough balance for eight sessions
+
+The local viewer binds only to `127.0.0.1`. Signed simulator URLs remain in the
+viewer process and are not printed to the terminal.
+
+## Run
+
+```bash
+npm run demo -- --open
+```
+
+Press Ctrl+C or select **End demo** in the viewer to release the sessions early.
+Omit `--open` when you only want the local viewer URL printed.
+
+For a local or preview tile host, set `RUN_CLOUD_DEMO_ORIGIN` to its absolute
+HTTP or HTTPS origin before starting the demo.

package/examples/eight-device-mosaic/demo.mjs

@@ -0,0 +1,329 @@
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+
+const DEVICE_COUNT = 8;
+const COLUMNS = 4;
+const ROWS = 2;
+const DEMO_LEASE_MS = 10 * 60 * 1000;
+
+export function parseOptions(args) {
+  const options = { open: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--open') {
+      options.open = true;
+      continue;
+    }
+    if (argument === '--help' || argument === '-h') {
+      options.help = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${argument}`);
+  }
+
+  return options;
+}
+
+function runCloud(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.env.RUNCLOUD_BIN || 'runcloud', args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(stderr.trim() || stdout.trim() || `runcloud exited with code ${code}`));
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout));
+      } catch {
+        reject(new Error(`runcloud returned invalid JSON: ${stdout.trim()}`));
+      }
+    });
+  });
+}
+
+export function browserCommand(url, platform = process.platform) {
+  return platform === 'darwin'
+    ? ['open', [url]]
+    : platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+}
+
+function openBrowser(url) {
+  const command = browserCommand(url);
+  const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore' });
+  child.on('error', () => undefined);
+  child.unref();
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function embedUrl(value) {
+  const url = new URL(value);
+  url.searchParams.set('loadingGuard', '1');
+  return url.toString();
+}
+
+export function mosaicViewerHtml(sessions, deadline = Date.now() + DEMO_LEASE_MS) {
+  const frames = sessions.map((session, index) => `
+        <section class="tile" data-tile="${index}">
+          <iframe title="Mosaic device ${index + 1}" src="${escapeHtml(embedUrl(session.url))}" allow="clipboard-read; clipboard-write"></iframe>
+          <span class="tile-number">${String(index + 1).padStart(2, '0')}</span>
+        </section>`).join('');
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>run.cloud eight-device mosaic</title>
+    <style>
+      :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, sans-serif; background: #030404; color: #f8fafc; }
+      * { box-sizing: border-box; }
+      html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; }
+      body { display: grid; grid-template-rows: 58px minmax(0, 1fr); background: #030404; }
+      header { display: flex; align-items: center; justify-content: space-between; gap: 20px; border-bottom: 1px solid rgba(255,255,255,.12); padding: 0 18px; background: #070909; }
+      .brand, .status, .actions { display: flex; align-items: center; gap: 10px; min-width: 0; }
+      .brand-mark { width: 22px; height: 14px; border: 2px solid #67e8f9; transform: skewX(-18deg); }
+      .brand strong { font-size: 14px; font-weight: 700; }
+      .brand span, .status { color: #94a3b8; font: 11px ui-monospace, SFMono-Regular, Menlo, monospace; }
+      .status b { color: #bef264; font-weight: 600; }
+      #timer { width: 48px; color: #e2e8f0; text-align: right; font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; }
+      button { height: 34px; border: 1px solid rgba(255,255,255,.18); border-radius: 4px; padding: 0 12px; background: transparent; color: #f8fafc; cursor: pointer; font: 600 12px ui-sans-serif, system-ui, sans-serif; }
+      button:hover { border-color: rgba(251,113,133,.7); color: #fda4af; }
+      main { min-height: 0; display: grid; place-items: center; padding: 8px; }
+      .mosaic { display: grid; grid-template-columns: repeat(${COLUMNS}, minmax(0, 1fr)); grid-template-rows: repeat(${ROWS}, minmax(0, 1fr)); gap: 5px; width: min(calc(100vw - 16px), calc((100vh - 74px) * 0.924)); height: min(calc(100vh - 74px), calc((100vw - 16px) / 0.924)); background: #111; }
+      .tile { position: relative; min-width: 0; min-height: 0; overflow: hidden; background: #080b0b; }
+      iframe { display: block; width: 100%; height: 100%; border: 0; }
+      .tile-number { position: absolute; top: 6px; left: 7px; z-index: 2; color: rgba(255,255,255,.55); font: 10px ui-monospace, SFMono-Regular, Menlo, monospace; pointer-events: none; transition: opacity 300ms ease; }
+      .tile[data-ready="true"] .tile-number { opacity: .18; }
+      .tile[data-ended="true"]::after { content: "ENDED"; position: absolute; inset: 0; display: grid; place-items: center; background: rgba(3,4,4,.82); color: #fda4af; font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; }
+      @media (max-width: 680px) {
+        header { padding: 0 10px; }
+        .brand span { display: none; }
+        .status { font-size: 10px; }
+        button { width: 34px; padding: 0; font-size: 0; }
+        button::after { content: "×"; font-size: 20px; }
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <div class="brand"><i class="brand-mark"></i><strong>run.cloud</strong><span>MOSAIC 08</span></div>
+      <div class="status"><b id="ready-count">0/${DEVICE_COUNT} LIVE</b><span id="timer">--:--</span></div>
+      <div class="actions"><button id="finish" type="button">End demo</button></div>
+    </header>
+    <main><div class="mosaic">${frames}</div></main>
+    <script>
+      const deadline = ${deadline};
+      const tiles = [...document.querySelectorAll('.tile')];
+      const frames = [...document.querySelectorAll('iframe')];
+      const ready = new Set();
+      const count = document.querySelector('#ready-count');
+      const timer = document.querySelector('#timer');
+      const tick = () => {
+        const remaining = Math.max(0, Math.ceil((deadline - Date.now()) / 1000));
+        timer.textContent = String(Math.floor(remaining / 60)).padStart(2, '0') + ':' + String(remaining % 60).padStart(2, '0');
+      };
+      tick();
+      setInterval(tick, 250);
+      window.addEventListener('message', (event) => {
+        const index = frames.findIndex((frame) => frame.contentWindow === event.source);
+        if (index < 0 || !event.data || typeof event.data !== 'object') return;
+        if (event.data.type === 'ios-simulator:status' && event.data.streaming === true) {
+          ready.add(index);
+          tiles[index].dataset.ready = 'true';
+          count.textContent = ready.size + '/${DEVICE_COUNT} LIVE';
+        }
+        if (event.data.type === 'ios-simulator:session-ended') tiles[index].dataset.ended = 'true';
+      });
+      document.querySelector('#finish').addEventListener('click', async () => {
+        document.querySelector('#finish').disabled = true;
+        await fetch('/finish', { method: 'POST' }).catch(() => undefined);
+      });
+    </script>
+  </body>
+</html>`;
+}
+
+export async function startMosaicViewer(sessions, deadline = Date.now() + DEMO_LEASE_MS) {
+  let finish;
+  const finished = new Promise((resolve) => { finish = resolve; });
+  const page = mosaicViewerHtml(sessions, deadline);
+  const server = createServer((request, response) => {
+    if (request.method === 'GET' && request.url === '/') {
+      response.writeHead(200, {
+        'Cache-Control': 'no-store',
+        'Content-Type': 'text/html; charset=utf-8',
+      });
+      response.end(page);
+      return;
+    }
+    if (request.method === 'POST' && request.url === '/finish') {
+      response.writeHead(204);
+      response.end();
+      finish('viewer');
+      return;
+    }
+    response.writeHead(404);
+    response.end('Not found');
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('Could not start the local mosaic viewer.');
+
+  return {
+    url: `http://127.0.0.1:${address.port}/`,
+    finished,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => error ? reject(error) : resolve());
+    }),
+  };
+}
+
+function stopSignal() {
+  let stop;
+  let stopped = false;
+  const promise = new Promise((resolve) => { stop = resolve; });
+  const interrupt = () => {
+    stopped = true;
+    stop('interrupt');
+  };
+  process.once('SIGINT', interrupt);
+  process.once('SIGTERM', interrupt);
+  return {
+    promise,
+    get stopped() { return stopped; },
+    dispose() {
+      process.removeListener('SIGINT', interrupt);
+      process.removeListener('SIGTERM', interrupt);
+    },
+  };
+}
+
+function waitForDemo(deadline, signals) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve('lease'), Math.max(0, deadline - Date.now()));
+  });
+  return Promise.race([timeout, ...signals]).finally(() => clearTimeout(timer));
+}
+
+async function releaseSessions(sessions) {
+  if (sessions.length === 0) return;
+  console.log('\nReleasing eight-device mosaic sessions...');
+  const results = await Promise.allSettled(
+    sessions.map((session) => runCloud(['ios', 'delete', session.id, '--json'])),
+  );
+  results.forEach((result, index) => {
+    const session = sessions[index];
+    if (result.status === 'fulfilled') console.log(`  released ${session.id}`);
+    else console.error(`  failed to release ${session.id}: ${result.reason.message}`);
+  });
+}
+
+function tileUrl(origin, tile) {
+  let url;
+  try {
+    url = new URL('/demos/eight-device-mosaic/', origin);
+  } catch {
+    throw new Error('RUN_CLOUD_DEMO_ORIGIN must be a valid absolute URL.');
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('RUN_CLOUD_DEMO_ORIGIN must use HTTP or HTTPS.');
+  }
+  url.searchParams.set('tile', String(tile));
+  return url.toString();
+}
+
+export async function runDemo(args = process.argv.slice(2), runtime = {}) {
+  const options = parseOptions(args);
+  if (options.help) {
+    console.log('Usage: npm run demo -- [--open]');
+    return;
+  }
+
+  const leaseMs = runtime.leaseMs ?? DEMO_LEASE_MS;
+  if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new Error('The demo lease must be positive.');
+  const deadline = Date.now() + leaseMs;
+  const origin = process.env.RUN_CLOUD_DEMO_ORIGIN || 'https://run.cloud';
+  const sessions = [];
+  const stop = stopSignal();
+  let viewer;
+
+  try {
+    console.log('Starting eight iOS simulator sessions for the mosaic...');
+    const starts = await Promise.allSettled(
+      Array.from({ length: DEVICE_COUNT }, async (_, index) => {
+        const session = await runCloud([
+          'ios',
+          'create',
+          '--display-name',
+          `mosaic-${String(index + 1).padStart(2, '0')}`,
+          '--label',
+          'demo=eight-device-mosaic',
+          '--label',
+          `tile=${index}`,
+          '--hard-timeout',
+          '10m',
+          '--json',
+        ]);
+        sessions[index] = session;
+        await runCloud([
+          'ios',
+          'open-url',
+          tileUrl(origin, index),
+          '--id',
+          session.id,
+          '--json',
+        ]);
+        return session;
+      }),
+    );
+
+    const failures = starts
+      .map((result, index) => ({ result, index }))
+      .filter(({ result }) => result.status === 'rejected');
+    failures.forEach(({ result, index }) => {
+      console.error(`  tile ${index + 1} failed: ${result.reason.message}`);
+    });
+    if (failures.length > 0 || stop.stopped) {
+      throw new Error(failures.length > 0
+        ? `The mosaic requires all ${DEVICE_COUNT} devices; ${failures.length} did not start.`
+        : 'The mosaic was interrupted during setup.');
+    }
+
+    viewer = await startMosaicViewer(sessions, deadline);
+    console.log(`\nEight-device mosaic: ${viewer.url}`);
+    if (options.open) openBrowser(viewer.url);
+    console.log('The mosaic lease is 10 minutes. Press Ctrl+C or select End demo to finish early.');
+    await waitForDemo(deadline, [stop.promise, viewer.finished]);
+  } finally {
+    stop.dispose();
+    if (viewer) await viewer.close();
+    await releaseSessions(sessions.filter(Boolean));
+  }
+}
+
+if (import.meta.url === new URL(process.argv[1], 'file:').href) {
+  runDemo().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/examples/eight-device-mosaic/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "run-cloud-eight-device-mosaic-demo",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "demo": "node demo.mjs",
+    "test": "node --test verify.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}