dsh-git-branch-manage 1.0.10 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# 变更日志
+
+本文件记录 `dsh-git-branch-manage` 的重要变更。版本号遵循语义化版本。
+
+## [1.2.0] - 2026-11-02
+
+### 新增
+
+- **凭据管理直接读写本机 `~/.git-credentials`**（决策 0037）：面板里存一次，任何 shell、任何子进程的 `git push/fetch/pull` 都用同一账号；文件里不属于本插件的行（注释、`ssh://` 等）原样保留，卸载插件后凭据仍属于用户。
+- **从本机导入凭据，启动时默认执行**（决策 0038）：按用户 gitconfig 里声明过的 credential 域名逐个探测（`git credential fill`，串行 + 20 秒超时），答出令牌即导入面板；面板另有手动「从本机导入」入口（`POST /credentials-import`），toast 汇总导入/跳过/失败数量。`gh`、GCM、`store` 里的账号一次导入即可接管。
+
+### 变更
+
+- 凭据生效通道改用 git 原生机制：`~/.gitconfig` 幂等追加一行 `[include]` 指向生成的 URL 作用域配置（每个已存域名重置 helper 链后装内置 `store`），不再向进程环境注入（废弃 0032/0034 的 `GIT_CONFIG_*` / `GIT_CONFIG_GLOBAL` 通道），令牌也不再进入命令行参数。
+- 未管理域名的机器原有 helper（gh、GCM 等）保持原样，不再被全局清空；未存域名依旧 fail-fast 不弹窗。
+- 令牌明文落在 `~/.git-credentials`（0600）——与 git 自带 `store` helper 一致的安全取舍；面板列表元数据（`method`/`updatedAt`）另存不含 secret 的旁文件。
+
+### 移除
+
+- 删除自研 `git-credential-bridge` helper，改用 git 内置 `credential-store`，不再为每次 git 调用拉起 node 进程。
+
+## [1.1.0] - 2026-11-02
+
+### 修复
+
+- **宿主里的 `git` 命令全部 `fatal`**（`fatal: unable to parse command-line config`）：0032 的 `GIT_CONFIG_KEY/VALUE_*` 环境注入被 DeepSeek Harness 的子进程环境清洗（按 `/KEY|PASSWORD|SECRET|TOKEN/i` 过滤变量名、并剥掉 `DSH_*` 前缀）半剥离——`KEY_n` 被删、`COUNT/VALUE_n` 幸存。改用 `GIT_CONFIG_GLOBAL` 指向一份会话临时 gitconfig 注入凭据（决策 0034）。
+- **shell 里的 `git` 走本机 gh 账号而非面板令牌**：会话配置用 URL 作用域的空 `helper` 重置，清掉 `~/.gitconfig` 里 `[credential "https://github.com"]` 的 gh helper，让已配置域名命中面板令牌。
+- **未配置域名弹 GCM 凭据对话框 / 挂死**：全局空 `helper` 清空机器 helper 链，未配置域名 `exit 128` 快速失败，不再弹窗。
+- **含空格的 node/helper 路径调用失败**（`sh: C:/Program: No such file or directory`）：`gitconfigEscape` / `shellQuote` 正确转义引号与反斜杠。
+
+### 变更
+
+- 新增 `createCredentialService`，把凭据入口收敛为单一服务（`store` / `authConfigArgs` / `refreshShellEnv` / `dispose`）；routes、`git_network`、密钥工具统一经它取 store 与注入通道（决策 0034）。
+- 桥 helper 环境变量改 `DGB_*` 命名（`DGB_BRIDGE_HELPER` 等），避开 DSH 环境清洗。
+- 新增真实 `git` 端到端回归测试（`shell-bridge-e2e`）：验证已配置域名命中桥令牌、空格路径正确调用、未配置域名快速失败。
+
+## [1.0.10] - 2026-10-30
+
+- shell 里的 `git push` 也走插件密钥（环境变量桥，决策 0032）。注：该注入通道在 DeepSeek Harness 宿主中失效，已由 1.1.0 修正（决策 0034）。
+
+更早版本见 [GitHub Releases](https://github.com/GaoHu1997/dsh-git-branch/releases)。

package/lib/client.js

@@ -144,6 +144,9 @@ window.__ModuleLoader__.load({
 		/** POST ROUTE_PREFIX/credentials-oauth-poll — poll a started browser sign-in;
 		* stores the token and answers the fresh masked list once the user approves. */
 		const ROUTE_CREDENTIALS_OAUTH_POLL = `${ROUTE_PREFIX}/credentials-oauth-poll`;
+		/** POST ROUTE_PREFIX/credentials-import — copy the credentials the machine's
+		* own helpers already answer for into the managed store (decision 0038). */
+		const ROUTE_CREDENTIALS_IMPORT = `${ROUTE_PREFIX}/credentials-import`;
 		/** POST ROUTE_PREFIX/remotes — the repository's configured remotes. */
 		const ROUTE_REMOTES = `${ROUTE_PREFIX}/remotes`;
 		/** POST ROUTE_PREFIX/remote — add, re-point or remove ONE remote. */
@@ -508,6 +511,16 @@ window.__ModuleLoader__.load({
 			return post(ROUTE_CREDENTIALS_OAUTH_POLL, body);
 		}
 		/**
+		* Adopt the credentials this machine's own git helpers already answer for
+		* (gh, Windows Credential Manager, Keychain) into the plugin's store. Hosts
+		* the panel already manages are skipped; a host whose helper had nothing is
+		* reported per host, never as a request failure.
+		* @param body - `{}` (probe what the gitconfig names) or `{ hosts }`.
+		*/
+		function requestImportCredentials(body = {}) {
+			return post(ROUTE_CREDENTIALS_IMPORT, body);
+		}
+		/**
 		* The repository's configured remotes (fetch/push URLs).
 		* @param repoPath - absolute directory inside the repository.
 		*/
@@ -4784,6 +4797,10 @@ window.__ModuleLoader__.load({
 			const [seed, setSeed] = (0, react.useState)();
 			const [formError, setFormError] = (0, react.useState)();
 			const [busy, setBusy] = (0, react.useState)(false);
+			/** The one-click machine import runs on its own flag: it is read-only on the
+			* form, so it must not disable editing, and a slow helper (a cold keychain
+			* prompt) must not look like a hung save. */
+			const [importing, setImporting] = (0, react.useState)(false);
 			/** Two-step delete: the first click only arms the row. */
 			const [confirmHost, setConfirmHost] = (0, react.useState)();
 			/** The editor starts collapsed; the "+" icon in the header row opens it,
@@ -5006,6 +5023,34 @@ window.__ModuleLoader__.load({
 				seed,
 				t
 			]);
+			/** Adopt what this machine's own git helpers already answer for. The host
+			* decides which hosts to probe (the user's gitconfig names them) and skips
+			* the ones the panel already manages, so this is always safe to click. */
+			const importLocal = (0, react.useCallback)(async () => {
+				if (busy || importing) return;
+				setImporting(true);
+				const result = await requestImportCredentials();
+				setImporting(false);
+				if (!result.ok) {
+					pushToast(result.error, "error");
+					return;
+				}
+				setEntries(result.credentials);
+				if (result.imported.length === 0) {
+					pushToast(t("cred.importNone"), result.failed.length === 0 ? "success" : "error");
+					return;
+				}
+				pushToast(t("cred.importDone", {
+					count: result.imported.length,
+					skipped: result.skipped.length,
+					failed: result.failed.length
+				}), "success");
+			}, [
+				busy,
+				importing,
+				pushToast,
+				t
+			]);
 			const title = seed === void 0 ? t("cred.add") : t("cred.edit");
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(_deepseek_ai_dsh_client_ui_primitives.Modal, {
 				open: true,
@@ -5021,21 +5066,34 @@ window.__ModuleLoader__.load({
 				children: [
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: GitHistoryPanel_module_default.credTop,
-						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-							className: GitHistoryPanel_module_default.credHint,
-							children: t("cred.hint")
-						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-							type: "button",
-							className: GitHistoryPanel_module_default.credAdd,
-							title: t("cred.add"),
-							"aria-label": t("cred.add"),
-							"aria-expanded": editorOpen,
-							onClick: openNew,
-							children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-								"aria-hidden": "true",
-								children: "+"
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: GitHistoryPanel_module_default.credHint,
+								children: t("cred.hint")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+								size: "sm",
+								variant: "ghost",
+								disabled: busy || importing,
+								title: t("cred.import"),
+								onClick: () => {
+									importLocal();
+								},
+								children: importing ? t("cred.importing") : t("cred.import")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: GitHistoryPanel_module_default.credAdd,
+								title: t("cred.add"),
+								"aria-label": t("cred.add"),
+								"aria-expanded": editorOpen,
+								onClick: openNew,
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									"aria-hidden": "true",
+									children: "+"
+								})
 							})
-						})]
+						]
 					}),
 					loadError !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 						className: GitHistoryPanel_module_default.formError,
@@ -8432,7 +8490,7 @@ window.__ModuleLoader__.load({
 			"accel.mirrorDownHint": "If the mirror is down, disable acceleration or change the URL",
 			"panel.credentials": "Credentials",
 			"cred.title": "Git credentials",
-			"cred.hint": "Global, one entry per host: a token saved for github.com serves every repository. Stored only on this machine in git-credentials.json.",
+			"cred.hint": "One entry per host, shared by all repos. Stored in ~/.git-credentials, so plain git uses it too.",
 			"cred.empty": "No credentials saved yet",
 			"cred.hostLabel": "Host",
 			"cred.hostPlaceholder": "github.com",
@@ -8447,6 +8505,10 @@ window.__ModuleLoader__.load({
 			"cred.methodPassword": "Password",
 			"cred.getToken": "Get a token",
 			"cred.add": "Add credential",
+			"cred.import": "Import from this machine",
+			"cred.importing": "Importing…",
+			"cred.importDone": "Imported {count} host(s) — skipped {skipped}, failed {failed}",
+			"cred.importNone": "Nothing new to import from this machine",
 			"cred.edit": "Edit",
 			"cred.save": "Save",
 			"cred.saving": "Saving…",
@@ -8718,7 +8780,7 @@ window.__ModuleLoader__.load({
 			"accel.mirrorDownHint": "若加速地址不可用，可停用国内加速或更换地址",
 			"panel.credentials": "密钥配置",
 			"cred.title": "Git 密钥配置",
-			"cred.hint": "全局生效：同一域名只需配置一次，该域名的所有仓库共用。密钥只保存在本机 git-credentials.json 中。",
+			"cred.hint": "按域名保存，所有仓库共用；密钥写入本机 ~/.git-credentials，命令行 git 同样生效。",
 			"cred.empty": "还没有配置任何密钥",
 			"cred.hostLabel": "域名",
 			"cred.hostPlaceholder": "github.com",
@@ -8733,6 +8795,10 @@ window.__ModuleLoader__.load({
 			"cred.methodPassword": "密码",
 			"cred.getToken": "获取令牌",
 			"cred.add": "新增密钥",
+			"cred.import": "从本机导入",
+			"cred.importing": "导入中…",
+			"cred.importDone": "已导入 {count} 个域名（跳过 {skipped}，失败 {failed}）",
+			"cred.importNone": "本机没有新的凭据可导入",
 			"cred.edit": "编辑",
 			"cred.save": "保存",
 			"cred.saving": "保存中…",

package/lib/credential-service.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The one entry point every credential channel goes through (decision 0037).
+ *
+ * The store is the machine's own `~/.git-credentials` (git's
+ * `credential-store` format), plus a secret-free metadata sidecar for the
+ * panel's "method / updated" columns. Every channel — the panel routes, both
+ * model-facing tools, and a plain `git` command in any shell — authenticates
+ * through the same `credential-store` helper, because `createShellBridge`
+ * installs a URL-scoped `helper = store` include into `~/.gitconfig`.
+ *
+ * `createCredentialService` owns the store instance and the include setup, so
+ * callers share one contract:
+ *
+ *  - {@link CredentialService.refreshShellEnv} — re-derive the include after a
+ *    store change and run the one-time legacy import. Call it after every save
+ *    / delete / sign-in; it never throws.
+ *  - {@link CredentialService.dispose} — remove the include line and the
+ *    generated file on plugin teardown. The credentials themselves stay in
+ *    `~/.git-credentials`: they belong to the user, not to the plugin.
+ *
+ * A store that cannot be read degrades to "no credentials" on every channel
+ * (an unauthenticated command runs as it always did; the credentials route is
+ * where the file problem surfaces) — a broken file must never break git.
+ */
+import { type CredentialStore } from './credentials.js';
+import { type LocalImportReport } from './local-import.js';
+/** Host-side seams the service reads through (tests substitute all of them). */
+export interface CredentialServiceDeps {
+    /** User home directory seam. */
+    readonly home: () => string;
+    /** `$DSH_HOME` seam (blank/undefined = unset). */
+    readonly envHome: () => string | undefined;
+    /** Store seam; the fs-backed local store when absent. */
+    readonly store?: CredentialStore;
+    /** The environment object to mutate; `process.env` when absent. */
+    readonly env?: Record<string, string | undefined>;
+    /** User global config the generated include is installed into;
+     * `<home>/.gitconfig` when absent. */
+    readonly userGitconfig?: string;
+}
+/** The single credential entry point. */
+export interface CredentialService {
+    /** The shared global store (one row per remote host). */
+    readonly store: CredentialStore;
+    /**
+     * Import the retired plugin-private file (once) and re-derive the git
+     * include after a credential changed, so a message sent in the same session
+     * can `git push` with the token the user just saved. Never throws: the worst
+     * case is a stale include until the next refresh.
+     */
+    readonly refreshShellEnv: () => Promise<void>;
+    /**
+     * Copy the credentials the machine's own helpers already answer for into
+     * the store, once per process (decision 0038). Runs on startup so a machine
+     * already signed in through gh / GCM / Keychain keeps working without the
+     * user re-entering a token here. Idempotent, never throws; the hosts that
+     * did import trigger one include refresh.
+     */
+    readonly autoImport: () => Promise<LocalImportReport>;
+    /** Remove the fail-fast switches, the include line and the generated file. */
+    readonly dispose: () => Promise<void>;
+}
+/**
+ * Build the credential service for one host process: one store instance, one
+ * gitconfig include, shared by the routes and every tool.
+ * @param deps - host seams (see {@link CredentialServiceDeps}).
+ */
+export declare function createCredentialService(deps: CredentialServiceDeps): CredentialService;

package/lib/credential-service.js

@@ -0,0 +1,85 @@
+/**
+ * The one entry point every credential channel goes through (decision 0037).
+ *
+ * The store is the machine's own `~/.git-credentials` (git's
+ * `credential-store` format), plus a secret-free metadata sidecar for the
+ * panel's "method / updated" columns. Every channel — the panel routes, both
+ * model-facing tools, and a plain `git` command in any shell — authenticates
+ * through the same `credential-store` helper, because `createShellBridge`
+ * installs a URL-scoped `helper = store` include into `~/.gitconfig`.
+ *
+ * `createCredentialService` owns the store instance and the include setup, so
+ * callers share one contract:
+ *
+ *  - {@link CredentialService.refreshShellEnv} — re-derive the include after a
+ *    store change and run the one-time legacy import. Call it after every save
+ *    / delete / sign-in; it never throws.
+ *  - {@link CredentialService.dispose} — remove the include line and the
+ *    generated file on plugin teardown. The credentials themselves stay in
+ *    `~/.git-credentials`: they belong to the user, not to the plugin.
+ *
+ * A store that cannot be read degrades to "no credentials" on every channel
+ * (an unauthenticated command runs as it always did; the credentials route is
+ * where the file problem surfaces) — a broken file must never break git.
+ */
+import { createLocalCredentialStore, migrateLegacyCredentialFile, } from './credentials.js';
+import { createShellBridge } from './shell-bridge.js';
+import { importLocalCredentials } from './local-import.js';
+/**
+ * Build the credential service for one host process: one store instance, one
+ * gitconfig include, shared by the routes and every tool.
+ * @param deps - host seams (see {@link CredentialServiceDeps}).
+ */
+export function createCredentialService(deps) {
+    const store = deps.store ?? createLocalCredentialStore(deps.home(), deps.envHome());
+    const bridgeDeps = {
+        home: deps.home,
+        envHome: deps.envHome,
+        store,
+        ...(deps.env === undefined ? {} : { env: deps.env }),
+        ...(deps.userGitconfig === undefined ? {} : { userGitconfig: deps.userGitconfig }),
+    };
+    const shellBridge = createShellBridge(bridgeDeps);
+    let autoImportTask;
+    return {
+        store,
+        async refreshShellEnv() {
+            try {
+                await migrateLegacyCredentialFile(deps.home(), deps.envHome(), store);
+            }
+            catch {
+                // A damaged legacy file must not block the include refresh; the
+                // credentials route reports it when the user opens the panel.
+            }
+            await shellBridge.apply();
+        },
+        autoImport() {
+            autoImportTask ??= (async () => {
+                try {
+                    // The legacy file migrates first so an imported host cannot
+                    // duplicate a row the panel already had.
+                    await migrateLegacyCredentialFile(deps.home(), deps.envHome(), store);
+                }
+                catch {
+                    // Same contract as refreshShellEnv: a broken legacy file is not
+                    // worth failing the startup import over.
+                }
+                try {
+                    const report = await importLocalCredentials(store, { env: deps.env ?? process.env });
+                    if (report.imported.length > 0)
+                        await shellBridge.apply();
+                    return report;
+                }
+                catch {
+                    // The import is opportunistic: a missing git, an unreadable store
+                    // or a helper that misbehaves just leaves the panel as it was.
+                    return { imported: [], skipped: [], failed: [] };
+                }
+            })();
+            return autoImportTask;
+        },
+        dispose() {
+            return shellBridge.dispose();
+        },
+    };
+}

package/lib/credentials.d.ts

@@ -1,25 +1,36 @@
 /**
- * Global git credential store (host half). Credentials belong to a remote
- * HOST, not to a project: the same `github.com` token serves every repository
- * the panel touches, so the record lives in one file under `$DSH_HOME`
- * (`~/.dsh`) instead of the per-repository settings document. The secret
- * never travels to the browser — the list route answers masked tails only —
- * and the store is read/written by the host alone.
+ * Global git credential store (host half), backed by the machine's own
+ * credential file (decision 0037).
  *
- * Authentication rides `git -c http.https://<host>/.extraHeader=…` on the
- * panel's own network commands and on the `git_network` tool: the user's git
- * configuration FILES are never written. Plain `git` commands in a spawned
- * shell are covered separately by the environment bridge in `shell-bridge.ts`,
- * which installs this store's per-host tokens as URL-scoped credential helpers
- * through `GIT_CONFIG_*` (process environment only, never a config file).
- * Only `https://` remotes receive the header; ssh and plain-http remotes are
- * never sent a secret.
+ * A credential belongs to a remote HOST, not to a project: the same
+ * `github.com` token serves every repository. Up to 1.1.x the plugin kept its
+ * own `~/.dsh/git-credentials.json`, which meant the panel's token was
+ * invisible to a plain `git` run in a shell and the machine's helpers
+ * answered instead (often with a different account). 0037 makes the panel
+ * manage the SAME file git's built-in `credential-store` helper uses —
+ * `~/.git-credentials` — so one save is visible to every git process:
+ *
+ *  - the secret lines are the store format (`https://user:pass@host`),
+ *    percent-encoded exactly as `git credential approve` writes them;
+ *  - method/updatedAt cannot live in that format, so a sibling
+ *    `<dsh-home>/git-credentials.meta.json` keeps the UI-only metadata
+ *    (no secret ever goes in there);
+ *  - a generated `<dsh-home>/git-credentials.include.gitconfig` scopes
+ *    `helper = store` to each managed host, and `~/.gitconfig` gains one
+ *    `[include] path = <that file>` line (idempotent, decision 0037
+ *    overturns 0021's "never write the user's git config" for exactly this
+ *    one scoped include).
+ *
+ * The secret never travels to the browser — the list route answers masked
+ * tails only — and only `https://` remotes are ever covered.
  */
 import type { CredentialMethod } from './wire.js';
 /**
  * The Basic-auth name git sends when a token was stored without a username.
  * GitHub, GitLab and Gitee all accept any non-empty name for a personal access
- * token, and `oauth2` is the conventional placeholder.
+ * token, and `oauth2` is the conventional placeholder. The store format has no
+ * "blank username", so this value is what a blank one becomes on disk and is
+ * read back as blank again.
  */
 export declare const TOKEN_USERNAME = "oauth2";
 /** One stored credential: exactly one per remote host. */
@@ -27,19 +38,19 @@ export interface GitCredential {
     /** Normalized remote host (`github.com`, `git.example.com:8443`). */
     host: string;
     /** Basic-auth username (a real account name, or a vendor-form placeholder
-     * such as `x-access-token` / `oauth2`). */
+     * such as `x-access-token` / `oauth2`). Blank for a bare token. */
     username: string;
     /** Token or password, verbatim (never returned to the client). */
     secret: string;
     /** How the secret is meant to be used — informational for the UI; git
      * itself only sees the Basic header. */
     method: CredentialMethod;
-    /** Epoch millis of the last save. */
+    /** Epoch millis of the last save (0 when unknown). */
     updatedAt: number;
 }
 /** Load/save seam for the credential file (tests substitute an in-memory one). */
 export interface CredentialStore {
-    /** Absolute file the store persists to (for diagnostics/UI hints). */
+    /** Absolute file the store persists secrets to (for diagnostics/UI hints). */
     readonly path: string;
     /** Every stored credential, one per host, sorted by host. A missing file
      * is the empty list; an unreadable/malformed one throws
@@ -54,11 +65,32 @@ export declare class CredentialStoreError extends Error {
     constructor(path: string, message: string);
 }
 /**
- * Resolve the credential file location: `<dsh-home>/git-credentials.json`.
+ * The retired 0021/0029 plugin-private file `<dsh-home>/git-credentials.json`.
+ * Read once by {@link migrateLegacyCredentialFile} and deleted afterwards.
  * @param home - user home directory seam.
  * @param envHome - `$DSH_HOME` environment value seam (blank = unset).
  */
 export declare function credentialFilePath(home: string, envHome: string | undefined): string;
+/**
+ * `~/.git-credentials` — the file git's `credential-store` helper reads and
+ * writes (`$HOME/.git-credentials` on every platform).
+ * @param home - user home directory seam.
+ */
+export declare function gitCredentialsFile(home: string): string;
+/**
+ * The UI-only metadata sidecar: method and `updatedAt` per host. Never holds a
+ * secret; a missing or damaged file only costs the "how/when" columns.
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ */
+export declare function credentialMetaFile(home: string, envHome: string | undefined): string;
+/**
+ * The generated gitconfig included from `~/.gitconfig`: one URL-scoped
+ * `helper = store` section per managed host.
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ */
+export declare function credentialIncludeFile(home: string, envHome: string | undefined): string;
 /** Why a user-typed host is not usable yet (undefined = fine). */
 export type CredentialHostIssue = 'empty' | 'invalid';
 /**
@@ -99,16 +131,6 @@ export declare function credentialSecretIssue(value: string): 'empty' | 'illegal
  * @param secret - the stored secret.
  */
 export declare function maskSecret(secret: string): string;
-/**
- * The git config argv that authenticates network commands against the stored
- * hosts: one `http.<https-url>.extraHeader` per host. Git applies a
- * `http.<url>.*` section only to a matching remote URL, so injecting every
- * stored host at once cannot leak one host's header to another; only
- * `https://` URLs match (ssh/http never receive it).
- * @param entries - stored credentials (duplicates collapsed by host).
- * @returns the `-c <key>=<value>` pairs, ready to prepend to a subcommand.
- */
-export declare function authConfigArgs(entries: readonly GitCredential[]): readonly string[];
 /**
  * Insert or update one credential; the pair `(host, updatedAt)` changes,
  * everything else is replaced. An existing host keeps its position.
@@ -127,22 +149,105 @@ export declare function removeCredential(entries: readonly GitCredential[], host
 /** Stable host order for the file and the UI. */
 export declare function sortCredentials(entries: readonly GitCredential[]): GitCredential[];
 /**
- * Parse the credential file. Unknown extra fields are tolerated (a
- * hand-edited file), but a malformed entry is an error rather than a silent
- * drop — losing a credential behind the user's back is worse than an
- * explicit message. Hosts are re-normalized and de-duplicated.
+ * Percent-encode one userinfo component the way git's store helper does:
+ * everything outside the RFC 3986 unreserved set becomes `%xx` (lowercase
+ * hex, matching `git credential approve`). `encodeURIComponent` would leave
+ * `!'()*` alone and git would then mis-split the line at a literal `@`.
+ * @param value - raw username or secret.
+ */
+export declare function encodeCredentialPart(value: string): string;
+/**
+ * One `<scheme>://user:pass@host` line, ready for `~/.git-credentials`.
+ * @param entry - the credential to write.
+ */
+export declare function formatCredentialLine(entry: GitCredential): string;
+/** A `~/.git-credentials` file split into credentials and untouched lines. */
+export interface ParsedCredentials {
+    /** One credential per https host; a duplicated host keeps the LAST line,
+     * which is the line git's store helper would resolve to after a rewrite. */
+    readonly entries: GitCredential[];
+    /** Lines this store does not own (comments, ssh/http rows, malformed
+     * text). Written back verbatim so a hand-edited file survives a save. */
+    readonly others: string[];
+}
+/**
+ * Parse a `~/.git-credentials` document.
+ * @param text - raw file contents (BOM tolerated).
+ */
+export declare function parseGitCredentials(text: string): ParsedCredentials;
+/**
+ * Parse the retired `<dsh-home>/git-credentials.json`. Unknown extra fields
+ * are tolerated (a hand-edited file), but a malformed entry is an error rather
+ * than a silent drop — losing a credential during the one-time migration is
+ * worse than an explicit message.
  * @param text - raw file contents.
  * @param path - file path (for the error message).
  */
 export declare function parseCredentialFile(text: string, path?: string): GitCredential[];
+/** Write-then-rename so a crashed save never truncates the real file. */
+export declare function writeFileAtomic(path: string, text: string, mode?: number): Promise<void>;
+/**
+ * The real store over `~/.git-credentials`. The secret lines are the git
+ * store format; the sibling metadata file carries method/updatedAt only.
+ * A missing file reads as "no credentials yet".
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ */
+export declare function createLocalCredentialStore(home: string, envHome: string | undefined): CredentialStore;
+/**
+ * One-time 0037 migration: import the retired plugin-private JSON into the
+ * local store (plugin values win for a host they share), then delete the old
+ * file so there is exactly one place a secret lives.
+ *
+ * Idempotent: a missing legacy file is a no-op, and the file is removed only
+ * after the store write succeeded — a failed migration keeps the old file.
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ * @param store - destination store.
+ * @returns true when a legacy file was imported and removed.
+ */
+export declare function migrateLegacyCredentialFile(home: string, envHome: string | undefined, store: CredentialStore): Promise<boolean>;
+/**
+ * The generated include file's contents: one URL-scoped section per host that
+ * resets any inherited helper for that exact URL and then installs the
+ * built-in `store` helper. The empty `helper =` line is what beats a
+ * user-level helper (`gh`, GCM) configured for the same host.
+ * @param hosts - managed remote hosts (already normalized).
+ */
+export declare function credentialIncludeBody(hosts: readonly string[]): string;
+/**
+ * Whether `~/.gitconfig` already includes the generated file. Matched loosely
+ * (any `path = <X>` line pointing at it) so a hand-reformatted include — or
+ * one with forward slashes on Windows — is not added a second time.
+ * @param text - current `~/.gitconfig` contents.
+ * @param includePath - the generated file.
+ */
+export declare function gitconfigHasInclude(text: string, includePath: string): boolean;
+/**
+ * Append the `[include] path = …` section, leaving every existing byte alone.
+ * @param text - current `~/.gitconfig` contents.
+ * @param includePath - the generated file.
+ */
+export declare function appendGitconfigInclude(text: string, includePath: string): string;
+/**
+ * Idempotently ensure `~/.gitconfig` includes the generated file. Rewrites
+ * atomically, preserving the file's existing mode; a missing file is created.
+ * @param gitconfigPath - user global config (`<home>/.gitconfig`).
+ * @param includePath - the generated file.
+ * @returns true when the file had to be changed.
+ */
+export declare function ensureGitconfigInclude(gitconfigPath: string, includePath: string): Promise<boolean>;
 /**
- * Serialize the credential set for the file.
- * @param entries - stored credentials.
+ * Remove the include section pointing at the generated file (plugin teardown).
+ * Every other line is preserved verbatim.
+ * @param text - current `~/.gitconfig` contents.
+ * @param includePath - the generated file.
  */
-export declare function serializeCredentialFile(entries: readonly GitCredential[]): string;
+export declare function stripGitconfigInclude(text: string, includePath: string): string;
 /**
- * The real file-backed store: atomic replace, `0600` where the platform
- * honours it. A missing file reads as "no credentials yet".
- * @param path - absolute credential file path.
+ * Remove the generated include from `~/.gitconfig`. Best effort: a teardown
+ * must not throw, and an already-clean file is left untouched.
+ * @param gitconfigPath - user global config (`<home>/.gitconfig`).
+ * @param includePath - the generated file.
  */
-export declare function createCredentialStore(path: string): CredentialStore;
+export declare function removeGitconfigInclude(gitconfigPath: string, includePath: string): Promise<void>;