dsh-git-ui 0.0.1 → 0.1.0

package/lib/host/actions.d.ts

@@ -0,0 +1,34 @@
+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
+ * UI never waits for the next poll).
+ */
+export declare function runAction(deps: SnapshotDeps, config: GitStatusConfig, request: GitActionRequest): Promise<GitActionResult>;

package/lib/host/core.d.ts

@@ -40,6 +40,30 @@ export interface SnapshotDeps {
 export declare const DEFAULT_CONFIG: GitStatusConfig;
 /** Coerce a raw patch config value into a validated GitStatusConfig. */
 export declare function normalizeConfig(raw: unknown): GitStatusConfig;
+/** Run one command, mapping a spawn-level failure to a snapshot failure. */
+export declare function runCommand(runner: GitRunner, argv: readonly string[], cwd: string, label: string, signal?: AbortSignal): Promise<{
+    readonly run: Awaited<ReturnType<GitRunner['run']>>;
+} | {
+    readonly failure: Extract<GitSnapshotResult, {
+        ok: false;
+    }>['error'];
+}>;
+/**
+ * Resolve a session's repository workspace: cwd (live or persisted), the
+ * realpath'd directory, and the git work-tree root via `rev-parse
+ * --show-toplevel`. Shared by the snapshot flow and the operation runner.
+ */
+export type WorkspaceResolution = {
+    readonly ok: true;
+    readonly cwd: string;
+    readonly root: string;
+} | {
+    readonly ok: false;
+    readonly error: Extract<GitSnapshotResult, {
+        ok: false;
+    }>['error'];
+};
+export declare function resolveWorkspace(deps: SnapshotDeps, sessionId: string): Promise<WorkspaceResolution>;
 /**
  * Build one frozen GitSnapshot for a session working directory.
  * Command sequence (all read-only; every command after the first runs with
@@ -47,7 +71,13 @@ export declare function normalizeConfig(raw: unknown): GitStatusConfig;
  *   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,23 +1,30 @@
 /**
  * dsh-git-ui host half: the `gitInfo` Remote service.
  *
- * Cordis shell only — every behavior lives in `core.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` through SRC
+ * 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).
  */
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { Context } from '@deepseek-ai/cordis';
-import type { GitSnapshotRequest, GitSnapshotResult } from './types.ts';
-export type { GitSnapshot, GitSnapshotResult, GitSnapshotFailure, GitSnapshotRequest, GitCommit, GitChange } from './types.ts';
+import type { GitActionResult, GitActionRequest, 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';
-/** The `gitInfo` service: one `snapshot` Remote endpoint. */
+export { parseStatusOutput, parseLogOutput, parseBranchOutput, parseNameStatusOutput } from './parser.ts';
+export { isSafePath, isValidBranchName, runAction } from './actions.ts';
+export { runQuery } from './queries.ts';
+/** The `gitInfo` service: `snapshot` (read) and `run` (management) endpoints. */
 export declare class GitStatusService extends TypertRemoteService {
     static inject: string[];
     private readonly config;
     constructor(ctx: Context, config: unknown);
+    /** Adapter face shared by both endpoints (injected services + runner). */
+    private deps;
     snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult>;
+    run(request: GitActionRequest, signal?: AbortSignal): Promise<GitActionResult>;
+    query(request: GitQueryRequest, signal?: AbortSignal): Promise<GitQueryResponse>;
 }
 export default GitStatusService;