dsh-git-ui 0.0.2 → 0.1.1

package/lib/contracts/host-endpoints.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Host 端点契约：纯业务逻辑，零框架依赖。
+ *
+ * 将 `snapshotForSession` / `runAction` / `runQuery` 聚合为统一的
+ * `HostEndpoints` 接口——宿主适配层（Cordis/typert 或其他框架）只需调用
+ * `createHostEndpoints(deps, config)` 即可获得全部端点方法，再以任何
+ * RPC 机制暴露。业务层对此一无所知。
+ */
+import { type GitStatusConfig, type SnapshotDeps } from '../host/core.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 declare function createHostEndpoints(deps: SnapshotDeps, config: GitStatusConfig): HostEndpoints;

package/lib/host/actions.d.ts

@@ -1,11 +1,31 @@
-import { type GitStatusConfig, type SnapshotDeps } from './core.ts';
-import type { GitActionResult, GitActionRequest } from './types.ts';
+import { resolveWorkspace, type GitStatusConfig, type SnapshotDeps } from './core.ts';
+import type { GitAction, GitActionResult, GitActionRequest, GitOperationErrorCode } from './types.ts';
+/**
+ * A branch name is valid when it matches git's ref-name grammar at the level
+ * we care about: non-empty, ASCII ref chars only, no leading `-` (option
+ * injection guard, though argv never shells out), no `..` (path traversal of
+ * refs), no trailing `/`, and no double slashes.
+ */
+export declare function isValidBranchName(name: string): boolean;
 /**
  * A path is safe when it is repo-relative and stays inside the work tree:
  * reject absolute paths, drive letters / backslashes, and `..` escapes
  * (checked via path resolution against the realpath'd root).
  */
 export declare function isSafePath(path: string, root: string): boolean;
+/** Map a snapshot-flow failure (which may carry git-unavailable) onto the operation error shape. */
+export declare function operationError(failure: Extract<Awaited<ReturnType<typeof resolveWorkspace>>, {
+    ok: false;
+}>['error']): GitActionResult & {
+    ok: false;
+};
+/**
+ * 把 git 命令失败归类为可预期的业务错误（其余保持 git-error）。
+ * 切分支被工作区未提交变更阻止是最常见的可预期失败：git 输出
+ * "would be overwritten by checkout"（或中文本地化 "将被 checkout 覆盖"），
+ * 归一化为 local-changes-block，client 据此给友好提示 + 处理变更引导。
+ */
+export declare function classifyOperationError(kind: GitAction['kind'], message: string): GitOperationErrorCode;
 /**
  * Execute one management action against the session's repository and return
  * the refreshed snapshot on success (the caller re-renders from it, so the

package/lib/host/core.d.ts

@@ -71,7 +71,13 @@ export declare function resolveWorkspace(deps: SnapshotDeps, sessionId: string):
  *   1. `git rev-parse --show-toplevel`      — repo detection (exit 128 → not-a-git-repo)
  *   2. `git branch --show-current`          — null when detached
  *   3. `git rev-parse --short HEAD`         — null + unborn when the repo has no commits
- *   4. `git status --porcelain=v1 -z --branch`
+ *   4. `git status --porcelain=v1 -z --branch --untracked-files=all`
  *   5. `git log -n 5 --format=%H%x1f%h%x1f%s%x1f%an%x1f%aI`
+ *
+ * --untracked-files=all：git 默认 normal 模式会把整目录未跟踪折叠为单条
+ * `?? dir/`（尾斜杠）且不枚举其内部文件——隐藏目录（.agent/.tianqi 等）的
+ * 变更因此从不进入变更清单。`all` 强制逐文件枚举（与 IDEA / VSCode 一致），
+ * 内部文件得以展示；maxChanges 截断列表、maxStatusBytes spill 保计数精确，
+ * 超大未跟踪树（如未 gitignore 的构建产物）经此路径优雅降级。
  */
 export declare function snapshotForSession(deps: SnapshotDeps, config: GitStatusConfig, sessionId: string): Promise<GitSnapshotResult>;

package/lib/host/index.d.ts

@@ -1,28 +1,38 @@
 /**
- * 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` 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` and
- * `gitInfo/run` 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 { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { Context } from '@deepseek-ai/cordis';
-import type { GitActionResult, GitActionRequest, GitSnapshotRequest, GitSnapshotResult } from './types.ts';
-export type { GitSnapshot, GitSnapshotResult, GitSnapshotFailure, GitSnapshotRequest, GitCommit, GitChange, GitAction, GitActionResult, GitActionRequest } from './types.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 } from './parser.ts';
-export { isSafePath, runAction } from './actions.ts';
-/** The `gitInfo` service: `snapshot` (read) and `run` (management) endpoints. */
+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';
+/**
+ * gitInfo Remote 服务：Cordis 壳。
+ *
+ * 构造时从 Cordis Context 取出宿主服务，适配为 `SnapshotDeps`，再调用
+ * `createHostEndpoints` 获得纯业务端点。三个 `@Remote` 方法仅做委托。
+ */
 export declare class GitStatusService extends TypertRemoteService {
     static inject: string[];
-    private readonly config;
+    private readonly endpoints;
     constructor(ctx: Context, config: unknown);
-    /** Adapter face shared by both endpoints (injected services + runner). */
-    private deps;
+    /** 将 Cordis 服务适配为结构化 SnapshotDeps。 */
+    private buildDeps;
     snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult>;
     run(request: GitActionRequest, signal?: AbortSignal): Promise<GitActionResult>;
+    query(request: GitQueryRequest, signal?: AbortSignal): Promise<GitQueryResponse>;
 }
 export default GitStatusService;