dsh-ros2-common 0.1.0 → 0.1.1

package/lib/runner.js

@@ -1,4 +1,6 @@
 import { execFile, spawn } from 'node:child_process';
+import path from 'node:path';
+import { accessSync, existsSync, readdirSync } from 'node:fs';
 const DEFAULT_TIMEOUT_MS = 15000;
 const MAX_BUFFER = 16 * 1024 * 1024;
 function execFileP(bin, args, options) {
@@ -20,6 +22,76 @@ function execFileP(bin, args, options) {
 function shq(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+// ── session-scoped workspace override + ros setup fallback chain ──────────
+// "装好即用、用错自纠、切环境不重启": a mutable per-session override (set by the
+// ros2_workspace tool) beats the configured rosSetup; an empty/missing setup
+// falls back through workspaceRoot/install/setup.bash -> /opt/ros/<distro>/setup.bash
+// -> no source; failures carry actionable diagnostics (sourceOk / envNote).
+let sessionRosSetup = null;
+/** Set/clear the session-level ros setup prefix (ros2_workspace use/reset). */
+export function setSessionRosSetup(prefix) {
+    sessionRosSetup = prefix;
+}
+/** Current session-level ros setup prefix (null = not overridden). */
+export function getSessionRosSetup() {
+    return sessionRosSetup;
+}
+/** Extract the first `source <path>` from a shell prefix, if any. */
+function extractSourcePath(prefix) {
+    const m = /\bsource\s+([^\s&;|]+)/.exec(prefix);
+    return m ? m[1] : undefined;
+}
+/** First existing candidate for `/opt/ros/<distro>/setup.bash`. */
+function globFirstRosSetup() {
+    try {
+        const entries = readdirSync('/opt/ros').sort();
+        for (const e of entries) {
+            const cand = path.join('/opt/ros', e, 'setup.bash');
+            if (existsSync(cand))
+                return cand;
+        }
+    }
+    catch {
+        /* /opt/ros missing */
+    }
+    return null;
+}
+/** Auto-detect: workspaceRoot/install/setup.bash, then /opt/ros/<distro>/setup.bash. */
+function autoDetectSetup(opts) {
+    if (opts.workspaceRoot) {
+        const cand = path.join(opts.workspaceRoot, 'install', 'setup.bash');
+        if (existsSync(cand))
+            return cand;
+    }
+    return globFirstRosSetup();
+}
+/** Resolve the effective setup prefix (session override -> config -> auto). */
+export function resolveSetup(opts) {
+    const explicit = sessionRosSetup ?? opts.rosSetup ?? '';
+    if (explicit) {
+        const src = extractSourcePath(explicit);
+        if (src && !existsSync(src)) {
+            // explicit source path is wrong: report + auto-correct via the chain
+            const auto = autoDetectSetup(opts);
+            return {
+                prefix: auto ? `source ${auto} && ` : '',
+                sourcePath: auto ?? null,
+                explicit: true,
+                autoCandidate: auto ?? null,
+                note: `配置的 rosSetup source 路径不存在：${src}；已自动回退${auto ? `到 ${auto}` : '（无可用 setup，直接调用 ros2，依赖宿主 PATH）'}。建议修正配置。`,
+            };
+        }
+        return { prefix: explicit, sourcePath: src ?? null, explicit: true, autoCandidate: null, note: '' };
+    }
+    const auto = autoDetectSetup(opts);
+    return {
+        prefix: auto ? `source ${auto} && ` : '',
+        sourcePath: auto ?? null,
+        explicit: false,
+        autoCandidate: auto ?? null,
+        note: auto ? '' : '未检测到 ros setup（直接调用 ros2，依赖宿主 PATH；可用 ros2_env_check 诊断）',
+    };
+}
 /**
  * Run a CLI command (default binary `ros2`) and normalize the outcome.
  * Non-zero exits and timeouts are reported as `ok: false` — the caller decides
@@ -43,16 +115,33 @@ export async function runCommand(bin, args, opts = {}) {
         cwd,
         env,
     };
+    const setup = resolveSetup(opts);
+    const cmd = setup.prefix ? `${setup.prefix}${command}` : command;
+    const envNote = setup.note;
     try {
-        const { stdout, stderr } = opts.rosSetup
-            ? await execFileP('bash', ['-lc', `${opts.rosSetup} ${command}`], baseOptions)
+        const { stdout, stderr } = setup.prefix
+            ? await execFileP('bash', ['-lc', cmd], baseOptions)
             : await execFileP(bin, args, baseOptions);
-        return { ok: true, command, stdout, stderr, exitCode: 0, timedOut: false, durationMs: Date.now() - startedAt };
+        return {
+            ok: true, command, stdout, stderr, exitCode: 0, timedOut: false, durationMs: Date.now() - startedAt,
+            sourceOk: true,
+            ...(envNote ? { envNote: `[env] ${envNote}` } : {}),
+        };
     }
     catch (error) {
         const e = error;
         const timedOut = e.killed === true || e.signal === 'SIGKILL';
         const exitCode = typeof e.code === 'number' ? e.code : null;
+        const hostEnv = `AMENT_PREFIX_PATH=${process.env.AMENT_PREFIX_PATH ?? ''} COLCON_PREFIX_PATH=${process.env.COLCON_PREFIX_PATH ?? ''}`;
+        const diag = [
+            envNote ? `[env] ${envNote}` : '',
+            setup.explicit && !setup.sourcePath ? '[env] 未检测到 source 路径（rosSetup 不含 source 或非标准格式）' : '',
+            timedOut ? '' : `[env] 宿主环境：${hostEnv}`,
+        ].filter(Boolean).join('\n');
+        const message = [
+            timedOut ? `timed out after ${timeoutMs}ms` : e.message,
+            diag ? `\n${diag}` : '',
+        ].join('');
         return {
             ok: false,
             command,
@@ -61,7 +150,9 @@ export async function runCommand(bin, args, opts = {}) {
             exitCode,
             timedOut,
             durationMs: Date.now() - startedAt,
-            error: timedOut ? `timed out after ${timeoutMs}ms` : e.message,
+            error: message,
+            sourceOk: setup.explicit && !setup.sourcePath ? false : setup.prefix ? true : undefined,
+            ...(diag ? { envNote: diag } : {}),
         };
     }
 }

package/lib/toolkit.js

@@ -30,7 +30,7 @@ export const resultSchema = {
 };
 export const renderResult = (_args, value) => [{ type: 'text', text: JSON.stringify(value) }];
 export { parseJsonOrRaw };
-export { runCommand, spawnJob } from './runner.js';
+export { runCommand, spawnJob, setSessionRosSetup, getSessionRosSetup, resolveSetup } 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) {
@@ -39,6 +39,7 @@ export function makeRun(config) {
         rosLogDir: opts.rosLogDir ?? config.rosLogDir,
         cwd: opts.cwd ?? (config.workspaceRoot.length > 0 ? config.workspaceRoot : undefined),
         rosSetup: opts.rosSetup ?? config.rosSetup,
+        workspaceRoot: config.workspaceRoot,
         env: opts.env,
     });
 }

package/lib/types/runner.d.ts

@@ -9,14 +9,38 @@ export interface RosResult {
     timedOut: boolean;
     durationMs: number;
     error?: string;
+    /** Whether the environment (ros setup) resolved cleanly (P1 error contract). */
+    sourceOk?: boolean;
+    /** Human-readable environment diagnostics (missing paths, fallback used). */
+    envNote?: string;
 }
 export interface RunOptions {
     timeoutMs?: number;
     cwd?: string;
     rosLogDir?: string;
     rosSetup?: string;
+    /** Workspace root used for the `workspaceRoot/install/setup.bash` fallback. */
+    workspaceRoot?: string;
     env?: Record<string, string>;
 }
+/** Set/clear the session-level ros setup prefix (ros2_workspace use/reset). */
+export declare function setSessionRosSetup(prefix: string | null): void;
+/** Current session-level ros setup prefix (null = not overridden). */
+export declare function getSessionRosSetup(): string | null;
+export interface SetupResolution {
+    /** Final shell prefix ('' = no source). */
+    prefix: string;
+    /** The source path used, if any. */
+    sourcePath: string | null;
+    /** Whether an explicit rosSetup/session override was configured. */
+    explicit: boolean;
+    /** The auto-detected path that would work (when the explicit one is wrong). */
+    autoCandidate: string | null;
+    /** Human note (fallback used / misconfiguration) — becomes envNote on errors. */
+    note: string;
+}
+/** Resolve the effective setup prefix (session override -> config -> auto). */
+export declare function resolveSetup(opts: RunOptions): SetupResolution;
 /**
  * Run a CLI command (default binary `ros2`) and normalize the outcome.
  * Non-zero exits and timeouts are reported as `ok: false` — the caller decides

package/lib/types/toolkit.d.ts

@@ -127,8 +127,8 @@ export declare const renderResult: (_args: unknown, value: JsonValue) => {
     text: string;
 }[];
 export { type JsonValue, parseJsonOrRaw };
-export { runCommand, spawnJob } from './runner.js';
-export type { RosResult, RunOptions, JobHooks } from './runner.js';
+export { runCommand, spawnJob, setSessionRosSetup, getSessionRosSetup, resolveSetup } from './runner.js';
+export type { RosResult, RunOptions, JobHooks, SetupResolution } from './runner.js';
 export { foldGraph, parseLines, parseNodeInfo, parseTopicList, parseTransforms } from './parse.js';
 /** Run-seam config (each domain package carries its own copy via Config). */
 export interface RunConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ros2-common",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared runtime for the dsh-ros2 plugin family: command runner, parsers, ToolDeps toolkit, and the robot-profile script (zero-copy across packages). Not a cordis bundle.",
   "type": "module",
   "main": "./lib/index.js",