dsh-ros2-common 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dsh-ros2 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# dsh-ros2-common
+
+Shared runtime for the dsh-ros2 plugin family — **not a cordis bundle**.
+
+- `runner.ts` — command runner (timeout / SIGKILL / ROS_LOG_DIR fallback / rosSetup), `spawnJob`
+- `parse.ts` — topic/graph/transform parsers
+- `toolkit.ts` — ToolDeps injection interface, result helpers, approval gate, `/safety/state` gate, profile loading (`robot_profile.py` via `commonScriptPath`), vision provider contract, `ros2Tool` adapter, `makeRun`
+- `scripts/robot_profile.py` — robot body profile + topology knowledge base (**zero-copy** shared by profile / moveit / safety)
+
+Consumers depend on `dsh-ros2-common` and import from the package root.
+

package/lib/index.js

@@ -0,0 +1,8 @@
+/**
+ * dsh-ros2-common — shared runtime for the dsh-ros2 plugin family.
+ * Plain library (NOT a cordis bundle): command runner, parsers, ToolDeps
+ * toolkit, and the robot-profile script (zero-copy across packages).
+ */
+export * from './toolkit.js';
+export * from './runner.js';
+export * from './parse.js';

package/lib/parse.js

@@ -0,0 +1,110 @@
+/** Pure parsers for `ros2 ...` CLI output. Kept side-effect free for testing. */
+/** Split stdout into non-empty trimmed lines. */
+export function parseLines(stdout) {
+    return stdout.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+}
+/** Parse `ros2 topic/service/action list` output: `name [type]` or `name`. */
+export function parseTopicList(stdout) {
+    return parseLines(stdout).map((line) => {
+        const match = line.match(/^(\S+)(?:\s*\[\s*([^\]]+)\s*\])?$/);
+        if (!match)
+            return { name: line };
+        return match[2] ? { name: match[1], type: match[2].trim() } : { name: match[1] };
+    });
+}
+const NODE_INFO_SECTIONS = [
+    ['subscribers', 'Subscribers'],
+    ['publishers', 'Publishers'],
+    ['serviceServers', 'Service Servers'],
+    ['serviceClients', 'Service Clients'],
+    ['actionServers', 'Action Servers'],
+    ['actionClients', 'Action Clients'],
+];
+/** Parse `ros2 node info <node>` (Jazzy layout). */
+export function parseNodeInfo(stdout, fallbackNode = '') {
+    const info = {
+        node: fallbackNode,
+        subscribers: [],
+        publishers: [],
+        serviceServers: [],
+        serviceClients: [],
+        actionServers: [],
+        actionClients: [],
+    };
+    let section = null;
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        const header = NODE_INFO_SECTIONS.find(([, label]) => line === label || line === `${label}:`);
+        if (header) {
+            section = header[0];
+            continue;
+        }
+        if (section === null) {
+            info.node = line;
+            continue;
+        }
+        const entry = line.replace(/^[:.\-]\s*/, '');
+        if (section === 'subscribers' || section === 'publishers') {
+            const match = entry.match(/^(\S+)(?:\s*:\s*(.+))?$/);
+            info[section].push(match ? { name: match[1], ...(match[2] ? { type: match[2].trim() } : {}) } : { name: entry });
+        }
+        else {
+            ;
+            info[section].push(entry);
+        }
+    }
+    return info;
+}
+/** Fold per-node info into a graph: node roster plus unique topic names. */
+export function foldGraph(nodes) {
+    const topics = new Set();
+    const folded = nodes.map((n) => {
+        const publishers = n.publishers.map((p) => p.name);
+        const subscribers = n.subscribers.map((s) => s.name);
+        for (const t of [...publishers, ...subscribers])
+            topics.add(t);
+        return {
+            name: n.node,
+            publishers,
+            subscribers,
+            services: [...n.serviceServers, ...n.serviceClients],
+            actions: [...n.actionServers, ...n.actionClients],
+        };
+    });
+    return { nodes: folded, topics: [...topics].sort(), nodeCount: folded.length };
+}
+/** Best-effort JSON parse of a topic sample; falls back to raw text. */
+export function parseJsonOrRaw(stdout) {
+    const text = stdout.trim();
+    if (text.length === 0)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text.slice(0, 4000) };
+    }
+}
+export function parseTransforms(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    const pairs = [];
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const header = entry.header;
+        const child = entry.child_frame_id;
+        const parent = header?.frame_id;
+        if (typeof parent === 'string' && typeof child === 'string') {
+            const key = `${parent}::${child}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                pairs.push({ parent, child });
+            }
+        }
+    }
+    return pairs;
+}

package/lib/runner.js

@@ -0,0 +1,168 @@
+import { execFile, spawn } from 'node:child_process';
+const DEFAULT_TIMEOUT_MS = 15000;
+const MAX_BUFFER = 16 * 1024 * 1024;
+function execFileP(bin, args, options) {
+    return new Promise((resolve, reject) => {
+        execFile(bin, args, options, (error, stdout, stderr) => {
+            const toText = (value) => (typeof value === 'string' ? value : value.toString('utf8'));
+            if (error) {
+                const e = error;
+                e.stdout = toText(stdout);
+                e.stderr = toText(stderr);
+                reject(error);
+                return;
+            }
+            resolve({ stdout: toText(stdout), stderr: toText(stderr) });
+        });
+    });
+}
+/** POSIX single-quote escape for embedding one argument into a shell string. */
+function shq(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Run a CLI command (default binary `ros2`) and normalize the outcome.
+ * Non-zero exits and timeouts are reported as `ok: false` — the caller decides
+ * whether they are findings or failures.
+ */
+export async function runCommand(bin, args, opts = {}) {
+    const startedAt = Date.now();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const cwd = opts.cwd;
+    const command = `${bin} ${args.map(shq).join(' ')}`;
+    const env = {
+        ...process.env,
+        ...(opts.rosLogDir ? { ROS_LOG_DIR: opts.rosLogDir } : {}),
+        ...opts.env,
+    };
+    ensureWritableRosLogDir(env);
+    const baseOptions = {
+        timeout: timeoutMs,
+        killSignal: 'SIGKILL',
+        maxBuffer: MAX_BUFFER,
+        cwd,
+        env,
+    };
+    try {
+        const { stdout, stderr } = opts.rosSetup
+            ? await execFileP('bash', ['-lc', `${opts.rosSetup} ${command}`], baseOptions)
+            : await execFileP(bin, args, baseOptions);
+        return { ok: true, command, stdout, stderr, exitCode: 0, timedOut: false, durationMs: Date.now() - startedAt };
+    }
+    catch (error) {
+        const e = error;
+        const timedOut = e.killed === true || e.signal === 'SIGKILL';
+        const exitCode = typeof e.code === 'number' ? e.code : null;
+        return {
+            ok: false,
+            command,
+            stdout: e.stdout ?? '',
+            stderr: e.stderr ?? '',
+            exitCode,
+            timedOut,
+            durationMs: Date.now() - startedAt,
+            error: timedOut ? `timed out after ${timeoutMs}ms` : e.message,
+        };
+    }
+}
+/** Convenience for `ros2 ...` subcommands. */
+export function runRos2(args, opts = {}) {
+    return runCommand('ros2', args, opts);
+}
+// ── writable ROS log dir fallback ──────────────────────────────────────
+// ROS2 Python CLIs (topic echo/pub, ros2 run) abort at startup when
+// ~/.ros/log is not writable. When no explicit ROS_LOG_DIR is configured,
+// probe once and transparently fall back to a writable per-user dir so the
+// plugin works on locked-down/headless hosts out of the box.
+let rosLogProbed = false;
+let rosLogFallback;
+function probeRosLogFallback() {
+    if (rosLogProbed)
+        return rosLogFallback;
+    rosLogProbed = true;
+    const home = process.env.HOME;
+    if (home) {
+        const target = `${home}/.ros/log`;
+        try {
+            const { mkdirSync, writeFileSync, rmSync } = require('node:fs');
+            mkdirSync(target, { recursive: true });
+            const probe = `${target}/.dsh-writable-probe`;
+            writeFileSync(probe, 'ok');
+            rmSync(probe);
+            return undefined; // writable — no fallback needed
+        }
+        catch {
+            // fall through to /tmp
+        }
+    }
+    const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+    rosLogFallback = `/tmp/ros-log-${uid}`;
+    try {
+        require('node:fs').mkdirSync(rosLogFallback, { recursive: true });
+    }
+    catch {
+        rosLogFallback = undefined;
+    }
+    return rosLogFallback;
+}
+/** Set ROS_LOG_DIR in `env` to a writable dir when the default would fail. */
+export function ensureWritableRosLogDir(env) {
+    if (env.ROS_LOG_DIR)
+        return;
+    if (process.env.ROS_LOG_DIR) {
+        env.ROS_LOG_DIR = process.env.ROS_LOG_DIR;
+        return;
+    }
+    const fallback = probeRosLogFallback();
+    if (fallback)
+        env.ROS_LOG_DIR = fallback;
+}
+/** Keep the last N lines of a stream, bounded. */
+export function tailLines(text, n = 8) {
+    const lines = text.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+    return lines.slice(-n);
+}
+/**
+ * Spawn a long-running CLI process for a background job: bounded captured
+ * output, cancel via SIGTERM, settled outcome on close/error.
+ */
+export function spawnJob(bin, args, opts = {}) {
+    const child = spawn(bin, args, {
+        cwd: opts.cwd,
+        env: opts.env ?? process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const limit = opts.outputLimitBytes ?? 8 * 1024 * 1024;
+    let out = '';
+    let err = '';
+    let truncated = false;
+    const append = (chunk, target) => {
+        if (truncated)
+            return target;
+        const text = chunk.toString();
+        if (target.length + text.length > limit) {
+            truncated = true;
+            return `${target}${text.slice(0, Math.max(0, limit - target.length))}\n[output truncated]`;
+        }
+        return target + text;
+    };
+    child.stdout?.on('data', (chunk) => { out = append(chunk, out); });
+    child.stderr?.on('data', (chunk) => { err = append(chunk, err); });
+    const done = new Promise((resolve) => {
+        child.on('error', (error) => resolve({ status: 'failed', detail: error.message }));
+        child.on('close', (code, signal) => {
+            if (signal)
+                resolve({ status: 'killed', detail: `signal: ${signal}` });
+            else
+                resolve({ status: code === 0 ? 'completed' : 'failed', detail: `exit code: ${code ?? 'unknown'}` });
+        });
+    });
+    return {
+        cancel: () => {
+            if (!child.killed)
+                child.kill('SIGTERM');
+        },
+        readOutput: () => `[stdout]\n${out}\n[stderr]\n${err}`.trim(),
+        done,
+    };
+}

package/lib/toolkit.js

@@ -0,0 +1,212 @@
+/**
+ * dsh-ros2-common toolkit: types + helpers shared across the dsh-ros2 plugin
+ * family (core / profile / moveit / safety / vision). Not a cordis bundle —
+ * a plain library every domain package depends on.
+ *
+ * Shared seams: the ToolDeps injection interface, result helpers, approval
+ * gate, safety-state gate, profile loading, the vision provider contract,
+ * and the ros2Tool adapter used by read-only CLI tools.
+ */
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runCommand } from './runner.js';
+import { parseJsonOrRaw } from './parse.js';
+export const resultSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ok: { type: 'boolean', required: true },
+        tool: { type: 'string', required: true },
+        command: { type: 'string', required: true },
+        data: { type: 'json', required: true },
+        warnings: { type: 'array', items: { type: 'string' } },
+        error: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { code: { type: 'string' }, message: { type: 'string' } },
+        },
+    },
+};
+export const renderResult = (_args, value) => [{ type: 'text', text: JSON.stringify(value) }];
+export { parseJsonOrRaw };
+export { runCommand, spawnJob } from './runner.js';
+export { foldGraph, parseLines, parseNodeInfo, parseTopicList, parseTransforms } from './parse.js';
+/** Build the injected run seam from a package's config (mirrors legacy index.ts). */
+export function makeRun(config) {
+    return (bin, args, opts = {}) => runCommand(bin, args, {
+        timeoutMs: opts.timeoutMs ?? config.timeoutMs,
+        rosLogDir: opts.rosLogDir ?? config.rosLogDir,
+        cwd: opts.cwd ?? (config.workspaceRoot.length > 0 ? config.workspaceRoot : undefined),
+        rosSetup: opts.rosSetup ?? config.rosSetup,
+        env: opts.env,
+    });
+}
+/** Path to a script shipped with dsh-ros2-common (e.g. robot_profile.py). */
+export function commonScriptPath(name) {
+    return fileURLToPath(new URL(`../scripts/${name}`, import.meta.url));
+}
+/** Optional value helpers (legacy ToolDeps params are loose). */
+export function strOrUndefined(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+export function numOrUndefined(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+export function jsonOf(value) {
+    return value;
+}
+export function tail(stderr) {
+    return stderr.split('\n').map((l) => l.trim()).filter((l) => l.length > 0).slice(-8);
+}
+/** Only approval outcome that grants execution. */
+const ALLOWED_ONCE = 'allowed-once';
+/**
+ * Gate a write operation behind DSH user approval. Fails closed: no approval
+ * service, no owning agent, an error, or any non-grant outcome all deny.
+ */
+export async function requestApproval(deps, exec, toolName, reason) {
+    if (!deps.approval || !exec.agent)
+        return { allowed: false, outcome: 'unavailable' };
+    try {
+        const outcome = await deps.approval({ agent: exec.agent, toolName, reason, signal: exec.signal });
+        return { allowed: outcome === ALLOWED_ONCE, outcome };
+    }
+    catch {
+        return { allowed: false, outcome: 'error' };
+    }
+}
+export function deniedResult(tool, command, outcome) {
+    return { ok: false, tool, command, data: null, error: { code: 'APPROVAL_DENIED', message: `approval ${outcome}` } };
+}
+/** Safety-gate rejection with a distinct error code (SAFETY_LOCKED / SAFETY_MONITOR_DOWN). */
+export function safetyDenied(tool, command, code, message) {
+    return { ok: false, tool, command, data: null, error: { code, message } };
+}
+export function toolError(tool, command, code, message) {
+    return { ok: false, tool, command, data: null, error: { code, message } };
+}
+export function okResult(tool, command, data) {
+    return { ok: true, tool, command, data };
+}
+// ── safety framework helpers ─────────────────────────────────────────────
+// Contract: docs/safety-handover.md — /safety/state is published by the
+// safety_monitor node (SafetyState.msg, transient-local). Motion tools gate
+// on it before executing.
+const SAFETY_STATE_TOPIC = '/safety/state';
+/** Parse the flat `field: value` echo output of SafetyState.msg. */
+export function parseSafetyEcho(stdout) {
+    const out = {};
+    for (const line of stdout.split('\n')) {
+        const m = /^(\w+):\s*(.*)$/.exec(line.trim());
+        if (m && (m[1] === 'state' || m[1] === 'severity' || m[1] === 'cause' || m[1] === 'detail')) {
+            out[m[1]] = m[2];
+        }
+    }
+    return out;
+}
+/**
+ * Tool-layer safety gate for motion tools. A LOCKED /safety/state always
+ * rejects (with the trigger cause); an unreachable monitor rejects in
+ * 'reject' mode (fail-closed) or warns in 'warn' mode (backward compatible).
+ */
+export async function enforceSafetyLock(deps, tool, command, opts = {}) {
+    if (opts.skip)
+        return {};
+    const res = await deps.run('ros2', ['topic', 'echo', SAFETY_STATE_TOPIC, '--once'], { timeoutMs: 3000 });
+    if (!res.ok || !res.stdout.trim()) {
+        const strict = deps.safetyStrict ?? 'warn';
+        if (strict === 'reject') {
+            return {
+                denied: safetyDenied(tool, command, 'SAFETY_MONITOR_DOWN', `safety_monitor 未运行（${SAFETY_STATE_TOPIC} 无响应），fail-closed 拒绝执行。请先 robot_safety_start 启动监视器，或配置 safetyStrict: 'warn' 放行。`),
+            };
+        }
+        return { warning: `safety_monitor 未运行（${SAFETY_STATE_TOPIC} 无响应）——已按 warn 模式放行；生产环境建议 safetyStrict: 'reject'。` };
+    }
+    const fields = parseSafetyEcho(res.stdout);
+    if (fields.state === 'LOCKED') {
+        return {
+            denied: safetyDenied(tool, command, 'SAFETY_LOCKED', `机器人已锁死（cause=${fields.cause ?? 'unknown'}，severity=${fields.severity ?? '?'}）：${fields.detail ?? ''}。需人工确认后经 robot_safety_unlock 解锁。`),
+        };
+    }
+    return {};
+}
+/** Read the current latched /safety/state (monitor may be offline). */
+export async function readSafetyState(deps) {
+    const res = await deps.run('ros2', ['topic', 'echo', SAFETY_STATE_TOPIC, '--once'], { timeoutMs: 3000 });
+    if (!res.ok || !res.stdout.trim())
+        return { running: false, fields: {} };
+    return { running: true, fields: parseSafetyEcho(res.stdout) };
+}
+/** Locate a robot profile path (explicit path, or via robot_profile load). */
+export async function resolveProfilePath(deps, robot, profile) {
+    if (profile)
+        return profile;
+    const res = await deps.run('python3', [commonScriptPath('robot_profile.py'), 'load', '--name', robot], { timeoutMs: 30000 });
+    if (res.ok && res.stdout.trim()) {
+        const data = parseJsonOrRaw(res.stdout);
+        if (data?.ok && data.profile_path)
+            return data.profile_path;
+    }
+    return '';
+}
+/** Load a registered robot profile (structured JSON, fast path). */
+export async function loadRobotProfile(deps, robot) {
+    const res = await deps.run('python3', [commonScriptPath('robot_profile.py'), 'load', '--name', robot], { timeoutMs: 30000 });
+    if (!res.ok || !res.stdout.trim())
+        return null;
+    const data = parseJsonOrRaw(res.stdout);
+    if (!data?.ok || !data.robot)
+        return null;
+    return { robot: data.robot, ...(data.profile_path ? { profile_path: data.profile_path } : {}) };
+}
+/**
+ * Build an L1 read-only tool from a `ros2`-style command spec. Shared by
+ * dsh-ros2-core (diagnostics) and dsh-ros2-vision (image/VLM topics).
+ */
+export function ros2Tool(deps, spec) {
+    const bin = spec.bin ?? 'ros2';
+    return defineTool({
+        name: spec.name,
+        description: spec.description,
+        parameters: (spec.parameters ?? {}),
+        output: {
+            schema: resultSchema,
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+        },
+        async execute(args) {
+            const params = args;
+            const commandArgs = spec.buildArgs(params);
+            const res = await deps.run(bin, commandArgs, spec.runOpts?.(params) ?? {});
+            const command = `${bin} ${commandArgs.join(' ')}`;
+            if (!res.ok) {
+                if (spec.onNonZero && !res.timedOut) {
+                    const value = {
+                        ok: true,
+                        tool: spec.name,
+                        command,
+                        data: spec.onNonZero(res),
+                        ...(deps.includeStderr && res.stderr.trim() ? { warnings: tail(res.stderr) } : {}),
+                    };
+                    return value;
+                }
+                const value = {
+                    ok: false,
+                    tool: spec.name,
+                    command,
+                    data: null,
+                    error: {
+                        code: res.timedOut ? 'TIMEOUT' : 'COMMAND_FAILED',
+                        message: res.error ?? `exit code ${res.exitCode ?? 'unknown'}`,
+                    },
+                    ...(res.stderr.trim() ? { warnings: tail(res.stderr) } : {}),
+                };
+                return value;
+            }
+            const data = spec.parse(res, params);
+            const warnings = deps.includeStderr && res.stderr.trim() ? tail(res.stderr) : undefined;
+            const value = { ok: true, tool: spec.name, command, data, ...(warnings ? { warnings } : {}) };
+            return value;
+        },
+    });
+}

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * dsh-ros2-common — shared runtime for the dsh-ros2 plugin family.
+ * Plain library (NOT a cordis bundle): command runner, parsers, ToolDeps
+ * toolkit, and the robot-profile script (zero-copy across packages).
+ */
+export * from './toolkit.js';
+export * from './runner.js';
+export * from './parse.js';

package/lib/types/parse.d.ts

@@ -0,0 +1,45 @@
+/** Pure parsers for `ros2 ...` CLI output. Kept side-effect free for testing. */
+/** Lossless JSON value (same shape as DSH's JsonValue). */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type TopicEntry = {
+    name: string;
+    type?: string;
+};
+/** Split stdout into non-empty trimmed lines. */
+export declare function parseLines(stdout: string): string[];
+/** Parse `ros2 topic/service/action list` output: `name [type]` or `name`. */
+export declare function parseTopicList(stdout: string): TopicEntry[];
+export type NodeInfo = {
+    node: string;
+    subscribers: TopicEntry[];
+    publishers: TopicEntry[];
+    serviceServers: string[];
+    serviceClients: string[];
+    actionServers: string[];
+    actionClients: string[];
+};
+/** Parse `ros2 node info <node>` (Jazzy layout). */
+export declare function parseNodeInfo(stdout: string, fallbackNode?: string): NodeInfo;
+export type GraphNode = {
+    name: string;
+    publishers: string[];
+    subscribers: string[];
+    services: string[];
+    actions: string[];
+};
+/** Fold per-node info into a graph: node roster plus unique topic names. */
+export declare function foldGraph(nodes: NodeInfo[]): {
+    nodes: GraphNode[];
+    topics: string[];
+    nodeCount: number;
+};
+/** Best-effort JSON parse of a topic sample; falls back to raw text. */
+export declare function parseJsonOrRaw(stdout: string): JsonValue;
+/** Unique frame pairs from a `/tf` transforms sample. */
+export type FramePair = {
+    parent: string;
+    child: string;
+};
+export declare function parseTransforms(value: unknown): FramePair[];

package/lib/types/runner.d.ts

@@ -0,0 +1,53 @@
+export interface RosResult {
+    ok: boolean;
+    /** Display form of the command that ran. */
+    command: string;
+    stdout: string;
+    stderr: string;
+    /** Exit code when the process terminated normally, otherwise null. */
+    exitCode: number | null;
+    timedOut: boolean;
+    durationMs: number;
+    error?: string;
+}
+export interface RunOptions {
+    timeoutMs?: number;
+    cwd?: string;
+    rosLogDir?: string;
+    rosSetup?: string;
+    env?: Record<string, string>;
+}
+/**
+ * Run a CLI command (default binary `ros2`) and normalize the outcome.
+ * Non-zero exits and timeouts are reported as `ok: false` — the caller decides
+ * whether they are findings or failures.
+ */
+export declare function runCommand(bin: string, args: string[], opts?: RunOptions): Promise<RosResult>;
+/** Convenience for `ros2 ...` subcommands. */
+export declare function runRos2(args: string[], opts?: RunOptions): Promise<RosResult>;
+/** Set ROS_LOG_DIR in `env` to a writable dir when the default would fail. */
+export declare function ensureWritableRosLogDir(env: Record<string, string>): void;
+/** Keep the last N lines of a stream, bounded. */
+export declare function tailLines(text: string, n?: number): string[];
+/** Background job outcome vocabulary (matches the DSH jobs registry). */
+export type JobOutcomeStatus = 'completed' | 'failed' | 'killed';
+export interface JobOutcome {
+    status: JobOutcomeStatus;
+    detail?: string;
+}
+/** Producer hooks a `ctx.jobs.start` spec must return. */
+export interface JobHooks {
+    cancel(): void;
+    readOutput?(): string;
+    done: Promise<JobOutcome>;
+}
+export interface SpawnJobOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    outputLimitBytes?: number;
+}
+/**
+ * Spawn a long-running CLI process for a background job: bounded captured
+ * output, cancel via SIGTERM, settled outcome on close/error.
+ */
+export declare function spawnJob(bin: string, args: string[], opts?: SpawnJobOptions): JobHooks;