dsh-git-ui 0.0.2 → 0.1.1

package/src/adapters/dsh/client-adapter.ts

@@ -0,0 +1,120 @@
+/**
+ * dsh Client 平台适配：将 Cordis Context 翻译为 `ClientPlatform` 接口。
+ *
+ * 本文件是 client 端**唯一**知道 Cordis / typert 插件生命周期的地方。
+ * dsh 升级导致插件 API 变更时，只需修改此文件。
+ *
+ * 关键适配点：
+ *   - `mountRemoteAndGetService`：处理 typert Remote 挂载 + Cordis child fiber
+ *   - `registerSlotEntry`：翻译 slot 注册两步模式（inject + register）
+ *   - `onEvent` / `effect`：直接映射 Cordis 同名方法
+ */
+import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol'
+import type { ReactNode } from 'react'
+import type { ClientPlatform, LocaleDicts, RemoteContribution, SlotEntryDescriptor, GitInjected, GitRemoteLike } from '../../contracts/client-platform.ts'
+
+/**
+ * Cordis Context 的结构化切片。
+ *
+ * 只声明本适配器实际使用的属性和方法。dsh 升级时若 API 变更，
+ * 只需更新此接口和下方的适配实现。
+ */
+export interface DshClientContext {
+  /** 订阅应用事件（自动在 fiber 卸载时清理）。 */
+  on(event: string, listener: (...args: never[]) => void): (() => void) | void
+  /** 注册副作用（自动在 fiber 卸载时清理）。 */
+  effect(callback: () => void | (() => void | Promise<void>), label?: string): void
+  /** Remote 服务：挂载贡献 + 访问已挂载的命名空间。 */
+  remote: {
+    $mount(contribution: TypertRemoteContribution): Promise<() => Promise<void>>
+    gitInfo: GitRemoteLike
+  }
+  /** Slot 注册表。 */
+  slots: {
+    inject(slotName: string, provider: () => (() => void) | void): void
+    register(
+      options: {
+        readonly name: string
+        readonly id: string
+        readonly order?: number
+        readonly locale?: string
+        readonly inject: (sessionId: string) => GitInjected
+      },
+      component: unknown,
+    ): () => void
+  }
+  /** 国际化服务。 */
+  locale: {
+    register(namespace: string, dictionaries: LocaleDicts): void
+  }
+}
+
+/**
+ * 将我们的 `RemoteContribution` 转换为 dsh 的 `TypertRemoteContribution`。
+ *
+ * 当前两者结构相同（字段一一对应），直接透传。若未来 typert 协议变更，
+ * 在此处做字段映射。
+ */
+function toTypertContribution(ours: RemoteContribution): TypertRemoteContribution {
+  return ours as TypertRemoteContribution
+}
+
+/**
+ * 将 Cordis Context 适配为 `ClientPlatform`。
+ *
+ * 注意：`mountRemoteAndGetService` 的实现利用了 Cordis 的特性——
+ * 挂载完成后，`ctx.remote.gitInfo` 立即可用。无需 child fiber 模式
+ * （该模式是 Cordis 内部为避免 inject 死锁的优化，此处我们在 mount
+ * 完成后直接访问，效果等价）。
+ */
+export function adaptDshClientContext(ctx: DshClientContext): ClientPlatform {
+  return {
+    registerLocale(namespace, dicts) {
+      ctx.locale.register(namespace, dicts)
+    },
+
+    async mountRemoteAndGetService(contribution, namespace) {
+      // 挂载 Remote 贡献
+      await ctx.remote.$mount(toTypertContribution(contribution))
+      // 挂载完成后，命名空间服务立即可用
+      // 当前只有 'gitInfo' 命名空间，直接返回
+      if (namespace === 'gitInfo') {
+        return ctx.remote.gitInfo
+      }
+      throw new Error(`adaptDshClientContext: 未知命名空间 "${namespace}"`)
+    },
+
+    registerSlotEntry(options, component) {
+      // Cordis slot 注册是两步模式：inject + register
+      // inject 注册一个 provider 工厂，register 在 provider 内调用
+      let disposeRegister: (() => void) | undefined
+      ctx.slots.inject(options.name, () => {
+        disposeRegister = ctx.slots.register(
+          {
+            name: options.name,
+            id: options.id,
+            order: options.order,
+            locale: options.locale,
+            inject: options.inject,
+          },
+          component,
+        )
+        return () => {
+          disposeRegister?.()
+        }
+      })
+      // 返回释放函数：调用时注销 slot 条目
+      return () => {
+        disposeRegister?.()
+      }
+    },
+
+    onEvent(event, listener) {
+      return ctx.on(event, listener as (...args: never[]) => void)
+    },
+
+    effect(callback, label) {
+      ctx.effect(callback, label)
+    },
+  }
+}

package/src/adapters/dsh/types/cordis.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Type shim for `@deepseek-ai/cordis`.
+ *
+ * The npm ecosystem does not carry the full dsh package chain (`@deepseek-ai/cordis`
+ * depends on unpublished packages), so this package cannot install cordis as a
+ * dev dependency. At runtime the host dsh installation provides the real cordis
+ * through peer dependency resolution; this file only supplies the compile-time
+ * surface used by dsh-git-ui (shapes copied from the deepseek-harness vendor
+ * tree, 0.1.0-rc.x). Keep this file in sync with the subset actually used.
+ */
+declare module '@deepseek-ai/cordis' {
+  /** Minimal Context surface used by host/client halves. */
+  export interface Context {
+    readonly root: Context
+    /** Service registry reflection (service list for gateway SRC discovery). */
+    readonly reflect: {
+      readonly props: Record<string, { type?: string; [key: string]: unknown }>
+      provide(name: string, value: unknown, check?: unknown): void
+    }
+    /** Look up an optional service by key (undefined when not provided). */
+    get<T = unknown>(key: string): T | undefined
+    /** Declare services this plugin needs before activation. */
+    inject(keys: readonly string[], callback: (ctx: Context) => void): void
+    /** Register a side effect with auto-cleanup on fiber dispose. */
+    effect(callback: () => void | (() => void | Promise<void>), label?: string): void
+    /** Subscribe to an application event; returns an unsubscribe function. */
+    on<K extends string>(event: K, listener: (...args: never[]) => void): (() => void) | void
+    /** Start a plugin fiber in the current context. */
+    plugin(plugin: unknown, config?: unknown): Promise<unknown> & { dispose(): Promise<void> }
+    [key: string]: unknown
+  }
+
+  /** Base class for services that expose a named API on `ctx`. */
+  export abstract class Service<out T = never> {
+    static readonly init: unique symbol
+    static readonly check: unique symbol
+    static readonly config: unique symbol
+    static readonly invoke: unique symbol
+    static readonly extend: unique symbol
+    static readonly tracker: unique symbol
+    static readonly resolveConfig: unique symbol
+    /** The service name this instance is registered under. */
+    public name!: string
+    /** Owning context (registered via `super(ctx, name)`). */
+    readonly ctx: Context
+    constructor(ctx: Context, name: string)
+  }
+}

package/src/adapters/dsh/types/typert-protocol.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Type shim for `@deepseek-ai/dsh-typert-protocol`.
+ *
+ * Same rationale as `cordis.d.ts`: the runtime implementation is provided by the
+ * host dsh installation (peer dependency); this file supplies the compile-time
+ * surface used by dsh-git-ui (shapes copied from the deepseek-harness
+ * `packages/typert/protocol` source, 0.1.0-rc.x).
+ */
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  import type { Context, Service } from '@deepseek-ai/cordis'
+
+  /** Visible declaration that one Service participates in Typert Gateway export. */
+  export interface TypertGatewayBinding<ServiceT extends object = object> {
+    readonly service: ServiceT
+    readonly serviceKey: string
+    readonly namespace: string
+  }
+
+  /** Cordis Service base that exposes its registered name through Typert Gateway. */
+  export abstract class TypertRemoteService<out T = never> extends Service<T> {
+    /** Visible binding consumed by the Gateway's source-mode discovery. */
+    readonly typertRemote: TypertGatewayBinding<this>
+    protected constructor(ctx: Context, serviceKey: string, options?: { namespace?: string })
+  }
+
+  /** Standard method decorator marking a Remote endpoint. */
+  export type RemoteMethodDecorator = <This extends object, Args extends unknown[], Result>(
+    method: (this: This, ...args: Args) => Result,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+  ) => void
+
+  /** Mark one public instance method as a direct Remote invocation. */
+  export function Remote(exportName: string): RemoteMethodDecorator
+
+  /** Read Remote markers attached to a live Service by decorator initializers. */
+  export function remoteMethods(service: object): readonly {
+    readonly method: string
+    readonly exportName?: string
+    readonly invocation: { readonly kind: 'direct' } | { readonly kind: 'context'; readonly context: string }
+  }[]
+
+  /** One codec for a Remote parameter/result (strict = zod-validated). */
+  export interface TypertCodec {
+    readonly mode: 'strict'
+    readonly typeSymbol: string
+    readonly schema: { parse(value: unknown): unknown }
+  }
+
+  /** One Remote method descriptor inside a contribution. */
+  export interface InvocationDescriptor {
+    readonly id: string
+    readonly service: string
+    readonly namespace: string
+    readonly method: string
+    readonly invocation: { readonly kind: 'direct' } | { readonly kind: 'context'; readonly context: string; readonly wire: string }
+    readonly parameters: readonly {
+      readonly name: string
+      readonly wire: string
+      readonly source: 'json'
+      readonly codec: TypertCodec
+    }[]
+    /**
+     * Optional caller-supplied cancellation slot: the descriptor carries an
+     * AbortSignal in the trailing business position, propagated over the
+     * carrier so an aborted call also aborts the host-side work.
+     */
+    readonly cancellation?: { readonly parameter: 'signal' }
+    readonly result: TypertCodec
+  }
+
+  /** Client-side contribution mounted via `ctx.remote.$mount`. */
+  export interface TypertRemoteContribution {
+    readonly package: string
+    readonly descriptors: readonly InvocationDescriptor[]
+  }
+
+  /** The `remote` service face mounted by the api-gateway client half. */
+  export interface TypertClientRemote {
+    $mount(contribution: TypertRemoteContribution): Promise<() => Promise<void>>
+  }
+}

package/src/adapters/dsh/types/ui-primitives.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Type shim for `@deepseek-ai/dsh-client-ui-primitives`.
+ *
+ * Platform module (externalized in the client bundle, provided by the host
+ * loader table); this package only needs the `Modal` dialog, the `Button`
+ * atom and the transient `Toast` banner, so the surface is declared here by
+ * hand (mirrored from the ui-primitives source, 0.1.0-rc.x).
+ */
+declare module '@deepseek-ai/dsh-client-ui-primitives' {
+  import type { ButtonHTMLAttributes, ReactNode } from 'react'
+
+  /** Controlled full-viewport dialog over a blurred mask (Escape/mask close). */
+  export function Modal(props: {
+    open: boolean
+    onClose: () => void
+    title: string
+    closeLabel?: string
+    description?: string
+    children?: ReactNode
+    footer?: ReactNode
+    className?: string
+    contentClassName?: string
+    headless?: boolean
+  }): ReactNode
+
+  /** Token-styled button atom (native button attributes pass through). */
+  export function Button(props: {
+    variant?: 'primary' | 'ghost' | 'outline' | 'toolbar'
+    size?: 'md' | 'sm'
+    icon?: ReactNode
+    className?: string | undefined
+    children?: ReactNode
+  } & ButtonHTMLAttributes<HTMLButtonElement>): ReactNode
+
+  /**
+   * Transient top-center banner: slides in, holds ~3s, fades out, then calls
+   * `onDone` so the owner can unmount it.
+   */
+  export function Toast(props: {
+    text: string
+    icon?: ReactNode
+    anchor?: HTMLElement | null
+    onDone: () => void
+  }): ReactNode
+}

package/src/adapters/dsh/ui-primitives.ts

@@ -0,0 +1,16 @@
+/**
+ * dsh UI 基础组件适配：将 `@deepseek-ai/dsh-client-ui-primitives` 的
+ * Modal / Button / Toast 包装为我们的 `UIPrimitives` 接口。
+ *
+ * 本文件是 client 端**唯一** import `@deepseek-ai/dsh-client-ui-primitives`
+ * 的地方。dsh 升级导致组件 API 变更时，只需修改此文件。
+ */
+import { Modal as DshModal, Button as DshButton, Toast as DshToast } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { UIPrimitives } from '../../contracts/ui-primitives.ts'
+
+/** dsh 宿主提供的 UI 基础组件实现。 */
+export const dshUIPrimitives: UIPrimitives = {
+  Modal: DshModal,
+  Button: DshButton,
+  Toast: DshToast,
+}