dsh-git-branch-manage 1.0.7 → 1.0.8

package/lib/routes.js

@@ -5,8 +5,10 @@
 import { basename, dirname, join, resolve } from 'node:path';
 import { mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { runPostCreateCopy } from './copy-files.js';
-import { appendWorktreeExclude, fsExcludeSeams, GitError, addWorktree, addWorktreeCutout, collectAiDiff, commitFiles, commitIndex, createBranch, createTag, cutoutBranchName, deleteBranch, fetchAll, fsDirExists, inspectWorktree, isAbsoluteDir, isStageablePath, listTagNames, logHistory, probeRepo, probeWorkspaceGit, pushTag, removeWorktree, renameBranch, resolveBranch, resolvePushRemote, pushBranch, stagePaths, switchBranch, updateBranch, workingChanges } from './git.js';
-import { ACCEL_DEFAULT_URL, accelerateUrlError, isAbsoluteConfigPath, normalizeAccelerateUrl, sanitizeBranchDir } from './normalize.js';
+import { authConfigArgs, credentialFilePath, createCredentialStore, credentialHostIssue, credentialSecretIssue, credentialUsernameIssue, maskSecret, normalizeCredentialHost, removeCredential, sortCredentials, upsertCredential } from './credentials.js';
+import { appendWorktreeExclude, fsExcludeSeams, GitError, addRemote, addWorktree, addWorktreeCutout, collectAiDiff, commitFiles, commitIndex, createBranch, createTag, cutoutBranchName, deleteBranch, fetchAll, fsDirExists, inspectWorktree, isAbsoluteDir, isStageablePath, listRemotes, listTagNames, logHistory, probeRepo, probeWorkspaceGit, pushTag, removeRemote, removeWorktree, renameBranch, resolveBranch, resolvePushRemote, pushBranch, setRemoteUrl, stagePaths, switchBranch, updateBranch, workingChanges } from './git.js';
+import { ACCEL_DEFAULT_URL, accelerateUrlError, isAbsoluteConfigPath, normalizeAccelerateUrl, remoteNameIssue, remoteUrlIssue, sanitizeBranchDir } from './normalize.js';
+import { deviceFlowClientId, isDeviceFlowHost, pollDeviceFlow, startDeviceFlow } from './oauth.js';
 import { resolveRootDir } from './settings.js';
 import { COMMIT_MESSAGE_LIMIT } from './wire.js';
 /** Real fs-backed one-level directory listing (names only). Plain FILES are
@@ -51,6 +53,26 @@ function accelPrefix(deps) {
     const url = deps.sectionCnAccelerateUrl?.() ?? ACCEL_DEFAULT_URL;
     return accelerateUrlError(url) === undefined ? normalizeAccelerateUrl(url) : undefined;
 }
+/** The global credential store: the wired one, else the fs-backed file at the
+ * resolved dsh home (`<dshHome>/git-credentials.json`). */
+function credentialStore(deps) {
+    return deps.credentialsStore ?? createCredentialStore(credentialFilePath(deps.home(), deps.envHome()));
+}
+/**
+ * `-c http.<url>.extraHeader` pairs for every stored credential, ready to
+ * prepend to a git network command. A broken credential FILE must never break
+ * git itself: an unreadable store degrades to "no credentials" (the network
+ * command then runs unauthenticated, as it always did) — the credentials
+ * route is where the file problem surfaces.
+ */
+async function authArgsFor(deps) {
+    try {
+        return authConfigArgs(await credentialStore(deps).load());
+    }
+    catch {
+        return [];
+    }
+}
 /** Upper bound on distinct paths one /group request may probe. */
 const GROUP_PATHS_LIMIT = 256;
 /** Probes per in-flight batch — polite on Windows, where each git call is a
@@ -426,7 +448,7 @@ export async function handleCreateWorktree(deps, body) {
             const resolved = await resolveBranch(deps.exec, facts.repoRoot, branch);
             if (resolved?.remote !== undefined) {
                 try {
-                    await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps));
+                    await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps), await authArgsFor(deps));
                 }
                 catch (error) {
                     fetchWarning = error instanceof GitError ? error.stderr.trim() : error instanceof Error ? error.message : String(error);
@@ -661,7 +683,7 @@ export async function handleFetch(deps, body) {
         const facts = await probeRepo(deps.exec, repoPath, deps.dirExists);
         if (facts === undefined)
             return fail(400, `"${repoPath}" is not inside a git repository`);
-        await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps));
+        await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps), await authArgsFor(deps));
         const result = { remote: 'all' };
         return { status: 200, body: result };
     }
@@ -694,7 +716,7 @@ export async function handleUpdate(deps, body) {
         // session "update current branch" means the branch that worktree holds.
         // `repoRoot` would fast-forward the main checkout behind the user's back
         // (both are the same directory when the session IS the main checkout).
-        const outcome = await updateBranch(deps.exec, facts.toplevel, accelPrefix(deps));
+        const outcome = await updateBranch(deps.exec, facts.toplevel, accelPrefix(deps), await authArgsFor(deps));
         const result = { branch: outcome.branch, updated: outcome.updated };
         return { status: 200, body: result };
     }
@@ -724,7 +746,7 @@ export async function handlePush(deps, body) {
             return fail(400, `"${repoPath}" is not inside a git repository`);
         // The session's OWN worktree, not the main checkout: in a linked-worktree
         // session "push current branch" means the branch that worktree holds.
-        const outcome = await pushBranch(deps.exec, facts.toplevel);
+        const outcome = await pushBranch(deps.exec, facts.toplevel, await authArgsFor(deps));
         const result = { branch: outcome.branch, pushed: outcome.pushed };
         return { status: 200, body: result };
     }
@@ -1156,7 +1178,7 @@ export async function handlePushTag(deps, body) {
         const choice = await resolvePushRemote(deps.exec, facts.toplevel);
         if (!choice.ok)
             return fail(400, choice.message);
-        const result = await pushTag(deps.exec, facts.toplevel, name, choice.remote);
+        const result = await pushTag(deps.exec, facts.toplevel, name, choice.remote, await authArgsFor(deps));
         const body = result;
         return { status: 200, body };
     }
@@ -1252,3 +1274,333 @@ export async function handleAiCommitMessage(deps, llm, body) {
         return checkoutFailure(error);
     }
 }
+/** Masked browser view: the stored secret never crosses the wire again. */
+function credentialView(entry) {
+    return {
+        host: entry.host,
+        username: entry.username,
+        method: entry.method,
+        updatedAt: entry.updatedAt,
+        secretMask: maskSecret(entry.secret),
+    };
+}
+/** Credential-store failures are host-side state (an unreadable/corrupt file,
+ * a failed write), so they answer 500 with the file's own explanation. */
+function storeFailure(error) {
+    return fail(500, error instanceof Error ? error.message : String(error));
+}
+/**
+ * POST /credentials — every stored credential as a MASKED row. One row per
+ * host: the store is global (not per repository), so the panel edits one
+ * address for github.com, gitlab.com, a self-hosted gitea alike.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: absent or `{}`.
+ */
+export async function handleCredentials(deps, body) {
+    const parsed = readBody(body ?? {}, []);
+    if (isOutcome(parsed))
+        return parsed;
+    try {
+        const entries = await credentialStore(deps).load();
+        const result = { credentials: sortCredentials(entries).map(credentialView) };
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        return storeFailure(error);
+    }
+}
+/**
+ * POST /credentials-save — create or update the credential of ONE host. A
+ * blank `secret` on an existing host keeps the stored secret (the browser
+ * only ever had the mask), while a new host requires one.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ host, username, method, secret? }`.
+ */
+export async function handleCredentialsSave(deps, body) {
+    const parsed = readBody(body, ['host', 'username', 'method'], [], ['secret']);
+    if (isOutcome(parsed))
+        return parsed;
+    const host = normalizeCredentialHost(parsed.host);
+    if (host === undefined) {
+        return fail(400, credentialHostIssue(parsed.host) === 'empty'
+            ? '"host" must be non-empty'
+            : '"host" must be a remote host such as github.com');
+    }
+    if (parsed.method !== 'token' && parsed.method !== 'password') {
+        return fail(400, '"method" must be "token" or "password"');
+    }
+    const username = parsed.username.trim();
+    const usernameIssue = credentialUsernameIssue(username, parsed.method);
+    if (usernameIssue !== undefined) {
+        return fail(400, usernameIssue === 'empty'
+            ? '"username" is required for "password" credentials'
+            : '"username" must not contain control characters');
+    }
+    try {
+        const store = credentialStore(deps);
+        const entries = await store.load();
+        const existing = entries.find(entry => entry.host === host);
+        const typed = parsed.secret === undefined ? '' : parsed.secret.trim();
+        let secret;
+        if (typed !== '')
+            secret = typed;
+        else if (existing !== undefined)
+            secret = existing.secret;
+        else
+            return fail(400, '"secret" is required for a new host');
+        const secretIssue = credentialSecretIssue(secret);
+        if (secretIssue !== undefined) {
+            return fail(400, secretIssue === 'empty'
+                ? '"secret" must be non-empty'
+                : '"secret" must not contain control characters');
+        }
+        const next = upsertCredential(entries, {
+            host,
+            username,
+            secret,
+            method: parsed.method,
+            updatedAt: Date.now(),
+        });
+        await store.save(next);
+        const result = { credentials: sortCredentials(next).map(credentialView) };
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        return storeFailure(error);
+    }
+}
+/**
+ * POST /credentials-delete — forget ONE host's credential. The other hosts
+ * keep theirs: deletion is per host, never a store reset.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ host }`.
+ */
+export async function handleCredentialsDelete(deps, body) {
+    const parsed = readBody(body, ['host']);
+    if (isOutcome(parsed))
+        return parsed;
+    const host = normalizeCredentialHost(parsed.host);
+    if (host === undefined)
+        return fail(400, '"host" must be a remote host such as github.com');
+    try {
+        const store = credentialStore(deps);
+        const entries = await store.load();
+        const next = removeCredential(entries, host);
+        if (next.length === entries.length)
+            return fail(400, `no credential is stored for "${host}"`);
+        await store.save(next);
+        const result = { credentials: sortCredentials(next).map(credentialView) };
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        return storeFailure(error);
+    }
+}
+/** The HTTP seam: the wired fake in tests, global fetch in production. */
+function fetchFor(deps) {
+    return deps.fetchImpl ?? globalThis.fetch;
+}
+/**
+ * POST /credentials-oauth-start — start a browser sign-in for ONE host
+ * (GitHub device flow). The answer carries a one-time user code and the
+ * polling credential; the dialog opens the verification page and polls
+ * /credentials-oauth-poll until the user approves.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ host }`.
+ */
+export async function handleCredentialsOAuthStart(deps, body) {
+    const parsed = readBody(body, ['host']);
+    if (isOutcome(parsed))
+        return parsed;
+    const host = normalizeCredentialHost(parsed.host);
+    if (host === undefined) {
+        return fail(400, credentialHostIssue(parsed.host) === 'empty'
+            ? '"host" must be non-empty'
+            : '"host" must be a remote host such as github.com');
+    }
+    if (!isDeviceFlowHost(host))
+        return fail(400, `browser sign-in is not available for "${host}"`);
+    try {
+        const grant = await startDeviceFlow(fetchFor(deps), host, deviceFlowClientId());
+        const result = {
+            userCode: grant.userCode,
+            verificationUri: grant.verificationUri,
+            ...(grant.verificationUriComplete === undefined ? {} : { verificationUriComplete: grant.verificationUriComplete }),
+            deviceCode: grant.deviceCode,
+            intervalSeconds: grant.intervalSeconds,
+            expiresInSeconds: grant.expiresInSeconds,
+        };
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        return fail(502, `could not start the browser sign-in: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * POST /credentials-oauth-poll — one poll of a started browser sign-in.
+ * A pending grant answers `{ status: 'pending' }` so the dialog keeps
+ * waiting; an approved grant is stored as a `token` credential for the host
+ * (the token itself never crosses the wire again) and the fresh masked list
+ * comes back.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ host, deviceCode }`.
+ */
+export async function handleCredentialsOAuthPoll(deps, body) {
+    const parsed = readBody(body, ['host', 'deviceCode']);
+    if (isOutcome(parsed))
+        return parsed;
+    const host = normalizeCredentialHost(parsed.host);
+    if (host === undefined)
+        return fail(400, '"host" must be a remote host such as github.com');
+    if (!isDeviceFlowHost(host))
+        return fail(400, `browser sign-in is not available for "${host}"`);
+    const deviceCode = parsed.deviceCode.trim();
+    if (deviceCode === '')
+        return fail(400, '"deviceCode" must be non-empty');
+    let poll;
+    try {
+        poll = await pollDeviceFlow(fetchFor(deps), host, deviceFlowClientId(), deviceCode);
+    }
+    catch (error) {
+        return fail(502, `could not poll the browser sign-in: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (poll.status === 'pending') {
+        const waiting = { status: 'pending' };
+        return { status: 200, body: waiting };
+    }
+    if (poll.status === 'slow_down') {
+        const backoff = { status: 'slow_down' };
+        return { status: 200, body: backoff };
+    }
+    if (poll.status === 'network') {
+        // Not a failure: the grant is untouched, so the dialog retries instead of
+        // throwing away a sign-in the user may already have approved. The client
+        // decides when repeated failures become an error.
+        const retry = { status: 'network', message: poll.message };
+        return { status: 200, body: retry };
+    }
+    if (poll.status !== 'token')
+        return fail(400, poll.message);
+    const secretIssue = credentialSecretIssue(poll.token);
+    if (secretIssue !== undefined)
+        return fail(502, 'the sign-in returned an unusable token');
+    try {
+        const store = credentialStore(deps);
+        const entries = await store.load();
+        const next = upsertCredential(entries, {
+            host,
+            username: '',
+            secret: poll.token,
+            method: 'token',
+            updatedAt: Date.now(),
+        });
+        await store.save(next);
+        const done = { status: 'done', credentials: sortCredentials(next).map(credentialView) };
+        return { status: 200, body: done };
+    }
+    catch (error) {
+        return storeFailure(error);
+    }
+}
+/** Human message for a rejected remote NAME. */
+function remoteNameMessage(issue) {
+    if (issue === 'empty')
+        return '"name" must be non-empty';
+    if (issue === 'leadingDash')
+        return '"name" must not start with "-"';
+    return '"name" may only contain letters, digits, ".", "_" and "-"';
+}
+/** Human message for a rejected remote URL. */
+function remoteUrlMessage(issue) {
+    if (issue === 'empty')
+        return '"url" must be non-empty';
+    if (issue === 'whitespace')
+        return '"url" must not contain whitespace';
+    return '"url" must be an address git accepts (https://..., git@host:path or an absolute path)';
+}
+/** Actions one /remote call may take. */
+const REMOTE_ACTIONS = ['add', 'set-url', 'remove'];
+/**
+ * POST /remotes — the repository's configured remotes with their fetch and
+ * push URLs. Remotes belong to the repository, not to a worktree, so any
+ * directory inside it answers the full list.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath }`.
+ */
+export async function handleRemotes(deps, body) {
+    const parsed = readBody(body, ['repoPath']);
+    if (isOutcome(parsed))
+        return parsed;
+    const { repoPath } = parsed;
+    if (!isAbsoluteDir(repoPath))
+        return fail(400, '"repoPath" must be an absolute directory');
+    try {
+        const facts = await probeRepo(deps.exec, repoPath, deps.dirExists);
+        if (facts === undefined)
+            return fail(400, `"${repoPath}" is not inside a git repository`);
+        const remotes = await listRemotes(deps.exec, facts.repoRoot);
+        const result = { remotes };
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        if (error instanceof GitError)
+            return gitFailure(error);
+        return fail(500, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * POST /remote — add, re-point or remove ONE remote, then answer the fresh
+ * list. Existence is checked against `git remote -v` first, so a duplicate
+ * `add` and a missing `set-url`/`remove` answer a clean 400 instead of git's
+ * stderr; the URL is pre-flighted by {@link remoteUrlIssue}.
+ * @param deps - host dependencies.
+ * @param body - parsed request body: `{ repoPath, action, name, url? }`.
+ */
+export async function handleRemote(deps, body) {
+    const parsed = readBody(body, ['repoPath', 'action', 'name'], [], ['url']);
+    if (isOutcome(parsed))
+        return parsed;
+    const { repoPath, action, name } = parsed;
+    if (!isAbsoluteDir(repoPath))
+        return fail(400, '"repoPath" must be an absolute directory');
+    if (!REMOTE_ACTIONS.includes(action))
+        return fail(400, '"action" must be "add", "set-url" or "remove"');
+    const nameIssue = remoteNameIssue(name);
+    if (nameIssue !== null)
+        return fail(400, remoteNameMessage(nameIssue));
+    const url = parsed.url === undefined ? '' : parsed.url.trim();
+    if (action !== 'remove') {
+        const urlIssue = remoteUrlIssue(url);
+        if (urlIssue !== undefined)
+            return fail(400, remoteUrlMessage(urlIssue));
+    }
+    try {
+        const facts = await probeRepo(deps.exec, repoPath, deps.dirExists);
+        if (facts === undefined)
+            return fail(400, `"${repoPath}" is not inside a git repository`);
+        const before = await listRemotes(deps.exec, facts.repoRoot);
+        const exists = before.some(remote => remote.name === name);
+        if (action === 'add') {
+            if (exists)
+                return fail(400, `remote "${name}" already exists`);
+            await addRemote(deps.exec, facts.repoRoot, name, url);
+        }
+        else if (!exists) {
+            return fail(400, `remote "${name}" does not exist`);
+        }
+        else if (action === 'set-url') {
+            await setRemoteUrl(deps.exec, facts.repoRoot, name, url);
+        }
+        else {
+            await removeRemote(deps.exec, facts.repoRoot, name);
+        }
+        const remotes = await listRemotes(deps.exec, facts.repoRoot);
+        const result = { remotes };
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        if (error instanceof GitError)
+            return gitFailure(error);
+        return fail(500, error instanceof Error ? error.message : String(error));
+    }
+}

package/lib/settings.d.ts

@@ -16,6 +16,15 @@
  * @returns an absolute directory path.
  */
 export declare function resolveRootDir(rootDir: string | undefined, home: string, envHome: string | undefined): string;
+/**
+ * Resolve the dsh configuration home: `$DSH_HOME` when set (a blank value
+ * counts as unset), else `~/.dsh`. Host-owned files that are NOT part of the
+ * settings document (the global git credential store) live directly here.
+ * @param home - user home directory (`os.homedir()` seam).
+ * @param envHome - `$DSH_HOME` environment value seam.
+ * @returns an absolute directory path.
+ */
+export declare function resolveDshHome(home: string, envHome: string | undefined): string;
 /**
  * Reject a stored rootDir the plugin could not act on: a non-blank value that
  * is not an absolute path. Blank/absent means the default location and passes.

package/lib/settings.js

@@ -21,8 +21,18 @@ export function resolveRootDir(rootDir, home, envHome) {
     const configured = rootDir?.trim();
     if (configured !== undefined && configured !== '')
         return configured;
-    const base = typeof envHome === 'string' && envHome.trim() !== '' ? envHome : join(home, '.dsh');
-    return join(base, 'gitworktree');
+    return join(resolveDshHome(home, envHome), 'gitworktree');
+}
+/**
+ * Resolve the dsh configuration home: `$DSH_HOME` when set (a blank value
+ * counts as unset), else `~/.dsh`. Host-owned files that are NOT part of the
+ * settings document (the global git credential store) live directly here.
+ * @param home - user home directory (`os.homedir()` seam).
+ * @param envHome - `$DSH_HOME` environment value seam.
+ * @returns an absolute directory path.
+ */
+export function resolveDshHome(home, envHome) {
+    return typeof envHome === 'string' && envHome.trim() !== '' ? envHome : join(home, '.dsh');
 }
 /**
  * Reject a stored rootDir the plugin could not act on: a non-blank value that

package/lib/tool.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The model-facing `git_credentials` tool (host half).
+ *
+ * The credential file is global, so a session that pushes to a new host often
+ * needs to know which hosts are already configured before asking the user to
+ * paste a token again. Hence one read-only tool over the same store the routes
+ * use: it lists hosts, methods and masked secrets, and never writes.
+ *
+ * Nothing here imports `@deepseek-ai/dsh-tools`: a plain definition object
+ * registered through `ctx.tools.register` is the documented path for a plugin
+ * that must not take a value dependency on the host runtime. The registry
+ * validates `output.schema` and passes model arguments through verbatim, so
+ * this module validates its own arguments.
+ *
+ * @module dsh-git-branch/tool
+ */
+import { type CredentialStore } from './credentials.js';
+/** Model-facing tool name. */
+export declare const GIT_CREDENTIALS_TOOL_NAME = "git_credentials";
+/** One text block in a tool result. */
+export interface ToolTextBlock {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** The arguments this tool accepts. */
+export interface GitCredentialsArgs {
+    /** Restrict the listing to one host (`github.com`); omitted lists all. */
+    readonly host?: string;
+    /** Return stored secrets verbatim instead of masking them. */
+    readonly includeSecret?: boolean;
+}
+/** One credential row as the model sees it. */
+export interface GitCredentialsRow {
+    readonly host: string;
+    readonly username: string;
+    readonly method: string;
+    /** Masked tail, or the secret verbatim when `includeSecret` was set. */
+    readonly secret: string;
+    /** ISO-8601 timestamp of the last save (empty when unknown). */
+    readonly updatedAt: string;
+}
+/** The canonical value `execute` returns. */
+export interface GitCredentialsValue {
+    /** Absolute credential file the rows come from. */
+    readonly path: string;
+    /** Total number of configured hosts, before `host` filtering. */
+    readonly total: number;
+    /** The rows, sorted by host. */
+    readonly credentials: readonly GitCredentialsRow[];
+    /** Why the store could not be read; rows are then empty. */
+    readonly error?: string;
+}
+/** Host-side seams the tool reads through. */
+export interface GitCredentialsToolDeps {
+    /** 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. */
+    readonly store?: CredentialStore;
+}
+/** A tool definition as `ctx.tools.register` accepts it. */
+export interface GitCredentialsTool {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly output: {
+        readonly schema: Record<string, unknown>;
+        readonly render: (args: GitCredentialsArgs, value: GitCredentialsValue) => readonly ToolTextBlock[];
+    };
+    readonly execute: (args: GitCredentialsArgs, exec?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<GitCredentialsValue>;
+}
+/** Compose the model-facing text of one result. */
+export declare function renderGitCredentials(value: GitCredentialsValue): string;
+/**
+ * Build the `git_credentials` tool definition.
+ * @param deps - host seams (home/env and an optional store override).
+ * @returns a definition ready for `ctx.tools.register`.
+ */
+export declare function gitCredentialsTool(deps: GitCredentialsToolDeps): GitCredentialsTool;

package/lib/tool.js

@@ -0,0 +1,133 @@
+/**
+ * The model-facing `git_credentials` tool (host half).
+ *
+ * The credential file is global, so a session that pushes to a new host often
+ * needs to know which hosts are already configured before asking the user to
+ * paste a token again. Hence one read-only tool over the same store the routes
+ * use: it lists hosts, methods and masked secrets, and never writes.
+ *
+ * Nothing here imports `@deepseek-ai/dsh-tools`: a plain definition object
+ * registered through `ctx.tools.register` is the documented path for a plugin
+ * that must not take a value dependency on the host runtime. The registry
+ * validates `output.schema` and passes model arguments through verbatim, so
+ * this module validates its own arguments.
+ *
+ * @module dsh-git-branch/tool
+ */
+import { basicUsername, createCredentialStore, credentialFilePath, maskSecret, } from './credentials.js';
+/** Model-facing tool name. */
+export const GIT_CREDENTIALS_TOOL_NAME = 'git_credentials';
+/** Project one stored entry onto its model-facing row. */
+function credentialRow(entry, includeSecret) {
+    return {
+        host: entry.host,
+        username: entry.username === '' ? basicUsername(entry) : entry.username,
+        method: entry.method,
+        secret: includeSecret ? entry.secret : maskSecret(entry.secret),
+        updatedAt: entry.updatedAt > 0 ? new Date(entry.updatedAt).toISOString() : '',
+    };
+}
+/** Compose the model-facing text of one result. */
+export function renderGitCredentials(value) {
+    if (value.error !== undefined)
+        return `git credentials are unavailable: ${value.error}`;
+    const head = `${String(value.total)} configured host${value.total === 1 ? '' : 's'} (${value.path})`;
+    if (value.credentials.length === 0)
+        return `${head}\n(no matching credential)`;
+    const rows = value.credentials.map((row) => {
+        const parts = [row.host, row.method, `user ${row.username}`, row.secret];
+        if (row.updatedAt !== '')
+            parts.push(`saved ${row.updatedAt}`);
+        return `- ${parts.join(' · ')}`;
+    });
+    return [head, ...rows].join('\n');
+}
+/**
+ * Build the `git_credentials` tool definition.
+ * @param deps - host seams (home/env and an optional store override).
+ * @returns a definition ready for `ctx.tools.register`.
+ */
+export function gitCredentialsTool(deps) {
+    const storeOf = () => deps.store ?? createCredentialStore(credentialFilePath(deps.home(), deps.envHome()));
+    /** Read the store, folding a read failure into the result value. */
+    const read = async (args) => {
+        const store = storeOf();
+        if (args.host !== undefined && typeof args.host !== 'string') {
+            throw new Error('invalid host: expected a string');
+        }
+        if (args.includeSecret !== undefined && typeof args.includeSecret !== 'boolean') {
+            throw new Error('invalid includeSecret: expected a boolean');
+        }
+        const wanted = args.host?.trim().toLowerCase();
+        const includeSecret = args.includeSecret === true;
+        try {
+            const entries = await store.load();
+            const rows = entries
+                .filter(entry => wanted === undefined || wanted === '' || entry.host === wanted)
+                .map(entry => credentialRow(entry, includeSecret));
+            return { path: store.path, total: entries.length, credentials: rows };
+        }
+        catch (error) {
+            return {
+                path: store.path,
+                total: 0,
+                credentials: [],
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    };
+    return {
+        name: GIT_CREDENTIALS_TOOL_NAME,
+        description: 'List the Git credentials this machine stores for remote hosts (GitHub, GitLab, Gitee, ...). '
+            + 'The store is global per host and the git-worktree plugin injects it automatically into its fetch, '
+            + 'update, push and tag-push commands, so a configured host needs no further setup. Secrets are masked; '
+            + 'pass includeSecret only when the user explicitly asked to see the stored token, because the value then '
+            + 'appears in the conversation transcript.',
+        parameters: {
+            type: 'object',
+            properties: {
+                host: {
+                    type: 'string',
+                    description: 'Only list this host, for example "github.com". Omit to list every configured host.',
+                },
+                includeSecret: {
+                    type: 'boolean',
+                    description: 'Return the stored secret verbatim instead of a masked tail. Only set this when the user '
+                        + 'explicitly asked to see the secret.',
+                },
+            },
+            additionalProperties: false,
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    total: { type: 'integer' },
+                    credentials: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                host: { type: 'string' },
+                                username: { type: 'string' },
+                                method: { type: 'string' },
+                                secret: { type: 'string' },
+                                updatedAt: { type: 'string' },
+                            },
+                            required: ['host', 'username', 'method', 'secret', 'updatedAt'],
+                        },
+                    },
+                    error: { type: 'string' },
+                },
+                required: ['path', 'total', 'credentials'],
+            },
+            render: (_args, value) => [
+                { type: 'text', text: renderGitCredentials(value) },
+            ],
+        },
+        async execute(args) {
+            return read(args ?? {});
+        },
+    };
+}