@hunan36/dsh-git-flow 0.0.0-stage → 0.4.0

package/lib/types/git.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Git process seam: one argument-array runner over `ctx.subprocess` plus the
+ * porcelain parsers the plugin needs. Nothing here touches the network or
+ * accepts a shell string, so a path from the browser can never become a
+ * command line.
+ */
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+/** Structured failure codes; the browser half turns them into copy. */
+export type GitErrorCode = 'git/not-installed' | 'git/not-a-repository' | 'git/timeout' | 'git/failed' | 'git/dirty-worktree' | 'git/detached-head' | 'git/invalid-input' | 'git/no-files-selected' | 'git/no-route' | 'git/develop-missing' | 'git/merge-conflict' | 'git/tag-exists' | 'git/gitflow-branch-required';
+/** A git operation that cannot be represented as a normal exit code. */
+export declare class GitError extends Error {
+    readonly code: GitErrorCode;
+    constructor(code: GitErrorCode, message: string);
+}
+/** One completed git invocation. */
+export interface GitResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** Turn `git status --porcelain=v2 --branch -z` into the facts the UI renders. */
+export interface GitStatus {
+    /** Branch name, `'(detached)'` when detached, `'(unknown)'` in an empty repo. */
+    head: string;
+    oid: string;
+    /** Upstream ref name, when the branch tracks one. */
+    upstream?: string;
+    /** Commits ahead of / behind the upstream, when it tracks one. */
+    ahead: number;
+    behind: number;
+    /** Tracked changes plus untracked paths. */
+    files: GitFileEntry[];
+}
+/** One changed path in the worktree or index. */
+export interface GitFileEntry {
+    /** Repository-relative path; for a rename this is the new path. */
+    path: string;
+    /** Renamed-from path, present only for `R` entries. */
+    oldPath?: string;
+    /** Index-vs-HEAD code (`'.'` when clean there). */
+    indexStatus: string;
+    /** Worktree-vs-index code (`'.'` when clean there). */
+    worktreeStatus: string;
+    /** True when the path already has staged content. */
+    staged: boolean;
+    /** True for `??` records. */
+    untracked: boolean;
+    /** True for `u` records. */
+    conflicted: boolean;
+}
+/**
+ * Run git without a shell and without ambient credentials leaking in.
+ * One instance per service; the executable is resolved lazily and cached.
+ */
+export declare class GitRunner {
+    private readonly subprocess;
+    private readonly timeoutMs;
+    private executable;
+    constructor(subprocess: SubprocessRuntime, timeoutMs: number);
+    private program;
+    /**
+     * @param cwd - directory the command runs in.
+     * @param args - git subcommand and flags; never interpolated into a shell.
+     * @returns exit code and collected streams; a non-zero exit is a result.
+     * @throws {GitError} when git is missing, the run times out, or spawn fails.
+     */
+    run(cwd: string, args: readonly string[]): Promise<GitResult>;
+    /** Run git and treat a non-zero exit as a `git/failed` error. */
+    runOk(cwd: string, args: readonly string[]): Promise<GitResult>;
+}
+/** Trim git's stderr into one line suitable for a UI detail message. */
+export declare function describeFailure(args: readonly string[], result: GitResult): string;
+/**
+ * Parse `git status --porcelain=v2 --branch -z`.
+ *
+ * The `-z` form is the only one whose paths can be trusted: in the line-based
+ * form git C-quotes any path holding a non-ASCII byte, a double quote, or a
+ * backslash, so a Chinese file name arrives as `"docs/00-\350\265\204..."`
+ * with the quotes and escapes intact. Handing that text back to git as a
+ * pathspec fails with `pathspec ... did not match any files`, which is why
+ * committing a Chinese-named file used to break. `-z` terminates every record
+ * (headers included) with NUL and never quotes a path.
+ * @param stdout - raw porcelain output.
+ * @returns branch facts and one entry per changed path.
+ */
+export declare function parseStatus(stdout: string): GitStatus;

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * dsh-git-flow, node half. The bundle patch mounts {@link GitFlow} as
+ * `ctx.gitFlow`; it provides the workspace git operations and registers
+ * `/api/dsh-git-flow/*` on the web profile. The browser half ships through
+ * `exports['./client']` and the package.json `dsh.client` declaration.
+ * @module dsh-git-flow
+ */
+import { GitFlow } from './service.ts';
+export { GitFlow };
+export default GitFlow;
+export type { GitFlowConfig } from './service.ts';
+export type * from './contract.ts';

package/lib/types/message.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AI commit messages: one auxiliary model call over the selected diff, riding
+ * the route the session's own conversation already used (the same way session
+ * titles are produced), with a template fallback so the panel never blocks.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { GitFileView, GitMessageView } from './contract.ts';
+import type { Session } from '@deepseek-ai/dsh-session';
+/** Everything the prompt needs, already gathered by the service. */
+export interface CommitMessageInput {
+    ctx: Context;
+    /** Live session for this request id; its logged header supplies the route. */
+    session: Session | undefined;
+    language: 'zh' | 'en';
+    head: string;
+    selected: readonly string[];
+    files: readonly GitFileView[];
+    diff: string;
+    truncated: boolean;
+}
+/**
+ * Produce one commit message for the selection.
+ * @throws {GitError} `git/no-route` when the session has no logged model route.
+ * @returns the message plus whether the template fallback had to be used, and
+ * why it was, so the panel can report a broken route instead of a vague notice.
+ */
+export declare function generateCommitMessage(input: CommitMessageInput): Promise<GitMessageView>;

package/lib/types/routes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `/api/dsh-git-flow/*` — the browser half's only door into git. Requests carry
+ * a session id and nothing else; the service derives the repository from the
+ * session's registered workspace, so a page can never name a directory.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { GitFlow } from './service.ts';
+/**
+ * Register every route on the mounted context.
+ * @param ctx - context that already sees `webServer`.
+ * @param service - the git surface to expose.
+ * @returns a disposer removing all routes.
+ */
+export declare function registerGitFlowRoutes(ctx: Context, service: GitFlow): () => void;

package/lib/types/service.d.ts

@@ -0,0 +1,178 @@
+/**
+ * `ctx.gitFlow` — the workspace git surface behind `/api/dsh-git-flow/*`.
+ * Every operation is keyed by session id: the repository directory is resolved
+ * by the host from the session's workspace, so the browser can never name a
+ * path for git to run in.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { GitBranchesView, GitCommitView, GitFlowFinishView, GitFlowKind, GitFlowStateView, GitMessageView, GitStatusView, MessageLanguage } from './contract.ts';
+export type { MessageLanguage };
+/** Mountable configuration. */
+export interface GitFlowConfig {
+    /** Deadline for read-only and local git commands. */
+    timeoutMs?: number;
+    /** Deadline for `git push`, which waits on a remote. */
+    pushTimeoutMs?: number;
+    /** Upper bound on diff bytes handed to the model. */
+    messageMaxDiffBytes?: number;
+    /** Default commit message language; the commit panel can override it per call. */
+    messageLanguage?: MessageLanguage;
+    /** Branch every release and hotfix is merged back into. */
+    productionBranch?: string;
+    /** Integration branch features start from and merge back into. */
+    developBranch?: string;
+    featurePrefix?: string;
+    releasePrefix?: string;
+    hotfixPrefix?: string;
+    /** Prefix of the tag a finished release or hotfix creates. */
+    tagPrefix?: string;
+}
+/**
+ * Branch switching, panel-scoped commits, pushes, and AI commit messages for
+ * the session's workspace.
+ */
+export declare class GitFlow extends Service {
+    /**
+     * `workspaceRegistry` is read through `ctx.get` rather than declared here: a
+     * profile without one (the shipped `headless` profile) must still activate
+     * this entry instead of reporting a permanently pending plugin. Every git
+     * call in such a profile answers `git/not-a-repository`, since no session can
+     * resolve a repository.
+     */
+    static inject: string[];
+    static Config: z<GitFlowConfig>;
+    private readonly config;
+    private readonly git;
+    /** Remote-waiting calls (push, pull) outlive the default runner deadline, so the runner is per-call-site. */
+    private readonly remoteGit;
+    constructor(ctx: Context, config?: GitFlowConfig);
+    /**
+     * @param sessionId - session whose workspace backs the repository.
+     * @returns branch, ahead/behind, and one row per changed path.
+     */
+    status(sessionId: string): Promise<GitStatusView>;
+    /**
+     * @param sessionId - session whose workspace backs the repository.
+     * @returns local and remote-tracking branch rows, current one flagged.
+     */
+    branches(sessionId: string): Promise<GitBranchesView>;
+    /**
+     * Switch branches, optionally creating a local branch for a unique remote one.
+     * @param sessionId - session whose workspace backs the repository.
+     * @param name - branch to check out.
+     * @param force - discard conflicting worktree changes; never used silently.
+     */
+    checkout(sessionId: string, name: string, force?: boolean): Promise<GitStatusView>;
+    /**
+     * Create one branch from `base` (default: current HEAD) and switch to it.
+     * @param sessionId - session whose workspace backs the repository.
+     * @param name - new branch name.
+     * @param base - existing ref to start from.
+     */
+    createBranch(sessionId: string, name: string, base?: string): Promise<GitStatusView>;
+    /**
+     * Throw away the worktree and index changes for the selected paths: tracked
+     * paths go back to HEAD (a staged addition is removed from the index and from
+     * disk), and untracked paths are deleted. Destructive by definition, so the
+     * caller confirms first; conflicted paths are refused rather than guessed at.
+     * @param sessionId - session whose workspace backs the repository.
+     * @param files - paths as reported by {@link status}; anything else is rejected.
+     */
+    discard(sessionId: string, files: readonly string[]): Promise<GitStatusView>;
+    /**
+     * Stage exactly the selected paths, commit them, and optionally push.
+     * @param sessionId - session whose workspace backs the repository.
+     * @param files - paths as reported by {@link status}; anything else is rejected.
+     * @param message - commit message text.
+     * @param push - push the resulting commit to the branch upstream.
+     */
+    commit(sessionId: string, files: readonly string[], message: string, push?: boolean): Promise<GitCommitView>;
+    /**
+     * Push the current branch to its upstream. Never force, and never to a
+     * caller-supplied remote or refspec.
+     * @param sessionId - session whose workspace backs the repository.
+     * @returns git's push summary.
+     */
+    push(sessionId: string): Promise<string>;
+    /**
+     * Pull the current branch's upstream with `--ff-only`: a fast-forward is the
+     * only allowed outcome, so a diverged branch fails instead of producing a
+     * merge commit or rewriting local commits. This is the plugin's one
+     * user-initiated network call outside push; nothing fetches in the background.
+     * @param sessionId - session whose workspace backs the repository.
+     * @returns git's pull summary.
+     */
+    pull(sessionId: string): Promise<string>;
+    /** The resolved branch layout, as the panel renders it. */
+    private layout;
+    /**
+     * Describe the flow state of the current branch: which family it belongs to,
+     * the version its name carries, whether the branches a run needs exist, and
+     * whether the tag a finish would create is already taken.
+     * @param sessionId - session whose workspace backs the repository.
+     */
+    gitflowState(sessionId: string): Promise<GitFlowStateView>;
+    /**
+     * Create a flow branch from the branch its family starts at and switch to it.
+     * A missing develop is reported as `git/develop-missing` so the panel can
+     * offer to create it rather than dead-ending on a raw git failure.
+     * @param sessionId - session whose workspace backs the repository.
+     * @param kind - branch family to start.
+     * @param name - name inside the family, without the prefix.
+     */
+    startFlow(sessionId: string, kind: GitFlowKind, name: string): Promise<GitStatusView>;
+    /**
+     * Create the develop branch from the production branch and switch to it.
+     * Only offered when develop is missing; an existing one is left untouched.
+     * @param sessionId - session whose workspace backs the repository.
+     */
+    initDevelop(sessionId: string): Promise<GitStatusView>;
+    /**
+     * Finish the current flow branch: merge it back (`--no-ff`), tag a release or
+     * hotfix, write its version, push, and delete the branch.
+     *
+     * Every check that can fail without side effects runs first: the worktree is
+     * clean, the merge would not conflict, and the tag is free. Past that point
+     * steps are not rolled back, because each one is a committed fact; a failure
+     * reports which step stopped the run and leaves the repository as it stands.
+     * @param sessionId - session whose workspace backs the repository.
+     * @param version - `package.json` version to write, release and hotfix only.
+     */
+    finishFlow(sessionId: string, version?: string): Promise<GitFlowFinishView>;
+    /** Merge one branch into a target with a merge commit, refusing on conflict. */
+    private mergeInto;
+    /** Push each merged target and the new tag; the first failure is reported, not thrown. */
+    private pushFinished;
+    /** Write `version` into the root `package.json`; a non-Node repo skips it. */
+    private writeVersion;
+    /** Version currently declared by the root package.json, when there is one. */
+    private currentVersion;
+    private countAhead;
+    private tagExists;
+    /**
+     * Ask the session's own model route for a commit message over the selected diff.
+     * @param sessionId - session whose workspace and route back the call.
+     * @param files - paths as reported by {@link status}.
+     * @param language - per-call override for the configured message language.
+     */
+    generateMessage(sessionId: string, files: readonly string[], language?: MessageLanguage): Promise<GitMessageView>;
+    /** Collect the selected diff without staging anything. */
+    private collectDiff;
+    /** Repository top level for one session's workspace. */
+    private resolveRepo;
+    private resolveWorkspace;
+    /**
+     * Keep only the selected paths whose staged content differs from HEAD.
+     * `add -A` has just run, so the index is the truth; a path that resolves to
+     * the HEAD blob (reverted, or touched between the status snapshot and now)
+     * would make `commit --only` reject the entire commit.
+     * @returns pathspecs in the same order git reported them, `-z` so a non-ASCII
+     * name is never C-quoted.
+     */
+    private changedInIndex;
+    private hasLocalBranch;
+    private remoteBranches;
+    private runSwitch;
+}

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@hunan36/dsh-git-flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Workspace git branch switcher, commit composer with AI-written messages, and push for DeepSeek Harness",
+  "keywords": [
+    "dsh",
+    "deepseek",
+    "deepseek-harness",
+    "plugin",
+    "dsh-plugin",
+    "git",
+    "branch",
+    "commit"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-session"
+      ]
+    }
+  },
+  "packageManager": "pnpm@10.22.0",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-workspace": "0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@types/node": "^22.19.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.7",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "watch": "tsdown --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}