dsh-ccgui 0.0.0-stage → 1.0.0

package/lib/git/git-run.js

@@ -0,0 +1,97 @@
+/**
+ * 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
+ */
+/** Plenty for status and numstat of a large checkout; diffs pass their own cap. */
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+/** stderr only carries messages for the user. */
+const STDERR_MAX_BYTES = 64 * 1024;
+const GRACE_MS = 2_000;
+/**
+ * Paths stay raw UTF-8 (no octal quoting), and nothing waits on a terminal: a push that
+ * needs a password fails fast instead of hanging on a prompt nobody can see.
+ *
+ * The panel reads status on a timer, without asking anyone, in a repository whose config an
+ * agent may have edited; `core.fsmonitor` names a command git would run on every status, so
+ * it is switched off here. Diff drivers are switched off where the diffs are read.
+ *
+ * Paths arrive from the panel as file names, so pathspec patterns are off: discarding
+ * `src/[id].tsx` must not also discard `src/d.tsx`, and `:memo.txt` is a file, not magic.
+ */
+const GIT_PREFIX = ['git', '-c', 'core.quotePath=false', '-c', 'color.ui=false', '-c', 'core.fsmonitor=false'];
+const GIT_ENV = { GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', GIT_LITERAL_PATHSPECS: '1', LC_ALL: 'C' };
+/**
+ * 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 async function runGit(spawn, cwd, args, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const child = spawn({
+        argv: [...GIT_PREFIX, ...args],
+        cwd,
+        env: GIT_ENV,
+        graceMs: GRACE_MS,
+        signal: options.signal,
+        stdio: {
+            stdin: options.input === undefined ? 'ignore' : { data: options.input },
+            stdout: { maxBytes },
+            stderr: { maxBytes: STDERR_MAX_BYTES },
+        },
+    });
+    const outcome = await child.done;
+    const stdout = child.collected.stdout?.readFrom(0);
+    const stderr = child.collected.stderr?.readFrom(0);
+    return {
+        exitCode: outcome.exitCode,
+        stdout: stdout?.text ?? '',
+        stderr: stderr?.text ?? '',
+        truncated: stdout?.lossy ?? false,
+    };
+}
+/** A git command that failed; the message is ready to show the user. */
+export class GitError extends Error {
+    name = 'GitError';
+}
+/** stderr lines git adds around the message that matters, such as push hints. */
+const NOISE = /^(hint:|remote:\s*$)/;
+function reasonOf(result) {
+    // Some refusals, such as "nothing to commit", are printed on stdout.
+    const text = result.stderr.trim() === '' ? result.stdout : result.stderr;
+    const lines = text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && !NOISE.test(line));
+    return lines.join('\n') || `git 退出码 ${String(result.exitCode)}`;
+}
+/**
+ * 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 function failureOf(result, failure) {
+    return new GitError(`${failure}：${reasonOf(result)}`);
+}
+/**
+ * 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 async function mustGit(spawn, cwd, args, how) {
+    const { failure, ...options } = typeof how === 'string' ? { failure: how } : how;
+    const result = await runGit(spawn, cwd, args, options);
+    if (result.exitCode !== 0)
+        throw failureOf(result, failure);
+    return result;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Parse `git status --porcelain=v2 --branch -z` and `git diff --numstat -z` into the shape
+ * the 变更 panel draws: one list per group (已暂存, 未暂存, 未跟踪), each entry with a status
+ * letter and line counts, plus the branch and how far it is from its upstream.
+ * @module dsh-ccgui/git/git-status
+ */
+/** M modified, A added, D deleted, R renamed, C copied, T type changed, U conflicted, ? untracked. */
+type ChangeStatus = 'M' | 'A' | 'D' | 'R' | 'C' | 'T' | 'U' | '?';
+export interface ChangeEntry {
+    readonly path: string;
+    /** The path before a rename or copy. */
+    readonly origPath?: string;
+    readonly status: ChangeStatus;
+    readonly additions?: number;
+    readonly deletions?: number;
+}
+export interface GitStatus {
+    /** Branch name, or undefined on a detached HEAD. */
+    readonly branch: string | undefined;
+    /** Set only when the branch has an upstream. */
+    readonly ahead: number | undefined;
+    readonly behind: number | undefined;
+    readonly staged: readonly ChangeEntry[];
+    readonly unstaged: readonly ChangeEntry[];
+    readonly untracked: readonly ChangeEntry[];
+}
+/** Line counts per path; binary files have none. */
+export type LineCounts = ReadonlyMap<string, {
+    readonly additions: number;
+    readonly deletions: number;
+}>;
+/**
+ * Parse porcelain v2 status output.
+ * @param output - stdout of `git status --porcelain=v2 --branch -z --untracked-files=all`.
+ * @returns the branch and the three groups, without line counts.
+ */
+export declare function parseStatus(output: string): GitStatus;
+/**
+ * Parse numstat output. A rename's counts are filed under its new path.
+ * @param output - stdout of `git diff --numstat -z`.
+ * @returns line counts per path; binary files are left out.
+ */
+export declare function parseNumstat(output: string): LineCounts;
+/**
+ * Attach line counts to entries that have them.
+ * @param entries - one group's entries.
+ * @param counts - that group's numstat.
+ * @returns new entries; ones without counts are returned as they were.
+ */
+export declare function withCounts(entries: readonly ChangeEntry[], counts: LineCounts): readonly ChangeEntry[];
+export {};

package/lib/git/git-status.js

@@ -0,0 +1,122 @@
+/**
+ * Parse `git status --porcelain=v2 --branch -z` and `git diff --numstat -z` into the shape
+ * the 变更 panel draws: one list per group (已暂存, 未暂存, 未跟踪), each entry with a status
+ * letter and line counts, plus the branch and how far it is from its upstream.
+ * @module dsh-ccgui/git/git-status
+ */
+const STATUS_LETTERS = new Set(['M', 'A', 'D', 'R', 'C', 'T']);
+/** Fields before the path in an ordinary (`1`) and a renamed (`2`) entry, and a conflict (`u`). */
+const ORDINARY_FIELDS = 8;
+const RENAMED_FIELDS = 9;
+const UNMERGED_FIELDS = 10;
+function letterOf(code) {
+    return code !== undefined && STATUS_LETTERS.has(code) ? code : undefined;
+}
+/** Split `count` space-separated fields off the front, keeping spaces in the path that follows. */
+function fieldsAndPath(record, count) {
+    const fields = record.split(' ', count);
+    const head = fields.join(' ').length + 1;
+    return { fields, path: record.slice(head) };
+}
+function parseBranchHeader(line, branch) {
+    if (line.startsWith('# branch.head ')) {
+        const name = line.slice('# branch.head '.length);
+        return { ...branch, branch: name === '(detached)' ? undefined : name };
+    }
+    const ab = /^# branch\.ab \+(\d+) -(\d+)$/.exec(line);
+    if (ab === null)
+        return branch;
+    return { ...branch, ahead: Number(ab[1]), behind: Number(ab[2]) };
+}
+function addTracked(groups, xy, path, origPath) {
+    const base = origPath === undefined ? { path } : { path, origPath };
+    const index = letterOf(xy[0]);
+    const tree = letterOf(xy[1]);
+    return {
+        ...groups,
+        staged: index === undefined ? groups.staged : [...groups.staged, { ...base, status: index }],
+        unstaged: tree === undefined ? groups.unstaged : [...groups.unstaged, { ...base, status: tree }],
+    };
+}
+function addRecord(groups, records, at) {
+    const record = records[at] ?? '';
+    const kind = record[0];
+    if (kind === '?') {
+        return {
+            groups: { ...groups, untracked: [...groups.untracked, { path: record.slice(2), status: '?' }] },
+            next: at + 1,
+        };
+    }
+    if (kind === '1') {
+        const { fields, path } = fieldsAndPath(record, ORDINARY_FIELDS);
+        return { groups: addTracked(groups, fields[1] ?? '', path), next: at + 1 };
+    }
+    if (kind === '2') {
+        // The path before the rename is the next NUL-separated record.
+        const { fields, path } = fieldsAndPath(record, RENAMED_FIELDS);
+        return { groups: addTracked(groups, fields[1] ?? '', path, records[at + 1]), next: at + 2 };
+    }
+    if (kind === 'u') {
+        const { path } = fieldsAndPath(record, UNMERGED_FIELDS);
+        return { groups: { ...groups, unstaged: [...groups.unstaged, { path, status: 'U' }] }, next: at + 1 };
+    }
+    return { groups, next: at + 1 };
+}
+/**
+ * Parse porcelain v2 status output.
+ * @param output - stdout of `git status --porcelain=v2 --branch -z --untracked-files=all`.
+ * @returns the branch and the three groups, without line counts.
+ */
+export function parseStatus(output) {
+    const records = output.split('\0').filter((record) => record !== '');
+    let branch = { branch: undefined, ahead: undefined, behind: undefined };
+    let groups = { staged: [], unstaged: [], untracked: [] };
+    let at = 0;
+    while (at < records.length) {
+        const record = records[at] ?? '';
+        if (record.startsWith('# ')) {
+            branch = parseBranchHeader(record, branch);
+            at += 1;
+            continue;
+        }
+        const step = addRecord(groups, records, at);
+        groups = step.groups;
+        at = step.next;
+    }
+    return { ...branch, ...groups };
+}
+/**
+ * Parse numstat output. A rename's counts are filed under its new path.
+ * @param output - stdout of `git diff --numstat -z`.
+ * @returns line counts per path; binary files are left out.
+ */
+export function parseNumstat(output) {
+    const records = output.split('\0');
+    const counts = new Map();
+    let at = 0;
+    while (at < records.length) {
+        const [added, deleted, path] = (records[at] ?? '').split('\t');
+        // A rename has an empty path here, then the old and the new path as records of their own.
+        const target = path === '' ? records[at + 2] : path;
+        at += path === '' ? 3 : 1;
+        if (target === undefined || added === undefined || deleted === undefined)
+            continue;
+        const additions = Number(added);
+        const deletions = Number(deleted);
+        if (Number.isInteger(additions) && Number.isInteger(deletions))
+            counts.set(target, { additions, deletions });
+    }
+    return counts;
+}
+/**
+ * Attach line counts to entries that have them.
+ * @param entries - one group's entries.
+ * @param counts - that group's numstat.
+ * @returns new entries; ones without counts are returned as they were.
+ */
+export function withCounts(entries, counts) {
+    return entries.map((entry) => {
+        const count = counts.get(entry.path);
+        return count === undefined ? entry : { ...entry, ...count };
+    });
+}

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

@@ -0,0 +1,75 @@
+/**
+ * The 变更 panel's writes: stage, unstage, discard, commit the selected files, push, pull,
+ * and switch or create branches. Paths are relative to the repository's top level and always
+ * follow `--`, so a file named like an option stays a file.
+ * @module dsh-ccgui/git/git-write
+ */
+import type { Spawn } from './git-run.ts';
+/**
+ * Stage files, deletions included.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param paths - files to stage.
+ */
+export declare function stage(spawn: Spawn, root: string, paths: readonly string[]): Promise<void>;
+/**
+ * Take files out of the index, keeping their changes in the working tree.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param paths - files to unstage.
+ */
+export declare function unstage(spawn: Spawn, root: string, paths: readonly string[]): Promise<void>;
+/**
+ * Throw away working-tree changes: tracked files go back to their staged version, untracked
+ * files are deleted.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param target - tracked and untracked files to discard.
+ */
+export declare function discard(spawn: Spawn, root: string, target: {
+    readonly tracked: readonly string[];
+    readonly untracked: readonly string[];
+}): Promise<void>;
+/**
+ * Commit exactly the selected files, as they are in the working tree. Files that were staged
+ * but not selected stay staged for a later commit, which spares the user the unstage-and-
+ * confirm step a commit of the whole index would need.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param change - the message and the files to commit.
+ */
+export declare function commit(spawn: Spawn, root: string, change: {
+    readonly message: string;
+    readonly paths: readonly string[];
+}): Promise<void>;
+/**
+ * Push the current branch. A branch without an upstream is pushed to origin and tracks it.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ */
+export declare function push(spawn: Spawn, root: string): Promise<void>;
+/**
+ * Pull the current branch, fast-forward only: a merge or a rebase needs decisions the panel
+ * cannot ask for, so those are left to the terminal.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ */
+export declare function pull(spawn: Spawn, root: string): Promise<void>;
+/**
+ * Switch to a branch. A remote branch is checked out as a local branch that tracks it,
+ * unless a local branch of that name exists already.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param branch - the branch, and whether it names a remote branch such as `origin/main`.
+ */
+export declare function checkout(spawn: Spawn, root: string, branch: {
+    readonly name: string;
+    readonly remote: boolean;
+}): Promise<void>;
+/**
+ * Create a branch from HEAD and switch to it.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param name - the new branch's name.
+ */
+export declare function createBranch(spawn: Spawn, root: string, name: string): Promise<void>;

package/lib/git/git-write.js

@@ -0,0 +1,134 @@
+/**
+ * The 变更 panel's writes: stage, unstage, discard, commit the selected files, push, pull,
+ * and switch or create branches. Paths are relative to the repository's top level and always
+ * follow `--`, so a file named like an option stays a file.
+ * @module dsh-ccgui/git/git-write
+ */
+import { GitError, mustGit, runGit } from "./git-run.js";
+/** Network commands wait on a remote; everything else is local and quick. */
+const NETWORK_TIMEOUT_MS = 120_000;
+const NO_ORIGIN = '没有名为 origin 的远程仓库';
+async function hasHead(spawn, root) {
+    const result = await runGit(spawn, root, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+    return result.exitCode === 0;
+}
+/**
+ * Stage files, deletions included.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param paths - files to stage.
+ */
+export async function stage(spawn, root, paths) {
+    if (paths.length === 0)
+        return;
+    await mustGit(spawn, root, ['add', '-A', '--', ...paths], '暂存失败');
+}
+/**
+ * Take files out of the index, keeping their changes in the working tree.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param paths - files to unstage.
+ */
+export async function unstage(spawn, root, paths) {
+    if (paths.length === 0)
+        return;
+    // Before the first commit there is no HEAD to reset to, so unstaging means removing.
+    const args = (await hasHead(spawn, root))
+        ? ['reset', '-q', 'HEAD', '--', ...paths]
+        : ['rm', '--cached', '-r', '-q', '--', ...paths];
+    await mustGit(spawn, root, args, '取消暂存失败');
+}
+/**
+ * Throw away working-tree changes: tracked files go back to their staged version, untracked
+ * files are deleted.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param target - tracked and untracked files to discard.
+ */
+export async function discard(spawn, root, target) {
+    if (target.tracked.length > 0) {
+        await mustGit(spawn, root, ['checkout', '-q', '--', ...target.tracked], '撤销更改失败');
+    }
+    if (target.untracked.length > 0) {
+        await mustGit(spawn, root, ['clean', '-f', '-q', '--', ...target.untracked], '删除未跟踪文件失败');
+    }
+}
+/**
+ * Commit exactly the selected files, as they are in the working tree. Files that were staged
+ * but not selected stay staged for a later commit, which spares the user the unstage-and-
+ * confirm step a commit of the whole index would need.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param change - the message and the files to commit.
+ */
+export async function commit(spawn, root, change) {
+    if (change.message.trim() === '')
+        throw new GitError('请填写提交信息');
+    if (change.paths.length === 0)
+        throw new GitError('请选择要提交的文件');
+    // `commit -- <paths>` only takes files git already knows, so new files are added first.
+    await stage(spawn, root, change.paths);
+    await mustGit(spawn, root, ['commit', '-q', '-F', '-', '--', ...change.paths], {
+        failure: '提交失败',
+        input: change.message,
+    });
+}
+async function hasOrigin(spawn, root) {
+    const result = await runGit(spawn, root, ['remote']);
+    return result.stdout.split('\n').includes('origin');
+}
+/**
+ * Push the current branch. A branch without an upstream is pushed to origin and tracks it.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ */
+export async function push(spawn, root) {
+    const signal = AbortSignal.timeout(NETWORK_TIMEOUT_MS);
+    const upstream = await runGit(spawn, root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+    if (upstream.exitCode === 0) {
+        await mustGit(spawn, root, ['push'], { failure: '推送失败', signal });
+        return;
+    }
+    if (!(await hasOrigin(spawn, root)))
+        throw new GitError(`推送失败：${NO_ORIGIN}`);
+    await mustGit(spawn, root, ['push', '-u', 'origin', 'HEAD'], { failure: '推送失败', signal });
+}
+/**
+ * Pull the current branch, fast-forward only: a merge or a rebase needs decisions the panel
+ * cannot ask for, so those are left to the terminal.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ */
+export async function pull(spawn, root) {
+    const signal = AbortSignal.timeout(NETWORK_TIMEOUT_MS);
+    await mustGit(spawn, root, ['pull', '--ff-only'], { failure: '拉取失败', signal });
+}
+async function validBranch(spawn, root, name) {
+    const result = await runGit(spawn, root, ['check-ref-format', '--branch', name]);
+    if (name.startsWith('-') || result.exitCode !== 0)
+        throw new GitError(`分支名称无效：${name}`);
+}
+/**
+ * Switch to a branch. A remote branch is checked out as a local branch that tracks it,
+ * unless a local branch of that name exists already.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param branch - the branch, and whether it names a remote branch such as `origin/main`.
+ */
+export async function checkout(spawn, root, branch) {
+    await validBranch(spawn, root, branch.name);
+    const local = branch.remote ? branch.name.slice(branch.name.indexOf('/') + 1) : branch.name;
+    const exists = await runGit(spawn, root, ['show-ref', '--verify', '--quiet', `refs/heads/${local}`]);
+    const args = branch.remote && exists.exitCode !== 0 ? ['switch', '--track', branch.name] : ['switch', local];
+    await mustGit(spawn, root, args, '切换分支失败');
+}
+/**
+ * Create a branch from HEAD and switch to it.
+ * @param spawn - the subprocess service's spawn.
+ * @param root - the repository's top level.
+ * @param name - the new branch's name.
+ */
+export async function createBranch(spawn, root, name) {
+    await validBranch(spawn, root, name);
+    await mustGit(spawn, root, ['switch', '-c', name], '新建分支失败');
+}

package/lib/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Host plugin: registers each configured CLI as a model provider and wires the
+ * session registry to the harness.
+ * @module dsh-ccgui
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ImageRef } from './prompt-images.ts';
+import type { GitConnection, GitWebServer } from './git/git-routes.ts';
+import type { CliAgentConfig } from './session-registry.ts';
+export type { CliAgentConfig } from './session-registry.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        cliBridge: CliBridge;
+        /** Provided by the harness's boot layer. */
+        dshHomePath?: (...segments: string[]) => string;
+        /**
+         * The harness's attachment store (`@deepseek-ai/dsh-attachment`), narrowed to the one
+         * call this plugin makes so the package does not have to depend on it.
+         */
+        attachments?: {
+            readImage(ref: ImageRef, signal?: AbortSignal): Promise<{
+                data: Uint8Array;
+            }>;
+        };
+        /** The harness's web server and its trust check, narrowed to what the git routes use. */
+        webServer: GitWebServer;
+        connection: GitConnection;
+    }
+}
+/** Plugin configuration. */
+export interface Config {
+    agents: CliAgentConfig[];
+    /** Signal-escalation grace when stopping a CLI, in milliseconds. */
+    disposeGraceMs: number;
+    /** Time after stdin EOF for a CLI to exit by itself, in milliseconds. */
+    disposeEofGraceMs: number;
+    /** Time a cancelled CLI may take to end its turn before it is abandoned, in milliseconds. */
+    cancelGraceMs: number;
+    /** Time a CLI may take to start and accept a session, which must allow for a cold `npx` download. */
+    startTimeoutMs: number;
+}
+/** Service behind `ctx.cliBridge`. */
+export default class CliBridge extends Service {
+    private readonly config;
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly registry;
+    private readonly catalog;
+    /** Ends any model probe still running when this plugin goes away. */
+    private readonly probes;
+    constructor(ctx: Context, config: Config);
+    /** Read in the background: the menu works without it, and fills in once it arrives. */
+    private restoreModels;
+    /** The harness's home, or `~/.dsh` when it does not say. */
+    private homePath;
+    /**
+     * The 变更 panel's git routes. Taken as optional dependencies: a harness without a web
+     * server (a headless run) still gets the CLIs, just not the panel's backend.
+     */
+    private serveGit;
+    private registerRoutes;
+    private followSessions;
+    private ask;
+    private openTransport;
+    /**
+     * The temporary session goes in a directory of its own, away from the user's projects.
+     * Some CLIs keep a folder per working directory even for a deleted session, so this one
+     * never changes: a new directory on every start would add a folder each time. It is under
+     * the harness's home rather than the system temp directory, where on a shared machine
+     * another user could plant a project config at a predictable path for a CLI to load.
+     */
+    private probeProvider;
+    /** Looked up on each read: the attachment service can come and go while the plugin runs. */
+    private readImage;
+    private createSession;
+}