@xbzbing/dsh-git-panel 0.1.0

package/lib/host/actions.d.ts

@@ -0,0 +1,16 @@
+import type { SnapshotDeps, GitPanelConfig } from './core.ts';
+import type { GitAction, GitActionRequest, GitActionResult, GitErrorCode } from './types.ts';
+/** A repository-relative path is safe when it stays inside the work tree. */
+export declare function isSafePath(path: string): boolean;
+interface CommandPlan {
+    readonly argv: readonly (readonly string[])[];
+}
+type PlanResult = CommandPlan | {
+    readonly error: GitErrorCode;
+    readonly message?: string;
+};
+/** Build the git command sequence for an action. */
+export declare function planAction(action: GitAction, unborn: boolean): PlanResult;
+/** Execute a management action, returning the fresh snapshot on success. */
+export declare function runAction(deps: SnapshotDeps, config: GitPanelConfig, request: GitActionRequest): Promise<GitActionResult>;
+export {};

package/lib/host/core.d.ts

@@ -0,0 +1,69 @@
+import type { GitRunner } from './git.ts';
+import type { GitChange, GitSnapshotResult } from './types.ts';
+export interface GitPanelConfig {
+    readonly timeoutMs: number;
+    /** Per-command stdout cap; also the per-side image-diff payload cap. */
+    readonly maxBytes: number;
+    readonly maxChanges: number;
+    readonly refreshIntervalMs: number;
+    /** Whether the input-bar git marker pill is shown. */
+    readonly showInputPill: boolean;
+}
+export declare const DEFAULT_CONFIG: GitPanelConfig;
+export declare function normalizeConfig(raw: unknown): GitPanelConfig;
+/**
+ * Read a boolean config field, unwrapping a schemastery volatile reference
+ * (`{ get() }`) so a live-editable toggle reflects the latest value. Absent or
+ * unrecognized shapes fall back to the default.
+ */
+export declare function readBool(value: unknown, fallback: boolean): boolean;
+/** Host capabilities the snapshot needs, structurally injected. */
+export interface SnapshotDeps {
+    readonly run: GitRunner;
+    readonly fs: {
+        realpath(path: string): Promise<string>;
+        stat(path: string): Promise<{
+            mtimeMs: number;
+            size: number;
+        }>;
+        /** Raw bytes (no encoding) — image sides for the image-diff query. */
+        readFile(path: string): Promise<Buffer>;
+        /** Best-effort unlink (force) — temp-blob cleanup. */
+        remove(path: string): Promise<void>;
+    };
+    readonly sessions: {
+        liveCwd(sessionId: string): string | undefined;
+        persistedMeta(sessionId: string): Promise<{
+            cwd?: string;
+        } | undefined>;
+    };
+    readonly signal?: AbortSignal;
+    /**
+     * Optional cwd→root cache, keyed by the resolved cwd. Resolving the work-tree
+     * root runs a `git rev-parse` + `realpath` on every call; sharing this map
+     * across a session's snapshot/query/run calls collapses that to one spawn per
+     * distinct cwd (a session's cwd is effectively stable).
+     */
+    readonly rootCache?: Map<string, string>;
+}
+export type WorkspaceResolution = {
+    readonly ok: true;
+    readonly root: string;
+} | {
+    readonly ok: false;
+    readonly failure: GitSnapshotResult & {
+        ok: false;
+    };
+};
+/** Resolve the git work-tree root for a session's cwd. */
+export declare function resolveWorkspace(deps: SnapshotDeps, sessionId: string): Promise<WorkspaceResolution>;
+/** Run one git command; a spawn-level failure returns { failure }. */
+export declare function runCommand(runner: GitRunner, argv: readonly string[], cwd: string, _label: string, signal?: AbortSignal): Promise<{
+    run: Awaited<ReturnType<GitRunner['run']>>;
+} | {
+    failure: unknown;
+}>;
+/** Produce a full snapshot for a session. */
+export declare function snapshotForSession(deps: SnapshotDeps, config: GitPanelConfig, sessionId: string): Promise<GitSnapshotResult>;
+/** Max mtime among changed files (epoch ms), capped for large sets. */
+export declare function maxChangeMtime(deps: SnapshotDeps, root: string, changes: readonly GitChange[], cap?: number): Promise<number | null>;

package/lib/host/git.d.ts

@@ -0,0 +1,62 @@
+interface CollectDisposition {
+    readonly collect: {
+        readonly maxBytes: number;
+        readonly spill?: {
+            readonly maxBytes: number;
+        };
+    };
+}
+interface SpawnSpec {
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly stdio: {
+        readonly stdin: 'ignore';
+        readonly stdout: CollectDisposition;
+        readonly stderr: CollectDisposition;
+    };
+    readonly graceMs: number;
+    readonly signal?: AbortSignal;
+}
+interface OutputRead {
+    readonly text: string;
+    readonly lossy: boolean;
+    readonly spillPath?: string;
+}
+interface SpawnHandle {
+    readonly done: Promise<{
+        readonly exitCode: number | null;
+        readonly signal: NodeJS.Signals | null;
+    }>;
+    readonly collected: {
+        readonly stdout?: {
+            readFrom(fromByte: number): OutputRead;
+        };
+        readonly stderr?: {
+            readFrom(fromByte: number): OutputRead;
+        };
+    };
+}
+/** Minimal subprocess service face the adapter consumes. */
+export interface SubprocessLike {
+    spawn(spec: SpawnSpec): SpawnHandle;
+}
+export interface GitRunResult {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    readonly stdoutLossy: boolean;
+}
+export interface GitRunner {
+    run(argv: readonly string[], opts: {
+        readonly cwd: string;
+        readonly signal?: AbortSignal;
+    }): Promise<GitRunResult>;
+}
+/**
+ * Adapt the subprocess service into a `GitRunner` with a per-command timeout.
+ * A timed-out run resolves (never rejects) with `timedOut: true`; only
+ * spawn-level failures (e.g. git not installed) reject.
+ */
+export declare function createGitRunner(subprocess: SubprocessLike, timeoutMs: number, maxBytes: number): GitRunner;
+export {};

package/lib/host/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * dsh-git-panel host half: Cordis + typert Remote service.
+ *
+ * `GitPanelService` binds the `gitPanel` namespace and exposes three @Remote
+ * endpoints (snapshot / run / query) that delegate to the framework-neutral
+ * command layer. Host services (subprocess / sessions / sessionPersistence)
+ * are adapted into a structural `SnapshotDeps` face.
+ */
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { GitActionRequest, GitActionResult, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult, GitVersionInfo, GitVersionRequest } from './types.ts';
+export type { GitSnapshot, GitSnapshotResult, GitSnapshotRequest, GitFailure, GitCommit, GraphCommit, GitRef, GitChange, GitChangeStatus, GitAction, GitActionRequest, GitActionResult, GitErrorCode, GitQuery, GitQueryRequest, GitQueryResponse, GitQueryResult, GitBranch, GitFileStat, WorktreeStats, GitVersionRequest, GitVersionInfo, } from './types.ts';
+export { normalizeConfig, DEFAULT_CONFIG, snapshotForSession, resolveWorkspace } from './core.ts';
+export { createGitRunner } from './git.ts';
+export { parseStatus, parseGraphLog, parseBranches, parseNameStatus, sumNumstat } from './parser.ts';
+export { isSafePath, planAction, runAction } from './actions.ts';
+export { runQuery } from './queries.ts';
+export { readVersionInfo, checkLatestVersion, compareVersions, parseRepository } from './version.ts';
+export declare class GitPanelService extends TypertRemoteService {
+    static inject: string[];
+    /**
+     * Config schema surfaced on the plugin detail page. Only `showInputPill` is
+     * `.volatile()`, so the settings host renders it as a live-editable toggle;
+     * the operational limits stay profile-only and out of the UI form.
+     */
+    static Config: Schema<Schemastery.ObjectS<NoInfer<{
+        showInputPill: Schema<boolean, boolean, "volatile-defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        showInputPill: Schema<boolean, boolean, "volatile-defined">;
+    }>>, "plain">;
+    private readonly deps;
+    private config;
+    private readonly rawConfig;
+    constructor(ctx: Context, config: unknown);
+    private buildDeps;
+    snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult>;
+    run(request: GitActionRequest, signal?: AbortSignal): Promise<GitActionResult>;
+    query(request: GitQueryRequest, signal?: AbortSignal): Promise<GitQueryResponse>;
+    version(request: GitVersionRequest): Promise<GitVersionInfo>;
+    /** Re-read config so a live-edited volatile field (showInputPill) is current. */
+    private liveConfig;
+    private withSignal;
+}
+export default GitPanelService;