@elinpf/dsh-ops-tool-ceph 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-tool-ceph"
+description:
+  zh: "ceph 工具 — 经 ops-access 接缝解析 Ceph 集群档案,自动注入凭证路径执行 ceph/rbd/rados"
+  en: "ceph tool — resolves Ceph cluster profiles via the ops-access seam and runs ceph/rbd/rados with credential paths injected"

package/README.md

@@ -0,0 +1,33 @@
+# @elinpf/dsh-ops-tool-ceph
+
+The `ceph` tool for DeepSeek Harness ops mode — resolves a named Ceph cluster profile through the ops-access seam and runs `ceph` / `rbd` / `rados` against it via `ctx.shell`, injecting the credential paths automatically.
+
+## What it does
+
+The model calls `ceph` with a `cluster` (profile name) and a `command`. The tool resolves the profile on every call (no caching — credential edits take effect immediately), builds the real command line with the profile's `--conf` / `--keyring` (and `--name` when the profile carries a cephx user) injected as `<id@tier:field>` token references, runs it through the shell service with a 30 s timeout, and returns the standard `{ exitCode, stdout, stderr, command, error? }` result.
+
+## Design notes
+
+- **Thin consumer, shared machinery.** This package supplies only four identity pieces — tool name, resolved kind (`ceph`), profile-arg name (`cluster`), and `buildCommand`. Everything else (result shape, output schema, render, resolve-per-call execute template, timeout and signal-death normalization) lives in `@elinpf/dsh-ops-shell-tool`, so the three consumer tools (`kubectl` / `ceph` / `ssh`) cannot drift apart.
+- **First word picks the binary.** `rbd` and `rados` are SEPARATE binaries, not ceph subcommands — `ceph rbd ls` is a mon-side "no valid command found". The command's first word selects from the allowlist `[ceph, rbd, rados]`; a bare word is treated as a ceph subcommand.
+- **Boundary errors over misleading ones.** Host-local ceph-ecosystem binaries (`mount.ceph`, `ceph-fuse`, `ceph-volume`, `rbd-nbd`, …) are explicitly NOT wrapped; such a call fails with a clear message pointing at the `ssh` tool instead of the mon's confusing error.
+- **stderr noise filtering.** The two known "no keyring under /etc/ceph" warnings (pure noise when credentials arrive via injected `--keyring`) are matched exactly and dropped; every other stderr line passes through verbatim.
+- **No secret material in band.** Profiles carry only paths and connection parameters; file paths become `<id@tier:field>` tokens in the assembled command, and the cephx entity name (not secret) stays inline. Read-only enforcement happens at the mon/osd via the credential's caps, never in this tool.
+- **Registration is an effect.** The tool registers via `ctx.effect(() => ctx.tools.register(...))` (inside `registerProfiledShellTool`), so fiber disposal / HMR unloads it cleanly. The `./invariant` subpath registers a no-op invariant companion: the tool is stateless and owns no session events, so there is no runtime invariant to install.
+
+## Configuration
+
+Schemastery schema, one option:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `timeoutMs` | `30000` | Per-call shell timeout for ceph runs (ms). Slow clusters may need more. |
+
+## Testing
+
+```sh
+npm run build     # tsc → lib/ (plugins load lib/, not src/)
+npx vitest run    # unit tests against a mock ctx (shell / tools / opsAccess)
+```
+
+The suite covers command assembly (ceph / rbd / rados / explicit-prefix stripping / `--name` injection), the not-wrapped boundary, profile-resolution and shell failure mapping, stderr noise filtering, render purity, export shape (`.` / `./invariant` / `./types` entries), and HMR unload (running every collected effect disposer unregisters the tool).

package/README.zh.md

@@ -0,0 +1,33 @@
+# @elinpf/dsh-ops-tool-ceph
+
+DeepSeek Harness 运维模式下的 `ceph` 工具 — 通过 ops-access 接缝按名字解析 Ceph 集群档案(profile),经由 `ctx.shell` 对集群执行 `ceph` / `rbd` / `rados` 命令,凭证路径自动注入。
+
+## 它做什么
+
+模型用 `cluster`(档案名)和 `command` 调用 `ceph` 工具。工具每次调用都重新解析档案(不缓存,凭证改动立即生效),把档案的 `--conf` / `--keyring`(档案带 cephx 用户时还有 `--name`)以 `<id@tier:field>` 令牌引用的形式拼进真实命令行,经 shell 服务以 30 秒超时执行,返回标准结果 `{ exitCode, stdout, stderr, command, error? }`。
+
+## 设计要点
+
+- **薄消费者,共享机制。** 本包只提供四件身份要素:工具名、解析类型(`ceph`)、档案参数名(`cluster`)、`buildCommand`。其余全部(结果形态、输出 schema、渲染、逐次解析的执行模板、超时与信号死亡归一化)都在 `@elinpf/dsh-ops-shell-tool`,保证三个消费工具(`kubectl` / `ceph` / `ssh`)不会各自漂移。
+- **首词选二进制。** `rbd` 和 `rados` 是独立二进制,不是 ceph 子命令 — `ceph rbd ls` 只会在 mon 侧报 "no valid command found"。按命令首词在白名单 `[ceph, rbd, rados]` 中选择;裸词视为 ceph 子命令。
+- **边界错误优于误导错误。** 跑在宿主机本地的 ceph 生态二进制(`mount.ceph`、`ceph-fuse`、`ceph-volume`、`rbd-nbd` 等)明确不包装;这类调用直接报清晰错误并指向 `ssh` 工具,而不是让 mon 的误导性报错带偏排查。
+- **stderr 噪音过滤。** 两条已知的" /etc/ceph 下找不到 keyring "警告(凭证都经注入的 `--keyring` 到达,纯属噪音)按精确模式剔除;其余 stderr 行原样透传。
+- **秘密不经过工具。** 档案只携带路径和连接参数;文件路径在拼装命令中变成 `<id@tier:field>` 令牌,cephx 实体名(非秘密)保持内联。只读强制由凭证 caps 在 mon/osd 侧执行,工具本身不做。
+- **注册即 effect。** 工具经 `ctx.effect(() => ctx.tools.register(...))` 注册(在 `registerProfiledShellTool` 内部),fiber 销毁 / HMR 时干净卸载。`./invariant` 子路径注册一个空实现的 invariant 伴生插件:本工具无状态、不拥有 session 事件,没有需要安装的运行时不变量。
+
+## 配置项
+
+schemastery schema,仅一项:
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `timeoutMs` | `30000` | 单次 ceph 执行的 shell 超时(毫秒)。慢集群可调大。 |
+
+## 测试方式
+
+```sh
+npm run build     # tsc → lib/(插件加载的是 lib/,不是 src/)
+npx vitest run    # 基于 mock ctx(shell / tools / opsAccess)的单元测试
+```
+
+测试覆盖:命令拼装(ceph / rbd / rados / 显式前缀剥离 / `--name` 注入)、不包装边界、档案解析与 shell 失败映射、stderr 噪音过滤、render 纯函数性、导出形态(`.` / `./invariant` / `./types` 三个入口)、以及 HMR 卸载(执行收集到的全部 effect disposer 后工具被注销)。

package/cordis.patch.yml

@@ -0,0 +1 @@
+[]

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ops ceph tool consumer.
+ *
+ * The `ceph` tool: resolves a `ceph` profile through the ops-access seam and
+ * runs the command via ctx.shell, injecting the profile's --conf and
+ * --keyring paths. The command's first word picks the binary from the
+ * allowlist [ceph, rbd, rados] — rbd/rados are SEPARATE binaries, not ceph
+ * subcommands (`ceph rbd ls` is a mon-side 'no valid command found', which
+ * once sent an agent chasing a phantom permissions problem, 2026-08-27).
+ * All shared machinery (result shape, output schema, render, execute
+ * template) lives in @elinpf/dsh-ops-shell-tool.
+ *
+ * @module @elinpf/dsh-ops-tool-ceph
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { CephToolConfig } from './types.js';
+export type { CephToolConfig } from './types.js';
+export declare const name = "ops-tool-ceph";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<{
+    /** Per-call shell timeout for ceph runs (ms). Slow clusters may need more. */
+    timeoutMs: z<number, number>;
+}>, Schemastery.ObjectT<{
+    /** Per-call shell timeout for ceph runs (ms). Slow clusters may need more. */
+    timeoutMs: z<number, number>;
+}>>;
+export declare function apply(ctx: Context, config: CephToolConfig): void;

package/lib/index.js

@@ -0,0 +1,74 @@
+/**
+ * Ops ceph tool consumer.
+ *
+ * The `ceph` tool: resolves a `ceph` profile through the ops-access seam and
+ * runs the command via ctx.shell, injecting the profile's --conf and
+ * --keyring paths. The command's first word picks the binary from the
+ * allowlist [ceph, rbd, rados] — rbd/rados are SEPARATE binaries, not ceph
+ * subcommands (`ceph rbd ls` is a mon-side 'no valid command found', which
+ * once sent an agent chasing a phantom permissions problem, 2026-08-27).
+ * All shared machinery (result shape, output schema, render, execute
+ * template) lives in @elinpf/dsh-ops-shell-tool.
+ *
+ * @module @elinpf/dsh-ops-tool-ceph
+ */
+import z from '@deepseek-ai/schemastery';
+import { registerProfiledShellTool } from '@elinpf/dsh-ops-shell-tool';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-tool-ceph';
+export const inject = ['shell', 'tools'];
+// ── Config ───────────────────────────────────────────────────────────────────
+export const Config = z.object({
+    /** Per-call shell timeout for ceph runs (ms). Slow clusters may need more. */
+    timeoutMs: z.number().default(30000),
+});
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+/**
+ * Known ceph-CLI stderr noise inside containers with no default keyring under
+ * /etc/ceph. Credentials always arrive via the injected --keyring, so these
+ * warnings are pure noise; the patterns match the two known message shapes
+ * exactly (tolerating the librados timestamp/entity prefix and the variable
+ * path list) — every other stderr line passes through verbatim.
+ */
+const STDERR_NOISE = [
+    // "unable to find a keyring on /etc/ceph/ceph.client.X.keyring,...: (2) No such file or directory"
+    /unable to find a keyring on .*: \(-?\d+\) No such file or directory\s*$/,
+    // "no keyring found at /etc/ceph/ceph.client.X.keyring, disabling cephx"
+    /no keyring found at .*disabling cephx\s*$/,
+];
+const CEPH_BINARIES = ['ceph', 'rbd', 'rados'];
+// ceph-ecosystem binaries this tool does NOT wrap — they run locally on a
+// host, not against the mon. Named so a confused call fails with a clear
+// boundary instead of the mon's misleading 'no valid command found'.
+const NOT_WRAPPED = ['mount', 'umount', 'mount.ceph', 'ceph-fuse', 'ceph-volume', 'rclone', 'rbd-nbd', 'rbd-mirror'];
+export function apply(ctx, config) {
+    registerProfiledShellTool(ctx, {
+        timeoutMs: config.timeoutMs,
+        name: 'ceph',
+        kind: 'ceph',
+        targetParam: 'cluster',
+        description: 'Execute a ceph, rbd or rados command on a specified Ceph cluster. The plugin automatically injects the correct --conf and --keyring credentials (shown as <id@tier:field> references). Use list_access to see available cluster names.',
+        targetParamDescription: 'Ceph cluster profile name. Use list_access to see options.',
+        commandDescription: 'A ceph, rbd or rados command. Bare ceph subcommands work as-is (health detail, osd tree, df). rbd and rados are SEPARATE binaries — include the binary name as the first word (rbd ls -p rbd-pool, rados df); they share the injected --conf/--keyring/--name. Discover pool names with "osd pool ls". Under an ro credential, write verbs (and some reads like rbd ls without class-read caps) fail at the mon/osd with a real permission error — that is the enforcement layer working, not a tool bug.',
+        stderrNoise: STDERR_NOISE,
+        buildCommand(fields, command, ref) {
+            const { name } = fields;
+            // --name matters: a non-admin keyring without it still authenticates as
+            // client.admin and fails with RADOS permission denied. The cephx entity
+            // name is not secret — it stays inline; only the file paths get tokens.
+            const nameArg = name ? ` --name ${name}` : '';
+            const trimmed = command.trim();
+            const first = trimmed.split(/\s+/, 1)[0] ?? '';
+            if (NOT_WRAPPED.includes(first)) {
+                throw new Error('the ceph tool wraps ceph/rbd/rados against the cluster only — \'' + first + '\' runs locally on a host; use the ssh tool for that');
+            }
+            // rbd and rados are SEPARATE binaries, not ceph subcommands — select by
+            // first word (an explicit 'ceph' prefix is stripped too); a bare word
+            // is a ceph subcommand and stays. Read-only-ness is enforced by the
+            // credential's caps at the mon/osd, never by the binary name.
+            const binary = CEPH_BINARIES.includes(first) ? first : 'ceph';
+            const rest = first === binary ? trimmed.slice(first.length).trimStart() : trimmed;
+            return `${binary} --conf=${ref('conf')} --keyring=${ref('keyring')}${nameArg} ${rest}`;
+        },
+    });
+}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-ceph.
+ *
+ * @module @elinpf/dsh-ops-tool-ceph/invariant
+ */
+/** Cordis companion plugin name. */
+declare const name = "ops-ceph-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,26 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-ceph.
+ *
+ * @module @elinpf/dsh-ops-tool-ceph/invariant
+ */
+const PACKAGE_NAME = '@elinpf/dsh-ops-tool-ceph';
+/** Cordis companion plugin name. */
+const name = 'ops-ceph-invariant';
+/** Service required before the companion can reserve package ownership. */
+const inject = ['invariants'];
+/**
+ * No runtime invariant: this tool is stateless. It owns no session events and
+ * no durable shape — every call re-resolves the credential profile through
+ * the ops-access seam and runs one shell command, so there is nothing to
+ * fold and nothing to check.
+ */
+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,15 @@
+/**
+ * Type definitions for the ops-tool-ceph plugin.
+ *
+ * Types only — no runtime values live here (not even consts), so importing
+ * this module never pulls in plugin code.
+ *
+ * @module @elinpf/dsh-ops-tool-ceph
+ */
+/**
+ * Resolved configuration of the ops-tool-ceph plugin (post-schema defaults).
+ */
+export interface CephToolConfig {
+    /** Per-call shell timeout for ceph runs (ms). Slow clusters may need more. */
+    timeoutMs: number;
+}

package/lib/types.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for the ops-tool-ceph plugin.
+ *
+ * Types only — no runtime values live here (not even consts), so importing
+ * this module never pulls in plugin code.
+ *
+ * @module @elinpf/dsh-ops-tool-ceph
+ */
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@elinpf/dsh-ops-tool-ceph",
+  "version": "0.1.0",
+  "description": "ceph tool consumer of the ops-access seam — resolves ceph profiles and runs commands via ctx.shell, injecting credential paths automatically.",
+  "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",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@elinpf/dsh-ops-shell-tool": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.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"
+  }
+}