dsh-git-ui 0.1.0 → 0.1.2

package/src/contracts/host-endpoints.ts

@@ -0,0 +1,58 @@
+/**
+ * Host 端点契约：纯业务逻辑，零框架依赖。
+ *
+ * 将 `snapshotForSession` / `runAction` / `runQuery` 聚合为统一的
+ * `HostEndpoints` 接口——宿主适配层（Cordis/typert 或其他框架）只需调用
+ * `createHostEndpoints(deps, config)` 即可获得全部端点方法，再以任何
+ * RPC 机制暴露。业务层对此一无所知。
+ */
+import { snapshotForSession, type GitStatusConfig, type SnapshotDeps } from '../host/core.ts'
+import { runAction } from '../host/actions.ts'
+import { runQuery } from '../host/queries.ts'
+import type { GitActionRequest, GitActionResult, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+
+/**
+ * 业务端点集合：三个 RPC 方法的纯函数实现。
+ * 每个方法接收 wire 请求、可选取消信号，返回 wire 响应。
+ */
+export interface HostEndpoints {
+  snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult>
+  run(request: GitActionRequest, signal?: AbortSignal): Promise<GitActionResult>
+  query(request: GitQueryRequest, signal?: AbortSignal): Promise<GitQueryResponse>
+}
+
+/**
+ * 构造业务端点实例。
+ *
+ * `deps` 携带全部宿主能力（子进程、会话查找、文件系统）；`config` 携带
+ * 运行参数。两者均为结构化接口，与任何框架无关。返回的端点对象可直接
+ * 绑定到 RPC 装饰器、HTTP 路由、或测试桩。
+ */
+export function createHostEndpoints(deps: SnapshotDeps, config: GitStatusConfig): HostEndpoints {
+  return {
+    snapshot(request, signal) {
+      // 合并调用方信号与 deps 自带信号（deps.signal 来自 Cordis Remote 的
+      // 取消槽；此处 signal 来自适配层传入——两者取并集，任一触发即中止）。
+      const merged = mergeSignals(deps.signal, signal)
+      const effectiveDeps = merged === deps.signal ? deps : { ...deps, signal: merged }
+      return snapshotForSession(effectiveDeps, config, request.sessionId)
+    },
+    run(request, signal) {
+      const merged = mergeSignals(deps.signal, signal)
+      const effectiveDeps = merged === deps.signal ? deps : { ...deps, signal: merged }
+      return runAction(effectiveDeps, config, request)
+    },
+    query(request, signal) {
+      const merged = mergeSignals(deps.signal, signal)
+      const effectiveDeps = merged === deps.signal ? deps : { ...deps, signal: merged }
+      return runQuery(effectiveDeps, config, request)
+    },
+  }
+}
+
+/** 合并两个可选信号：任一 undefined 取另一个，均存在则 AbortSignal.any。 */
+function mergeSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined {
+  if (a === undefined) return b
+  if (b === undefined) return a
+  return AbortSignal.any([a, b])
+}

package/src/contracts/plugin-activation.ts

@@ -0,0 +1,129 @@
+/**
+ * 插件激活逻辑：纯业务编排，零框架依赖。
+ *
+ * 接收 `ClientPlatform` 接口和插件依赖，完成：
+ *   1. 注册国际化字典
+ *   2. 挂载 Remote 并获取 gitInfo 服务
+ *   3. 注册 header utility slot
+ *   4. 订阅连接重置事件
+ *
+ * 适配层（如 `adapters/dsh/client-adapter.ts`）负责将宿主 API 翻译为
+ * `ClientPlatform`，然后调用本函数。业务层对宿主一无所知。
+ */
+import type { ClientPlatform, SlotEntryDescriptor, GitInjected, GitRemoteLike } from './client-platform.ts'
+import type { RemoteContribution } from './client-platform.ts'
+import type { LocaleDicts } from './client-platform.ts'
+import type { GitAction } from '../host/types.ts'
+import type { GitQueryRequest, GitActionResult } from '../host/types.ts'
+import type { GitQueryOutcome } from './client-platform.ts'
+
+/** Slot 名称常量。 */
+const HEADER_UTILITIES_SLOT = 'conversation.session.header.utilities'
+
+/** 本插件的 slot 条目 ID。 */
+const SLOT_ENTRY_ID = 'git'
+
+/** 国际化命名空间。 */
+const LOCALE_NS = 'git'
+
+/** 控制器接口：插件激活逻辑依赖的控制器能力。 */
+export interface ControllerLike {
+  subscribe(listener: () => void): () => void
+  getSnapshot(): import('./client-platform.ts').GitView
+  refresh(): Promise<void>
+  resync(): void
+  run(action: GitAction): Promise<GitActionResult>
+  query(query: GitQueryRequest['query']): Promise<GitQueryOutcome>
+  dispose(): void
+}
+
+/** 插件依赖：由调用方提供的具体实现。 */
+export interface PluginDependencies {
+  /** Remote 贡献配置 */
+  remoteContribution: RemoteContribution
+  /** 国际化字典 */
+  locales: LocaleDicts
+  /** 控制器构造函数 */
+  createController: (remote: GitRemoteLike, sessionId: string) => ControllerLike
+}
+
+/**
+ * 激活插件。
+ *
+ * @param platform 宿主平台能力
+ * @param deps 插件依赖（由调用方提供）
+ * @param component 要注册的 UI 组件（已包裹 UI 基础组件上下文）
+ */
+export async function activatePlugin(
+  platform: ClientPlatform,
+  deps: PluginDependencies,
+  component: unknown,
+): Promise<void> {
+  // 1. 注册国际化字典
+  platform.effect(
+    () => platform.registerLocale(LOCALE_NS, deps.locales),
+    'dsh-git-ui: dictionaries',
+  )
+
+  // 2. 挂载 Remote 并获取 gitInfo 服务
+  const gitInfoService = await platform.mountRemoteAndGetService(deps.remoteContribution, 'gitInfo')
+
+  // 3. 控制器缓存（按 sessionId）
+  const controllers = new Map<string, ControllerLike>()
+  const faces = new Map<string, GitInjected>()
+
+  const controllerFor = (sessionId: string): ControllerLike => {
+    let controller = controllers.get(sessionId)
+    if (controller === undefined) {
+      controller = deps.createController(gitInfoService, sessionId)
+      controllers.set(sessionId, controller)
+    }
+    return controller
+  }
+
+  // 4. 注册 slot 条目
+  const slotOptions: SlotEntryDescriptor = {
+    name: HEADER_UTILITIES_SLOT,
+    id: SLOT_ENTRY_ID,
+    order: 10,
+    locale: LOCALE_NS,
+    inject: (sessionId): GitInjected => {
+      // Per-session stable face: the slot runtime may re-invoke the
+      // inject factory on every render, and components depend on the
+      // `refresh` reference staying stable (a fresh arrow function per
+      // call would re-run mount effects and loop: refresh → view
+      // change → re-render → new refresh → refresh …). Cache the face
+      // so the same controller (and its bound refresh/run) is always
+      // handed out per session.
+      let face = faces.get(sessionId)
+      if (face === undefined) {
+        const controller = controllerFor(sessionId)
+        face = {
+          hooks: { git: controller as GitInjected['hooks']['git'] },
+          refresh: () => controller.refresh(),
+          run: (action) => controller.run(action),
+          query: (query) => controller.query(query),
+        }
+        faces.set(sessionId, face)
+      }
+      return face
+    },
+  }
+
+  const disposeSlot = platform.registerSlotEntry(slotOptions, component)
+
+  // 5. 注册清理：释放 slot 并销毁全部控制器
+  platform.effect(() => {
+    return () => {
+      disposeSlot()
+      for (const controller of controllers.values()) controller.dispose()
+      controllers.clear()
+      faces.clear()
+    }
+  }, 'dsh-git-ui: slot and controller lifecycle')
+
+  // 6. 订阅连接重置事件：重连后刷新全部控制器
+  platform.onEvent('connection/reset', () => {
+    for (const controller of controllers.values()) controller.resync()
+  })
+}

package/src/contracts/ui-context.tsx

@@ -0,0 +1,28 @@
+/**
+ * UI 基础组件 React Context：业务组件通过 `useUI()` 获取实现，
+ * 适配层在插件激活时通过 `<UIPrimitivesProvider>` 注入宿主组件。
+ *
+ * 设计要点：
+ *   - 默认值为 null——若未提供则 `useUI()` 抛出明确错误，而非静默渲染空组件。
+ *   - Provider 在插件入口（client/index.ts）包裹整棵组件树。
+ *   - 测试可直接用 Provider 注入 mock 组件，无需模拟宿主环境。
+ */
+import { createContext, useContext } from 'react'
+import type { ReactNode } from 'react'
+import type { UIPrimitives } from './ui-primitives.ts'
+
+const UIPrimitivesContext = createContext<UIPrimitives | null>(null)
+
+/** 消费 UI 基础组件。必须在 `<UIPrimitivesProvider>` 内使用。 */
+export function useUI(): UIPrimitives {
+  const value = useContext(UIPrimitivesContext)
+  if (value === null) {
+    throw new Error('useUI(): missing <UIPrimitivesProvider> — 插件入口未注入 UI 基础组件')
+  }
+  return value
+}
+
+/** 注入 UI 基础组件实现。在插件入口包裹整棵组件树。 */
+export function UIPrimitivesProvider({ value, children }: { value: UIPrimitives; children?: ReactNode }): ReactNode {
+  return <UIPrimitivesContext.Provider value={value}>{children}</UIPrimitivesContext.Provider>
+}

package/src/contracts/ui-primitives.ts

@@ -0,0 +1,48 @@
+/**
+ * UI 基础组件契约：业务层只依赖此接口，不直接 import 任何宿主 UI 库。
+ *
+ * 属性集取「实际使用的最小并集」——GitPill / GitCenter 用到的全部 props
+ * 均已覆盖；宿主适配层可提供更丰富的实现，但业务代码保证只消费此处的
+ * 声明。未来 dsh 升级导致 Modal/Button/Toast 变更时，只需更新适配层，
+ * 业务组件零改动。
+ */
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+
+/** 受控全屏对话框：遮罩 + Escape 关闭。 */
+export interface ModalProps {
+  readonly open: boolean
+  readonly onClose: () => void
+  readonly title: string
+  readonly closeLabel?: string
+  readonly description?: string
+  readonly children?: ReactNode
+  readonly footer?: ReactNode
+  readonly className?: string
+  readonly contentClassName?: string
+  /** 隐藏默认标题栏（自定义头部时使用）。 */
+  readonly headless?: boolean
+}
+
+/** 令牌化按钮原子。原生 button 属性透传。 */
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  readonly variant?: 'primary' | 'ghost' | 'outline' | 'toolbar'
+  readonly size?: 'md' | 'sm'
+  readonly icon?: ReactNode
+  readonly className?: string | undefined
+  readonly children?: ReactNode
+}
+
+/** 瞬时顶部提示条：自动消失后调用 onDone 通知父级卸载。 */
+export interface ToastProps {
+  readonly text: string
+  readonly icon?: ReactNode
+  readonly anchor?: HTMLElement | null
+  readonly onDone: () => void
+}
+
+/** 三个基础组件的聚合：适配层一次性提供整套实现。 */
+export interface UIPrimitives {
+  readonly Modal: (props: ModalProps) => ReactNode
+  readonly Button: (props: ButtonProps) => ReactNode
+  readonly Toast: (props: ToastProps) => ReactNode
+}

package/src/host/index.ts

@@ -1,107 +1,102 @@
 /**
- * dsh-git-ui host half: the `gitInfo` Remote service.
+ * dsh-git-ui host 适配层：Cordis/typert 壳。
  *
- * Cordis shell only — every behavior lives in `core.ts`/`actions.ts`/
- * `queries.ts` behind injected structural faces, so tests never need a
- * cordis runtime. The class is a plugin in its own right (class form),
- * mounted by the bundle patch row with the package name; the gateway exposes
- * `gitInfo/snapshot`, `gitInfo/run` and `gitInfo/query` through SRC
- * discovery (`typertRemote` binding + `@Remote` marker).
+ * 本文件是 host 端**唯一** import `@deepseek-ai/*` 的地方。职责：
+ *   1. 将 Cordis 服务（subprocess / sessions / sessionPersistence）适配为
+ *      结构化 `SnapshotDeps` 接口；
+ *   2. 调用 `createHostEndpoints(deps, config)` 获得纯业务端点；
+ *   3. 以 `@Remote` 装饰器将端点暴露给 typert Gateway。
+ *
+ * 业务逻辑全部在 `contracts/host-endpoints.ts` → `host/core.ts` /
+ * `host/actions.ts` / `host/queries.ts`，与框架无关。
  */
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import type { Context } from '@deepseek-ai/cordis'
 import { realpath, stat } from 'node:fs/promises'
 import { createGitRunner, type SubprocessLike } from './git.ts'
-import { normalizeConfig, snapshotForSession, type GitStatusConfig, type SnapshotDeps } from './core.ts'
-import { runAction } from './actions.ts'
-import { runQuery } from './queries.ts'
-import type { GitActionResult, GitActionRequest, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult } from './types.ts'
+import { normalizeConfig, type GitStatusConfig, type SnapshotDeps } from './core.ts'
+import { createHostEndpoints, type HostEndpoints } from '../contracts/host-endpoints.ts'
+import type { GitActionRequest, GitActionResult, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult } from './types.ts'
 
 export type { GitSnapshot, GitSnapshotResult, GitSnapshotFailure, GitSnapshotRequest, GitCommit, GitChange, GitAction, GitActionResult, GitActionRequest, GitQuery, GitQueryResult, GitQueryRequest, GitQueryResponse, GitBranch, GitFileStat, GitRef } from './types.ts'
 export { normalizeConfig, DEFAULT_CONFIG } from './core.ts'
 export { parseStatusOutput, parseLogOutput, parseBranchOutput, parseNameStatusOutput } from './parser.ts'
 export { isSafePath, isValidBranchName, runAction } from './actions.ts'
 export { runQuery } from './queries.ts'
+export { createHostEndpoints, type HostEndpoints } from '../contracts/host-endpoints.ts'
 
-/** Structural face of a live session header. */
-interface SessionLike {
-  readonly header?: { readonly cwd?: string }
-}
-
-/** Structural face of the sessions service. */
+/** Cordis sessions 服务的结构化切片。 */
 interface SessionsLike {
-  get(id: string): SessionLike | undefined
+  get(id: string): { readonly header?: { readonly cwd?: string } } | undefined
 }
 
-/** Structural face of the session-persistence service. */
+/** Cordis sessionPersistence 服务的结构化切片。 */
 interface SessionPersistenceLike {
   inspect(id: string): Promise<{ readonly meta: { readonly cwd?: string } }>
 }
 
-/** The `gitInfo` service: `snapshot` (read) and `run` (management) endpoints. */
+/**
+ * gitInfo Remote 服务：Cordis 壳。
+ *
+ * 构造时从 Cordis Context 取出宿主服务，适配为 `SnapshotDeps`，再调用
+ * `createHostEndpoints` 获得纯业务端点。三个 `@Remote` 方法仅做委托。
+ */
 export class GitStatusService extends TypertRemoteService {
   static inject = ['subprocess', 'sessions', 'sessionPersistence']
 
-  private readonly config: GitStatusConfig
+  private readonly endpoints: HostEndpoints
 
   constructor(ctx: Context, config: unknown) {
     super(ctx, 'gitInfo')
-    this.config = normalizeConfig(config)
+    const normalizedConfig = normalizeConfig(config)
+    const deps = this.buildDeps(ctx, normalizedConfig)
+    this.endpoints = createHostEndpoints(deps, normalizedConfig)
   }
 
-  /** Adapter face shared by both endpoints (injected services + runner). */
-  private deps(signal?: AbortSignal): { readonly deps: SnapshotDeps } | { readonly failure: { readonly code: 'git-unavailable'; readonly detail: string } } {
-    const subprocess = this.ctx.get('subprocess') as SubprocessLike | undefined
+  /** 将 Cordis 服务适配为结构化 SnapshotDeps。 */
+  private buildDeps(ctx: Context, config: GitStatusConfig): SnapshotDeps {
+    const subprocess = ctx.get('subprocess') as SubprocessLike | undefined
     if (subprocess === undefined) {
-      return { failure: { code: 'git-unavailable', detail: 'subprocess service unavailable' } }
+      // 返回一个永远失败的 deps——端点调用会走到 git-unavailable 降级路径。
+      return {
+        run: { run: async () => { throw new Error('subprocess service unavailable') } },
+        fs: { realpath, stat },
+        sessions: { liveCwd: () => undefined, persistedMeta: async () => undefined },
+      }
     }
-    const sessions = this.ctx.get('sessions') as SessionsLike | undefined
-    const persistence = this.ctx.get('sessionPersistence') as SessionPersistenceLike | undefined
-    const runner = createGitRunner(subprocess, this.config.timeoutMs, this.config.maxStatusBytes)
+    const sessions = ctx.get('sessions') as SessionsLike | undefined
+    const persistence = ctx.get('sessionPersistence') as SessionPersistenceLike | undefined
     return {
-      deps: {
-        run: runner,
-        fs: { realpath, stat },
-        sessions: {
-          liveCwd: (id) => sessions?.get(id)?.header?.cwd,
-          persistedMeta: async (id) => {
-            if (persistence === undefined) return undefined
-            try {
-              const inspection = await persistence.inspect(id)
-              return { cwd: inspection.meta.cwd }
-            } catch {
-              return undefined
-            }
-          },
+      run: createGitRunner(subprocess, config.timeoutMs, config.maxStatusBytes),
+      fs: { realpath, stat },
+      sessions: {
+        liveCwd: (id) => sessions?.get(id)?.header?.cwd,
+        persistedMeta: async (id) => {
+          if (persistence === undefined) return undefined
+          try {
+            const inspection = await persistence.inspect(id)
+            return { cwd: inspection.meta.cwd }
+          } catch {
+            return undefined
+          }
         },
-        signal,
       },
     }
   }
 
   @Remote('snapshot')
   async snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult> {
-    const adapted = this.deps(signal)
-    if ('failure' in adapted) return { ok: false, error: adapted.failure }
-    return snapshotForSession(adapted.deps, this.config, request.sessionId)
+    return this.endpoints.snapshot(request, signal)
   }
 
   @Remote('run')
   async run(request: GitActionRequest, signal?: AbortSignal): Promise<GitActionResult> {
-    const adapted = this.deps(signal)
-    if ('failure' in adapted) {
-      return { ok: false, error: { code: 'git-error', message: adapted.failure.detail } }
-    }
-    return runAction(adapted.deps, this.config, request)
+    return this.endpoints.run(request, signal)
   }
 
   @Remote('query')
   async query(request: GitQueryRequest, signal?: AbortSignal): Promise<GitQueryResponse> {
-    const adapted = this.deps(signal)
-    if ('failure' in adapted) {
-      return { ok: false, error: { code: 'git-error', message: adapted.failure.detail } }
-    }
-    return runQuery(adapted.deps, this.config, request)
+    return this.endpoints.query(request, signal)
   }
 }