dsh-git-branch-manage 1.1.0 → 1.3.0

package/lib/credential-service.d.ts

@@ -1,49 +1,41 @@
 /**
- * The one entry point every credential channel goes through (decision 0034).
+ * The one entry point every credential channel goes through (decision 0037).
  *
- * Before this module the store, the `-c http.<url>.extraHeader` injection
- * (`authConfigArgs`, 0021/0029) and the shell environment bridge
- * (`shell-bridge.ts`, 0032/0034) were assembled in three places — the routes,
- * the two model-facing tools and the plugin entry — each resolving the store
- * path itself. Every future plugin that needs git credentials would have
- * repeated that wiring and drifted from it.
+ * 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 both injection
- * channels, so callers share one contract:
+ * `createCredentialService` owns the store instance and the include setup, so
+ * callers share one contract:
  *
- *  - {@link CredentialService.authConfigArgs} — the `-c extraHeader` pairs for
- *    git commands the plugin itself runs (panel routes, `git_network`). The
- *    token rides the argv of that one command and never an environment.
- *  - {@link CredentialService.refreshShellEnv} — re-derive the session
- *    gitconfig + `GIT_CONFIG_GLOBAL` environment so a plain shell `git push`
- *    authenticates as configured. Call it after every store change.
- *  - {@link CredentialService.dispose} — undo the environment injection and
- *    delete the session config file (plugin teardown).
+ *  - {@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 store at the resolved path when absent. */
+    /** 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>;
-    /** Absolute helper script path; the compiled sibling under `helpers/` when absent. */
-    readonly helperPath?: string;
-    /** Node executable that runs the helper; `process.execPath` when absent. */
-    readonly nodePath?: string;
-    /** Directory for the session config; the OS temp dir when absent. */
-    readonly configDir?: () => string;
-    /** Exact session config path (tests); derived from the pid when absent. */
-    readonly configPath?: string;
-    /** User global config the session file includes; `<home>/.gitconfig` when absent. */
+    /** User global config the generated include is installed into;
+     * `<home>/.gitconfig` when absent. */
     readonly userGitconfig?: string;
 }
 /** The single credential entry point. */
@@ -51,24 +43,26 @@ export interface CredentialService {
     /** The shared global store (one row per remote host). */
     readonly store: CredentialStore;
     /**
-     * `-c http.<url>.extraHeader` pairs for every stored credential, ready to
-     * prepend to a git network command the plugin runs itself. A broken store
-     * degrades to "no credentials" rather than throwing.
+     * 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 authConfigArgs: () => Promise<readonly string[]>;
+    readonly refreshShellEnv: () => Promise<void>;
     /**
-     * Re-derive the shell credential environment 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 environment until the
-     * next refresh.
+     * 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 refreshShellEnv: () => Promise<void>;
-    /** Remove the environment injection and delete the session config file. */
+    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
- * session-gitconfig bridge, shared by the routes and every tool.
+ * 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

@@ -1,53 +1,82 @@
 /**
- * The one entry point every credential channel goes through (decision 0034).
+ * The one entry point every credential channel goes through (decision 0037).
  *
- * Before this module the store, the `-c http.<url>.extraHeader` injection
- * (`authConfigArgs`, 0021/0029) and the shell environment bridge
- * (`shell-bridge.ts`, 0032/0034) were assembled in three places — the routes,
- * the two model-facing tools and the plugin entry — each resolving the store
- * path itself. Every future plugin that needs git credentials would have
- * repeated that wiring and drifted from it.
+ * 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 both injection
- * channels, so callers share one contract:
+ * `createCredentialService` owns the store instance and the include setup, so
+ * callers share one contract:
  *
- *  - {@link CredentialService.authConfigArgs} — the `-c extraHeader` pairs for
- *    git commands the plugin itself runs (panel routes, `git_network`). The
- *    token rides the argv of that one command and never an environment.
- *  - {@link CredentialService.refreshShellEnv} — re-derive the session
- *    gitconfig + `GIT_CONFIG_GLOBAL` environment so a plain shell `git push`
- *    authenticates as configured. Call it after every store change.
- *  - {@link CredentialService.dispose} — undo the environment injection and
- *    delete the session config file (plugin teardown).
+ *  - {@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 { authConfigArgs, createCredentialStore, credentialFilePath, } from './credentials.js';
+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
- * session-gitconfig bridge, shared by the routes and every tool.
+ * gitconfig include, shared by the routes and every tool.
  * @param deps - host seams (see {@link CredentialServiceDeps}).
  */
 export function createCredentialService(deps) {
-    const store = deps.store
-        ?? createCredentialStore(credentialFilePath(deps.home(), deps.envHome()));
-    const bridgeDeps = { ...deps, store };
+    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 authConfigArgs() {
+        async refreshShellEnv() {
             try {
-                return authConfigArgs(await store.load());
+                await migrateLegacyCredentialFile(deps.home(), deps.envHome(), store);
             }
             catch {
-                return [];
+                // A damaged legacy file must not block the include refresh; the
+                // credentials route reports it when the user opens the panel.
             }
+            await shellBridge.apply();
         },
-        refreshShellEnv() {
-            return 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>;