@elinpf/dsh-ops-access 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-access"
+description:
+  zh: "运维访问能力缝 — 持有 YAML 凭据注册表并暴露 ctx.opsAccess"
+  en: "Ops access capability seam — owns the YAML credential registry and exposes ctx.opsAccess"

package/README.md

@@ -0,0 +1,42 @@
+# @elinpf/dsh-ops-access
+
+The ops access capability seam — owns the YAML credential registry (default `~/.dsh-ops/access.yaml`) and exposes `ctx.opsAccess` (resolve / list / register) to provider plugins and consumer tools.
+
+## What it does
+
+- **Single registry file, zero cache**: every `resolve`/`list`/`writeEntry` re-reads, re-parses, and re-validates the YAML — edits take effect immediately, no restart.
+- **Tiered entries**: each profile carries an `ro` tier (agent-readable default) and an `rw` tier (served only through a registered broker grant).
+- **Provider seam**: one provider per credential kind (`k8s`/`ceph`/`ssh` packages) supplies only a zod schema plus field processing (`~` expansion, content validation, capability probe). Providers register via `registerAccessProvider(ctx, provider)` — never hand-write `ctx.inject` for sibling services, it deadlocks the loader.
+- **`register_access` tool**: the agent's self-service path for writing the ro tier (rw stays human-managed via the admin HTTP routes).
+- **Mention support**: `@[kind/name](dsh-access:<payload>)` mentions are parsed on `agent/pre-step` and rewritten to readable references with envelope context; `GET /ops-access/list` feeds the browser's `@` picker. The encoding lives in the `./mention` subpath.
+- **Admin routes**: `GET /ops-access/admin/list`, `GET /ops-access/admin/kinds`, `GET|POST|DELETE /ops-access/admin/entry` — envelope + validation status only, never field values.
+
+## Design notes
+
+- **Secrets never cross**: profiles carry only file paths and connection parameters — logs, errors, and model context cannot contain secret material. File-field content is write-only after save (`getEntry` withholds even the stored path).
+- **Why the seam is split**: core owns the registry file and the service; providers own per-kind field knowledge; consumer tools (`ops-tool-kubectl` & co.) own command building. Each side changes independently.
+- **Broker, not gatekeeper-in-core**: policy (who may read rw) lives in a registered `AccessBroker` — a pure decision function consulted on every resolve. Without one, resolve serves ro byte-for-byte as before.
+- **Everything is an effect**: tool, routes, provider and broker registrations are all tied to the cordis effect lifecycle, so fiber disposal / HMR unload removes them cleanly.
+
+## Configuration
+
+```yaml
+- id: ops-access
+  name: '@elinpf/dsh-ops-access'
+  registryFile: ~/.dsh-ops/access.yaml   # default
+  credentialsDir: ~/.dsh-ops/credentials # default; managed credential content files (0600)
+```
+
+## Testing
+
+```sh
+npm run build      # tsc → lib/
+npx vitest run     # specs drive the real plugin through a mock context
+                   # against a real tmp-dir registry file
+```
+
+## Known Limitations and Deferred Work
+
+- No caching means a stat+parse per call — fine at ops-scale registries.
+- `ssh` providers cannot capability-probe (no read-only shell to test) — their tiers stay unprobed.
+- The registry file is human-editable by design; there is no lock against concurrent writers.

package/README.zh.md

@@ -0,0 +1,42 @@
+# @elinpf/dsh-ops-access
+
+运维访问能力缝（capability seam）— 持有 YAML 凭据注册表（默认 `~/.dsh-ops/access.yaml`），向 provider 插件和消费工具暴露 `ctx.opsAccess`（resolve / list / register）。
+
+## 功能
+
+- **单注册表文件、零缓存**：每次 `resolve`/`list`/`writeEntry` 都重新读取、解析、校验 YAML — 改文件立即生效，无需重启。
+- **分层条目**：每个 profile 携带 `ro` 层（agent 默认可读）和 `rw` 层（只有注册了 broker 授权后才发放）。
+- **Provider 缝**：每种凭据类型一个 provider（`k8s`/`ceph`/`ssh` 包），只提供 zod schema 加字段处理（`~` 展开、内容校验、能力探测）。provider 通过 `registerAccessProvider(ctx, provider)` 注册 — 绝不要手写 `ctx.inject` 依赖兄弟服务，会死锁 loader。
+- **`register_access` 工具**：agent 自助写入 ro 层的路径（rw 层始终由人通过 admin HTTP 路由管理）。
+- **Mention 支持**：`@[kind/name](dsh-access:<payload>)` mention 在 `agent/pre-step` 上被解析、重写为可读引用并注入 envelope 上下文；`GET /ops-access/list` 给浏览器的 `@` 选择器供数。编码在 `./mention` 子路径。
+- **Admin 路由**：`GET /ops-access/admin/list`、`GET /ops-access/admin/kinds`、`GET|POST|DELETE /ops-access/admin/entry` — 只出 envelope + 校验状态，绝不出字段值。
+
+## 设计要点
+
+- **秘密不过境**：profile 只携带文件路径和连接参数 — 日志、报错、模型上下文都不可能含秘密材料。文件字段保存后只写不读（`getEntry` 连存储路径都不返回）。
+- **为什么这样拆**：core 持有注册表文件和服务；provider 持有各类型的字段知识；消费工具（`ops-tool-kubectl` 等）持有命令拼装。三方各自独立演进。
+- **broker 而非内置守门**：策略（谁能读 rw）住在注册的 `AccessBroker` 里 — 一个纯决策函数，每次 resolve 都咨询。没有 broker 时 resolve 与之前逐字节一致地发 ro。
+- **一切皆 effect**：工具、路由、provider 和 broker 注册都绑在 cordis effect 生命周期上，fiber 销毁 / HMR 卸载会干净移除。
+
+## 配置
+
+```yaml
+- id: ops-access
+  name: '@elinpf/dsh-ops-access'
+  registryFile: ~/.dsh-ops/access.yaml   # 默认值
+  credentialsDir: ~/.dsh-ops/credentials # 默认值；托管凭据内容文件（0600）
+```
+
+## 测试
+
+```sh
+npm run build      # tsc → lib/
+npx vitest run     # spec 用 mock context 驱动真实插件，
+                   # 注册表是真实的 tmp 目录文件
+```
+
+## 已知限制和待办事项
+
+- 无缓存意味着每次调用一次 stat+解析 — 运维规模的注册表下没问题。
+- `ssh` provider 无法做能力探测（没有只读 shell 可测）— 其分层保持未探测状态。
+- 注册表文件按设计可人工编辑；没有并发写锁。

package/cordis.patch.yml

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

package/lib/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Ops access capability seam.
+ *
+ * Owns the YAML credential registry file (default `~/.dsh-ops/access.yaml`)
+ * and exposes `ctx.opsAccess`: a generic `resolve(kind, name)` / `list()`
+ * entry plus a `register(provider)` surface for provider plugins. Providers
+ * (one per credential kind) supply the zod schema for their entry shape and
+ * an optional `process` step (e.g. `~` expansion); secret material never
+ * leaves the filesystem — profiles carry only paths and connection params.
+ *
+ * The registry file is re-read, re-parsed, and re-validated on every call —
+ * edits take effect immediately, nothing is cached.
+ *
+ * Also registers the `register_access` tool: the agent's self-service path
+ * for writing the ro tier of a profile (rw tiers stay human-managed via the
+ * admin HTTP routes below).
+ *
+ * Registry format:
+ *
+ * ```yaml
+ * version: 1
+ * k8s:
+ *   prod:
+ *     description: 生产集群
+ *     environment: prod
+ *     ro:
+ *       kubeconfig: ~/.dsh-ops/credentials/k8s/prod/ro/kubeconfig
+ *     rw:
+ *       kubeconfig: ~/.dsh-ops/credentials/k8s/prod/rw/kubeconfig
+ * ```
+ *
+ * Every top-level section besides `version` is a kind; keys inside a section
+ * are profile names. `description` and `environment` are envelope fields
+ * on the entry; `ro` and `rw` are tier sub-objects holding the
+ * provider-specific fields for that tier.
+ *
+ * @module @elinpf/dsh-ops-access
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AccessProvider, AccessBroker, OpsAccess } from './types.js';
+export declare const name = "ops-access";
+export declare const inject: string[];
+export interface Config {
+    /** Path to the YAML access registry; a leading `~` expands to $HOME. */
+    registryFile: string;
+    /** Root directory for managed credential content files; a leading `~` expands to $HOME. */
+    credentialsDir: string;
+}
+export declare const Config: z<Config>;
+export type { AccessProvider, AccessProfile, EntryEnvelope, ProbeState, AdminTierStatus, AdminEntry, KindDescriptor, AccessAgent, AccessBrokerDecision, AccessBroker, OpsAccess, } from './types.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        opsAccess?: OpsAccess;
+    }
+}
+/**
+ * Register a provider into the seam from a provider plugin's `apply()`. The
+ * preset mounts sibling rows concurrently, so a static inject on 'opsAccess'
+ * can deadlock the loader against the definition row — this defers through
+ * `ctx.inject` and ties the registration to the plugin's effect lifecycle.
+ * Provider packages should call this and nothing else.
+ */
+export declare function registerAccessProvider(ctx: Context, provider: AccessProvider): void;
+/**
+ * Register an access broker (the gate) from the gate plugin's `apply()`. Same
+ * deferred-mount discipline as {@link registerAccessProvider}: the preset
+ * mounts sibling rows concurrently, so a static inject on 'opsAccess' can
+ * deadlock the loader against the definition row — this defers through
+ * `ctx.inject` and ties the registration to the plugin's effect lifecycle.
+ */
+export declare function registerAccessBroker(ctx: Context, broker: AccessBroker): void;
+/** Expand a leading `~` (or `~/`) to the user's home directory. */
+export declare function expandHome(p: string): string;
+export declare function apply(ctx: Context, config: Config): void;