dsh-git-branch-manage 1.0.2 → 1.0.4

package/lib/routes.d.ts

@@ -4,7 +4,7 @@
  */
 import { type CopyFilesSeams } from './copy-files.js';
 import { type DirExists, type ExcludeSeams, type Exec } from './git.js';
-import type { CreateBranchResult, CreateWorktreeResult, EnsureDirectoryResult, FetchResult, GroupWorkspacesResult, InspectWorktreeResult, PathExistsResult, PurgeDirectoryResult, RemoveWorktreeResult, RepoStatus, RouteError, SwitchResult, UpdateResult, WorktreesAllResult } from './wire.js';
+import type { AiCommitMessageResult, ChangesResult, CommitFilesResult, CommitResult, CreateBranchResult, CreateWorktreeResult, EnsureDirectoryResult, FetchResult, GroupWorkspacesResult, InspectWorktreeResult, LogResult, PathExistsResult, PurgeDirectoryResult, RemoveWorktreeResult, RepoStatus, RouteError, StageResult, SwitchResult, UpdateResult, WorktreesAllResult } from './wire.js';
 /** Everything the handlers need from the host half. */
 export interface RouteDeps {
     exec: Exec;
@@ -46,7 +46,7 @@ export declare function fsMkdirRecursive(path: string): Promise<void>;
 /** One route outcome: HTTP status plus the JSON body. */
 export interface RouteOutcome {
     status: number;
-    body: RepoStatus | CreateWorktreeResult | SwitchResult | CreateBranchResult | FetchResult | UpdateResult | GroupWorkspacesResult | InspectWorktreeResult | RemoveWorktreeResult | PathExistsResult | EnsureDirectoryResult | WorktreesAllResult | PurgeDirectoryResult | RouteError;
+    body: RepoStatus | CreateWorktreeResult | SwitchResult | CreateBranchResult | FetchResult | UpdateResult | GroupWorkspacesResult | InspectWorktreeResult | RemoveWorktreeResult | PathExistsResult | EnsureDirectoryResult | WorktreesAllResult | PurgeDirectoryResult | ChangesResult | StageResult | CommitResult | LogResult | CommitFilesResult | AiCommitMessageResult | RouteError;
 }
 /**
  * POST /group — git belonging facts for a batch of workspace directories.
@@ -120,7 +120,12 @@ export declare function handleStatus(deps: RouteDeps, path: string | undefined):
  */
 export declare function handleCreateWorktree(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
 /**
- * POST /switch 鈥?in-place branch switch of the main checkout.
+ * POST /switch — in-place branch switch of the QUERIED directory's own
+ * checkout. A main-checkout session switches the main checkout; a linked
+ * worktree session switches ITS worktree. (It used to always run in the
+ * main checkout: a worktree session's checkout appeared to succeed while its
+ * own branch never moved. git itself refuses a branch another worktree
+ * holds — an honest error beats moving a checkout nobody was looking at.)
  * @param deps - host dependencies.
  * @param body - parsed request body.
  */
@@ -229,3 +234,86 @@ export declare function handlePathExists(deps: RouteDeps, body: unknown): Promis
  * @param body - parsed request body: `{ path }`.
  */
 export declare function handleEnsureDirectory(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/** Upper bound on the rows one /changes answer lists; a busier working tree
+ * is flagged `truncated` instead of flooding the panel. */
+export declare const CHANGES_ROWS_LIMIT = 500;
+/**
+ * POST /changes — the queried checkout's working-tree rows (staged,
+ * unstaged, untracked), straight from `git status --porcelain=v1 -z`,
+ * capped at {@link CHANGES_ROWS_LIMIT} rows (`truncated` flags the cut).
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath }`.
+ */
+export declare function handleChanges(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * POST /stage — stage (`git add`) or unstage (`git reset -q HEAD --`) the
+ * given relative paths of the queried checkout. Paths must be relative,
+ * `..`-free, and bounded ({@link STAGE_PATHS_LIMIT}); they are passed to git
+ * as execFile arguments, never through a shell.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, paths, stage }`.
+ */
+export declare function handleStage(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/** Upper bound for one commit message (characters): the shared wire constant,
+ * so the client's input cap and this rejection can never drift apart. */
+/**
+ * POST /commit — commit the queried checkout's index (`git commit -m`).
+ * Hooks run as usual; an empty index is git's own refusal, surfaced verbatim.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, message }`.
+ */
+export declare function handleCommit(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/** Default and maximum page size of POST /log. */
+export declare const LOG_LIMIT_DEFAULT = 50;
+export declare const LOG_LIMIT_MAX = 200;
+/**
+ * POST /log — one page of the queried checkout's history. The optional `ref`
+ * is verified server-side (`rev-parse --verify`), an unborn checkout answers
+ * an empty page, and everything else surfaces git's own stderr.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, limit?, skip?, ref? }`.
+ */
+export declare function handleLog(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * POST /commit-files — the files one commit of the queried checkout changed.
+ * The hash is verified server-side; unknown revisions answer 400.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, hash }`.
+ */
+export declare function handleCommitFiles(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/** Narrow face of the host llm runtime the AI route needs. The service is
+ * registered by the dsh-llm host plugin; the panel mounts this route only
+ * where that injection resolves. Message content is the model-facing BLOCK
+ * list (a plain string is rejected), and visible text arrives only as
+ * `text-delta` chunks (reasoning deltas carry text too and must not fold). */
+export interface LlmStreamRuntime {
+    stream(options: {
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+        messages: ReadonlyArray<{
+            role: 'user';
+            content: ReadonlyArray<{
+                type: 'text';
+                text: string;
+            }>;
+        }>;
+        system?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): AsyncIterable<{
+        type: string;
+        text?: string;
+    }>;
+}
+/**
+ * POST /ai-commit-message — generate a commit message from the checkout's
+ * diff with ONE one-shot llm call. The model route (provider/model/effort)
+ * arrives from the requesting session's own selection, so the generation uses
+ * the model the user is already talking to; the diff is truncated and the
+ * reply folded to plain text.
+ * @param deps - host dependencies.
+ * @param llm - the resolved llm runtime (the route is mounted only with one).
+ * @param body - parsed request body: `{ repoPath, provider, model, effort?, hint? }`.
+ */
+export declare function handleAiCommitMessage(deps: RouteDeps, llm: LlmStreamRuntime, body: unknown): Promise<RouteOutcome>;

package/lib/routes.js

@@ -5,9 +5,10 @@
 import { basename, dirname, join, resolve } from 'node:path';
 import { mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { runPostCreateCopy } from './copy-files.js';
-import { appendWorktreeExclude, fsExcludeSeams, GitError, addWorktree, addWorktreeCutout, createBranch, cutoutBranchName, deleteBranch, fetchAll, fsDirExists, inspectWorktree, isAbsoluteDir, probeRepo, probeWorkspaceGit, removeWorktree, renameBranch, resolveBranch, pushBranch, switchBranch, updateBranch } from './git.js';
+import { appendWorktreeExclude, fsExcludeSeams, GitError, addWorktree, addWorktreeCutout, collectAiDiff, commitFiles, commitIndex, createBranch, cutoutBranchName, deleteBranch, fetchAll, fsDirExists, inspectWorktree, isAbsoluteDir, isStageablePath, logHistory, probeRepo, probeWorkspaceGit, removeWorktree, renameBranch, resolveBranch, pushBranch, stagePaths, switchBranch, updateBranch, workingChanges } from './git.js';
 import { isAbsoluteConfigPath, sanitizeBranchDir } from './normalize.js';
 import { resolveRootDir } from './settings.js';
+import { COMMIT_MESSAGE_LIMIT } from './wire.js';
 /** Real fs-backed one-level directory listing (names only). Plain FILES are
  * filtered out — the storage root can carry strays (a legacy settings.json
  * was seen in the wild), and the scan lists worktree SLOTS, not entries. */
@@ -321,18 +322,19 @@ export async function handleStatus(deps, path) {
             main: facts.main,
             currentBranch: facts.currentBranch,
             branches: facts.branches,
+            remoteBranches: facts.remoteBranches,
             worktrees: facts.worktrees,
             rootDir,
         },
     };
 }
 /** Validate a JSON body object with exactly the expected keys. */
-function readBody(body, keys, booleanKeys = [], optionalKeys = []) {
+function readBody(body, keys, booleanKeys = [], optionalKeys = [], numberKeys = []) {
     if (typeof body !== 'object' || body === null || Array.isArray(body))
         return fail(400, 'request body must be a JSON object');
     const record = body;
     for (const key of Object.keys(record)) {
-        if (!keys.includes(key) && !booleanKeys.includes(key) && !optionalKeys.includes(key)) {
+        if (!keys.includes(key) && !booleanKeys.includes(key) && !optionalKeys.includes(key) && !numberKeys.includes(key)) {
             return fail(400, `unknown body key "${key}"`);
         }
     }
@@ -352,6 +354,12 @@ function readBody(body, keys, booleanKeys = [], optionalKeys = []) {
             return fail(400, `body key "${key}" must be a string`);
         }
     }
+    for (const key of numberKeys) {
+        // Optional number: absent stays absent (`limit?: number`), present must type-check.
+        if (record[key] !== undefined && typeof record[key] !== 'number') {
+            return fail(400, `body key "${key}" must be a number`);
+        }
+    }
     return record;
 }
 /** Discriminator: a RouteOutcome carries the `status`/`body` pair no request body has. */
@@ -463,7 +471,12 @@ export async function handleCreateWorktree(deps, body) {
     }
 }
 /**
- * POST /switch 鈥?in-place branch switch of the main checkout.
+ * POST /switch — in-place branch switch of the QUERIED directory's own
+ * checkout. A main-checkout session switches the main checkout; a linked
+ * worktree session switches ITS worktree. (It used to always run in the
+ * main checkout: a worktree session's checkout appeared to succeed while its
+ * own branch never moved. git itself refuses a branch another worktree
+ * holds — an honest error beats moving a checkout nobody was looking at.)
  * @param deps - host dependencies.
  * @param body - parsed request body.
  */
@@ -480,7 +493,7 @@ export async function handleSwitch(deps, body) {
         const facts = await probeRepo(deps.exec, repoPath, deps.dirExists);
         if (facts === undefined)
             return fail(400, `"${repoPath}" is not inside a git repository`);
-        const switched = await switchBranch(deps.exec, facts.repoRoot, branch);
+        const switched = await switchBranch(deps.exec, facts.toplevel, branch);
         const result = { branch: switched };
         return { status: 200, body: result };
     }
@@ -862,3 +875,241 @@ export async function handleEnsureDirectory(deps, body) {
         return fail(500, error instanceof Error ? error.message : String(error));
     }
 }
+/* ------------------------------------------------------------------ *
+ * Git panel routes: working tree, staging, commit, history, AI message.
+ * All of them act on the QUERIED checkout (repoPath = any directory inside
+ * it), so a linked-worktree session reads and mutates its own worktree.
+ * ------------------------------------------------------------------ */
+/** Upper bound on paths one /stage request accepts. */
+const STAGE_PATHS_LIMIT = 500;
+/** Upper bound on the rows one /changes answer lists; a busier working tree
+ * is flagged `truncated` instead of flooding the panel. */
+export const CHANGES_ROWS_LIMIT = 500;
+/** Common validation: `{ repoPath }`-shaped bodies and their checkout directory. */
+function readRepoPath(parsed) {
+    if (isOutcome(parsed))
+        return parsed;
+    if (!isAbsoluteDir(parsed.repoPath))
+        return fail(400, '"repoPath" must be an absolute directory');
+    return parsed.repoPath;
+}
+/** Map a git failure on the queried checkout to the uniform 400 envelope. */
+function checkoutFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return fail(400, message);
+}
+/**
+ * POST /changes — the queried checkout's working-tree rows (staged,
+ * unstaged, untracked), straight from `git status --porcelain=v1 -z`,
+ * capped at {@link CHANGES_ROWS_LIMIT} rows (`truncated` flags the cut).
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath }`.
+ */
+export async function handleChanges(deps, body) {
+    const parsed = readBody(body, ['repoPath']);
+    if (isOutcome(parsed))
+        return parsed;
+    const repoPath = readRepoPath(parsed);
+    if (typeof repoPath !== 'string')
+        return repoPath;
+    try {
+        const { changes } = await workingChanges(deps.exec, repoPath);
+        if (changes.length > CHANGES_ROWS_LIMIT) {
+            return { status: 200, body: { changes: changes.slice(0, CHANGES_ROWS_LIMIT), truncated: true } };
+        }
+        return { status: 200, body: { changes } };
+    }
+    catch (error) {
+        return checkoutFailure(error);
+    }
+}
+/**
+ * POST /stage — stage (`git add`) or unstage (`git reset -q HEAD --`) the
+ * given relative paths of the queried checkout. Paths must be relative,
+ * `..`-free, and bounded ({@link STAGE_PATHS_LIMIT}); they are passed to git
+ * as execFile arguments, never through a shell.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, paths, stage }`.
+ */
+export async function handleStage(deps, body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return fail(400, 'request body must be a JSON object');
+    const record = body;
+    for (const key of Object.keys(record)) {
+        if (key !== 'repoPath' && key !== 'paths' && key !== 'stage')
+            return fail(400, `unknown body key "${key}"`);
+    }
+    const repoPathRaw = record.repoPath;
+    if (typeof repoPathRaw !== 'string' || !isAbsoluteDir(repoPathRaw))
+        return fail(400, '"repoPath" must be an absolute directory');
+    if (record.stage !== true && record.stage !== false)
+        return fail(400, 'body key "stage" must be a boolean');
+    const paths = record.paths;
+    if (!Array.isArray(paths) || !paths.every(item => typeof item === 'string')) {
+        return fail(400, 'body key "paths" must be an array of relative paths');
+    }
+    if (paths.length === 0)
+        return fail(400, 'body key "paths" must not be empty');
+    if (paths.length > STAGE_PATHS_LIMIT)
+        return fail(400, `body key "paths" accepts at most ${String(STAGE_PATHS_LIMIT)} paths`);
+    const bad = paths.find(path => !isStageablePath(path));
+    if (bad !== undefined)
+        return fail(400, `"${bad}" is not a stageable relative path`);
+    try {
+        await stagePaths(deps.exec, repoPathRaw, paths, record.stage);
+        return { status: 200, body: { staged: true } };
+    }
+    catch (error) {
+        return checkoutFailure(error);
+    }
+}
+/** Upper bound for one commit message (characters): the shared wire constant,
+ * so the client's input cap and this rejection can never drift apart. */
+/**
+ * POST /commit — commit the queried checkout's index (`git commit -m`).
+ * Hooks run as usual; an empty index is git's own refusal, surfaced verbatim.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, message }`.
+ */
+export async function handleCommit(deps, body) {
+    const parsed = readBody(body, ['repoPath', 'message']);
+    if (isOutcome(parsed))
+        return parsed;
+    const repoPath = readRepoPath(parsed);
+    if (typeof repoPath !== 'string')
+        return repoPath;
+    const message = parsed.message;
+    if (message.trim() === '')
+        return fail(400, '"message" must not be blank');
+    if (message.length > COMMIT_MESSAGE_LIMIT)
+        return fail(400, `"message" accepts at most ${String(COMMIT_MESSAGE_LIMIT)} characters`);
+    try {
+        const result = await commitIndex(deps.exec, repoPath, message);
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        return checkoutFailure(error);
+    }
+}
+/** Default and maximum page size of POST /log. */
+export const LOG_LIMIT_DEFAULT = 50;
+export const LOG_LIMIT_MAX = 200;
+/**
+ * POST /log — one page of the queried checkout's history. The optional `ref`
+ * is verified server-side (`rev-parse --verify`), an unborn checkout answers
+ * an empty page, and everything else surfaces git's own stderr.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, limit?, skip?, ref? }`.
+ */
+export async function handleLog(deps, body) {
+    const parsed = readBody(body, ['repoPath'], [], ['ref'], ['limit', 'skip']);
+    if (isOutcome(parsed))
+        return parsed;
+    const repoPath = readRepoPath(parsed);
+    if (typeof repoPath !== 'string')
+        return repoPath;
+    const limit = parsed.limit ?? LOG_LIMIT_DEFAULT;
+    const skip = parsed.skip ?? 0;
+    if (!Number.isInteger(limit) || limit < 1 || limit > LOG_LIMIT_MAX) {
+        return fail(400, `"limit" must be an integer between 1 and ${String(LOG_LIMIT_MAX)}`);
+    }
+    if (!Number.isInteger(skip) || skip < 0)
+        return fail(400, '"skip" must be an integer >= 0');
+    const ref = parsed.ref;
+    if (ref !== undefined && (ref.trim() === '' || ref.length > 300 || ref.startsWith('-'))) {
+        return fail(400, '"ref" must be a non-empty revision name');
+    }
+    try {
+        const commits = await logHistory(deps.exec, repoPath, limit, skip, ref);
+        return { status: 200, body: { commits } };
+    }
+    catch (error) {
+        return checkoutFailure(error);
+    }
+}
+/**
+ * POST /commit-files — the files one commit of the queried checkout changed.
+ * The hash is verified server-side; unknown revisions answer 400.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, hash }`.
+ */
+export async function handleCommitFiles(deps, body) {
+    const parsed = readBody(body, ['repoPath', 'hash']);
+    if (isOutcome(parsed))
+        return parsed;
+    const repoPath = readRepoPath(parsed);
+    if (typeof repoPath !== 'string')
+        return repoPath;
+    const hash = parsed.hash;
+    if (!/^[0-9a-fA-F]{4,64}$/.test(hash))
+        return fail(400, '"hash" must be a git object id');
+    try {
+        const files = await commitFiles(deps.exec, repoPath, hash);
+        return { status: 200, body: { hash, files } };
+    }
+    catch (error) {
+        return checkoutFailure(error);
+    }
+}
+/** Bound for the AI-generated message (characters). */
+const AI_MESSAGE_LIMIT = 2000;
+/**
+ * POST /ai-commit-message — generate a commit message from the checkout's
+ * diff with ONE one-shot llm call. The model route (provider/model/effort)
+ * arrives from the requesting session's own selection, so the generation uses
+ * the model the user is already talking to; the diff is truncated and the
+ * reply folded to plain text.
+ * @param deps - host dependencies.
+ * @param llm - the resolved llm runtime (the route is mounted only with one).
+ * @param body - parsed request body: `{ repoPath, provider, model, effort?, hint? }`.
+ */
+export async function handleAiCommitMessage(deps, llm, body) {
+    const parsed = readBody(body, ['repoPath', 'provider', 'model'], [], ['effort', 'hint']);
+    if (isOutcome(parsed))
+        return parsed;
+    const repoPath = readRepoPath(parsed);
+    if (typeof repoPath !== 'string')
+        return repoPath;
+    if (parsed.provider.trim() === '' || parsed.model.trim() === '') {
+        return fail(400, '"provider" and "model" must be non-empty');
+    }
+    if (parsed.hint !== undefined && parsed.hint.length > 2000)
+        return fail(400, '"hint" accepts at most 2000 characters');
+    try {
+        const { diff, recentSubjects, staged } = await collectAiDiff(deps.exec, repoPath);
+        if (diff.trim() === '')
+            return fail(400, 'no changes to describe (the working tree and index are clean)');
+        const style = recentSubjects.length > 0
+            ? `Recent commit subjects of this repository (follow their language and style):\n${recentSubjects.map(subject => `- ${subject}`).join('\n')}`
+            : '';
+        const userText = [
+            `Generate a git commit message for the ${staged ? 'staged' : 'working-tree'} changes below.`,
+            style,
+            parsed.hint === undefined ? undefined : `User hint (rewrite or style request): ${parsed.hint}`,
+            'Diff:',
+            diff,
+        ].filter(part => part !== undefined).join('\n\n');
+        let text = '';
+        for await (const chunk of llm.stream({
+            provider: parsed.provider,
+            model: parsed.model,
+            ...(parsed.effort === undefined || parsed.effort === '' ? {} : { reasoningEffort: parsed.effort }),
+            messages: [{ role: 'user', content: [{ type: 'text', text: userText }] }],
+            system: 'You write git commit messages. Reply with the message ONLY: one conventional-commit subject line (matching the repository language), optionally followed by a blank line and a short body of bullet points. No explanations, no markdown fences.',
+            temperature: 0.2,
+            maxTokens: 500,
+        })) {
+            if (chunk.type === 'text-delta')
+                text += chunk.text ?? '';
+        }
+        text = text.replace(/^```[a-z]*\n?|```\n?$/g, '').trim();
+        if (text === '')
+            return fail(502, 'the model returned an empty message');
+        if (text.length > AI_MESSAGE_LIMIT)
+            text = text.slice(0, AI_MESSAGE_LIMIT);
+        return { status: 200, body: { message: text } };
+    }
+    catch (error) {
+        return checkoutFailure(error);
+    }
+}

package/lib/wire.d.ts

@@ -43,6 +43,23 @@ export declare const ROUTE_WORKTREES_ALL = "/plugin/git-worktree/worktrees-all";
 /** POST ROUTE_PREFIX/purge — delete a NON-git directory sitting DIRECTLY in
  * the storage root (an orphaned leftover whose .git is already gone). */
 export declare const ROUTE_PURGE = "/plugin/git-worktree/purge";
+/** POST ROUTE_PREFIX/changes — working-tree changes (staged/unstaged rows). */
+export declare const ROUTE_CHANGES = "/plugin/git-worktree/changes";
+/** POST ROUTE_PREFIX/stage — batch stage (git add) or unstage paths. */
+export declare const ROUTE_STAGE = "/plugin/git-worktree/stage";
+/** POST ROUTE_PREFIX/commit — commit the index with a message. */
+export declare const ROUTE_COMMIT = "/plugin/git-worktree/commit";
+/** POST ROUTE_PREFIX/log — paginated commit history of the checkout. */
+export declare const ROUTE_LOG = "/plugin/git-worktree/log";
+/** POST ROUTE_PREFIX/commit-files — the files one commit changed. */
+export declare const ROUTE_COMMIT_FILES = "/plugin/git-worktree/commit-files";
+/** POST ROUTE_PREFIX/ai-commit-message — one-shot LLM commit message from
+ * the staged diff (mounted only where the host provides the llm service). */
+export declare const ROUTE_AI_COMMIT_MESSAGE = "/plugin/git-worktree/ai-commit-message";
+/** Upper bound for one commit message (characters). The host rejects longer
+ * bodies and the client caps its input at the same value, so the two ends
+ * can never disagree. */
+export declare const COMMIT_MESSAGE_LIMIT = 2000;
 /** One selectable branch row. */
 export interface BranchEntry {
     /** Display name: a bare local name (`main`) or `<remote>/<name>`. */
@@ -82,6 +99,11 @@ export type RepoStatus = {
     /** Local branches plus every remote's remote-only branches (those
      * without a same-named local twin; `<remote>/HEAD` dropped). */
     branches: BranchEntry[];
+    /** The FULL remote view: every remote branch, local twins included
+     * (the git panel's remote tree; `<remote>/HEAD` and bare leftover
+     * refs dropped). Absent from hosts serving an older build of this
+     * route — the client falls back to filtering `branches`. */
+    remoteBranches?: BranchEntry[];
     /** Every worktree of the repository, main first (git order). */
     worktrees: WorktreeEntry[];
     /** Resolved worktree storage root (absolute) — what the settings say today. */
@@ -364,3 +386,137 @@ export interface PurgeDirectoryResult {
     path: string;
     removed: boolean;
 }
+/** Status letter of one working-tree or commit file change. `U` never comes
+ * from a commit's file list — it marks an UNMERGED working-tree path. */
+export type ChangeStatus = 'A' | 'M' | 'D' | 'R' | 'C' | 'T' | 'U';
+/** One working-tree change row of POST changes. */
+export interface WorktreeChange {
+    /** New path, relative to the repository root. */
+    path: string;
+    /** Original path for a rename/copy. */
+    oldPath?: string;
+    /** Index (staged) status; absent when the index matches HEAD. */
+    staged?: ChangeStatus;
+    /** Worktree (unstaged) status; absent when the worktree matches the index. */
+    unstaged?: ChangeStatus;
+    /** True for an untracked path (neither staged nor tracked). */
+    untracked?: boolean;
+}
+/** POST changes request body. */
+export interface ChangesBody {
+    /** Any directory inside the repository (the queried checkout). */
+    repoPath: string;
+}
+/** POST changes response body. */
+export interface ChangesResult {
+    /** One row per changed path, in git status order; capped server-side. */
+    changes: WorktreeChange[];
+    /** True when the working tree had more rows than the server cap and only
+     * the first ones are listed here. */
+    truncated?: boolean;
+}
+/** POST stage request body. */
+export interface StageBody {
+    /** Any directory inside the repository (the queried checkout). */
+    repoPath: string;
+    /** Relative paths to (un)stage; they must come from POST changes output. */
+    paths: string[];
+    /** True stages (git add); false unstages (git reset / git rm --cached). */
+    stage: boolean;
+}
+/** POST stage response body. */
+export interface StageResult {
+    /** Always true on 200 — the index now reflects the request. */
+    staged: boolean;
+}
+/** POST commit request body. */
+export interface CommitBody {
+    /** Any directory inside the repository (the queried checkout). */
+    repoPath: string;
+    /** The commit message, verbatim (git -m). */
+    message: string;
+}
+/** POST commit response body. */
+export interface CommitResult {
+    /** The created commit's full hash. */
+    hash: string;
+    /** The commit subject (first line of the message, trimmed). */
+    subject: string;
+}
+/** One commit row of POST log. */
+export interface CommitEntry {
+    /** Full hash. */
+    hash: string;
+    /** Abbreviated hash (%h). */
+    short: string;
+    authorName: string;
+    authorEmail: string;
+    /** Author date, epoch milliseconds. */
+    date: number;
+    /** Parent hashes; more than one marks a merge commit. */
+    parents: string[];
+    /** The commit subject (%s). */
+    subject: string;
+    /** The commit body (%b); empty when none. */
+    body: string;
+    /** Decorations (%D), raw segments: `HEAD -> main`, `tag: v1.0.2`, `origin/main`. */
+    refs: string[];
+}
+/** POST log request body. */
+export interface LogBody {
+    /** Any directory inside the repository (the queried checkout). */
+    repoPath: string;
+    /** Page size; default 50, capped at 200. */
+    limit?: number;
+    /** Offset into the filtered history; default 0. */
+    skip?: number;
+    /** Optional starting ref (a branch name, `HEAD`, …); validated server-side. */
+    ref?: string;
+}
+/** POST log response body. */
+export interface LogResult {
+    commits: CommitEntry[];
+}
+/** One file row of POST commit-files. */
+export interface CommitFileEntry {
+    /** New path, relative to the repository root. */
+    path: string;
+    /** Original path for a rename/copy. */
+    oldPath?: string;
+    status: ChangeStatus;
+    /** Added lines; absent for a binary file or when parsing fell short. */
+    insertions?: number;
+    /** Deleted lines; same conditions. */
+    deletions?: number;
+    /** True when git numstat reported `-` (binary content). */
+    binary?: boolean;
+}
+/** POST commit-files request body. */
+export interface CommitFilesBody {
+    /** Any directory inside the repository (the queried checkout). */
+    repoPath: string;
+    /** The commit hash (validated server-side). */
+    hash: string;
+}
+/** POST commit-files response body. */
+export interface CommitFilesResult {
+    hash: string;
+    files: CommitFileEntry[];
+}
+/** POST ai-commit-message request body. */
+export interface AiCommitMessageBody {
+    /** Any directory inside the repository (the queried checkout). */
+    repoPath: string;
+    /** The model route to call, as selected by the requesting session. */
+    provider: string;
+    model: string;
+    /** Adapter-owned reasoning effort for the exact model; absent = default. */
+    effort?: string;
+    /** Optional user hint (an existing draft to rewrite, or style directions). */
+    hint?: string;
+}
+/** POST ai-commit-message response body. */
+export interface AiCommitMessageResult {
+    /** The generated commit message (subject, optionally followed by a body). */
+    message: string;
+}

package/lib/wire.js

@@ -43,3 +43,20 @@ export const ROUTE_WORKTREES_ALL = `${ROUTE_PREFIX}/worktrees-all`;
 /** POST ROUTE_PREFIX/purge — delete a NON-git directory sitting DIRECTLY in
  * the storage root (an orphaned leftover whose .git is already gone). */
 export const ROUTE_PURGE = `${ROUTE_PREFIX}/purge`;
+/** POST ROUTE_PREFIX/changes — working-tree changes (staged/unstaged rows). */
+export const ROUTE_CHANGES = `${ROUTE_PREFIX}/changes`;
+/** POST ROUTE_PREFIX/stage — batch stage (git add) or unstage paths. */
+export const ROUTE_STAGE = `${ROUTE_PREFIX}/stage`;
+/** POST ROUTE_PREFIX/commit — commit the index with a message. */
+export const ROUTE_COMMIT = `${ROUTE_PREFIX}/commit`;
+/** POST ROUTE_PREFIX/log — paginated commit history of the checkout. */
+export const ROUTE_LOG = `${ROUTE_PREFIX}/log`;
+/** POST ROUTE_PREFIX/commit-files — the files one commit changed. */
+export const ROUTE_COMMIT_FILES = `${ROUTE_PREFIX}/commit-files`;
+/** POST ROUTE_PREFIX/ai-commit-message — one-shot LLM commit message from
+ * the staged diff (mounted only where the host provides the llm service). */
+export const ROUTE_AI_COMMIT_MESSAGE = `${ROUTE_PREFIX}/ai-commit-message`;
+/** Upper bound for one commit message (characters). The host rejects longer
+ * bodies and the client caps its input at the same value, so the two ends
+ * can never disagree. */
+export const COMMIT_MESSAGE_LIMIT = 2000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-branch-manage",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "提供 git 分支与 worktree 管理：输入框工具栏显示当前分支、可原地切换；支持 IDEA 风格分支选择器、远程分支检出、右键操作菜单（新建/重命名/删除/复制）、推送与更新当前分支，以及把分支隔离到独立 worktree 工作区，并管理其创建与删除。",
   "keywords": [
     "dsh",