@elinpf/dsh-ops-shell-tool 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-shell-tool"
+description:
+  zh: "ops-access 消费方工具共享的工厂：统一结果形状、输出 schema、按调用解析的 execute 模板"
+  en: "Shared factory for ops-access consumer tools: standard result shape, output schema, resolve-per-call execute template"

package/README.md

@@ -0,0 +1,32 @@
+# @elinpf/dsh-ops-shell-tool
+
+Shared factory for ops-access consumer tools: the standard shell result shape `{ exitCode, stdout, stderr, command, error? }`, its output schema and render, and the resolve-per-call execute template.
+
+## What it does
+
+A pure library (not a plugin) — the single home for the boilerplate every ops command tool (`ops-tool-kubectl`, `ops-tool-ceph`, `ops-tool-ssh`) would otherwise duplicate. A consumer calls `registerProfiledShellTool(ctx, spec)` from its own plugin and keeps only its identity: tool name, the ops-access kind it resolves, the profile-arg name, and `buildCommand`.
+
+- **Standard result shape** — one `ShellToolResult` definition, one output schema, one pure render, shared by every consumer tool.
+- **Resolve per call** — the profile is resolved through `ctx.get('opsAccess')` inside execute, never statically injected, never cached.
+- **Credential tokens** — `buildCommand` marks file-bearing fields with `ref(field)`, which mints a display token `<id@tier:field>`; the executed command carries the shell-quoted real value, while the displayed command and all captured stdout/stderr are scrubbed back to tokens. Credential paths never reach the model or the session event log.
+- **Honest kill reporting** — 30 s default timeout; a signal death normalizes to `exitCode: -1` with the cause (timeout / caller abort / signal name) spelled out in the `error` field, never a bare -1.
+- **stderr noise filtering** — consumer-declared regexes drop known-noise stderr lines (e.g. ceph keyring chatter) after scrubbing.
+- **`shellQuote`** — exported for consumers that must embed a whole remote command as one argument (ops-tool-ssh).
+
+## Design notes
+
+- **Why a factory, not a base plugin:** the three consumer tools differ only in identity pieces. Owning the execute template here means timeout handling, kill notes, and credential scrubbing are fixed once, not three times.
+- **Why `ctx.get` per call instead of a static inject:** the preset mounts the group concurrently, so a static `inject: ['opsAccess']` risks a loader deadlock against the definition row; by tool-call time the service is long since provided. Same discipline as the registry file itself: resolve per operation, cache nothing.
+- **Why per-call tokens:** token → value mappings live only inside one execute, so a credential path can never leak across calls or sessions.
+
+## Configuration
+
+None — the package has no plugin `Config`. All behavior is parameterized per consumer through `ProfiledShellToolSpec`: `name`, `kind`, `targetParam`, the three description strings, `buildCommand`, `timeoutMs` (default 30000), and `stderrNoise`.
+
+## Testing
+
+```sh
+npx vitest run
+```
+
+The spec drives the factory through a mock ctx: resolve-per-call, agent passthrough, the absent-seam guard, error passthrough, exitCode normalization, timeout/abort/signal kill notes, credential token substitution and scrubbing, stderr noise filtering, render purity, and HMR unload (the registered tool disappears when the fiber's effect disposers run).

package/README.zh.md

@@ -0,0 +1,32 @@
+# @elinpf/dsh-ops-shell-tool
+
+ops-access 消费方工具共享的工厂：统一的 shell 结果形状 `{ exitCode, stdout, stderr, command, error? }`、输出 schema 与 render、以及按调用解析（resolve-per-call）的 execute 模板。
+
+## 功能
+
+纯库（不是插件）——把每个 ops 命令工具（`ops-tool-kubectl`、`ops-tool-ceph`、`ops-tool-ssh`）否则会各自重复的样板收敛到一处。消费方在自己的插件里调用 `registerProfiledShellTool(ctx, spec)`，只保留身份四件套：工具名、解析的 ops-access kind、profile 参数名、`buildCommand`。
+
+- **统一结果形状** — 一份 `ShellToolResult` 定义、一份输出 schema、一份纯 render，所有消费方工具共用。
+- **按调用解析** — profile 在 execute 内通过 `ctx.get('opsAccess')` 解析，不做静态 inject，不缓存。
+- **凭据 token** — `buildCommand` 用 `ref(field)` 标记含文件的字段，生成展示 token `<id@tier:field>`；实际执行的命令携带 shell 转义后的真实值，而展示命令和捕获的 stdout/stderr 全部洗回 token。凭据路径永远不进入模型上下文或会话事件日志。
+- **诚实的 kill 报告** — 默认 30s 超时；信号死亡归一为 `exitCode: -1`，并在 `error` 字段写明原因（超时 / 调用方取消 / 信号名），绝不留一个光秃秃的 -1。
+- **stderr 噪音过滤** — 消费方声明的正则在清洗之后丢弃已知噪音行（如 ceph keyring 唠叨）。
+- **`shellQuote`** — 导出给需要把整条远端命令作为单个参数嵌入的消费方（ops-tool-ssh）。
+
+## 设计要点
+
+- **为什么是工厂而不是基类插件：** 三个消费方工具只差身份件。execute 模板收在这里，超时处理、kill 说明、凭据清洗只修一处，而不是三处。
+- **为什么用 `ctx.get` 按调用解析而不是静态 inject：** preset 并发挂载同组插件，静态 `inject: ['opsAccess']` 有对定义行死锁的风险；到工具调用时服务早已就绪。与 registry 文件同一纪律：按操作解析，什么都不缓存。
+- **为什么 token 按调用生成：** token → 真实值的映射只存活于单次 execute 内，凭据路径不可能跨调用、跨会话泄漏。
+
+## 配置项
+
+无 —— 本包没有插件 `Config`。所有行为由消费方通过 `ProfiledShellToolSpec` 参数化：`name`、`kind`、`targetParam`、三段描述文案、`buildCommand`、`timeoutMs`（默认 30000）、`stderrNoise`。
+
+## 测试方式
+
+```sh
+npx vitest run
+```
+
+测试用 mock ctx 驱动工厂：按调用解析、agent 透传、seam 缺失守卫、错误透传、exitCode 归一、超时/中止/信号三类 kill 说明、凭据 token 替换与清洗、stderr 噪音过滤、render 纯函数性，以及 HMR 卸载（fiber 的 effect disposer 执行后注册的工具随之消失）。

package/lib/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Ops shell tool factory.
+ *
+ * One home for the boilerplate every ops-access consumer tool shares:
+ * the result shape `{ exitCode, stdout, stderr, command, error? }`, its
+ * output schema, the render function, and the execute template (resolve the
+ * profile per call through `ctx.get('opsAccess')` — never a static inject,
+ * never cached — assemble the command, run it through `ctx.shell` with a
+ * fixed 30s timeout, normalize a signal-killed exitCode to -1 while
+ * surfacing the kill cause (timeout / caller abort / signal name) in the
+ * error field, pass errors through verbatim).
+ *
+ * Credential paths never reach the model or the event log. Consumers mark
+ * file-bearing fields with the `ref()` helper, which emits a display token
+ * `<id@tier:field>`; the factory substitutes the shell-quoted real value
+ * only in the command handed to `ctx.shell`, and scrubs every occurrence
+ * of a referenced value back to its token in the displayed command AND in
+ * captured stdout/stderr (CLIs like kubectl print their --kubeconfig path
+ * in error output). The model sees `kubectl --kubeconfig=<prod@rw:kubeconfigPath>`,
+ * never `/root/.dsh-ops/credentials/...`.
+ *
+ * A consumer package keeps only its identity: tool name, the kind it
+ * resolves, how to assemble the command from profile fields, and optionally
+ * `stderrNoise` — regexes for known-noise stderr lines (e.g. ceph's
+ * missing-default-keyring chatter) the factory drops after scrubbing.
+ *
+ * @module @elinpf/dsh-ops-shell-tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ProfiledShellToolSpec } from './types.js';
+export type { CredentialRef, ProfiledShellToolSpec, ShellToolExec, ShellToolResult } from './types.js';
+/**
+ * Single-quote a value for safe shell embedding. Used for ref-token
+ * substitutes, and exported for consumers that must pass a whole remote
+ * command as ONE argument (ops-tool-ssh).
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * Register a profiled shell tool on `ctx.tools`, disposed with the plugin's
+ * fiber. The caller's plugin must declare `inject = ['shell', 'tools']`.
+ */
+export declare function registerProfiledShellTool(ctx: Context, spec: ProfiledShellToolSpec): void;

package/lib/index.js

@@ -0,0 +1,188 @@
+/**
+ * Ops shell tool factory.
+ *
+ * One home for the boilerplate every ops-access consumer tool shares:
+ * the result shape `{ exitCode, stdout, stderr, command, error? }`, its
+ * output schema, the render function, and the execute template (resolve the
+ * profile per call through `ctx.get('opsAccess')` — never a static inject,
+ * never cached — assemble the command, run it through `ctx.shell` with a
+ * fixed 30s timeout, normalize a signal-killed exitCode to -1 while
+ * surfacing the kill cause (timeout / caller abort / signal name) in the
+ * error field, pass errors through verbatim).
+ *
+ * Credential paths never reach the model or the event log. Consumers mark
+ * file-bearing fields with the `ref()` helper, which emits a display token
+ * `<id@tier:field>`; the factory substitutes the shell-quoted real value
+ * only in the command handed to `ctx.shell`, and scrubs every occurrence
+ * of a referenced value back to its token in the displayed command AND in
+ * captured stdout/stderr (CLIs like kubectl print their --kubeconfig path
+ * in error output). The model sees `kubectl --kubeconfig=<prod@rw:kubeconfigPath>`,
+ * never `/root/.dsh-ops/credentials/...`.
+ *
+ * A consumer package keeps only its identity: tool name, the kind it
+ * resolves, how to assemble the command from profile fields, and optionally
+ * `stderrNoise` — regexes for known-noise stderr lines (e.g. ceph's
+ * missing-default-keyring chatter) the factory drops after scrubbing.
+ *
+ * @module @elinpf/dsh-ops-shell-tool
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function errorMessage(e) {
+    return String(e?.message || e);
+}
+/**
+ * Single-quote a value for safe shell embedding. Used for ref-token
+ * substitutes, and exported for consumers that must pass a whole remote
+ * command as ONE argument (ops-tool-ssh).
+ */
+export function shellQuote(value) {
+    return "'" + value.split("'").join("'\\''") + "'";
+}
+/**
+ * Credential tokens minted per tool call: display token `<id@tier:field>` →
+ * raw field value. The display command keeps tokens; the executed command
+ * substitutes quoted values; captured output is scrubbed value → token so
+ * credential paths never reach the model or the session event log — one
+ * mechanism, shared by every consumer tool.
+ */
+function createCredentialTokens(profileName, tier, fields) {
+    const secrets = new Map();
+    const ref = (field) => {
+        const value = fields[field];
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error('ops-access: profile ' + profileName + ' field "' + field + '" is not a non-empty string — ref() is for credential file fields');
+        }
+        const token = '<' + profileName + '@' + tier + ':' + field + '>';
+        secrets.set(token, value);
+        return token;
+    };
+    return {
+        ref,
+        executable(displayCommand) {
+            let out = displayCommand;
+            for (const [token, value] of secrets) {
+                out = out.split(token).join(shellQuote(value));
+            }
+            return out;
+        },
+        scrub(text) {
+            let out = text;
+            for (const [token, value] of secrets) {
+                if (value.length >= 8)
+                    out = out.split(value).join(token);
+            }
+            return out;
+        },
+    };
+}
+/**
+ * Drop stderr lines matching any consumer-declared noise pattern. Line-based:
+ * a trailing newline survives filtering (the final empty segment is not a
+ * line), and stdout is never touched.
+ */
+function dropNoiseLines(text, patterns) {
+    if (!patterns?.length || !text)
+        return text;
+    return text.split('\n').filter((line) => !patterns.some((p) => p.test(line))).join('\n');
+}
+/** The shared output contract: schema + render, both pure. */
+const output = {
+    schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            exitCode: { type: 'number', required: true },
+            stdout: { type: 'string', required: true },
+            stderr: { type: 'string', required: true },
+            command: { type: 'string', required: true },
+            error: { type: 'string' },
+        },
+    },
+    // Pure function of (args, value): same inputs, same text, no state touched.
+    render: (_args, value) => {
+        const parts = [];
+        if (value.command)
+            parts.push(`$ ${value.command}`);
+        if (value.stdout)
+            parts.push(value.stdout);
+        if (value.stderr)
+            parts.push(`[stderr]\n${value.stderr}`);
+        if (value.error)
+            parts.push(`[error] ${value.error}`);
+        if (value.exitCode !== 0 && value.exitCode !== undefined && value.exitCode !== null) {
+            parts.push(`[exit code: ${value.exitCode}]`);
+        }
+        return [{ type: 'text', text: parts.join('\n\n') || '(no output)' }];
+    },
+};
+// ── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Register a profiled shell tool on `ctx.tools`, disposed with the plugin's
+ * fiber. The caller's plugin must declare `inject = ['shell', 'tools']`.
+ */
+export function registerProfiledShellTool(ctx, spec) {
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: spec.name,
+        description: spec.description,
+        parameters: {
+            [spec.targetParam]: { type: 'string', required: true, description: spec.targetParamDescription },
+            command: { type: 'string', required: true, description: spec.commandDescription },
+        },
+        output,
+        async execute(args, exec) {
+            let fullCommand = '';
+            try {
+                // Resolve the seam per call through ctx.get: the preset mounts the
+                // group concurrently, so 'opsAccess' must not be a static inject
+                // (deadlock risk against the definition row), and by tool-call time
+                // the service is long since provided. Same discipline as the
+                // registry file itself: resolve per operation, cache nothing.
+                const opsAccess = ctx.get('opsAccess');
+                if (!opsAccess) {
+                    const message = 'ops-access service unavailable — is the ops-access plugin mounted in this preset?';
+                    return { error: message, exitCode: -1, stdout: '', stderr: message, command: '' };
+                }
+                // Pass the caller agent through so the access gate (if mounted) can
+                // key grants on the session id. Without a gate this arg is inert.
+                const profile = await opsAccess.resolve(spec.kind, args[spec.targetParam], exec.agent);
+                // Mint per-call credential tokens: buildCommand marks file fields via
+                // ref(); the display command (model-visible, logged) keeps the tokens,
+                // only the executed command carries the real values.
+                const tokens = createCredentialTokens(profile.name, profile.tier, profile.fields);
+                fullCommand = tokens.scrub(spec.buildCommand(profile.fields, args.command, tokens.ref));
+                const request = { command: tokens.executable(fullCommand), timeoutMs: spec.timeoutMs ?? 30000, signal: exec.signal };
+                const resolved = ctx.shell.resolve(request);
+                const result = await ctx.shell.run(resolved);
+                // exitCode is null when the process died from a signal — normalize to
+                // -1, and the kill's cause is always surfaced in the error field so
+                // the model never has to guess WHY there is no exit code — a bare -1
+                // used to leave it guessing, and it guessed wrong ('unstable pipes'
+                // for a wedged remote end, 2026-08-27).
+                // stdout/stderr are scrubbed value → token: CLIs echo credential
+                // paths in errors, and the event log must never see them. stderr then
+                // loses the consumer-declared noise lines (e.g. ceph keyring chatter).
+                const killNote = result.timedOut
+                    ? 'killed: exceeded the ' + Math.round(result.timeoutMs / 1000) + 's tool timeout — the command never finished and may have partially taken effect (e.g. a delete was already issued). If the remote end may be hung, give the remote command its own timeout (e.g. wget -T N, timeout Ns); for slow batch operations use a non-waiting form (e.g. kubectl delete --wait=false).'
+                    : result.aborted
+                        ? 'aborted: the caller cancelled this run before it finished.'
+                        : result.exitCode === null
+                            ? 'killed by signal ' + (result.signal ?? 'unknown') + ' — no normal exit code; the process was terminated externally (OOM killer, sandbox policy, or a deliberate kill).'
+                            : undefined;
+                return {
+                    exitCode: result.exitCode ?? -1,
+                    stdout: tokens.scrub(result.stdout.text),
+                    stderr: dropNoiseLines(tokens.scrub(result.stderr.text), spec.stderrNoise),
+                    command: fullCommand,
+                    ...(killNote !== undefined ? { error: killNote } : {}),
+                };
+            }
+            catch (e) {
+                // Unknown profile names land here too — resolve's message already
+                // lists the available names, so pass it through verbatim.
+                const message = errorMessage(e);
+                return { error: message, exitCode: -1, stdout: '', stderr: message, command: fullCommand };
+            }
+        },
+    })));
+}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-shell-tool.
+ *
+ * @module @elinpf/dsh-ops-shell-tool/invariant
+ */
+/** Cordis companion plugin name. */
+declare const name = "ops-shell-tool-invariant";
+/** Service required before the companion can reserve package ownership. */
+declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+declare const apply: (ctx: any) => Promise<void>;
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-shell-tool.
+ *
+ * @module @elinpf/dsh-ops-shell-tool/invariant
+ */
+const PACKAGE_NAME = '@elinpf/dsh-ops-shell-tool';
+/** Cordis companion plugin name. */
+const name = 'ops-shell-tool-invariant';
+/** Service required before the companion can reserve package ownership. */
+const inject = ['invariants'];
+/**
+ * No runtime invariant: this package is a pure library — it appends no
+ * session events and owns no durable shape. Its only state is per-call
+ * credential tokens, created and dropped inside a single execute.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+const apply = async (ctx) => {
+    ctx.invariants.register(PACKAGE_NAME, install);
+};
+export { apply, inject, name };

package/lib/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Type definitions for the ops shell tool factory.
+ *
+ * Types only — every runtime value (the credential token machinery, the
+ * output contract, the factory itself) lives in index.ts.
+ *
+ * @module @elinpf/dsh-ops-shell-tool
+ */
+import type { AccessAgent } from '@elinpf/dsh-ops-access';
+import type { ShellExecRequest } from '@deepseek-ai/dsh-shell';
+/** Shell tool result — the standard shape for ops command tools. */
+export interface ShellToolResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command: string;
+    error?: string;
+}
+/** Everything a consumer tool must supply; the factory owns the rest. */
+export interface ProfiledShellToolSpec {
+    /** Tool name as the model sees it (e.g. 'kubectl', 'ceph', 'ssh'). */
+    name: string;
+    /** ops-access kind to resolve (e.g. 'k8s', 'ceph', 'ssh'). */
+    kind: string;
+    /** Name of the profile-name parameter (e.g. 'cluster', 'host'). */
+    targetParam: string;
+    /** Tool description. */
+    description: string;
+    /** Description for the profile-name parameter. */
+    targetParamDescription: string;
+    /** Description for the command parameter. */
+    commandDescription: string;
+    /**
+     * Assemble the full shell command from resolved profile fields + the
+     * model's command arg. Mark every file-bearing field with `ref(field)` —
+     * it returns a display token `<id@tier:field>` that the factory swaps for
+     * the shell-quoted real value at execution time and scrubs back out of all
+     * captured output. Inline only non-secret values (flags, user@host, names).
+     */
+    buildCommand: (fields: Record<string, unknown>, command: string, ref: CredentialRef) => string;
+    /**
+     * Per-call shell timeout in ms (default 30000). Deployment-varying: slow
+     * batch operations and distant clusters legitimately need more, and the
+     * kill note tells the model exactly which ceiling it hit.
+     */
+    timeoutMs?: number;
+    /**
+     * Known-noise stderr line patterns: any captured stderr line matching one
+     * of these regexes is dropped from the result. For warnings the CLI prints
+     * on every call that carry no information (e.g. ceph's missing-default-
+     * keyring lines when credentials arrive via --keyring). Keep them exact —
+     * every other stderr line passes through verbatim. Applied after
+     * credential scrubbing. Use plain (non-global) regexes.
+     */
+    stderrNoise?: RegExp[];
+}
+/**
+ * Mints a credential display token for one resolved profile field and
+ * registers the field's value for execution-time substitution and output
+ * scrubbing. Throws when the field is absent or not a non-empty string —
+ * ref() exists for credential file fields, not optional inline values.
+ */
+export type CredentialRef = (field: string) => string;
+/**
+ * The exec context the factory's execute runs under. Structurally a subset of
+ * dsh's ToolRunContext: `signal` (required there, optional here for tests)
+ * and the optional caller `agent`, whose `id` is the session the access gate
+ * keys grants on. The factory passes `agent` straight through to resolve —
+ * consumers stay identity-only and need no changes.
+ */
+export interface ShellToolExec {
+    signal?: ShellExecRequest['signal'];
+    agent?: AccessAgent;
+}

package/lib/types.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for the ops shell tool factory.
+ *
+ * Types only — every runtime value (the credential token machinery, the
+ * output contract, the factory itself) lives in index.ts.
+ *
+ * @module @elinpf/dsh-ops-shell-tool
+ */
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@elinpf/dsh-ops-shell-tool",
+  "version": "0.1.0",
+  "description": "Shared factory for ops-access consumer tools: standard shell result shape, output schema, render, and the resolve-per-call execute template.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types.js",
+    "lib/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@elinpf/dsh-ops-access": "^0.1.0",
+    "@deepseek-ai/dsh-shell": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-shell": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-tools": "0.0.1-rc.1",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11",
+    "@elinpf/dsh-ops-access": "0.1.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}