dsh-ros2-common 0.1.0

package/lib/types/toolkit.d.ts

@@ -0,0 +1,225 @@
+import { type JobHooks, type RunOptions, type RosResult } from './runner.js';
+import { type JsonValue, parseJsonOrRaw } from './parse.js';
+/** Execution seam injected by the plugin entry (real runner in prod, fake in tests). */
+export type RunFn = (bin: string, args: string[], opts?: RunOptions) => Promise<RosResult>;
+/** Minimal structural view of the DSH approval service (`ctx.approval.request`). */
+export interface ApprovalRequest {
+    agent?: unknown;
+    toolName: string;
+    reason?: string;
+    signal?: AbortSignal;
+}
+/** Minimal structural view of the DSH jobs registry (`ctx.jobs`). */
+export interface JobSnapshot {
+    id: string;
+    kind: string;
+    label: string;
+    status: string;
+    detail?: string;
+    startedAt?: number;
+    finishedAt?: number;
+}
+export interface JobSpec {
+    owner?: unknown;
+    kind: string;
+    label: string;
+    outputLimitBytes?: number;
+    run(): JobHooks;
+}
+export interface JobsApi {
+    start(spec: JobSpec): string;
+    list(caller?: unknown): JobSnapshot[];
+    get(id: string, caller?: unknown): JobSnapshot | undefined;
+}
+/**
+ * Pluggable vision contract (the vision package provides a concrete backend
+ * as an optional cordis service; core's ros2_gui_observe consumes it).
+ */
+export interface VisionConfig {
+    provider: string;
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+}
+export interface DescribeOptions {
+    signal?: AbortSignal;
+}
+export interface VisionProvider {
+    readonly name: string;
+    describe(imagePath: string, prompt: string, opts?: DescribeOptions): Promise<string>;
+}
+export interface ToolDeps {
+    run: RunFn;
+    /** Attach trailing stderr to successful results (default: drop noise). */
+    includeStderr?: boolean;
+    /** DSH approval service (L2 write tools fail closed without it). */
+    approval?: (req: ApprovalRequest) => Promise<string>;
+    /** DSH background jobs registry (needed by ros2_colcon_build). */
+    jobs?: JobsApi;
+    /** Workspace root used as fallback cwd / interface output root. */
+    workspaceRoot?: string;
+    /** L3 GUI lifecycle manager (ros2_gui_* / ros2_screenshot) — concrete type lives in dsh-ros2-core. */
+    gui?: unknown;
+    /** L3 pluggable multimodal vision (ros2_vision_describe / ros2_gui_observe). */
+    vision?: VisionProvider;
+    /**
+     * Tool-layer safety posture when the safety_monitor is unreachable:
+     * 'warn' (default, backward compatible) proceeds with a warning;
+     * 'reject' fails closed. A LOCKED /safety/state always rejects motion
+     * tools in both modes.
+     */
+    safetyStrict?: 'warn' | 'reject';
+}
+/** Canonical result value shared by every tool (validated against `resultSchema`). */
+export interface ToolResult {
+    ok: boolean;
+    tool: string;
+    command: string;
+    data: JsonValue;
+    warnings?: string[];
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export declare const resultSchema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly ok: {
+            readonly type: "boolean";
+            readonly required: true;
+        };
+        readonly tool: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly command: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly data: {
+            readonly type: "json";
+            readonly required: true;
+        };
+        readonly warnings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly error: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly code: {
+                    readonly type: "string";
+                };
+                readonly message: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+};
+export declare const renderResult: (_args: unknown, value: JsonValue) => {
+    type: "text";
+    text: string;
+}[];
+export { type JsonValue, parseJsonOrRaw };
+export { runCommand, spawnJob } from './runner.js';
+export type { RosResult, RunOptions, JobHooks } 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 {
+    rosSetup: string;
+    timeoutMs: number;
+    rosLogDir: string;
+    workspaceRoot: string;
+    includeStderr: boolean;
+}
+/** Build the injected run seam from a package's config (mirrors legacy index.ts). */
+export declare function makeRun(config: RunConfig): RunFn;
+/** Path to a script shipped with dsh-ros2-common (e.g. robot_profile.py). */
+export declare function commonScriptPath(name: string): string;
+/** Optional value helpers (legacy ToolDeps params are loose). */
+export declare function strOrUndefined(value: unknown): string | undefined;
+export declare function numOrUndefined(value: unknown): number | undefined;
+export declare function jsonOf(value: unknown): JsonValue;
+export declare function tail(stderr: string): string[];
+/**
+ * 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 declare function requestApproval(deps: ToolDeps, exec: {
+    agent?: unknown;
+    signal?: AbortSignal;
+}, toolName: string, reason: string): Promise<{
+    allowed: boolean;
+    outcome: string;
+}>;
+export declare function deniedResult(tool: string, command: string, outcome: string): ToolResult;
+/** Safety-gate rejection with a distinct error code (SAFETY_LOCKED / SAFETY_MONITOR_DOWN). */
+export declare function safetyDenied(tool: string, command: string, code: string, message: string): ToolResult;
+export declare function toolError(tool: string, command: string, code: string, message: string): ToolResult;
+export declare function okResult(tool: string, command: string, data: JsonValue): ToolResult;
+export interface SafetyFields {
+    state?: string;
+    severity?: string;
+    cause?: string;
+    detail?: string;
+}
+/** Parse the flat `field: value` echo output of SafetyState.msg. */
+export declare function parseSafetyEcho(stdout: string): SafetyFields;
+/**
+ * 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 declare function enforceSafetyLock(deps: ToolDeps, tool: string, command: string, opts?: {
+    skip?: boolean;
+}): Promise<{
+    denied?: ToolResult;
+    warning?: string;
+}>;
+/** Read the current latched /safety/state (monitor may be offline). */
+export declare function readSafetyState(deps: ToolDeps): Promise<{
+    running: boolean;
+    fields: SafetyFields;
+}>;
+/** Locate a robot profile path (explicit path, or via robot_profile load). */
+export declare function resolveProfilePath(deps: ToolDeps, robot: string, profile: string): Promise<string>;
+/** Robot profile safety-view (the subset tools read for validation/gating). */
+export interface ProfileSafetyView {
+    safety?: Record<string, unknown>;
+    joints?: Array<{
+        name: string;
+        limits?: Record<string, unknown>;
+    }>;
+    moveit?: {
+        groups?: Record<string, {
+            joints?: string[];
+        }>;
+    };
+}
+/** Load a registered robot profile (structured JSON, fast path). */
+export declare function loadRobotProfile(deps: ToolDeps, robot: string): Promise<{
+    robot: ProfileSafetyView;
+    profile_path?: string;
+} | null>;
+export interface RosToolSpec {
+    name: string;
+    description: string;
+    bin?: string;
+    parameters?: Record<string, unknown>;
+    buildArgs: (params: Record<string, unknown>) => string[];
+    runOpts?: (params: Record<string, unknown>) => RunOptions;
+    parse: (res: RosResult, params: Record<string, unknown>) => JsonValue;
+    /** Interpret a non-zero exit as a finding instead of a failure. */
+    onNonZero?: (res: RosResult) => JsonValue;
+}
+/**
+ * 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 declare function ros2Tool(deps: ToolDeps, spec: RosToolSpec): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "dsh-ros2-common",
+  "version": "0.1.0",
+  "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",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "ros2"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StvLi/dsh-ros2.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}