runcloud 0.1.109 → 0.1.111

package/README.md

@@ -67,6 +67,10 @@ runcloud ios open-url myapp://path --id <id>               # open a URL or deep
 runcloud ios tap <id> 0.5 0.75                             # normalized top-left display coordinates
 runcloud ios type-text <id> "Hello from iOS!"              # printable US ASCII, tab, and line feed
 runcloud ios screenshot <id> --output ios.png              # save a PNG without exposing the viewer URL
+runcloud ios recording start <id> --json                   # start an idempotent MP4 screen recording
+runcloud ios recording stop <id> <recording-id> --json     # stop and finalize it
+runcloud ios recording download <id> <recording-id> \
+  --output ios.mp4 --json                                  # download through the authenticated API
 runcloud ios logs <id> --tail 200                          # read logs from this lease
 runcloud ios logs <id> --follow                            # follow new log entries
 runcloud ios delete <id>                                   # release the session
@@ -96,6 +100,12 @@ report `capsLock`, `numLock`, and `scrollLock` as unsupported keys.
 Coordinates are inclusive normalized display coordinates: `(0, 0)` is the
 top-left and `(1, 1)` is the bottom-right.
 
+The `recording` group is shared by iOS and Android. It provides `start`,
+`list`, `status` (`get` alias), `stop`, and `download`. Pass a stable
+`--idempotency-key` to retry `start` without creating a second recording.
+`download --output <path>` validates the MP4 and reports its byte size and
+SHA-256 digest without printing a signed storage URL.
+
 Interaction commands wait for a correlated simulator acknowledgement. They
 accept `--timeout <milliseconds>` (15 seconds by default), `--request-id <id>`,
 and `--json`. Successful JSON is the API's typed completion envelope. Failures

package/dist/commands/run-cloud.js

@@ -485,6 +485,47 @@ async function captureSimulatorScreenshot(platform, id, opts) {
     else
         console.log(`Saved ${platform} simulator screenshot to ${output} (${bytes.byteLength} bytes)`);
 }
+function simulatorRecordingBase(platform, sessionId) {
+    return `/run-cloud/${platform}/${encodeURIComponent(sessionId)}/recordings`;
+}
+function recordingIdempotencyKey(value) {
+    if (value === undefined)
+        return undefined;
+    const key = value.trim();
+    const hasControlCharacter = [...key].some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31 || code === 127;
+    });
+    if (!key || key.length > 200 || hasControlCharacter) {
+        throw new Error('--idempotency-key must contain 1-200 printable characters');
+    }
+    return key;
+}
+async function downloadSimulatorRecording(platform, sessionId, recordingId, opts) {
+    const bytes = await client().getBinary(`${simulatorRecordingBase(platform, sessionId)}/${encodeURIComponent(recordingId)}/download`);
+    if (bytes.length < 8 || bytes.subarray(4, 8).toString('ascii') !== 'ftyp') {
+        throw new Error('Simulator recording response was not a valid MP4 file');
+    }
+    const output = resolve(opts.output);
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, bytes);
+    const result = {
+        ok: true,
+        sessionId,
+        recordingId,
+        platform,
+        action: 'recording.download',
+        status: 'completed',
+        output,
+        contentType: 'video/mp4',
+        byteSize: bytes.byteLength,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+    };
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(`Saved ${platform} simulator recording to ${output} (${bytes.byteLength} bytes)`);
+}
 function fileBlob(path) {
     const resolved = resolve(path);
     if (!existsSync(resolved))
@@ -715,7 +756,7 @@ function registerSimulatorCommands(program, platform) {
         .addOption(new Option('--dev-host <host>', 'dev-only: target a specific simulator fleet host').hideHelp())
         .action((opts) => action(async () => {
         print(await createSimulatorSession(platform, opts), opts);
-    }));
+    }, opts));
     simulator
         .command('list')
         .description(`List active ${label} sessions`)
@@ -724,7 +765,7 @@ function registerSimulatorCommands(program, platform) {
         .action((opts) => action(async () => {
         const qs = opts.all ? '?all=1' : '';
         print(await client().get(`/run-cloud/${platform}${qs}`), opts);
-    }));
+    }, opts));
     simulator
         .command('get')
         .description(`Show ${article} ${label} session`)
@@ -732,7 +773,7 @@ function registerSimulatorCommands(program, platform) {
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
         print(await client().get(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
-    }));
+    }, opts));
     simulator
         .command('delete')
         .description(`Release ${article} ${label} session`)
@@ -740,7 +781,7 @@ function registerSimulatorCommands(program, platform) {
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
         print(await client().delete(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
-    }));
+    }, opts));
     simulator
         .command('open-url')
         .description(`Open a URL or deep link in ${article} ${label} session`)
@@ -749,7 +790,7 @@ function registerSimulatorCommands(program, platform) {
         .option('--json', 'output JSON', false)
         .action((url, opts) => action(async () => {
         print(await client().post(`/run-cloud/${platform}/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
-    }));
+    }, opts));
     addInteractionOptions(simulator
         .command('tap')
         .description(`Tap normalized display coordinates in ${article} ${label} session`)
@@ -882,6 +923,56 @@ function registerSimulatorCommands(program, platform) {
         .description(`Capture the current display from ${article} ${label} session`)
         .argument('<id>', 'session id')
         .requiredOption('-o, --output <path>', 'PNG output path')).action((id, opts) => action(() => captureSimulatorScreenshot(platform, id, opts), opts));
+    const recording = simulator
+        .command('recording')
+        .alias('recordings')
+        .description(`Record the display of ${article} ${label} session`);
+    recording
+        .command('start')
+        .description(`Start an MP4 screen recording for ${article} active ${label} session`)
+        .argument('<id>', 'session id')
+        .option('--idempotency-key <key>', 'retry-safe key; reuse it to receive the same recording')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        const key = recordingIdempotencyKey(opts.idempotencyKey);
+        const headers = key ? { 'Idempotency-Key': key } : {};
+        print(await client().postWithHeaders(simulatorRecordingBase(platform, id), {}, headers), opts);
+    }, opts));
+    recording
+        .command('list')
+        .description(`List retained screen recordings for ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().get(simulatorRecordingBase(platform, id)), opts);
+    }, opts));
+    recording
+        .command('status')
+        .alias('get')
+        .description(`Show lifecycle state, failures, events, and retrieval metadata for a recording`)
+        .argument('<id>', 'session id')
+        .argument('<recording-id>', 'recording id')
+        .option('--json', 'output JSON', false)
+        .action((id, recordingId, opts) => action(async () => {
+        print(await client().get(`${simulatorRecordingBase(platform, id)}/${encodeURIComponent(recordingId)}`), opts);
+    }, opts));
+    recording
+        .command('stop')
+        .description(`Stop and finalize a screen recording as an MP4`)
+        .argument('<id>', 'session id')
+        .argument('<recording-id>', 'recording id')
+        .option('--json', 'output JSON', false)
+        .action((id, recordingId, opts) => action(async () => {
+        print(await client().post(`${simulatorRecordingBase(platform, id)}/${encodeURIComponent(recordingId)}/stop`), opts);
+    }, opts));
+    recording
+        .command('download')
+        .description(`Download a ready screen recording through the authenticated API`)
+        .argument('<id>', 'session id')
+        .argument('<recording-id>', 'recording id')
+        .requiredOption('-o, --output <path>', 'MP4 output path')
+        .option('--json', 'output file metadata as JSON', false)
+        .action((id, recordingId, opts) => action(() => downloadSimulatorRecording(platform, id, recordingId, opts), opts));
     simulator
         .command('logs')
         .description(`Read or follow logs from ${article} active ${label} session`)
@@ -921,7 +1012,7 @@ function registerSimulatorCommands(program, platform) {
             for (const entry of parsed.entries)
                 writeSimulatorLogEntry(entry, opts.json === true);
         }
-    }));
+    }, opts));
     return simulator;
 }
 function jsonErrorEnvelope(error) {

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.109';
+export const CLI_VERSION = '0.1.111';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.109",
+  "version": "0.1.111",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [

package/skills/run-cloud-ios-simulator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-cloud-ios-simulator
-description: Operate run.cloud iOS simulator and Android emulator sessions with the CLI or TypeScript SDK. Use for creating, installing, inspecting, reading logs, controlling, embedding, smoke-testing, connecting local Metro, taking screenshots, injecting iOS media, or releasing remote mobile sessions.
+description: Operate run.cloud iOS simulator and Android emulator sessions with the CLI or TypeScript SDK. Use for creating, installing, inspecting, reading logs, controlling, embedding, smoke-testing, connecting local Metro, taking screenshots or screen recordings, injecting iOS media, or releasing remote mobile sessions.
 ---
 
 # Operate run.cloud Mobile Sessions
@@ -79,6 +79,22 @@ controls or the `capsLock`, `numLock`, and `scrollLock` keys. Handle structured
 An acknowledgement means input dispatch completed. Confirm visible app effects
 with a screenshot or the signed viewer when the outcome matters.
 
+## Record the Screen
+
+Both platforms expose the same session-scoped recording lifecycle:
+
+```bash
+RECORDING_ID=$(runcloud ios recording start "$SESSION_ID" \
+  --idempotency-key "task-${TASK_ID:-manual}" --json | jq -r '.id')
+runcloud ios recording stop "$SESSION_ID" "$RECORDING_ID" --json
+runcloud ios recording download "$SESSION_ID" "$RECORDING_ID" \
+  --output ./recording.mp4 --json
+```
+
+Use `recording list` and `recording status` to inspect retained state,
+lifecycle events, and actionable failures. Replace `ios` with `android` for an
+Android session. Reuse the idempotency key when retrying `start`.
+
 ## Use the TypeScript SDK
 
 ```bash
@@ -116,11 +132,14 @@ typed acknowledgements. Use `RunCloudError` fields such as `code`, `retryable`,
 `requestId`, and `action` when reporting API failures.
 
 The lifecycle surface also includes `create`, `list`, `get`, `openUrl`, `logs`,
-`followLogs`, and `delete`. Both platforms expose `screenshot`; iOS additionally
-supports `uploadVideo` and `uploadMicrophoneAudio`. Inspect the installed types
-for complete create, asset, log, and media options.
-
-In compact form, `cloud.ios`: `create`, `list`, `get`, `openUrl`, `logs`, `followLogs`, `screenshot`.
+`followLogs`, and `delete`. Both platforms expose `screenshot`,
+`startRecording`, `listRecordings`, `getRecording`, `stopRecording`, and
+`downloadRecording`; iOS additionally supports `uploadVideo` and
+`uploadMicrophoneAudio`. Inspect the installed types for complete create,
+asset, log, recording, and media options.
+
+In compact form, `cloud.ios`: `create`, `list`, `get`, `openUrl`, `logs`,
+`followLogs`, `screenshot`, and the five recording methods above.
 `cloud.android` provides the same shared lifecycle and control operations.
 
 ## Diagnose App Failures