@ytspar/sweetlink 1.17.0 → 1.19.0

package/dist/cli/sweetlink.js

@@ -112,11 +112,24 @@ function getRelativePath(absolutePath) {
  * Report screenshot success to console
  */
 function reportScreenshotSuccess(outputPath, width, height, method, selector) {
-    console.log(`[Sweetlink] ✓ Screenshot saved to: ${getRelativePath(outputPath)}`);
-    console.log(`[Sweetlink] Dimensions: ${width}x${height}`);
-    if (selector)
-        console.log(`[Sweetlink] Selector: ${selector}`);
-    console.log(`[Sweetlink] Method: ${method}`);
+    // One compact line by default; the multi-line version is preserved
+    // behind SWEETLINK_VERBOSE=1 for log-scrapers and the curious.
+    let sizeKb = '';
+    try {
+        sizeKb = ` · ${Math.round(fs.statSync(outputPath).size / 1024)}KB`;
+    }
+    catch { /* file may have been moved or removed */ }
+    const selPart = selector ? ` · ${selector}` : '';
+    if (process.env.SWEETLINK_VERBOSE === '1') {
+        console.log(`[Sweetlink] ✓ Screenshot saved to: ${getRelativePath(outputPath)}`);
+        console.log(`[Sweetlink] Dimensions: ${width}x${height}`);
+        if (selector)
+            console.log(`[Sweetlink] Selector: ${selector}`);
+        console.log(`[Sweetlink] Method: ${method}`);
+    }
+    else {
+        console.log(`[Sweetlink] ✓ Screenshot saved: ${getRelativePath(outputPath)} · ${width}x${height}${sizeKb}${selPart} · ${method}`);
+    }
 }
 let resolvedWsUrl = null;
 const DEFAULT_WS_URL = process.env.SWEETLINK_WS_URL || 'ws://localhost:9223';
@@ -459,6 +472,7 @@ async function screenshot(options) {
             fullPage: options.fullPage,
             viewport: options.viewport,
             padding: options.padding,
+            theme: options.theme,
         });
         const data = resp.data;
         const outputPath = options.output || getDefaultScreenshotPath();
@@ -1852,11 +1866,62 @@ const COMMAND_HELP = {
       stop                        Stop recording and generate session manifest
       status                      Show recording status (default)
 
+    Options for start:
+      --label <text>              Human-friendly label embedded in the manifest + SUMMARY title
+      --viewport <preset|WxH>     Recording viewport (default: 1512x982)
+
     Examples:
-      pnpm sweetlink record start
+      pnpm sweetlink record start --label "login flow"
       pnpm sweetlink snapshot -i
       pnpm sweetlink click @e3
       pnpm sweetlink record stop`,
+    sim: `  sim <ios|android> <command...>
+    Record iOS Simulator or Android Emulator screen while running a command.
+    Wraps \`xcrun simctl io booted recordVideo\` (iOS) or
+    \`adb shell screenrecord\` (Android), writing an .mp4 of what was on
+    screen during your XCUITest / Espresso / fastlane / appium run.
+
+    Options:
+      --output <path>             .mp4 path (default: .sweetlink/sim/<label>-<stamp>.mp4)
+      --label <text>              Embedded in filename
+      --device <name|udid>        Pick a specific simulator/emulator (default: first booted)
+      --time-limit <sec>          Android only — caps screen recording (max 180)
+      --ignore-exit               Don't propagate the recorded command's exit code
+
+    Requirements:
+      iOS:     Xcode + a booted Simulator (Simulator.app)
+      Android: Android Platform Tools (\`adb\`) + a running emulator
+
+    Examples:
+      pnpm sweetlink sim ios "fastlane scan" --device "iPhone 15"
+      pnpm sweetlink sim android "./gradlew connectedAndroidTest"`,
+    term: `  term <command...>
+    Record a shell command's stdout/stderr into asciicast v2 + a self-contained
+    HTML player. Captures real timing; the player has play/pause, 0.1×–4×
+    speed, seek bar, and ANSI colour rendering.
+
+    Options:
+      --output <path>             .cast file path (default: .sweetlink/term/<label>-<stamp>.cast)
+      --label <text>              Label embedded in the .cast title + filename
+      --shell <path>              Shell to invoke the command in (default: /bin/sh)
+      --cols <n>                  Reported terminal width (default: 120)
+      --rows <n>                  Reported terminal height (default: 30)
+      --ignore-exit               Don't propagate the recorded command's exit code
+
+    Examples:
+      pnpm sweetlink term "pytest -v" --label api-tests
+      pnpm sweetlink term "go test ./..." --label go-tests
+      pnpm sweetlink term "make build" --output .sweetlink/term/build.cast`,
+    sessions: `  sessions [list|open]
+    List or open all recorded sessions in this project.
+
+    Subcommands:
+      list                        Print every session with label, duration, action count, error count (default)
+      open                        Open .sweetlink/index.html in the default browser
+
+    Examples:
+      pnpm sweetlink sessions list
+      pnpm sweetlink sessions open`,
     report: `  report [options]
     Print or share the latest session report.
 
@@ -1935,13 +2000,29 @@ Sweetlink CLI - Autonomous Development Bridge
 
 Usage:
   pnpm sweetlink <command> [options]
-
-Commands:
-`);
-    for (const help of Object.values(COMMAND_HELP)) {
-        console.log(help);
-        console.log('');
+  pnpm sweetlink <command> --help        Detailed help for a single command
+  pnpm sweetlink --help --all            Show full help for every command
+
+Commands:`);
+    // Extract the first descriptive sentence from each command's help block
+    // so the top-level help is scannable in <40 lines.
+    for (const [name, help] of Object.entries(COMMAND_HELP)) {
+        // Each block looks like:
+        //   "  command [args]\n    First-line description.\n..."
+        // We pick the first non-empty line after the signature.
+        const lines = help.split('\n').map((l) => l.trim()).filter(Boolean);
+        const desc = lines[1] ?? '';
+        const summary = desc.length > 70 ? desc.slice(0, 67) + '…' : desc;
+        console.log(`  ${name.padEnd(14)} ${summary}`);
+    }
+    if (process.argv.includes('--all')) {
+        console.log('\n— Full per-command details —\n');
+        for (const help of Object.values(COMMAND_HELP)) {
+            console.log(help);
+            console.log('');
+        }
     }
+    console.log('');
     console.log(GLOBAL_HELP);
 }
 function showCommandHelp(command) {
@@ -2003,6 +2084,9 @@ if (hasFlag('--output-schema')) {
         'fill',
         'console',
         'record',
+        'term',
+        'sim',
+        'sessions',
         'proof',
         'report',
         'demo',
@@ -2131,6 +2215,7 @@ async function handleStatusCommand() {
                     height: getArg('--height') ? parseInt(getArg('--height'), 10) : undefined,
                     hover: hasFlag('--hover'),
                     padding: getArg('--padding') ? parseInt(getArg('--padding'), 10) : undefined,
+                    theme: getArg('--theme'),
                     url: getArg('--url'),
                     wait: !hasFlag('--no-wait'), // Wait by default, --no-wait to skip
                     waitTimeout: getArg('--wait-timeout')
@@ -2393,9 +2478,22 @@ async function handleStatusCommand() {
                 const subcommand = args[1];
                 const state = await ensureDaemon(projRoot, targetUrl);
                 if (subcommand === 'start') {
-                    const resp = await daemonRequest(state, 'record-start');
+                    const params = {};
+                    const label = getArg('--label');
+                    const viewport = getArg('--viewport');
+                    const storageState = getArg('--storage-state');
+                    if (label)
+                        params.label = label;
+                    if (viewport)
+                        params.viewport = viewport;
+                    if (storageState)
+                        params.storageState = storageState;
+                    if (hasFlag('--trace'))
+                        params.trace = true;
+                    const resp = await daemonRequest(state, 'record-start', params);
                     const data = resp.data;
-                    console.log(`[Sweetlink] Recording started: ${data.sessionId}`);
+                    console.log(`[Sweetlink] Recording started: ${data.sessionId}` +
+                        (data.label ? ` (${data.label})` : ''));
                     result = data;
                 }
                 else if (subcommand === 'stop') {
@@ -2404,12 +2502,17 @@ async function handleStatusCommand() {
                     const m = data.manifest;
                     console.log(`[Sweetlink] Recording stopped: ${m.sessionId}`);
                     console.log(`  Duration: ${m.duration.toFixed(1)}s | Actions: ${m.commands.length}${m.video ? ' | Video: ' + m.video : ''}`);
-                    // Auto-open the viewer
+                    // Auto-open the viewer (cross-platform; --no-open to suppress)
                     if (data.viewerPath && !hasFlag('--no-open')) {
                         console.log(`  Viewer: ${data.viewerPath}`);
                         const { execFile } = await import('child_process');
-                        const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-                        execFile(openCmd, [data.viewerPath], (err) => {
+                        // `start` on Windows is a cmd builtin, not an exe — must invoke via cmd.
+                        const cmd = process.platform === 'darwin' ? 'open'
+                            : process.platform === 'win32' ? 'cmd'
+                                : 'xdg-open';
+                        const args = process.platform === 'win32' ? ['/c', 'start', '', data.viewerPath]
+                            : [data.viewerPath];
+                        execFile(cmd, args, (err) => {
                             if (err)
                                 console.error('  Could not open viewer:', err.message);
                         });
@@ -2420,6 +2523,100 @@ async function handleStatusCommand() {
                     }
                     result = data;
                 }
+                else if (subcommand === 'exec') {
+                    // record exec "click @e2; fill @e3 hello world; click @e5"
+                    // Runs a semicolon-separated DSL inside a fresh recording, then
+                    // auto-stops. Each step is one of:
+                    //   click <selector|@ref>
+                    //   fill <@ref> <value>          (rest of line after ref = value)
+                    //   press <key>
+                    //   sleep <ms>
+                    // Strip known --flag value pairs from positional args before
+                    // joining what remains as the script body.
+                    const flagsWithValues = new Set(['--url', '--label', '--viewport', '--storage-state']);
+                    const positional = [];
+                    for (let i = 2; i < args.length; i++) {
+                        const a = args[i];
+                        if (a.startsWith('--')) {
+                            if (flagsWithValues.has(a))
+                                i++; // skip its value
+                            continue;
+                        }
+                        positional.push(a);
+                    }
+                    const script = positional.join(' ').trim();
+                    if (!script) {
+                        console.error('[Sweetlink] Error: record exec requires a script. Example: `record exec "click @e2; fill @e3 hello"`');
+                        process.exit(1);
+                    }
+                    const label = getArg('--label');
+                    const startResp = await daemonRequest(state, 'record-start', label ? { label } : {});
+                    const startData = startResp.data;
+                    console.log(`[Sweetlink] Recording: ${startData.sessionId}${label ? ` (${label})` : ''}`);
+                    const steps = script.split(';').map((s) => s.trim()).filter(Boolean);
+                    // Snapshot once up-front so refs resolve.
+                    await daemonRequest(state, 'snapshot', { interactive: true });
+                    for (const step of steps) {
+                        const [verb, ...rest] = step.split(/\s+/);
+                        try {
+                            if (verb === 'click') {
+                                const target = rest[0];
+                                if (!target)
+                                    throw new Error('click needs a target');
+                                if (/^@e\d+$/.test(target)) {
+                                    await daemonRequest(state, 'click-ref', { ref: target });
+                                }
+                                else {
+                                    await daemonRequest(state, 'click-css', { selector: target });
+                                }
+                                console.log(`  · click ${target}`);
+                            }
+                            else if (verb === 'fill') {
+                                const ref = rest[0];
+                                const value = rest.slice(1).join(' ');
+                                if (!ref || !/^@e\d+$/.test(ref))
+                                    throw new Error('fill needs a @ref and a value');
+                                await daemonRequest(state, 'fill-ref', { ref, value });
+                                console.log(`  · fill ${ref} = "${value}"`);
+                            }
+                            else if (verb === 'press') {
+                                const key = rest[0];
+                                if (!key)
+                                    throw new Error('press needs a key');
+                                await daemonRequest(state, 'press-key', { key });
+                                console.log(`  · press ${key}`);
+                            }
+                            else if (verb === 'sleep') {
+                                const ms = parseInt(rest[0] ?? '0', 10);
+                                await new Promise((r) => setTimeout(r, ms));
+                                console.log(`  · sleep ${ms}ms`);
+                            }
+                            else {
+                                throw new Error(`Unknown verb '${verb}'. Allowed: click, fill, press, sleep.`);
+                            }
+                        }
+                        catch (err) {
+                            console.error(`  ✗ step "${step}" failed: ${err instanceof Error ? err.message : err}`);
+                            // Continue to record-stop so the partial recording is preserved.
+                        }
+                    }
+                    const stopResp = await daemonRequest(state, 'record-stop');
+                    const stopData = stopResp.data;
+                    console.log(`[Sweetlink] Done: ${stopData.manifest.commands.length} actions in ` +
+                        `${stopData.manifest.duration.toFixed(1)}s${stopData.viewerPath ? ` · ${stopData.viewerPath}` : ''}`);
+                    result = stopData;
+                }
+                else if (subcommand === 'pause') {
+                    const resp = await daemonRequest(state, 'record-pause');
+                    console.log('[Sweetlink] Recording paused. Use `record resume` to continue.');
+                    result = resp.data;
+                }
+                else if (subcommand === 'resume') {
+                    const resp = await daemonRequest(state, 'record-resume');
+                    const d = resp.data;
+                    console.log(`[Sweetlink] Recording resumed. Paused for ${(d.pausedDurationMs / 1000).toFixed(1)}s.`);
+                    result = resp.data;
+                }
                 else {
                     const resp = await daemonRequest(state, 'record-status');
                     const data = resp.data;
@@ -2553,6 +2750,223 @@ async function handleStatusCommand() {
                 }
                 break;
             }
+            case 'sim': {
+                // Record iOS Simulator or Android Emulator screen while running a command.
+                // Example: sweetlink sim ios "fastlane scan" --device "iPhone 15"
+                const platform = args[1];
+                if (platform !== 'ios' && platform !== 'android') {
+                    console.error('[Sweetlink] Usage: sweetlink sim <ios|android> "<command>" [--output path] [--device <name>]');
+                    process.exit(1);
+                }
+                const flagsWithValues = new Set(['--output', '--label', '--device', '--time-limit']);
+                const positional = [];
+                for (let i = 2; i < args.length; i++) {
+                    const a = args[i];
+                    if (a.startsWith('--')) {
+                        if (flagsWithValues.has(a))
+                            i++;
+                        continue;
+                    }
+                    positional.push(a);
+                }
+                const command = positional.join(' ').trim();
+                if (!command) {
+                    console.error(`[Sweetlink] Error: sim ${platform} requires a command. Example: sweetlink sim ${platform} "fastlane scan"`);
+                    process.exit(1);
+                }
+                const label = getArg('--label');
+                const labelSlug = label
+                    ? label.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40)
+                    : `sim-${platform}`;
+                const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+                const defaultDir = path.join(findProjectRoot(), '.sweetlink', 'sim');
+                const output = getArg('--output') ?? path.join(defaultDir, `${labelSlug}-${stamp}.mp4`);
+                ensureDir(output);
+                const device = getArg('--device');
+                console.log(`[Sweetlink] Recording ${platform} simulator: ${command}`);
+                let recResult;
+                if (platform === 'ios') {
+                    const { recordIosSimulator } = await import('../simulator/ios.js');
+                    recResult = await recordIosSimulator({ command, output, device });
+                }
+                else {
+                    const { recordAndroidEmulator } = await import('../simulator/android.js');
+                    const tl = getArg('--time-limit');
+                    recResult = await recordAndroidEmulator({
+                        command, output, device,
+                        timeLimit: tl ? parseInt(tl, 10) : undefined,
+                    });
+                }
+                let sizeKb = '?';
+                try {
+                    sizeKb = String(Math.round(fs.statSync(output).size / 1024));
+                }
+                catch { /* file may not exist if recordingClosed is false */ }
+                console.log(`[Sweetlink] ${recResult.recordingClosed ? '✓' : '⚠'} ${getRelativePath(output)} · ` +
+                    `${recResult.durationSec.toFixed(1)}s · ${sizeKb}KB · ${recResult.device} · exit=${recResult.exitCode}` +
+                    (recResult.recordingClosed ? '' : ' (recording was force-killed; mp4 may be incomplete)'));
+                result = {
+                    path: output,
+                    device: recResult.device,
+                    durationSec: recResult.durationSec,
+                    exitCode: recResult.exitCode,
+                    recordingClosed: recResult.recordingClosed,
+                };
+                if (recResult.exitCode !== 0 && !hasFlag('--ignore-exit')) {
+                    process.exit(recResult.exitCode);
+                }
+                break;
+            }
+            case 'term': {
+                // Record a shell command's stdout/stderr into asciicast v2 + HTML player.
+                // Example: sweetlink term "pytest -v" --label api-tests
+                const flagsWithValues = new Set(['--output', '--label', '--shell', '--cols', '--rows']);
+                const positional = [];
+                for (let i = 1; i < args.length; i++) {
+                    const a = args[i];
+                    if (a.startsWith('--')) {
+                        if (flagsWithValues.has(a))
+                            i++;
+                        continue;
+                    }
+                    positional.push(a);
+                }
+                const command = positional.join(' ').trim();
+                if (!command) {
+                    console.error('[Sweetlink] Error: term requires a command. Example: sweetlink term "pytest tests/"');
+                    process.exit(1);
+                }
+                const label = getArg('--label');
+                const labelSlug = label
+                    ? label.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40)
+                    : 'term';
+                const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+                const defaultDir = path.join(findProjectRoot(), '.sweetlink', 'term');
+                const output = getArg('--output') ?? path.join(defaultDir, `${labelSlug}-${stamp}.cast`);
+                ensureDir(output);
+                console.log(`[Sweetlink] Recording terminal: ${command}`);
+                const { captureTerminal } = await import('../term/recorder.js');
+                const { generatePlayer } = await import('../term/player.js');
+                const cap = await captureTerminal({
+                    command,
+                    output,
+                    label,
+                    shell: getArg('--shell'),
+                    cols: getArg('--cols') ? parseInt(getArg('--cols'), 10) : undefined,
+                    rows: getArg('--rows') ? parseInt(getArg('--rows'), 10) : undefined,
+                });
+                const playerPath = await generatePlayer({ castPath: output });
+                console.log(`[Sweetlink] ✓ ${getRelativePath(output)} · ${cap.durationSec.toFixed(1)}s · ` +
+                    `${cap.events} events · ${(cap.bytes / 1024).toFixed(0)}KB · exit=${cap.exitCode}`);
+                console.log(`[Sweetlink] ▶ ${getRelativePath(playerPath)}`);
+                result = {
+                    castPath: output,
+                    playerPath,
+                    durationSec: cap.durationSec,
+                    bytes: cap.bytes,
+                    events: cap.events,
+                    exitCode: cap.exitCode,
+                };
+                // Propagate the recorded command's exit code by default so CI fails
+                // when the wrapped tests fail.
+                if (cap.exitCode !== 0 && !hasFlag('--ignore-exit')) {
+                    process.exit(cap.exitCode);
+                }
+                break;
+            }
+            case 'sessions': {
+                const sub = args[1];
+                const projRoot = findProjectRoot();
+                const targetUrl = getArg('--url') ?? 'http://localhost:3000';
+                const state = await ensureDaemon(projRoot, targetUrl);
+                const resp = await daemonRequest(state, 'sessions-list');
+                const data = resp.data;
+                if (sub === 'list' || !sub) {
+                    if (data.sessions.length === 0) {
+                        console.log('[Sweetlink] No sessions found.');
+                    }
+                    else {
+                        console.log(`[Sweetlink] ${data.sessions.length} session(s):\n`);
+                        for (const s of data.sessions) {
+                            const errTotal = s.errors ? s.errors.console + s.errors.network + s.errors.server : 0;
+                            const errBadge = errTotal > 0 ? ` · ${errTotal} err` : '';
+                            const labelTxt = s.label ? ` [${s.label}]` : '';
+                            const dur = s.duration ? `${s.duration.toFixed(1)}s` : '—';
+                            console.log(`  ${s.sessionId}${labelTxt} · ${dur} · ${s.actionCount} actions${errBadge}`);
+                        }
+                        if (data.indexPath)
+                            console.log(`\n  Index: ${data.indexPath}`);
+                    }
+                    result = { sessions: data.sessions };
+                }
+                else if (sub === 'diff') {
+                    // sessions diff <a> <b> — compare two recordings
+                    const [aId, bId] = [args[2], args[3]];
+                    if (!aId || !bId) {
+                        console.error('[Sweetlink] Usage: sessions diff <session-A> <session-B>');
+                        process.exit(1);
+                    }
+                    const findSession = (id) => data.sessions.find((s) => s.sessionId === id || s.sessionId.endsWith(id));
+                    const a = findSession(aId);
+                    const b = findSession(bId);
+                    if (!a || !b) {
+                        console.error(`[Sweetlink] Could not find session: ${!a ? aId : bId}`);
+                        process.exit(1);
+                    }
+                    const aManifest = JSON.parse(fs.readFileSync(a.manifestPath, 'utf-8'));
+                    const bManifest = JSON.parse(fs.readFileSync(b.manifestPath, 'utf-8'));
+                    const aActions = aManifest.commands.map((c) => `${c.action} ${c.args.join(' ')}`);
+                    const bActions = bManifest.commands.map((c) => `${c.action} ${c.args.join(' ')}`);
+                    console.log(`\n${a.sessionId}${a.label ? ` "${a.label}"` : ''}  vs  ${b.sessionId}${b.label ? ` "${b.label}"` : ''}\n`);
+                    console.log(`Duration: ${a.duration?.toFixed(1)}s  vs  ${b.duration?.toFixed(1)}s`);
+                    console.log(`Actions:  ${a.actionCount}  vs  ${b.actionCount}`);
+                    const aErr = a.errors ? a.errors.console + a.errors.network + a.errors.server : 0;
+                    const bErr = b.errors ? b.errors.console + b.errors.network + b.errors.server : 0;
+                    console.log(`Errors:   ${aErr}  vs  ${bErr}`);
+                    // Action diff (myers-style "added/removed" by line)
+                    const inA = new Set(aActions);
+                    const inB = new Set(bActions);
+                    const added = bActions.filter((x) => !inA.has(x));
+                    const removed = aActions.filter((x) => !inB.has(x));
+                    if (removed.length) {
+                        console.log(`\nOnly in ${a.sessionId}:`);
+                        removed.forEach((s) => console.log(`  - ${s}`));
+                    }
+                    if (added.length) {
+                        console.log(`\nOnly in ${b.sessionId}:`);
+                        added.forEach((s) => console.log(`  + ${s}`));
+                    }
+                    if (!added.length && !removed.length) {
+                        console.log('\nAction sequences are identical.');
+                    }
+                    result = {
+                        a: { id: a.sessionId, label: a.label, duration: a.duration, actions: a.actionCount, errors: aErr },
+                        b: { id: b.sessionId, label: b.label, duration: b.duration, actions: b.actionCount, errors: bErr },
+                        added,
+                        removed,
+                    };
+                }
+                else if (sub === 'open') {
+                    // Open the index.html in the browser
+                    if (data.indexPath) {
+                        const { execFile } = await import('child_process');
+                        const cmd = process.platform === 'darwin' ? 'open'
+                            : process.platform === 'win32' ? 'cmd'
+                                : 'xdg-open';
+                        const cmdArgs = process.platform === 'win32'
+                            ? ['/c', 'start', '', data.indexPath]
+                            : [data.indexPath];
+                        execFile(cmd, cmdArgs, () => { });
+                        console.log(`[Sweetlink] Opened ${data.indexPath}`);
+                    }
+                    result = { indexPath: data.indexPath };
+                }
+                else {
+                    console.error(`[Sweetlink] Unknown sessions subcommand: ${sub}. Try: list, open`);
+                    process.exit(1);
+                }
+                break;
+            }
             case 'demo': {
                 const sub = args[1];
                 const projRoot = findProjectRoot();