dsh-ccgui 0.0.0-stage → 1.0.0

package/lib/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared names.
+ * @module dsh-ccgui/constants
+ */
+/**
+ * The only tool a CLI session calls in the harness. The name is deliberately not
+ * one the harness ships, so a CLI call can never reach a real tool body and run a
+ * command the CLI already ran.
+ */
+export declare const CLI_TOOL_NAME = "cli_tool";
+/** Every CLI's provider route starts with this; the rest is its configured id. */
+export declare const CLI_ROUTE_PREFIX = "cli-";
+/**
+ * Name a CLI's provider route.
+ * @param id - the configured agent id.
+ * @returns its route.
+ */
+export declare const cliRoute: (id: string) => string;
+/** Model id meaning whatever the CLI itself is set to. */
+export declare const DEFAULT_MODEL_ID = "default";
+/** Path prefix of the 变更 panel's git routes; the browser posts to `<prefix>/<operation>`. */
+export declare const GIT_ROUTE_PREFIX = "/dsh-ccgui/git";

package/lib/constants.js

@@ -0,0 +1,22 @@
+/**
+ * Shared names.
+ * @module dsh-ccgui/constants
+ */
+/**
+ * The only tool a CLI session calls in the harness. The name is deliberately not
+ * one the harness ships, so a CLI call can never reach a real tool body and run a
+ * command the CLI already ran.
+ */
+export const CLI_TOOL_NAME = 'cli_tool';
+/** Every CLI's provider route starts with this; the rest is its configured id. */
+export const CLI_ROUTE_PREFIX = 'cli-';
+/**
+ * Name a CLI's provider route.
+ * @param id - the configured agent id.
+ * @returns its route.
+ */
+export const cliRoute = (id) => `${CLI_ROUTE_PREFIX}${id}`;
+/** Model id meaning whatever the CLI itself is set to. */
+export const DEFAULT_MODEL_ID = 'default';
+/** Path prefix of the 变更 panel's git routes; the browser posts to `<prefix>/<operation>`. */
+export const GIT_ROUTE_PREFIX = '/dsh-ccgui/git';

package/lib/git/git-read.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The 变更 panel's reads: where a directory's repository is, its status with line counts,
+ * its branches, and the patch of one file.
+ * @module dsh-ccgui/git/git-read
+ */
+import type { Spawn } from './git-run.ts';
+import type { GitStatus } from './git-status.ts';
+export interface RepoStatus extends GitStatus {
+    /** The repository's top level; every path in the status is relative to it. */
+    readonly root: string;
+}
+export interface BranchList {
+    readonly current: string | undefined;
+    readonly local: readonly string[];
+    readonly remote: readonly string[];
+}
+export interface FileDiff {
+    readonly patch: string;
+    readonly truncated: boolean;
+}
+/** Which version of a file a diff compares. */
+export type DiffSide = 'staged' | 'unstaged' | 'untracked';
+/**
+ * Find the repository a directory belongs to.
+ * @param spawn - the subprocess service's spawn.
+ * @param cwd - any directory.
+ * @returns the top level, or undefined when the directory is not in a repository.
+ */
+export declare function repoRoot(spawn: Spawn, cwd: string): Promise<string | undefined>;
+/**
+ * Whether a path is one of the untracked files the status lists. git does not descend into a
+ * symlinked directory, so `link/key.txt` behind `link -> ~/.ssh` is not one of them; the check
+ * runs through git rather than the file system because git may run on another host.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param path - a path relative to the root.
+ * @returns true when git lists the path as untracked and not ignored.
+ */
+export declare function isUntracked(spawn: Spawn, root: string, path: string): Promise<boolean>;
+/**
+ * Read the status of the repository at `root`, with line counts for every group.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @returns the branch, its distance from upstream, and the three groups.
+ */
+export declare function readStatus(spawn: Spawn, root: string): Promise<RepoStatus>;
+/**
+ * List local and remote branches.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @returns the checked-out branch and the others, locals first as git sorts them.
+ */
+export declare function readBranches(spawn: Spawn, root: string): Promise<BranchList>;
+/**
+ * Read the unified patch of one file.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param target - the file, the side compared, and the path it had before a rename.
+ * @returns the patch, cut at the size limit.
+ */
+export declare function readDiff(spawn: Spawn, root: string, target: {
+    readonly path: string;
+    readonly side: DiffSide;
+    readonly origPath?: string | undefined;
+}): Promise<FileDiff>;

package/lib/git/git-read.js

@@ -0,0 +1,139 @@
+/**
+ * The 变更 panel's reads: where a directory's repository is, its status with line counts,
+ * its branches, and the patch of one file.
+ * @module dsh-ccgui/git/git-read
+ */
+import { failureOf, mustGit, runGit } from "./git-run.js";
+import { parseNumstat, parseStatus, withCounts } from "./git-status.js";
+/** Untracked files beyond this many are listed without line counts; each count is one git run. */
+const MAX_COUNTED_UNTRACKED = 100;
+/**
+ * Larger patches are not shown at all: collection keeps the tail of a stream, and a patch
+ * missing its head cannot be read. The panel cuts what it draws by lines on its own.
+ */
+const MAX_DIFF_BYTES = 8 * 1024 * 1024;
+const NULL_DEVICE = '/dev/null';
+/** `git diff --no-index` exits with 1 when the files differ, which is the answer, not a failure. */
+const DIFFERS = 1;
+/**
+ * Untracked counts run this many git processes at a time: each one is a process start, and a
+ * timer repeats the whole read, so a burst of a hundred would recur every few seconds.
+ */
+const COUNT_CONCURRENCY = 8;
+/**
+ * External diff programs and textconv drivers are commands named by repository config; the
+ * panel reads diffs without asking anyone, so it never runs them.
+ */
+const NO_DRIVERS = ['--no-ext-diff', '--no-textconv'];
+/**
+ * Find the repository a directory belongs to.
+ * @param spawn - the subprocess service's spawn.
+ * @param cwd - any directory.
+ * @returns the top level, or undefined when the directory is not in a repository.
+ */
+export async function repoRoot(spawn, cwd) {
+    const result = await runGit(spawn, cwd, ['rev-parse', '--show-toplevel']);
+    const root = result.stdout.trim();
+    return result.exitCode === 0 && root !== '' ? root : undefined;
+}
+async function untrackedCount(spawn, root, entry) {
+    const args = ['diff', '--no-index', ...NO_DRIVERS, '--numstat', '-z', '--', NULL_DEVICE, entry.path];
+    const result = await runGit(spawn, root, args);
+    // The no-index numstat names the pair, not the file, so the single record is the count.
+    const [count] = parseNumstat(result.stdout).values();
+    return count === undefined ? entry : { ...entry, ...count };
+}
+async function untrackedCounts(spawn, root, entries) {
+    const counted = entries.slice(0, MAX_COUNTED_UNTRACKED);
+    const batches = Array.from({ length: Math.ceil(counted.length / COUNT_CONCURRENCY) }, (_, index) => counted.slice(index * COUNT_CONCURRENCY, (index + 1) * COUNT_CONCURRENCY));
+    const results = await batches.reduce(async (done, batch) => [
+        ...(await done),
+        ...(await Promise.all(batch.map((entry) => untrackedCount(spawn, root, entry)))),
+    ], Promise.resolve([]));
+    return [...results, ...entries.slice(MAX_COUNTED_UNTRACKED)];
+}
+/**
+ * Whether a path is one of the untracked files the status lists. git does not descend into a
+ * symlinked directory, so `link/key.txt` behind `link -> ~/.ssh` is not one of them; the check
+ * runs through git rather than the file system because git may run on another host.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param path - a path relative to the root.
+ * @returns true when git lists the path as untracked and not ignored.
+ */
+export async function isUntracked(spawn, root, path) {
+    const result = await mustGit(spawn, root, ['ls-files', '-z', '--others', '--exclude-standard', '--', path], '读取 Git 状态失败');
+    return result.stdout === `${path}\0`;
+}
+/**
+ * Read the status of the repository at `root`, with line counts for every group.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @returns the branch, its distance from upstream, and the three groups.
+ */
+export async function readStatus(spawn, root) {
+    const failure = '读取 Git 状态失败';
+    const [status, staged, unstaged] = await Promise.all([
+        mustGit(spawn, root, ['status', '--porcelain=v2', '--branch', '-z', '--untracked-files=all'], failure),
+        mustGit(spawn, root, ['diff', '--cached', ...NO_DRIVERS, '--numstat', '-z', '-M'], failure),
+        mustGit(spawn, root, ['diff', ...NO_DRIVERS, '--numstat', '-z'], failure),
+    ]);
+    const parsed = parseStatus(status.stdout);
+    return {
+        ...parsed,
+        root,
+        staged: withCounts(parsed.staged, parseNumstat(staged.stdout)),
+        unstaged: withCounts(parsed.unstaged, parseNumstat(unstaged.stdout)),
+        untracked: await untrackedCounts(spawn, root, parsed.untracked),
+    };
+}
+/**
+ * List local and remote branches.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @returns the checked-out branch and the others, locals first as git sorts them.
+ */
+export async function readBranches(spawn, root) {
+    const format = '%(refname)%00%(refname:short)%00%(HEAD)';
+    const result = await mustGit(spawn, root, ['for-each-ref', `--format=${format}`, 'refs/heads', 'refs/remotes'], '读取分支失败');
+    const rows = result.stdout
+        .split('\n')
+        .filter((line) => line !== '')
+        .map((line) => {
+        const [ref = '', name = '', head = ''] = line.split('\0');
+        return { ref, name, head: head === '*' };
+    });
+    return {
+        current: rows.find((row) => row.head)?.name,
+        local: rows.filter((row) => row.ref.startsWith('refs/heads/')).map((row) => row.name),
+        // A remote's HEAD is an alias for one of its branches, not a branch to pick.
+        remote: rows
+            .filter((row) => row.ref.startsWith('refs/remotes/') && !row.ref.endsWith('/HEAD'))
+            .map((row) => row.name),
+    };
+}
+function diffArgs(side, path, origPath) {
+    const paths = origPath === undefined ? [path] : [origPath, path];
+    if (side === 'untracked')
+        return ['diff', '--no-index', ...NO_DRIVERS, '--', NULL_DEVICE, path];
+    if (side === 'staged')
+        return ['diff', '--cached', ...NO_DRIVERS, '-M', '--', ...paths];
+    return ['diff', ...NO_DRIVERS, '--', path];
+}
+/**
+ * Read the unified patch of one file.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param target - the file, the side compared, and the path it had before a rename.
+ * @returns the patch, cut at the size limit.
+ */
+export async function readDiff(spawn, root, target) {
+    const args = diffArgs(target.side, target.path, target.origPath);
+    const result = await runGit(spawn, root, args, { maxBytes: MAX_DIFF_BYTES });
+    // A missing file also exits with 1 under --no-index; only that case writes to stderr.
+    const differs = target.side === 'untracked' && result.exitCode === DIFFERS && result.stderr.trim() === '';
+    const ok = result.exitCode === 0 || differs;
+    if (!ok)
+        throw failureOf(result, '读取差异失败');
+    return result.truncated ? { patch: '', truncated: true } : { patch: result.stdout, truncated: false };
+}

package/lib/git/git-requests.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Validate the JSON the 变更 panel posts and run the git operation it names. Everything
+ * arriving here is untrusted: the directory must be absolute, and every file path must stay
+ * inside the repository.
+ * @module dsh-ccgui/git/git-requests
+ */
+import type { Spawn } from './git-run.ts';
+/** A request the panel got wrong; answered with 400 rather than 500. */
+export declare class GitRequestError extends Error {
+    name: string;
+}
+/** The operations the routes accept, by the last segment of their path. */
+export declare const GIT_OPERATIONS: readonly ["status", "branches", "diff", "stage", "unstage", "discard", "commit", "push", "pull", "checkout", "create-branch"];
+export type GitOperation = (typeof GIT_OPERATIONS)[number];
+type Body = Readonly<Record<string, unknown>>;
+/**
+ * Narrow a parsed value to an object body.
+ * @param value - the parsed JSON.
+ * @returns the body.
+ * @throws GitRequestError for anything but a plain object.
+ */
+export declare function asBody(value: unknown): Body;
+/**
+ * Check that an operation name is one the routes serve.
+ * @param name - the last path segment.
+ * @returns the operation, or undefined for an unknown name.
+ */
+export declare function operationOf(name: string): GitOperation | undefined;
+/**
+ * Run one operation for the directory in the body. A directory outside any repository
+ * answers `{ repo: false }` to every operation, which the panel shows as its empty state.
+ * @param spawn - the subprocess service's spawn.
+ * @param operation - what to do.
+ * @param body - the validated-on-read request body.
+ * @returns the operation's data; writes answer with the fresh status.
+ */
+export declare function runOperation(spawn: Spawn, operation: GitOperation, body: Body): Promise<unknown>;
+/**
+ * The HTTP status for an error an operation threw.
+ * @param error - what was thrown.
+ * @returns 400 for a bad request, 409 for a git refusal, 500 otherwise.
+ */
+export declare function statusFor(error: unknown): number;
+export {};

package/lib/git/git-requests.js

@@ -0,0 +1,153 @@
+/**
+ * Validate the JSON the 变更 panel posts and run the git operation it names. Everything
+ * arriving here is untrusted: the directory must be absolute, and every file path must stay
+ * inside the repository.
+ * @module dsh-ccgui/git/git-requests
+ */
+import { isAbsolute } from 'node:path';
+import { isUntracked, readBranches, readDiff, readStatus, repoRoot } from "./git-read.js";
+import { GitError } from "./git-run.js";
+import { checkout, commit, createBranch, discard, pull, push, stage, unstage } from "./git-write.js";
+/** A request the panel got wrong; answered with 400 rather than 500. */
+export class GitRequestError extends Error {
+    name = 'GitRequestError';
+}
+/** The operations the routes accept, by the last segment of their path. */
+export const GIT_OPERATIONS = [
+    'status',
+    'branches',
+    'diff',
+    'stage',
+    'unstage',
+    'discard',
+    'commit',
+    'push',
+    'pull',
+    'checkout',
+    'create-branch',
+];
+/** More files than any selection the panel can make; a cap on argv length. */
+const MAX_PATHS = 5_000;
+const MAX_TEXT = 64 * 1024;
+const DIFF_SIDES = ['staged', 'unstaged', 'untracked'];
+const NOT_A_REPO = { repo: false };
+/**
+ * Narrow a parsed value to an object body.
+ * @param value - the parsed JSON.
+ * @returns the body.
+ * @throws GitRequestError for anything but a plain object.
+ */
+export function asBody(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new GitRequestError('请求格式无效');
+    return value;
+}
+function text(body, key) {
+    const value = body[key];
+    if (typeof value !== 'string' || value === '' || value.length > MAX_TEXT || value.includes('\0')) {
+        throw new GitRequestError(`缺少或无效的参数：${key}`);
+    }
+    return value;
+}
+/** Relative, without `..` segments, so git never reaches outside the repository. */
+function repoPath(value) {
+    if (typeof value !== 'string' || value === '' || value.includes('\0') || isAbsolute(value)) {
+        throw new GitRequestError('文件路径无效');
+    }
+    if (value.split(/[\\/]/).includes('..'))
+        throw new GitRequestError('文件路径无效');
+    return value;
+}
+function paths(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > MAX_PATHS)
+        throw new GitRequestError(`缺少或无效的参数：${key}`);
+    return value.map(repoPath);
+}
+function diffSide(body) {
+    const side = DIFF_SIDES.find((candidate) => candidate === body.side);
+    if (side === undefined)
+        throw new GitRequestError('缺少或无效的参数：side');
+    return side;
+}
+/**
+ * Check that an operation name is one the routes serve.
+ * @param name - the last path segment.
+ * @returns the operation, or undefined for an unknown name.
+ */
+export function operationOf(name) {
+    return GIT_OPERATIONS.find((operation) => operation === name);
+}
+async function write(spawn, root, operation, body) {
+    switch (operation) {
+        case 'stage':
+            return stage(spawn, root, paths(body, 'paths'));
+        case 'unstage':
+            return unstage(spawn, root, paths(body, 'paths'));
+        case 'discard':
+            return discard(spawn, root, { tracked: paths(body, 'tracked'), untracked: paths(body, 'untracked') });
+        case 'commit':
+            return commit(spawn, root, { message: text(body, 'message'), paths: paths(body, 'paths') });
+        case 'push':
+            return push(spawn, root);
+        case 'pull':
+            return pull(spawn, root);
+        case 'checkout':
+            return checkout(spawn, root, { name: text(body, 'branch'), remote: body.remote === true });
+        case 'create-branch':
+            return createBranch(spawn, root, text(body, 'branch'));
+        default:
+            throw new GitRequestError(`不支持的操作：${operation}`);
+    }
+}
+async function diff(spawn, root, body) {
+    const path = repoPath(body.path);
+    const side = diffSide(body);
+    // An untracked diff reads the file itself, outside git's object store, so it is limited to
+    // the files the status lists; anything else could follow a symlink out of the repository.
+    if (side === 'untracked' && !(await isUntracked(spawn, root, path))) {
+        throw new GitRequestError('只能查看仓库内未跟踪文件的差异');
+    }
+    return readDiff(spawn, root, {
+        path,
+        side,
+        origPath: body.origPath === undefined ? undefined : repoPath(body.origPath),
+    });
+}
+/**
+ * Run one operation for the directory in the body. A directory outside any repository
+ * answers `{ repo: false }` to every operation, which the panel shows as its empty state.
+ * @param spawn - the subprocess service's spawn.
+ * @param operation - what to do.
+ * @param body - the validated-on-read request body.
+ * @returns the operation's data; writes answer with the fresh status.
+ */
+export async function runOperation(spawn, operation, body) {
+    const cwd = text(body, 'cwd');
+    if (!isAbsolute(cwd))
+        throw new GitRequestError('工作目录必须是绝对路径');
+    const root = await repoRoot(spawn, cwd);
+    if (root === undefined)
+        return NOT_A_REPO;
+    if (operation === 'branches')
+        return readBranches(spawn, root);
+    if (operation === 'diff')
+        return diff(spawn, root, body);
+    if (operation !== 'status')
+        await write(spawn, root, operation, body);
+    return { repo: true, ...(await readStatus(spawn, root)) };
+}
+/**
+ * The HTTP status for an error an operation threw.
+ * @param error - what was thrown.
+ * @returns 400 for a bad request, 409 for a git refusal, 500 otherwise.
+ */
+export function statusFor(error) {
+    if (error instanceof GitRequestError)
+        return 400;
+    if (error instanceof GitError)
+        return 409;
+    return 500;
+}

package/lib/git/git-routes.d.ts

@@ -0,0 +1,38 @@
+/**
+ * HTTP routes the 变更 panel posts to, under `/dsh-ccgui/git/<operation>`. The harness's
+ * web server leaves authentication to each route, so every request first asks the
+ * `connection` service for a rejection: its Host/Origin fence stops cross-site and DNS-
+ * rebinding callers, and its login-token check stops anyone who is not the signed-in browser.
+ * @module dsh-ccgui/git/git-routes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Spawn } from './git-run.ts';
+/** The parts of the harness's `webServer` service this module uses. */
+export interface GitWebServer {
+    register(route: {
+        kind: 'prefix';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    }): () => void;
+}
+/** The parts of the harness's `connection` service this module uses. */
+export interface GitConnection {
+    requestRejection(request: {
+        readonly headers: IncomingMessage['headers'];
+    }): 401 | 403 | undefined;
+}
+/**
+ * Build the handler for every git route.
+ * @param spawn - the subprocess service's spawn.
+ * @param connection - the harness's trust check.
+ * @param warn - logs failures that are not the user's doing.
+ * @returns the request handler.
+ */
+export declare function gitHandler(spawn: Spawn, connection: GitConnection, warn: (message: string) => void): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/**
+ * Register the git routes on the web server.
+ * @param webServer - the harness's web server.
+ * @param handler - the handler from {@link gitHandler}.
+ * @returns the unregister function.
+ */
+export declare function registerGitRoutes(webServer: GitWebServer, handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>): () => void;

package/lib/git/git-routes.js

@@ -0,0 +1,78 @@
+/**
+ * HTTP routes the 变更 panel posts to, under `/dsh-ccgui/git/<operation>`. The harness's
+ * web server leaves authentication to each route, so every request first asks the
+ * `connection` service for a rejection: its Host/Origin fence stops cross-site and DNS-
+ * rebinding callers, and its login-token check stops anyone who is not the signed-in browser.
+ * @module dsh-ccgui/git/git-routes
+ */
+import { GIT_ROUTE_PREFIX } from "../constants.js";
+import { asBody, operationOf, runOperation, statusFor } from "./git-requests.js";
+/** Request bodies are a directory and a list of paths; anything larger is refused. */
+const MAX_BODY_BYTES = 1024 * 1024;
+class BodyTooLarge extends Error {
+    name = 'BodyTooLarge';
+}
+function sendJson(res, status, payload, headers = {}) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', ...headers });
+    res.end(JSON.stringify(payload));
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += buffer.length;
+        if (size > MAX_BODY_BYTES)
+            throw new BodyTooLarge('请求内容过大');
+        chunks.push(buffer);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Build the handler for every git route.
+ * @param spawn - the subprocess service's spawn.
+ * @param connection - the harness's trust check.
+ * @param warn - logs failures that are not the user's doing.
+ * @returns the request handler.
+ */
+export function gitHandler(spawn, connection, warn) {
+    return async (req, res) => {
+        const rejection = connection.requestRejection(req);
+        if (rejection !== undefined) {
+            sendJson(res, rejection, { success: false, error: '未授权' });
+            return;
+        }
+        if (req.method !== 'POST') {
+            sendJson(res, 405, { success: false, error: '只支持 POST' }, { allow: 'POST' });
+            return;
+        }
+        const name = (req.url ?? '').split('?')[0]?.split('/').pop() ?? '';
+        const operation = operationOf(name);
+        if (operation === undefined) {
+            sendJson(res, 404, { success: false, error: '接口不存在' });
+            return;
+        }
+        try {
+            const data = await runOperation(spawn, operation, asBody(await readJson(req)));
+            sendJson(res, 200, { success: true, data });
+        }
+        catch (error) {
+            const status = error instanceof BodyTooLarge ? 413 : error instanceof SyntaxError ? 400 : statusFor(error);
+            if (status === 500)
+                warn(`ccgui: git ${operation} failed: ${messageOf(error)}`);
+            sendJson(res, status, { success: false, error: status === 500 ? 'Git 操作失败，请查看日志' : messageOf(error) });
+        }
+    };
+}
+/**
+ * Register the git routes on the web server.
+ * @param webServer - the harness's web server.
+ * @param handler - the handler from {@link gitHandler}.
+ * @returns the unregister function.
+ */
+export function registerGitRoutes(webServer, handler) {
+    return webServer.register({ kind: 'prefix', path: GIT_ROUTE_PREFIX, handler });
+}

package/lib/git/git-run.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Run one git command in a working directory through the harness's subprocess service, so
+ * git resolves in the same execution world as the CLIs (a remote or sandboxed host included).
+ * @module dsh-ccgui/git/git-run
+ */
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** Starts a child process; the harness's `ctx.subprocess.spawn` in production. */
+export type Spawn = (spec: SubprocessSpawnSpec) => SubprocessHandle;
+/** What a finished git command reported. */
+export interface GitResult {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** True when stdout outgrew the cap and lost its head. */
+    readonly truncated: boolean;
+}
+export interface GitRunOptions {
+    /** Ends the command; the caller owns the deadline. */
+    readonly signal?: AbortSignal | undefined;
+    /** Largest stdout kept in memory, in bytes. */
+    readonly maxBytes?: number | undefined;
+    /** Written to stdin, which is then closed; a commit message, for instance. */
+    readonly input?: string | undefined;
+}
+/**
+ * Run `git <args>` in `cwd` and collect its output. A non-zero exit is reported, not thrown;
+ * a failure to start git at all rejects.
+ * @param spawn - the subprocess service's spawn.
+ * @param cwd - the working directory.
+ * @param args - git's arguments, never shell-interpreted.
+ * @param options - abort signal and output cap.
+ * @returns the exit code and the collected output.
+ */
+export declare function runGit(spawn: Spawn, cwd: string, args: readonly string[], options?: GitRunOptions): Promise<GitResult>;
+/** A git command that failed; the message is ready to show the user. */
+export declare class GitError extends Error {
+    name: string;
+}
+/**
+ * Describe a failed command for the user.
+ * @param result - what git reported.
+ * @param failure - what failed, in front of git's own reason.
+ * @returns the error to throw.
+ */
+export declare function failureOf(result: GitResult, failure: string): GitError;
+/**
+ * Run git and require success.
+ * @param spawn - the subprocess service's spawn.
+ * @param cwd - the working directory.
+ * @param args - git's arguments.
+ * @param how - what the user is told failed, in front of git's own reason; with run options
+ * (abort signal, output cap, stdin) as an object.
+ * @returns the result of a command that exited with 0.
+ * @throws GitError when git exits with anything else.
+ */
+export declare function mustGit(spawn: Spawn, cwd: string, args: readonly string[], how: string | (GitRunOptions & {
+    readonly failure: string;
+})): Promise<GitResult>;