pi-extensions-tool-display 0.1.1

package/README.md

@@ -0,0 +1,32 @@
+# pi-extensions-tool-display
+
+`pi-extensions-tool-display` provides the shared tool-result rendering protocol and component helpers used by Pi extensions.
+
+It provides:
+
+- registration, disposal, and activity checks for result-render middleware;
+- a pending registration queue for when the Pi display host loads later;
+- safe component detection and a helper for appending an audit panel to the original tool result.
+
+It is not a standalone Pi extension: it registers no tools, commands, or entry renderers. It is intended to be consumed as a runtime dependency by extensions such as `pi-distill` and `pi-tool-supervisor`.
+
+## Boundary
+
+This package owns the display protocol and generic component composition only. Each feature extension continues to own its domain-specific audit extraction, copy, status, and layout.
+
+## Upstream attribution
+
+The display integration is designed to work with the MIT-licensed [`MasuRii/pi-tool-display`](https://github.com/MasuRii/pi-tool-display), the original full-featured Pi tool-display project. We thank MasuRii for that work.
+
+This package is a separate shared-runtime extraction from this repository's own extension bridges. It does not bundle or redistribute `pi-tool-display`'s implementation; the upstream project remains the reference for full tool rendering.
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+```
+
+## License
+
+[MIT](../../LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,32 @@
+# pi-extensions-tool-display
+
+`pi-extensions-tool-display` 是 Pi 扩展共享的工具结果展示协议和组件工具包。
+
+它提供：
+
+- 结果渲染 middleware 的注册、注销和状态判断；
+- Pi 展示宿主尚未加载时的 pending 注册队列；
+- 安全识别组件，以及把审计面板追加到原始工具结果后的通用组件组合。
+
+它不是一个独立的 Pi 扩展，不注册工具、命令或 entry renderer。通常由 `pi-distill`、`pi-tool-supervisor` 等扩展作为运行时依赖使用。
+
+## 设计边界
+
+这个包只负责展示协议和通用组件组合。具体业务的审计数据提取、文案、状态和布局仍由调用方维护，避免把不同扩展耦合在一起。
+
+## 上游引用
+
+本包的展示集成设计用于兼容 MIT 许可的 [`MasuRii/pi-tool-display`](https://github.com/MasuRii/pi-tool-display)，这是 Pi 生态中原始的完整工具展示项目。感谢 MasuRii 的工作。
+
+本包是从本仓库自身的扩展 bridge 中提取出的独立共享运行时，不打包或再发布 `pi-tool-display` 的实现；完整工具渲染仍以上游项目为参考实现。
+
+## 开发
+
+```bash
+npm test
+npm run typecheck
+```
+
+## 许可证
+
+[MIT](../../LICENSE)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-extensions-tool-display",
+  "version": "0.1.1",
+  "description": "Shared result-rendering protocol and component helpers for Pi extensions",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README.zh-CN.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/tool-display.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "maplezzk",
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-extensions-tool-display",
+  "bugs": "https://github.com/maplezzk/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-extensions-tool-display"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "coding-agent",
+    "tool-display"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-tui": ">=0.80.0 <0.81.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-tui": "0.80.10",
+    "@types/node": "24.12.4",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+import { Container, type Component } from "@earendil-works/pi-tui";
+
+export const TOOL_DISPLAY_API_KEY = Symbol.for("pi-tool-display.api.v1");
+export const PENDING_MIDDLEWARES_KEY = Symbol.for("pi-tool-display.pendingResultRenderMiddlewares.v1");
+
+export type RenderTheme = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+};
+
+export type ResultMiddlewareContext = {
+  toolName: string;
+  result: unknown;
+  options: { expanded?: boolean };
+  theme: RenderTheme;
+};
+
+export type ResultMiddleware = (
+  context: ResultMiddlewareContext,
+  next: () => unknown,
+) => unknown;
+
+export type MiddlewareRegistration = {
+  id: string;
+  toolName: string;
+  middleware: ResultMiddleware;
+};
+
+export type ToolDisplayApi = {
+  registerResultRenderMiddleware?(registration: MiddlewareRegistration): string;
+  unregisterResultRenderMiddleware?(id: string): boolean;
+  hasResultRenderMiddleware?(id: string): boolean;
+  isResultRenderPipelineActive?(toolName: string): boolean;
+};
+
+type GlobalProtocol = typeof globalThis & {
+  [TOOL_DISPLAY_API_KEY]?: ToolDisplayApi;
+  [PENDING_MIDDLEWARES_KEY]?: MiddlewareRegistration[];
+};
+
+function getApi(): ToolDisplayApi | undefined {
+  return (globalThis as GlobalProtocol)[TOOL_DISPLAY_API_KEY];
+}
+
+function queueRegistration(registration: MiddlewareRegistration): void {
+  const globalProtocol = globalThis as GlobalProtocol;
+  const queue = Array.isArray(globalProtocol[PENDING_MIDDLEWARES_KEY])
+    ? globalProtocol[PENDING_MIDDLEWARES_KEY]!
+    : [];
+  const index = queue.findIndex((entry) => entry?.id === registration.id);
+  if (index >= 0) queue[index] = registration;
+  else queue.push(registration);
+  globalProtocol[PENDING_MIDDLEWARES_KEY] = queue;
+}
+
+function removeQueuedRegistration(id: string): void {
+  const queue = (globalThis as GlobalProtocol)[PENDING_MIDDLEWARES_KEY];
+  if (!Array.isArray(queue)) return;
+  const index = queue.findIndex((entry) => entry?.id === id);
+  if (index >= 0) queue.splice(index, 1);
+}
+
+export function registerResultRenderMiddleware(
+  registration: MiddlewareRegistration,
+): () => void {
+  const api = getApi();
+  if (typeof api?.registerResultRenderMiddleware === "function") {
+    api.registerResultRenderMiddleware(registration);
+  } else {
+    queueRegistration(registration);
+  }
+
+  return () => {
+    getApi()?.unregisterResultRenderMiddleware?.(registration.id);
+    removeQueuedRegistration(registration.id);
+  };
+}
+
+export function isResultRenderMiddlewareActive(id: string, toolName: string): boolean {
+  const api = getApi();
+  return api?.hasResultRenderMiddleware?.(id) === true
+    && api.isResultRenderPipelineActive?.(toolName) === true;
+}
+
+export function asComponent(value: unknown): Component | undefined {
+  return value && typeof value === "object" && typeof (value as Component).render === "function"
+    ? value as Component
+    : undefined;
+}
+
+export function appendResultRenderPanel(baseValue: unknown, panel: Component): Component {
+  const base = asComponent(baseValue);
+  if (!base) return panel;
+  const container = new Container();
+  container.addChild(base);
+  container.addChild(panel);
+  return container;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}