dsh-easygit-plugin 0.2.0

package/lib/types/client/index.d.ts

@@ -0,0 +1,34 @@
+import { createPanelController } from './panel-controller';
+import { appendCommandLog, beginTrackedRequest, buildFileTree, cancelTrackedRequest, clampWorkbenchRatio, commitFileTone, deriveCommitGraph, filterLocalBranches, isCurrentCommitRequest, isLatestRequest, isTrackedRequestCurrent, mutationCommand, nextCommitSelection, parseReviewRows, repositoryName, type AnyRecord } from './view-model';
+type RefreshState = 'idle' | 'loading' | 'succeeded' | 'failed';
+declare function injectStyles(): () => void;
+declare function refreshButtonLabel(state: RefreshState): string;
+declare function renderRawDiffSurface(diff: string): any;
+declare function renderReviewSurface(diff: string): any;
+declare const plugin: {
+    inject: string[];
+    apply(ctx: AnyRecord): void;
+    __testing: {
+        createPanelController: typeof createPanelController;
+        buildFileTree: typeof buildFileTree;
+        parseReviewRows: typeof parseReviewRows;
+        renderRawDiffSurface: typeof renderRawDiffSurface;
+        renderReviewSurface: typeof renderReviewSurface;
+        injectStyles: typeof injectStyles;
+        filterLocalBranches: typeof filterLocalBranches;
+        clampWorkbenchRatio: typeof clampWorkbenchRatio;
+        deriveCommitGraph: typeof deriveCommitGraph;
+        repositoryName: typeof repositoryName;
+        mutationCommand: typeof mutationCommand;
+        appendCommandLog: typeof appendCommandLog;
+        refreshButtonLabel: typeof refreshButtonLabel;
+        isCurrentCommitRequest: typeof isCurrentCommitRequest;
+        nextCommitSelection: typeof nextCommitSelection;
+        commitFileTone: typeof commitFileTone;
+        isLatestRequest: typeof isLatestRequest;
+        beginTrackedRequest: typeof beginTrackedRequest;
+        cancelTrackedRequest: typeof cancelTrackedRequest;
+        isTrackedRequestCurrent: typeof isTrackedRequestCurrent;
+    };
+};
+export = plugin;

package/lib/types/client/panel-controller.d.ts

@@ -0,0 +1,38 @@
+export type Dispose = () => void;
+export interface PanelSnapshot {
+    detailsReady: boolean;
+    activeSessionId: string | null;
+    open: boolean;
+    error: string;
+}
+export interface PanelController {
+    attachDetails(): Dispose;
+    open(sessionId: unknown): boolean;
+    close(sessionId?: unknown): boolean;
+    toggle(sessionId: unknown): boolean;
+    isOpen(sessionId: unknown): boolean;
+    subscribe(listener: (state: PanelSnapshot) => void): Dispose;
+    snapshot(): PanelSnapshot;
+}
+interface SlotsLike {
+    register(definition: Record<string, unknown>, renderer: (props: Record<string, unknown>) => unknown): unknown;
+}
+interface LayoutLike {
+    openDetails(): void;
+    closeDetails(): void;
+}
+export interface PanelControllerOptions {
+    slots?: SlotsLike | null;
+    layout?: LayoutLike | null;
+    renderPanel: (props: {
+        sessionId: string;
+        close: Dispose;
+    }) => unknown;
+}
+/**
+ * Mount the workbench only while it is open. Harness's built-in DetailsPanel
+ * uses priority 0, so the workbench temporarily overrides it at -10 and
+ * immediately releases the registration when closed.
+ */
+export declare function createPanelController(options: PanelControllerOptions): PanelController;
+export {};

package/lib/types/client/view-model.d.ts

@@ -0,0 +1,99 @@
+import type { BranchSummary, CommitSummary, RepositoryFile } from '../shared/contracts';
+export type AnyRecord = Record<string, any>;
+export type RepositoryMutationAction = 'stage-paths' | 'unstage-paths' | 'stage-all' | 'unstage-all' | 'commit' | 'create-branch' | 'switch-branch' | 'delete-branch';
+export interface CommandLogEntry {
+    id: number;
+    label: string;
+    command: string;
+    status: 'running' | 'succeeded' | 'failed';
+}
+export interface RequestSlot {
+    controller: AbortController | null;
+    sequence: number;
+}
+export interface TrackedRequest {
+    sequence: number;
+    signal: AbortSignal;
+}
+export interface FileTreeNode {
+    name: string;
+    path: string;
+    folders: FileTreeNode[];
+    files: RepositoryFile[];
+}
+export interface ReviewRow {
+    kind: 'context' | 'added' | 'deleted' | 'skipped' | 'annotation';
+    oldNumber: number | null;
+    newNumber: number | null;
+    text: string;
+}
+export interface CommitGraphEdge {
+    from: number;
+    to: number | null;
+    active: boolean;
+}
+export interface CommitGraphRow {
+    commit: CommitSummary;
+    lane: number;
+    laneCount: number;
+    edges: CommitGraphEdge[];
+}
+export interface HostSplitLayout {
+    frame: HTMLElement;
+    sidebar: HTMLElement;
+    center: HTMLElement;
+    details: HTMLElement;
+}
+export interface ActiveHostSplit {
+    layout: HostSplitLayout;
+    splitColumns: string;
+    previousGridTemplateColumns: string;
+    previousTrack: string;
+    previousDetailsWidth: string;
+    previousDetailsMinWidth: string;
+    previousDetailsMaxWidth: string;
+    previousDetailsBorderLeft: string;
+}
+export interface ResizeDrag {
+    pointerId: number;
+    startX: number;
+    startWidth: number;
+    currentRatio: number;
+}
+export declare const WORKBENCH_RATIO_KEY = "dsh-easygit-plugin:workbench-ratio";
+export declare const WORKBENCH_TRACK = "--dsh-easygit-plugin-workbench-width";
+export declare const WORKBENCH_DEFAULT_RATIO = 0.36;
+export declare const WORKBENCH_MIN_RATIO = 0.24;
+export declare const WORKBENCH_MAX_RATIO = 0.75;
+export declare function appendCommandLog(current: CommandLogEntry[], entry: CommandLogEntry): CommandLogEntry[];
+export declare function filterLocalBranches(branches: BranchSummary[], query: string): BranchSummary[];
+export declare function isCurrentCommitRequest(selectedHash: string, requestedHash: string, currentSequence: number, requestSequence: number): boolean;
+export declare function nextCommitSelection(currentHash: string, requestedHash: string): string;
+export declare function commitFileTone(status: string): string;
+export declare function isLatestRequest(currentSequence: number, requestSequence: number): boolean;
+export declare function beginTrackedRequest(ref: {
+    current: RequestSlot;
+}): TrackedRequest;
+export declare function cancelTrackedRequest(ref: {
+    current: RequestSlot;
+}): void;
+export declare function isTrackedRequestCurrent(ref: {
+    current: RequestSlot;
+}, request: TrackedRequest): boolean;
+export declare function isAbortError(error: unknown): boolean;
+export declare function deriveCommitGraph(commits: CommitSummary[]): CommitGraphRow[];
+export declare function clampWorkbenchRatio(value: number): number;
+export declare function readWorkbenchRatio(): number;
+export declare function persistWorkbenchRatio(value: number | null): void;
+export declare function workbenchTrackForRatio(ratio: number): string;
+export declare function repositoryName(topLevel: unknown): string;
+export declare function mutationCommand(action: string, payload?: AnyRecord): {
+    label: string;
+    command: string;
+} | null;
+export declare function viewportWidth(): number;
+export declare function sidebarTrackWidth(layout: HostSplitLayout): number;
+export declare function findWorkbenchHostSplit(anchor: HTMLElement): HostSplitLayout | null;
+export declare function buildFileTree(files: RepositoryFile[]): FileTreeNode;
+export declare function parseReviewRows(diff: string): ReviewRow[];
+export declare function diffLineClass(line: string): string;

package/lib/types/host/actions.d.ts

@@ -0,0 +1,41 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ProposalView } from '../shared/contracts';
+import { deriveChecks } from './command-policy';
+import type { GitRepositoryService, ShellService } from './git-repository-service';
+import type { StoredProposal } from './proposal-service';
+type UnknownRecord = Record<string, unknown>;
+export interface WebServerService {
+    register(definition: {
+        kind: 'prefix';
+        path: string;
+        handler(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    }): unknown;
+}
+interface ProposalVerification {
+    changed: boolean;
+    verified: boolean;
+    partial: boolean;
+    message: string;
+    changedState: string;
+}
+interface GitGuideActionDependencies {
+    repository: GitRepositoryService;
+    proposalStorageReady: Promise<void>;
+    shell: ShellService | null;
+    repositoryContext(sessionId: string): {
+        workdir: string;
+        policy: unknown;
+    } | null;
+    latestPending(sessionId: string): StoredProposal | null;
+    findProposal(sessionId: string, proposalId: unknown): StoredProposal | undefined;
+    proposalView(proposal: StoredProposal): ProposalView;
+    flushProposal(sessionId: string): Promise<void>;
+    captureFingerprint(shell: ShellService | null, workdir: string): Promise<string | null>;
+    runChecks(shell: ShellService | null, workdir: string, checks: ReturnType<typeof deriveChecks>): Promise<string[]>;
+    verifyProposal(shell: ShellService | null, proposal: StoredProposal): Promise<ProposalVerification>;
+    executeProposal(shell: ShellService | null, proposal: StoredProposal, policy: unknown, persist: () => Promise<void>): Promise<UnknownRecord>;
+    resolveExecutionPolicy(sessionId: string): unknown;
+}
+/** Register the Client-to-Host POST dispatcher with a 1 MiB body limit. */
+export declare function registerGitGuideActions(webServer: WebServerService | null, dependencies: GitGuideActionDependencies): unknown;
+export {};

package/lib/types/host/command-policy.d.ts

@@ -0,0 +1,38 @@
+export type RiskLevel = 'safe' | 'normal' | 'hard';
+export interface ParsedCommand {
+    ok: true;
+    args: string[];
+    subcommand: string;
+    normalized: string;
+}
+export interface InvalidCommand {
+    ok: false;
+    error: string;
+}
+export type ParseResult = ParsedCommand | InvalidCommand;
+export interface RiskAssessment {
+    level: RiskLevel;
+    reasons: string[];
+}
+export interface ModernizedCommand {
+    command: string;
+    changed: boolean;
+}
+export interface ExpectedCheck {
+    type: 'branch' | 'branch-gone' | 'commit-msg' | 'staged' | 'clean' | 'stash-nonempty' | 'stash-empty' | 'no-ahead';
+    value: string | string[] | boolean;
+    label: string;
+}
+export declare const MAX_COMMAND_LENGTH = 800;
+export declare function quoteShellArg(value: unknown): string;
+export declare function parseCommand(command: unknown): ParseResult;
+export declare function validateCommand(command: unknown): ParseResult & {
+    segments?: string[];
+};
+export declare function modernizeCommand(command: unknown): ModernizedCommand;
+export declare function classifyRisk(command: unknown): RiskAssessment;
+export declare function classifyStepsRisk(commands: readonly string[]): RiskAssessment;
+export declare function redactSecrets(value: unknown): string;
+export declare function redactAndLimit(value: unknown, maxChars?: number): string;
+export declare function addPathsOf(command: string): string | null;
+export declare function deriveChecks(commands: readonly string[]): ExpectedCheck[];

package/lib/types/host/git-repository-service.d.ts

@@ -0,0 +1,53 @@
+import type { ActionResult, CommitDetail, CommitDiffResult, CommitSummary, DiffResult, RepositoryReferences, RepositorySummary, StashSummary } from '../shared/contracts';
+export type { BranchSummary, CommitDetail, CommitDiffResult, CommitFileChange, CommitRefSummary, CommitSummary, DiffResult, ReferenceSummary, RepositoryFile, RepositoryReferences, RepositorySummary, StashSummary, } from '../shared/contracts';
+export interface GitRunResult {
+    exitCode: number | null;
+    signal?: string | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    stdout?: {
+        text?: string;
+    };
+    stderr?: {
+        text?: string;
+    };
+}
+export interface ShellService {
+    resolve(request: Record<string, unknown>): unknown;
+    run(specification: unknown): Promise<GitRunResult>;
+}
+interface MutationRequest {
+    sessionId: string;
+    workdir: string;
+    operationId: unknown;
+    signal?: AbortSignal;
+    sandboxPolicy?: unknown;
+}
+export declare class GitRepositoryService {
+    private readonly shell;
+    private readonly locks;
+    private readonly operations;
+    constructor(shell: ShellService | undefined);
+    run(workdir: string, command: string, timeoutMs?: number, stdoutMaxBytes?: number, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<GitRunResult>;
+    getTopLevel(workdir: string, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<{
+        topLevel: string;
+    }>>;
+    getSummary(workdir: string, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<RepositorySummary>>;
+    getDiff(workdir: string, path: unknown, staged: boolean, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<DiffResult>>;
+    getBranches(workdir: string, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<RepositoryReferences>>;
+    getCommits(workdir: string, limit: unknown, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<CommitSummary[]>>;
+    getCommitDetail(workdir: string, hash: unknown, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<CommitDetail>>;
+    getCommitDiff(workdir: string, hash: unknown, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<CommitDiffResult>>;
+    getStashes(workdir: string, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<ActionResult<StashSummary[]>>;
+    stagePaths(request: MutationRequest, paths: unknown): Promise<ActionResult<RepositorySummary>>;
+    unstagePaths(request: MutationRequest, paths: unknown): Promise<ActionResult<RepositorySummary>>;
+    stageAll(request: MutationRequest): Promise<ActionResult<RepositorySummary>>;
+    unstageAll(request: MutationRequest): Promise<ActionResult<RepositorySummary>>;
+    commit(request: MutationRequest, message: unknown): Promise<ActionResult<RepositorySummary>>;
+    createBranch(request: MutationRequest, name: unknown, base: unknown): Promise<ActionResult<RepositorySummary>>;
+    switchBranch(request: MutationRequest, name: unknown): Promise<ActionResult<RepositorySummary>>;
+    deleteBranch(request: MutationRequest, name: unknown, force: boolean, confirmRisk: boolean): Promise<ActionResult<RepositorySummary>>;
+    private validatePaths;
+    private mutate;
+    private pruneOperations;
+}

package/lib/types/host/index.d.ts

@@ -0,0 +1,3 @@
+/** Host entry point. */
+import plugin = require('./plugin');
+export = plugin;

package/lib/types/host/plugin.d.ts

@@ -0,0 +1,109 @@
+/**
+ * dsh-easygit-plugin Host plugin package.
+ *
+ * It is mounted as one profile composition entry and serves every DeepSeek
+ * Harness session. It uses only ctx.tools.register for tools and a
+ * ctx.webServer POST /git-guide route for Client-to-Host actions.
+ *
+ * The exposed model tools are git_propose and git_repo_state. Repository changes
+ * are only available through the Client action route.
+ */
+import { ProposalService, type ProposalView, type StoredProposal } from './proposal-service';
+import { type ShellService } from './git-repository-service';
+import { addPathsOf, classifyRisk, classifyStepsRisk, deriveChecks, modernizeCommand, parseCommand, quoteShellArg, redactAndLimit, redactSecrets, validateCommand, type ExpectedCheck } from './command-policy';
+type UnknownRecord = Record<string, unknown>;
+interface HostContext {
+    get<T = unknown>(name: string): T;
+    inject?(services: string[], callback: (context: HostContext) => unknown): unknown;
+    effect?(callback: () => () => void | Promise<void>): unknown;
+}
+interface ProposalExecutionResult extends UnknownRecord {
+    ok: boolean;
+    proposalId: string;
+    command: string;
+    steps: Array<{
+        command: string;
+        ok: boolean;
+        exitCode: number;
+    }>;
+    exitCode: number;
+    signal: string;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    diagnostics: string;
+    recovery?: {
+        suggestion: string;
+        command: string;
+        proposalId: string | null;
+    } | null;
+    error: string;
+}
+interface ProposalVerification {
+    changed: boolean;
+    verified: boolean;
+    partial: boolean;
+    message: string;
+    changedState: string;
+}
+interface RecoverySuggestion {
+    suggestion: string;
+    command: string | null;
+    proposalId?: string;
+}
+declare function captureFingerprint(shell: ShellService | null | undefined, workdir: string): Promise<string | null>;
+declare function captureDiagnostics(shell: ShellService | null | undefined, workdir: string): Promise<string>;
+declare function runChecks(shell: ShellService | null | undefined, workdir: string, checks: readonly ExpectedCheck[]): Promise<string[]>;
+declare function verifyProposal(shell: ShellService | null | undefined, proposal: StoredProposal): Promise<ProposalVerification>;
+declare function executeProposalSteps(shell: ShellService, proposal: StoredProposal, signal?: AbortSignal, policy?: unknown): Promise<{
+    ok: boolean;
+    stepsResult: Array<{
+        command: string;
+        ok: boolean;
+        exitCode: number;
+    }>;
+}>;
+declare function executeRegisteredProposal(shell: ShellService | null | undefined, proposal: StoredProposal | null | undefined, signal?: AbortSignal, policy?: unknown, persistStatus?: () => Promise<void>): Promise<ProposalExecutionResult>;
+/**
+ * Derive a safe recovery command from a failed step and repository diagnostics.
+ * A null command means the condition requires manual remediation.
+ */
+declare function buildRecovery(_proposal: StoredProposal, failedStep: StoredProposal['steps'][number] | undefined, diagnostics: string): RecoverySuggestion | null;
+/** Register a recovery command as a pending proposal in the same session. */
+declare function registerRecoveryProposal(failedProposal: Pick<StoredProposal, 'sessionId' | 'workdir'>, recovery: RecoverySuggestion): StoredProposal | null;
+declare function storeProposal(sessionId: string, proposal: StoredProposal): StoredProposal;
+declare function findProposal(sessionId: string, proposalId: unknown): StoredProposal | undefined;
+declare function proposalView(proposal: StoredProposal): ProposalView;
+declare function latestPending(sessionId: string): StoredProposal | null;
+declare const _default: {
+    name: string;
+    inject: string[];
+    apply(ctx: HostContext): void;
+} & {
+    helpers: {
+        parseCommand: typeof parseCommand;
+        validateCommand: typeof validateCommand;
+        modernizeCommand: typeof modernizeCommand;
+        classifyRisk: typeof classifyRisk;
+        classifyStepsRisk: typeof classifyStepsRisk;
+        quoteShellArg: typeof quoteShellArg;
+        redactSecrets: typeof redactSecrets;
+        redactAndLimit: typeof redactAndLimit;
+        addPathsOf: typeof addPathsOf;
+        deriveChecks: typeof deriveChecks;
+        runChecks: typeof runChecks;
+        verifyProposal: typeof verifyProposal;
+        captureFingerprint: typeof captureFingerprint;
+        captureDiagnostics: typeof captureDiagnostics;
+        executeProposalSteps: typeof executeProposalSteps;
+        executeRegisteredProposal: typeof executeRegisteredProposal;
+        buildRecovery: typeof buildRecovery;
+        registerRecoveryProposal: typeof registerRecoveryProposal;
+        storeProposal: typeof storeProposal;
+        findProposal: typeof findProposal;
+        proposalView: typeof proposalView;
+        latestPending: typeof latestPending;
+        ProposalService: typeof ProposalService;
+    };
+};
+export = _default;

package/lib/types/host/proposal-service.d.ts

@@ -0,0 +1,60 @@
+import type { ProposalStatus, ProposalView } from '../shared/contracts';
+export type { ProposalView } from '../shared/contracts';
+import type { RiskLevel } from './command-policy';
+export interface ProposalStep {
+    command: string;
+    result: Record<string, unknown> | null;
+}
+export interface StoredProposal {
+    proposalId: string;
+    sessionId: string;
+    intent: string;
+    command: string;
+    steps: ProposalStep[];
+    explanation: string;
+    risk: RiskLevel;
+    reasons: string[];
+    confirmed: boolean;
+    workdir: string;
+    createdAt: number;
+    status: ProposalStatus;
+    closed: boolean;
+    copied: boolean;
+    fingerprint: string | null;
+    verified: boolean;
+    result: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+export interface ProposalStorageUnit {
+    loadAll(): Promise<{
+        tables: Record<string, Record<string, unknown>>;
+        global: unknown;
+    }>;
+    putRecord(table: string, key: string, value: unknown): Promise<void>;
+    deleteRecord(table: string, key: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class ProposalService {
+    private readonly proposalsPerSession;
+    private readonly maxSessions;
+    private readonly sessionTtlMs;
+    private readonly proposalsBySession;
+    private storage;
+    private storageTail;
+    constructor(proposalsPerSession?: number, maxSessions?: number, sessionTtlMs?: number);
+    attachStorage(storage: ProposalStorageUnit): Promise<void>;
+    closeStorage(storage: ProposalStorageUnit): Promise<void>;
+    flush(sessionId: string): Promise<void>;
+    newId(): string;
+    list(sessionId: string): StoredProposal[] | undefined;
+    hasRunning(sessionId: string): boolean;
+    closeOpen(sessionId: string): void;
+    store(sessionId: string, proposal: StoredProposal): StoredProposal;
+    prune(now?: number): void;
+    private pruneMap;
+    private readStoredEntries;
+    find(sessionId: string, proposalId: unknown): StoredProposal | undefined;
+    latestPending(sessionId: string): StoredProposal | null;
+    view(proposal: StoredProposal): ProposalView;
+}
+export declare const proposalService: ProposalService;