@elinpf/dsh-ops-panel 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-panel"
+description:
+  zh: "运维插件的面板缝 — 会话作用域对话框的公共机制"
+  en: "The panel seam for ops plugins — session-scoped overlay dialogs triggered by slash commands"

package/README.md

@@ -0,0 +1,53 @@
+# @elinpf/dsh-ops-panel
+
+The panel seam for DeepSeek Harness ops plugins — one shared mechanism for session-scoped overlay dialogs triggered by slash commands (ADR-0004).
+
+## What it does
+
+Business packages should not each invent their own dialog shell, keyboard handling, and command dispatch. ops-panel splits that concern in two:
+
+- **Client half** (`ops-panel-client`): provides the `opsPanels` registry service. Consumers register one panel definition per command — `registerPanel({ command, title, component })`. The shell renders the open panel as a centered modal over a backdrop (Escape / backdrop click closes), injected into the `conversation.input.overlay` slot. A single `command/executed` listener dispatches to the right panel by command name, so N panels cost one listener, not N.
+- **Host helper** (`registerPanelCommand(ctx, { name, description })`): registers the slash command itself — a no-op success handler whose only job is to exist in the session's command directory so the UI lets the user submit it and fires `command/executed`. Registers agent-scoped when called from the preset plane; fails loud when the `commands` service is absent.
+
+A panel component receives `{ sessionId, close }` and owns everything inside the card — data fetching, polling, actions.
+
+## Why a service, not a library
+
+Bundling this code per consumer would give every consumer its own registry, its own `command/executed` listener, and its own overlay shell — and only the last-registered shell would win. As a cordis service there is exactly one registry and one shell per page, and panels can be registered from any plugin.
+
+## Installation
+
+Add to the app dependencies and reference in `cordis.patch.yml` (host plane):
+
+```yaml
+- id: ops-panel
+  name: '@elinpf/dsh-ops-panel'
+```
+
+Consumers register from their own client halves:
+
+```ts
+ctx.inject(['opsPanels'], (pctx) => {
+  pctx.effect(() => pctx.opsPanels.registerPanel({
+    command: 'access',
+    title: '访问授权',
+    component: AccessPanel,
+  }))
+})
+```
+
+…and register the command from their preset-plane host half:
+
+```ts
+ctx.inject(['commands'], (cctx) => {
+  registerPanelCommand(cctx, { name: 'access', description: '打开授权面板' })
+})
+```
+
+First consumer: the access panel (`ops-access-ui` + `ops-access/gate`, spec 0003).
+
+## Known Limitations
+
+- One open panel at a time (opening another replaces the current one).
+- The shell is deliberately minimal (title + close) — tab bars, sizing, and drag belong to a later iteration if a second consumer needs them.
+- `command/executed` fires only for sessions whose preset mounts the command — panels are inherently preset-scoped.

package/README.zh.md

@@ -0,0 +1,31 @@
+# @elinpf/dsh-ops-panel
+
+DeepSeek Harness 运维插件的面板缝 — 会话作用域对话框的公共机制，由斜杠命令触发（ADR-0004）。
+
+## 它做什么
+
+业务包不应各自重造对话框外壳、键盘处理和命令分发。ops-panel 把这件事拆成两半：
+
+- **client 半**（`ops-panel-client`）：提供 `opsPanels` 注册表服务。消费方每个命令注册一条面板定义 — `registerPanel({ command, title, component })`。外壳把打开的面板渲染为遮罩上的居中卡片（Escape / 点遮罩关闭），注入 `conversation.input.overlay` 槽位。单一的 `command/executed` 监听器按命令名分发 — N 个面板只花一个监听器。
+- **host 助手**（`registerPanelCommand(ctx, { name, description })`）：注册斜杠命令本身 — 一个空操作的成功 handler，唯一职责是存在于会话命令目录里，让 UI 允许提交并触发 `command/executed`。从 preset 面调用时按 agent 作用域注册；`commands` 服务缺席时直接报错。
+
+面板组件收到 `{ sessionId, close }`，卡片内的一切（取数、轮询、动作）归它自己管。
+
+## 为什么是服务而不是库
+
+按消费方各自打包会得到 N 份注册表、N 个 `command/executed` 监听器、N 个遮罩外壳 — 而只有最后注册的外壳生效。作为 cordis 服务，每个页面只有一份注册表和一个外壳，任何插件都能注册面板。
+
+## 安装
+
+加入 app 依赖并在 `cordis.patch.yml` 引用（host 面）：
+
+```yaml
+- id: ops-panel
+  name: '@elinpf/dsh-ops-panel'
+```
+
+## 已知限制
+
+- 同时只打开一个面板（打开另一个会替换当前的）。
+- 外壳刻意极简（标题 + 关闭）——标签页、尺寸、拖拽留给有第二个消费者时再迭代。
+- `command/executed` 只在挂了这个命令的会话里触发 — 面板天然是 preset 作用域的。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: ops-panel
+      name: '@elinpf/dsh-ops-panel'

package/lib/client.js

@@ -0,0 +1,167 @@
+window.__ModuleLoader__.load({ id: "@elinpf/dsh-ops-panel", factory: (require) => {
+var module = { exports: {} }; var exports = module.exports;
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  ShellView: () => ShellView,
+  apply: () => apply,
+  createPanelCore: () => createPanelCore,
+  inject: () => inject,
+  name: () => name
+});
+module.exports = __toCommonJS(client_exports);
+var import_react = require("react");
+var import_react2 = require("react");
+var name = "ops-panel-client";
+var inject = ["slots"];
+function createPanelCore() {
+  const registry = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = /* @__PURE__ */ new Map();
+  function emit() {
+    for (const fn of listeners) fn();
+  }
+  function open(sessionId, command) {
+    const def = registry.get(command);
+    if (!def) return false;
+    if (def.available && !def.available(sessionId)) return false;
+    const next = new Map(snapshot);
+    next.set(sessionId, command);
+    snapshot = next;
+    emit();
+    return true;
+  }
+  return {
+    registerPanel(def) {
+      if (registry.has(def.command)) {
+        throw new Error("ops-panel: a panel is already registered for command " + def.command);
+      }
+      registry.set(def.command, def);
+      return () => {
+        registry.delete(def.command);
+      };
+    },
+    get(command) {
+      return registry.get(command);
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    open,
+    close(sessionId) {
+      if (!snapshot.has(sessionId)) return;
+      const next = new Map(snapshot);
+      next.delete(sessionId);
+      snapshot = next;
+      emit();
+    },
+    handleCommandExecuted(sessionId, commandName) {
+      open(sessionId, commandName);
+    }
+  };
+}
+var CSS = [
+  ".ops-panel-backdrop { position: fixed; inset: 0; z-index: 1000; display: flex; align-items: center; justify-content: center; background: rgba(0, 0, 0, 0.4); }",
+  ".ops-panel-card { box-sizing: border-box; width: min(560px, calc(100vw - 48px)); max-height: min(70vh, 640px); display: flex; flex-direction: column; border-radius: 12px; border: 1px solid var(--dsw-alias-border-l1, #e5e7eb); background: var(--dsw-alias-bg-primary, #ffffff); color: var(--dsw-alias-text-primary, #1f2328); box-shadow: 0 8px 30px rgba(0, 0, 0, 0.18); overflow: hidden; }",
+  ".ops-panel-header { flex: none; display: flex; align-items: center; justify-content: space-between; padding: 10px 16px; font-size: 14px; font-weight: 600; border-bottom: 1px solid var(--dsw-alias-border-l1, #e5e7eb); }",
+  ".ops-panel-close { border: none; background: transparent; color: inherit; font-size: 16px; line-height: 1; padding: 4px 8px; cursor: pointer; border-radius: 6px; opacity: 0.6; }",
+  ".ops-panel-close:hover { opacity: 1; background: var(--dsw-alias-bg-secondary, #f6f8fa); }",
+  ".ops-panel-body { flex: 1 1 auto; overflow-y: auto; padding: 12px 16px; font-size: 13px; }"
+].join("\n");
+var cssInjected = false;
+function injectCSS() {
+  if (cssInjected || typeof document === "undefined") return;
+  cssInjected = true;
+  const el = document.createElement("style");
+  el.setAttribute("data-ops-panel", "");
+  el.textContent = CSS;
+  document.head.appendChild(el);
+}
+function ShellView({ sessionId }, core) {
+  const openMap = (0, import_react2.useSyncExternalStore)(core.subscribe, core.getSnapshot);
+  const sid = sessionId;
+  const command = sid ? openMap.get(sid) : void 0;
+  const def = command ? core.get(command) : void 0;
+  const open = Boolean(sid && def);
+  (0, import_react.useEffect)(() => {
+    if (!open || !sid) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") core.close(sid);
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, sid]);
+  if (!open || !sid || !def) return null;
+  const close = () => core.close(sid);
+  return (0, import_react.createElement)(
+    "div",
+    { className: "ops-panel-backdrop", onClick: close },
+    (0, import_react.createElement)(
+      "div",
+      { className: "ops-panel-card", onClick: (e) => e.stopPropagation() },
+      (0, import_react.createElement)(
+        "div",
+        { className: "ops-panel-header" },
+        (0, import_react.createElement)("span", null, def.title),
+        (0, import_react.createElement)("button", { className: "ops-panel-close", onClick: close, "aria-label": "\u5173\u95ED" }, "\xD7")
+      ),
+      (0, import_react.createElement)("div", { className: "ops-panel-body" }, (0, import_react.createElement)(def.component, { sessionId: sid, close }))
+    )
+  );
+}
+function apply(ctx) {
+  injectCSS();
+  const core = createPanelCore();
+  const service = {
+    registerPanel: (def) => core.registerPanel(def),
+    // The imperative open path (ADR-0004 §9): ambient affordances like the
+    // access-request badge pull the panel up without a typed command.
+    open: (sessionId, command) => core.open(sessionId, command),
+    close: (sessionId) => core.close(sessionId)
+  };
+  ctx.provide("opsPanels", service);
+  const events = ctx;
+  events.on("command/executed", (sessionId, commandName) => {
+    core.handleCommandExecuted(String(sessionId), commandName);
+  });
+  const slots = ctx.get("slots");
+  if (slots !== void 0) {
+    ctx.effect(
+      () => slots.inject(
+        "conversation.input.overlay",
+        () => slots.register(
+          { name: "conversation.input.overlay", id: "ops-panel", order: 5 },
+          (props) => ShellView(props, core)
+        )
+      )
+    );
+  }
+}
+
+return module.exports; } });
+//# sourceMappingURL=client.js.map

package/lib/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Ops panel seam, node half (ADR-0004). The plugin row itself is an empty
+ * shell whose only job is client-bundle discovery (same pattern as
+ * ops-access-ui). The node-side value is the registerPanelCommand helper:
+ * a panel trigger is a host slash command whose handler is a deliberate
+ * no-op — the lifecycle pair (command/run, command/done) is the durable,
+ * log-only record, and the command/executed local browser event is what
+ * opens the panel on the client half.
+ *
+ * @module @elinpf/dsh-ops-panel
+ */
+import z from '@deepseek-ai/schemastery';
+import type { PanelCommandSpec } from './types.ts';
+export type { OpsPanels, PanelCommandSpec, PanelComponent, PanelContentProps, PanelDefinition } from './types.ts';
+export declare const name = "ops-panel";
+export declare const inject: string[];
+/** No options: the row is a discovery-only shell, the helper takes its spec per call. */
+export declare const Config: z<Schemastery.ObjectS<{}>, Schemastery.ObjectT<{}>>;
+/** Empty by design: the row exists so the web resolver finds lib/client.js. */
+export declare function apply(_ctx: never): void;
+/**
+ * The structural host this helper needs — deliberately NOT cordis's Context:
+ * consumers link their own cordis instance (pnpm hoisting yields two type
+ * graphs for the same version), and a structural parameter sidesteps the
+ * dual-instance type clash. Any cordis context satisfies this.
+ */
+export interface PanelCommandHost {
+    get(name: string): unknown;
+    effect(fn: () => () => void): unknown;
+}
+/**
+ * Register the slash command that triggers a panel. The handler is a no-op
+ * success: all behavior lives on the client half, dispatched from the local
+ * command/executed event. The command registers agent-scoped when the caller
+ * sits under agent.ctx (preset plane), so a panel command only exists in the
+ * presets that mount the calling plugin.
+ *
+ * Misconfiguration fails loud at load: an invalid name or a missing commands
+ * service throws instead of silently registering nothing.
+ *
+ * @param ctx - the calling plugin context (preset plane scopes the command).
+ * @param spec - command name and menu description.
+ */
+export declare function registerPanelCommand(ctx: PanelCommandHost, spec: PanelCommandSpec): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,51 @@
+/**
+ * Ops panel seam, node half (ADR-0004). The plugin row itself is an empty
+ * shell whose only job is client-bundle discovery (same pattern as
+ * ops-access-ui). The node-side value is the registerPanelCommand helper:
+ * a panel trigger is a host slash command whose handler is a deliberate
+ * no-op — the lifecycle pair (command/run, command/done) is the durable,
+ * log-only record, and the command/executed local browser event is what
+ * opens the panel on the client half.
+ *
+ * @module @elinpf/dsh-ops-panel
+ */
+import z from '@deepseek-ai/schemastery';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-panel';
+export const inject = [];
+// ── Config ───────────────────────────────────────────────────────────────────
+/** No options: the row is a discovery-only shell, the helper takes its spec per call. */
+export const Config = z.object({});
+/** Empty by design: the row exists so the web resolver finds lib/client.js. */
+export function apply(_ctx) { }
+// ── registerPanelCommand ─────────────────────────────────────────────────────
+/** Slash command names parse as lowercase letters, digits, underscore, dash. */
+const COMMAND_NAME = /^[a-z0-9_-]+$/;
+/**
+ * Register the slash command that triggers a panel. The handler is a no-op
+ * success: all behavior lives on the client half, dispatched from the local
+ * command/executed event. The command registers agent-scoped when the caller
+ * sits under agent.ctx (preset plane), so a panel command only exists in the
+ * presets that mount the calling plugin.
+ *
+ * Misconfiguration fails loud at load: an invalid name or a missing commands
+ * service throws instead of silently registering nothing.
+ *
+ * @param ctx - the calling plugin context (preset plane scopes the command).
+ * @param spec - command name and menu description.
+ */
+export function registerPanelCommand(ctx, spec) {
+    if (!COMMAND_NAME.test(spec.name)) {
+        throw new Error('ops-panel: invalid panel command name ' + JSON.stringify(spec.name) + ' (lowercase letters, digits, underscore, dash only)');
+    }
+    const commands = ctx.get('commands');
+    if (!commands) {
+        throw new Error('ops-panel: the commands service is not composed — panel command ' + spec.name + ' cannot be registered in this deployment');
+    }
+    ctx.effect(() => commands.register({
+        name: spec.name,
+        description: spec.description,
+        handler: () => ({ kind: 'success', text: 'Opening panel: ' + spec.name })
+    }));
+}
+//# sourceMappingURL=index.js.map

package/lib/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Vocabulary types of the panel seam (ADR-0004). Types only — no runtime
+ * code. Both halves import from here: the node half for the command helper,
+ * the client half for the registry contract, consumers for both.
+ */
+/**
+ * Props every panel content component receives from the shell. sessionId
+ * is the session the slash command ran in (panels are session-scoped);
+ * close dismisses the panel (e.g. after a successful submit).
+ */
+export interface PanelContentProps {
+    readonly sessionId: string;
+    readonly close: () => void;
+}
+/**
+ * A panel content renderer, hosted inside the shell card. React-free by
+ * design: no repo package compiles against React types (client bundles are
+ * esbuild-only, excluded from tsc), so the return type stays structural —
+ * the shell hands the component to createElement, consumers return React
+ * elements.
+ */
+export type PanelComponent = (props: PanelContentProps) => unknown;
+/**
+ * One panel registration. The panel identity IS its command name: the
+ * node half registers a host slash command of the same name via
+ * registerPanelCommand, and the browser that executed it opens this panel.
+ */
+export interface PanelDefinition {
+    /** Slash command name without the slash (lowercase letters, digits, underscore, dash). */
+    readonly command: string;
+    /** Title shown in the shell header bar. */
+    readonly title: string;
+    /** Content component rendered inside the shell card. */
+    readonly component: PanelComponent;
+    /**
+     * Capability filter evaluated when the command executes: return false to
+     * keep the panel closed for that session (e.g. non-ops presets).
+     */
+    readonly available?: (sessionId: string) => boolean;
+}
+/**
+ * The ctx.opsPanels client service face (plural key — a registry).
+ * Registration is an effect: the returned disposer removes the panel.
+ */
+export interface OpsPanels {
+    /**
+     * Register one panel. Duplicate command names throw at registration.
+     * @param def - the panel identity and content.
+     * @returns disposer removing the panel.
+     */
+    registerPanel(def: PanelDefinition): () => void;
+    /**
+     * Open a panel without a slash command (ADR-0004 §9): the imperative
+     * path for ambient affordances — e.g. the access-request badge pulling
+     * up the approval deck while a request_access call parks.
+     * @param sessionId - the session whose overlay hosts the panel.
+     * @param command - the panel's command name.
+     * @returns false when nothing is registered for the command or the
+     *   panel's capability filter declines this session.
+     */
+    open(sessionId: string, command: string): boolean;
+    /**
+     * Dismiss the session's open panel. No-op when none is open.
+     * @param sessionId - the session whose panel to close.
+     */
+    close(sessionId: string): void;
+}
+/** Spec for the node-side slash command that triggers a panel. */
+export interface PanelCommandSpec {
+    /** Command name without the slash; must match the panel command field. */
+    readonly name: string;
+    /** Menu row description. */
+    readonly description: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@elinpf/dsh-ops-panel",
+  "version": "0.1.0",
+  "description": "Panel seam for ops plugins — a slash-command-triggered, session-scoped dialog shell. Provides the ctx.opsPanels client registry (single command/executed dispatcher + overlay shell) and the node-side registerPanelCommand helper. The first consumer is the access-grant panel (ADR-0004).",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "esbuild": "^0.24.0",
+    "jsdom": "^30.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node esbuild.config.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}