robopark 2.8.35 → 3.0.0

package/dist/robopark/motor-control.js

@@ -0,0 +1,195 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { registerAutoStart, unregisterAutoStart } from './auto-start.js';
+import { findPython, findVisionMotorPath, prepareRobotPython } from './python-env.js';
+import { resolveContext } from './profile.js';
+const stateDir = join(homedir(), '.robopark');
+const registryPath = join(stateDir, 'motors.json');
+function slug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'robot';
+}
+function serviceUnit(name) {
+    return `robopark-robot-motor-${slug(name)}.service`;
+}
+function serviceConfigPath(name) {
+    return join(stateDir, `motor-${slug(name)}.json`);
+}
+function atomicJson(path, value) {
+    mkdirSync(stateDir, { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, path);
+}
+export function parseMotorDefinitions(specs = []) {
+    const definitions = [];
+    for (const raw of specs) {
+        const match = String(raw).trim().match(/^(\d{1,2})[-:=]([a-zA-Z][a-zA-Z0-9_-]*)(?::(low|high))?$/i);
+        if (!match)
+            throw new Error(`invalid motor '${raw}'; use GPIO-NAME, for example 17-head or 27-eyes:low`);
+        const gpio = Number(match[1]);
+        if (gpio < 2 || gpio > 27)
+            throw new Error(`BCM GPIO ${gpio} is outside the safe range 2..27`);
+        definitions.push({ name: match[2].toLowerCase(), gpio, active_high: match[3]?.toLowerCase() !== 'low' });
+    }
+    const names = new Set();
+    const pins = new Set();
+    for (const motor of definitions) {
+        if (names.has(motor.name))
+            throw new Error(`motor name '${motor.name}' is duplicated`);
+        if (pins.has(motor.gpio))
+            throw new Error(`BCM GPIO ${motor.gpio} is assigned more than once`);
+        names.add(motor.name);
+        pins.add(motor.gpio);
+    }
+    return definitions;
+}
+function mergeRegistry(definitions) {
+    if (!definitions.length)
+        return;
+    let current = {};
+    if (existsSync(registryPath)) {
+        try {
+            current = JSON.parse(readFileSync(registryPath, 'utf8'));
+        }
+        catch { /* replace malformed registry */ }
+    }
+    const merged = {};
+    for (const [name, value] of Object.entries(current)) {
+        merged[name] = typeof value === 'number'
+            ? { name, gpio: value, active_high: true }
+            : { name: value.name || name, gpio: Number(value.gpio), active_high: value.active_high !== false };
+    }
+    for (const definition of definitions) {
+        for (const [name, existing] of Object.entries(merged)) {
+            if (existing.gpio === definition.gpio && name !== definition.name)
+                delete merged[name];
+        }
+        merged[definition.name] = definition;
+    }
+    atomicJson(registryPath, merged);
+}
+function loadServiceConfig(name) {
+    const path = serviceConfigPath(name);
+    if (!existsSync(path))
+        return { name, host: '127.0.0.1', port: 8001 };
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+async function request(name, path, init = {}) {
+    const config = loadServiceConfig(name);
+    const headers = new Headers(init.headers);
+    if (config.token)
+        headers.set('x-robopark-motor-token', config.token);
+    if (init.body)
+        headers.set('content-type', 'application/json');
+    const response = await fetch(`http://127.0.0.1:${config.port}${path}`, {
+        ...init,
+        headers,
+        signal: AbortSignal.timeout(5_000),
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(body.detail || body.message || `motor API HTTP ${response.status}`);
+    return body;
+}
+export async function ensureMotorService(name, opts = {}) {
+    if (process.platform !== 'linux')
+        throw new Error('the production GPIO motor server requires Linux/Raspberry Pi');
+    const script = await findVisionMotorPath();
+    if (!script)
+        throw new Error('could not find motor_server.py');
+    const python = prepareRobotPython(findPython(), script, ['fastapi', 'uvicorn', 'pydantic', 'lgpio'], 'requirements_motor.txt');
+    if (!python)
+        throw new Error('could not prepare the motor server Python environment');
+    const context = await resolveContext({ token: opts.token });
+    const config = {
+        name,
+        host: opts.host ?? '127.0.0.1',
+        port: Number(opts.port ?? 8001),
+        token: context.token,
+    };
+    if (config.host !== '127.0.0.1' && config.host !== 'localhost') {
+        throw new Error('motor server must bind to loopback; remote actuation is routed through the authenticated robot supervisor');
+    }
+    if (!Number.isInteger(config.port) || config.port < 1024 || config.port > 65535)
+        throw new Error('motor port must be 1024..65535');
+    mergeRegistry(parseMotorDefinitions(opts.motor));
+    atomicJson(serviceConfigPath(name), config);
+    const env = {
+        ROBOPARK_ROBOT_NAME: name,
+        ROBOPARK_MOTOR_HOST: '127.0.0.1',
+        ROBOPARK_MOTOR_PORT: String(config.port),
+        ROBOPARK_MOTORS_FILE: registryPath,
+    };
+    if (config.token)
+        env.ROBOPARK_MOTOR_TOKEN = config.token;
+    if (opts.autoStart === false) {
+        const child = spawn(python, [script], { env: { ...process.env, ...env }, detached: true, stdio: 'ignore' });
+        child.unref();
+        return `started motor server for ${name} without boot registration`;
+    }
+    const registered = await registerAutoStart({
+        role: 'robot-motor', name, command: python, args: [script], env,
+    });
+    if (!registered.ok)
+        throw new Error(registered.message);
+    return registered.message;
+}
+export async function roboparkMotorUp(name, opts) {
+    console.log(chalk.bold('\n  robopark motor up'));
+    console.log(chalk.dim('  ' + '-'.repeat(52)));
+    const message = await ensureMotorService(name, opts);
+    console.log(`  robot:    ${chalk.cyan(name)}`);
+    console.log(`  endpoint: ${chalk.cyan(`http://127.0.0.1:${opts.port ?? '8001'}`)}`);
+    console.log(`  registry: ${chalk.cyan(registryPath)}`);
+    console.log(chalk.green(`  ${message}`));
+}
+export async function roboparkMotorStatus(name) {
+    const service = process.platform === 'linux'
+        ? spawnSync('systemctl', ['is-active', serviceUnit(name)], { encoding: 'utf8' }).stdout.trim()
+        : 'unknown';
+    try {
+        const status = await request(name, '/status');
+        const discovered = await request(name, '/discover');
+        console.log(chalk.bold(`\n  ${name} motors`));
+        console.log(`  service:  ${service === 'active' ? chalk.green(service) : chalk.yellow(service)}`);
+        console.log(`  API:      ${chalk.green(status.status || 'ready')}`);
+        console.log(`  GPIO:     ${discovered.gpio_available ? chalk.green('available') : chalk.red('unavailable')}`);
+        console.log(`  registry: ${discovered.count} motor(s)`);
+        for (const motor of discovered.motors || [])
+            console.log(`    ${motor.name}: BCM GPIO ${motor.gpio}${motor.active_high === false ? ' (active low)' : ''}`);
+    }
+    catch (error) {
+        throw new Error(`motor endpoint is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function roboparkMotorRestart(name) {
+    if (process.platform !== 'linux')
+        throw new Error('motor restart currently requires systemd');
+    const result = spawnSync('systemctl', ['restart', serviceUnit(name)], { encoding: 'utf8' });
+    if (result.status !== 0)
+        throw new Error(String(result.stderr || result.stdout || 'motor restart failed').trim());
+    console.log(chalk.green(`  restarted ${serviceUnit(name)}`));
+}
+export function roboparkMotorDown(name) {
+    const result = unregisterAutoStart('robot-motor', name);
+    if (!result.ok)
+        throw new Error(result.message);
+    console.log(chalk.green(`  ${result.message}`));
+}
+export async function roboparkMotorDiscover(name) {
+    const data = await request(name, '/discover');
+    console.log(JSON.stringify(data, null, 2));
+}
+export async function roboparkMotorTest(name, motorName, seconds = 0.3) {
+    const data = motorName
+        ? await request(name, '/trigger-motor', { method: 'POST', body: JSON.stringify({ motor_name: motorName, seconds }) })
+        : await request(name, '/test', { method: 'POST', body: JSON.stringify({ seconds_on: seconds, seconds_pause: 0.2 }) });
+    console.log(chalk.green(`  ${data.message || 'motor test started'}`));
+}
+export async function roboparkMotorStop(name) {
+    const data = await request(name, '/stop-motors', { method: 'POST', body: '{}' });
+    console.log(chalk.green(`  ${data.message || 'motors stopped'}`));
+}

package/dist/robopark/preview-agent-launcher.js

@@ -0,0 +1,77 @@
+/**
+ * RoboPark — `robopark preview-agent` launcher.
+ *
+ * Starts preview_agent.py with the right Python interpreter, auto-discovers
+ * the scheduler URL from mesh/hub, and detaches unless --foreground.
+ */
+import { spawn } from 'node:child_process';
+import { hostname } from 'node:os';
+import chalk from 'chalk';
+import { discoverContext } from './discovery.js';
+import { findPython, findSchedulerPath, prepareRobotPython } from './python-env.js';
+const DEFAULT_SCHEDULER_PORT = 8080;
+export async function roboparkPreviewAgent(opts) {
+    const ctx = await discoverContext();
+    const port = DEFAULT_SCHEDULER_PORT;
+    const schedulerUrl = opts.schedulerUrl !== 'http://localhost:8080'
+        ? opts.schedulerUrl
+        : ctx.hub
+            ? `http://${ctx.hub.ip}:${port}`
+            : 'http://localhost:8080';
+    const robotId = opts.robotId ?? hostname().split('.')[0];
+    const script = await findSchedulerPath();
+    if (!script) {
+        console.log(chalk.red('  ✗ could not find preview_agent.py'));
+        process.exit(1);
+    }
+    const python = prepareRobotPython(findPython(), script);
+    if (!python)
+        process.exit(1);
+    const args = [
+        script,
+        '--scheduler-url', schedulerUrl,
+        '--robot-id', robotId,
+        '--video-device', opts.videoDevice,
+        '--audio-device', opts.audioDevice,
+        '--width', opts.width,
+        '--height', opts.height,
+        '--fps', opts.fps,
+    ];
+    if (opts.deviceToken)
+        args.push('--device-token', opts.deviceToken);
+    if (opts.enrollmentToken)
+        args.push('--enrollment-token', opts.enrollmentToken);
+    if (opts.visionWebhookPort)
+        args.push('--vision-webhook-port', opts.visionWebhookPort);
+    if (opts.visionTriggerCooldown)
+        args.push('--vision-trigger-cooldown', opts.visionTriggerCooldown);
+    if (opts.visionSessionSeconds)
+        args.push('--vision-session-seconds', opts.visionSessionSeconds);
+    if (opts.robovisionUrl)
+        args.push('--robovision-url', opts.robovisionUrl);
+    if (opts.saveConfig)
+        args.push('--save-config');
+    console.log(chalk.bold('\n  robopark preview-agent'));
+    console.log(chalk.dim('  ' + '─'.repeat(52)));
+    console.log(`  robot:     ${chalk.cyan(robotId)}`);
+    console.log(`  scheduler: ${chalk.cyan(schedulerUrl)}`);
+    console.log(`  video:     ${chalk.cyan(opts.videoDevice)}`);
+    console.log(`  audio:     ${chalk.cyan(opts.audioDevice)}`);
+    if (opts.visionWebhookPort)
+        console.log(`  vision webhook: ${chalk.cyan(':' + opts.visionWebhookPort)} (point RoboVisionAI_PI's motion webhook here)`);
+    console.log();
+    if (opts.foreground) {
+        const proc = spawn(python, args, { stdio: 'inherit' });
+        await new Promise((resolve) => {
+            proc.on('close', () => resolve());
+        });
+        return;
+    }
+    const proc = spawn(python, args, {
+        stdio: 'ignore',
+        detached: true,
+        env: { ...process.env, ROBOPARK_PREVIEW_AGENT: '1' },
+    });
+    proc.unref();
+    console.log(chalk.green('  ✓ preview agent started in background'));
+}

package/dist/robopark/probe.js

@@ -0,0 +1,138 @@
+/**
+ * RoboPark — `robopark probe`.
+ *
+ * Spawn opencode agents (locally or over mesh) to build an accurate
+ * infrastructure map. Discovers peers via Tailscale, then runs a structured
+ * prompt through the locally installed `opencode` CLI for each node.
+ *
+ * The agent is asked only to report facts — it does not mutate anything.
+ */
+import { spawn } from 'node:child_process';
+import { hostname, networkInterfaces } from 'node:os';
+import chalk from 'chalk';
+import { discoverContext } from './discovery.js';
+function getLanIps() {
+    const out = [];
+    for (const [name, addrs] of Object.entries(networkInterfaces())) {
+        if (!addrs)
+            continue;
+        for (const a of addrs) {
+            if (a.family === 'IPv4' && !a.internal)
+                out.push(a.address);
+        }
+    }
+    return out;
+}
+function findOpencode() {
+    const names = process.platform === 'win32' ? ['opencode.exe', 'opencode'] : ['opencode'];
+    for (const name of names) {
+        try {
+            const { execSync } = require('node:child_process');
+            execSync(`${name} --version`, { stdio: 'ignore' });
+            return name;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function runOpencodePrompt(prompt, timeoutMs) {
+    const bin = findOpencode();
+    if (!bin)
+        return Promise.resolve('opencode CLI not found; install opencode to run probes');
+    return new Promise((resolve) => {
+        const proc = spawn(bin, ['--no-project', '--non-interactive'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, OPENCODE_QUIET: '1' },
+        });
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            proc.kill('SIGTERM');
+        }, timeoutMs);
+        proc.stdin?.write(prompt);
+        proc.stdin?.end();
+        proc.stdout?.on('data', (d) => { stdout += d.toString(); });
+        proc.stderr?.on('data', (d) => { stderr += d.toString(); });
+        proc.on('close', () => {
+            clearTimeout(timer);
+            if (killed)
+                resolve(stdout + '\n[probe timed out]');
+            else
+                resolve(stdout || stderr || '(no output)');
+        });
+        proc.on('error', (err) => {
+            clearTimeout(timer);
+            resolve(`opencode error: ${err.message}`);
+        });
+    });
+}
+function probePrompt(target, token) {
+    const tokenHint = token ? `mesh token is "${token}"` : 'no mesh token provided';
+    return `You are an infrastructure probe for the RoboPark fleet.
+Target node: ${target.name} (${target.ip}) via ${target.source}.
+${tokenHint}.
+
+Do NOT modify anything. Only report facts. Keep your answer under 600 words.
+
+Please report:
+1. Hostname, OS, architecture.
+2. LAN IPs and Tailscale IP if available.
+3. Whether these processes are running: infinicode node, robopark scheduler, robopark preview_agent.
+4. If this node is the hub, whether the scheduler at http://localhost:8080/api/settings responds and what production_mode is.
+5. If this node is a robot/satellite, whether it has enrolled to the scheduler and whether ~/.robopark/device_token exists.
+6. Any recent errors in journalctl/systemctl for infinicode or robopark services (last 10 lines).
+7. Whether a camera (/dev/video0) or microphone is detected.
+
+Answer as concise structured Markdown bullet list.`;
+}
+async function probeTarget(target, opts) {
+    const timeoutMs = opts.timeout ? parseInt(opts.timeout, 10) * 1000 : 60000;
+    try {
+        const summary = await runOpencodePrompt(probePrompt(target, opts.token), timeoutMs);
+        return { target, ok: true, summary, timestamp: new Date().toISOString() };
+    }
+    catch (e) {
+        return { target, ok: false, error: e.message, summary: '', timestamp: new Date().toISOString() };
+    }
+}
+export async function roboparkProbe(opts) {
+    const ctx = await discoverContext();
+    const self = { name: hostname().split('.')[0], ip: getLanIps()[0] || '127.0.0.1', source: 'self' };
+    const rawTargets = opts.local ? [self] : [self, ...(ctx.robots || []), ...(ctx.hub ? [ctx.hub] : [])];
+    const targets = rawTargets.map((t) => ({
+        name: t.name,
+        ip: t.ip,
+        source: t === self ? 'self' : 'tailscale',
+    }));
+    console.log(chalk.bold('\n  robopark probe'));
+    console.log(chalk.dim('  ' + '─'.repeat(52)));
+    console.log(`  targets: ${chalk.cyan(targets.length)}`);
+    console.log();
+    const results = [];
+    for (const t of targets) {
+        process.stdout.write(chalk.dim(`  probing ${t.name}… `));
+        const r = await probeTarget(t, opts);
+        results.push(r);
+        console.log(r.ok ? chalk.green('ok') : chalk.red('failed'));
+    }
+    console.log();
+    console.log(chalk.bold('  Probe results'));
+    console.log(chalk.dim('  ' + '─'.repeat(52)));
+    for (const r of results) {
+        console.log(`\n  ${chalk.cyan(r.target.name)} (${r.target.ip})`);
+        if (!r.ok) {
+            console.log(chalk.red(`    error: ${r.error}`));
+            continue;
+        }
+        console.log(r.summary.split('\n').map(l => '    ' + l).join('\n'));
+    }
+    if (opts.output) {
+        const { writeFileSync } = await import('node:fs');
+        writeFileSync(opts.output, JSON.stringify(results, null, 2), 'utf8');
+        console.log(`\n  ${chalk.green('✓')} wrote ${opts.output}`);
+    }
+}

package/dist/robopark/profile.js

@@ -0,0 +1,69 @@
+/**
+ * RoboPark — persisted hub profile.
+ *
+ * Operators kept hand-typing the same --hub-url/--token/--scheduler-url/--site
+ * flags on every command. `robopark hub-use` (see robopark-cli.ts) saves those
+ * once to ~/.robopark/hub-profile.json; `resolveContext()` here is the single
+ * place that layers them back in as defaults so every command benefits without
+ * having to re-implement the precedence logic itself.
+ *
+ * Precedence (highest wins): explicit CLI flags > saved hub profile > existing
+ * discoverContext() auto-discovery (Tailscale/LAN/local config files).
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { discoverContext } from './discovery.js';
+const PROFILE_DIR = join(homedir(), '.robopark');
+const PROFILE_PATH = join(PROFILE_DIR, 'hub-profile.json');
+/** Persist a hub profile to ~/.robopark/hub-profile.json. */
+export function saveHubProfile(profile) {
+    mkdirSync(PROFILE_DIR, { recursive: true });
+    writeFileSync(PROFILE_PATH, JSON.stringify(profile, null, 2), 'utf8');
+}
+/** Load the saved hub profile, or null if none has been saved. */
+export function loadHubProfile() {
+    if (!existsSync(PROFILE_PATH))
+        return null;
+    try {
+        return JSON.parse(readFileSync(PROFILE_PATH, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Delete the saved hub profile, if any. */
+export function clearHubProfile() {
+    if (existsSync(PROFILE_PATH)) {
+        try {
+            rmSync(PROFILE_PATH);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+const DEFAULT_MESH_PORT = 47913;
+const DEFAULT_SCHEDULER_PORT = 8080;
+/**
+ * Resolve hub/scheduler/token/site context with the standard precedence:
+ * explicit CLI flags win, then the saved hub profile, then discoverContext()
+ * auto-discovery as the final fallback.
+ *
+ * Kept as a separate wrapper (rather than changing discoverContext()'s
+ * signature/behavior) so every existing discoverContext() caller keeps
+ * working unchanged when no profile has been saved.
+ */
+export async function resolveContext(opts = {}) {
+    const discovered = await discoverContext();
+    const profile = loadHubProfile();
+    const hubUrl = opts.hubUrl
+        ?? profile?.hubUrl
+        ?? (discovered.hub ? `http://${discovered.hub.ip}:${discovered.meshPort ?? DEFAULT_MESH_PORT}` : undefined);
+    const token = opts.token ?? profile?.token ?? discovered.meshToken;
+    const schedulerUrl = opts.schedulerUrl
+        ?? profile?.schedulerUrl
+        ?? (hubUrl ? hubUrl.replace(/:\d+$/, `:${DEFAULT_SCHEDULER_PORT}`) : undefined);
+    const site = opts.site ?? profile?.site;
+    return { hubUrl, token, schedulerUrl, site, discovered };
+}

package/dist/robopark/python-env.js

@@ -0,0 +1,162 @@
+/**
+ * RoboPark — shared Python environment helpers for `enroll`, `preview-agent`,
+ * and `vision-agent`, which spawn preview_agent.py / app_pi_clean.py.
+ */
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import chalk from 'chalk';
+/** Modules preview_agent.py imports — kept in sync with requirements-robot.txt. */
+const REQUIRED_MODULES = ['httpx', 'cv2', 'pyaudio', 'livekit'];
+/** Modules app_pi_clean.py imports — kept in sync with requirements_pi_unified.txt. */
+export const VISION_REQUIRED_MODULES = ['flask', 'flask_cors', 'cv2', 'numpy', 'requests'];
+async function findPackageScript(relativePath) {
+    const parts = relativePath.split('/');
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // Standalone npm package: dist/robopark/python-env.js -> package root.
+        join(here, '..', '..', ...parts),
+        // InfiniCode monorepo/local build compatibility.
+        join(here, '..', '..', '..', 'packages', 'robopark', ...parts),
+        join(process.cwd(), 'packages', 'robopark', ...parts),
+        join(process.cwd(), ...parts),
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    try {
+        const { createRequire } = await import('node:module');
+        const require = createRequire(import.meta.url);
+        const pkgMain = require.resolve('infinicode/package.json');
+        const p = join(pkgMain, '..', 'packages', 'robopark', ...relativePath.split('/'));
+        if (existsSync(p))
+            return p;
+    }
+    catch { /* ignore */ }
+    return null;
+}
+export async function findSchedulerPath() {
+    return findPackageScript('scheduler/preview_agent.py');
+}
+export async function findRobotSupervisorPath() {
+    return findPackageScript('scheduler/robot_supervisor.py');
+}
+export async function findVisionPath() {
+    return findPackageScript('vision/app_pi_clean.py');
+}
+export async function findVisionAudioPath() {
+    return findPackageScript('vision/audio_server_pi.py');
+}
+export async function findVisionMotorPath() {
+    return findPackageScript('vision/motor_server.py');
+}
+export async function findConversationPath() {
+    return findPackageScript('conversation/elevenlabs_agent.py');
+}
+export async function findScreenRuntimePath() {
+    return findPackageScript('screen/screen_runtime.py');
+}
+export function findPython() {
+    const names = process.platform === 'win32'
+        ? ['python', 'python3', 'py']
+        : ['python3', 'python'];
+    for (const name of names) {
+        try {
+            execSync(`${name} --version`, { stdio: 'ignore' });
+            return name;
+        }
+        catch {
+            continue;
+        }
+    }
+    return process.platform === 'win32' ? 'python' : 'python3';
+}
+const ROBOPARK_VENV = join(homedir(), '.robopark', 'venv');
+function venvPythonPath() {
+    return process.platform === 'win32'
+        ? join(ROBOPARK_VENV, 'Scripts', 'python.exe')
+        : join(ROBOPARK_VENV, 'bin', 'python');
+}
+function missingModules(python, modules) {
+    return modules.filter(mod => {
+        const res = spawnSync(python, ['-c', `import ${mod}`], { stdio: 'ignore' });
+        return res.status !== 0;
+    });
+}
+/**
+ * Ensure a robot-side script's Python deps are importable, installing them
+ * from a requirements file (next to the script) if not. Returns false — with
+ * a message already printed — if deps are still missing after the install
+ * attempt, so callers can bail out before hitting a raw traceback.
+ *
+ * Defaults match preview_agent.py; pass `modules`/`reqFile` for other scripts
+ * (e.g. app_pi_clean.py + requirements_pi_unified.txt).
+ */
+export function ensurePythonDeps(python, scriptPath, modules = REQUIRED_MODULES, reqFile = 'requirements-robot.txt') {
+    const missing = missingModules(python, modules);
+    if (missing.length === 0)
+        return true;
+    const reqPath = join(scriptPath, '..', reqFile);
+    if (!existsSync(reqPath)) {
+        console.log(chalk.red(`  ✗ missing Python modules: ${missing.join(', ')} (and ${reqFile} not found next to ${scriptPath})`));
+        return false;
+    }
+    console.log(chalk.dim(`  installing Python deps (${missing.join(', ')})…`));
+    const install = spawnSync(python, ['-m', 'pip', 'install', '-r', reqPath], { stdio: 'inherit' });
+    if (install.status !== 0) {
+        console.log(chalk.red(`  ✗ pip install failed — install manually: ${python} -m pip install -r "${reqPath}"`));
+        return false;
+    }
+    const stillMissing = missingModules(python, modules);
+    if (stillMissing.length > 0) {
+        console.log(chalk.red(`  ✗ still missing after install: ${stillMissing.join(', ')} — install manually: ${python} -m pip install -r "${reqPath}"`));
+        return false;
+    }
+    return true;
+}
+/**
+ * Create and maintain the isolated robot runtime at ~/.robopark/venv.
+ * System site packages stay visible so Pi apt packages such as OpenCV,
+ * PyAudio and Picamera2 do not need to be rebuilt by pip on ARM.
+ */
+export function prepareRobotPython(basePython, scriptPath, modules = REQUIRED_MODULES, reqFile = 'requirements-robot.txt') {
+    const reqPath = join(scriptPath, '..', reqFile);
+    if (!existsSync(reqPath)) {
+        console.log(chalk.red(`  ✗ ${reqFile} not found next to ${scriptPath}`));
+        return null;
+    }
+    const python = venvPythonPath();
+    if (!existsSync(python)) {
+        console.log(chalk.dim(`  creating RoboPark Python environment: ${ROBOPARK_VENV}`));
+        mkdirSync(join(homedir(), '.robopark'), { recursive: true });
+        const created = spawnSync(basePython, ['-m', 'venv', '--system-site-packages', ROBOPARK_VENV], { stdio: 'inherit' });
+        if (created.status !== 0 || !existsSync(python)) {
+            console.log(chalk.red('  ✗ could not create ~/.robopark/venv. On Debian/Raspberry Pi install python3-venv, then retry.'));
+            return null;
+        }
+    }
+    const requirements = readFileSync(reqPath, 'utf8');
+    const fingerprint = createHash('sha256').update(requirements).digest('hex');
+    const marker = join(ROBOPARK_VENV, `.robopark-${reqFile}.sha256`);
+    const installedFingerprint = existsSync(marker) ? readFileSync(marker, 'utf8').trim() : '';
+    if (installedFingerprint !== fingerprint || missingModules(python, modules).length > 0) {
+        console.log(chalk.dim(`  syncing RoboPark Python dependencies from ${reqFile}…`));
+        const install = spawnSync(python, ['-m', 'pip', 'install', '--upgrade', '-r', reqPath], { stdio: 'inherit' });
+        if (install.status !== 0) {
+            console.log(chalk.red(`  ✗ dependency install failed in ${ROBOPARK_VENV}`));
+            return null;
+        }
+        writeFileSync(marker, `${fingerprint}\n`);
+    }
+    const stillMissing = missingModules(python, modules);
+    if (stillMissing.length) {
+        console.log(chalk.red(`  ✗ venv is still missing: ${stillMissing.join(', ')}`));
+        return null;
+    }
+    return python;
+}