dsh-git-branch-manage 1.0.7 → 1.0.9

package/lib/credentials.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ *
+ * Authentication rides `git -c http.https://<host>/.extraHeader=…` on the
+ * panel's own network commands: the user's global git config and credential
+ * helpers are left untouched. Only `https://` remotes receive the header;
+ * ssh and plain-http remotes are never sent a secret.
+ */
+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.
+ */
+export declare const TOKEN_USERNAME = "oauth2";
+/** One stored credential: exactly one per remote host. */
+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`). */
+    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. */
+    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). */
+    readonly path: string;
+    /** Every stored credential, one per host, sorted by host. A missing file
+     * is the empty list; an unreadable/malformed one throws
+     * {@link CredentialStoreError}. */
+    load: () => Promise<GitCredential[]>;
+    /** Replace the whole set atomically (temp file + rename). */
+    save: (entries: readonly GitCredential[]) => Promise<void>;
+}
+/** A credential file the store could not read or understand. */
+export declare class CredentialStoreError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+/**
+ * Resolve the credential file location: `<dsh-home>/git-credentials.json`.
+ * @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;
+/** Why a user-typed host is not usable yet (undefined = fine). */
+export type CredentialHostIssue = 'empty' | 'invalid';
+/**
+ * Normalize a remote host typed or pasted by the user. Accepts a bare host
+ * (`github.com`), a host with a port (`git.example.com:8443`), a full remote
+ * URL (`https://github.com/org/repo.git`), an scp-like remote
+ * (`git@github.com:org/repo.git`) and a URL with userinfo — the host is the
+ * only part the credential needs. Lowercased, no scheme, path, userinfo or
+ * trailing slash.
+ * @param value - raw draft text.
+ * @returns the normalized host, or undefined when nothing usable is left.
+ */
+export declare function normalizeCredentialHost(value: string): string | undefined;
+/**
+ * Pre-flight check of a user-typed credential host.
+ * @param value - raw draft text.
+ */
+export declare function credentialHostIssue(value: string): CredentialHostIssue | undefined;
+/**
+ * Why a username is not usable yet (undefined = fine). A token credential may
+ * leave the username empty: vendors accept any non-empty Basic-auth name
+ * alongside a personal access token, so only password mode requires one.
+ * @param value - raw draft text.
+ * @param method - the method the draft targets (defaults to password mode).
+ */
+export declare function credentialUsernameIssue(value: string, method?: CredentialMethod): 'empty' | 'illegal' | undefined;
+/**
+ * The Basic-auth username git actually sends for one entry.
+ * @param entry - the stored credential.
+ * @returns the stored username, or {@link TOKEN_USERNAME} for a token saved
+ * without one.
+ */
+export declare function basicUsername(entry: GitCredential): string;
+/** Why a secret is not usable yet (undefined = fine). */
+export declare function credentialSecretIssue(value: string): 'empty' | 'illegal' | undefined;
+/**
+ * Mask a stored secret for the list route: the tail only, never the value.
+ * @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.
+ * @param entries - current credentials.
+ * @param next - the entry to store (host already normalized).
+ * @returns a NEW sorted array.
+ */
+export declare function upsertCredential(entries: readonly GitCredential[], next: GitCredential): GitCredential[];
+/**
+ * Drop one host's credential.
+ * @param entries - current credentials.
+ * @param host - normalized host to forget.
+ * @returns a NEW sorted array.
+ */
+export declare function removeCredential(entries: readonly GitCredential[], host: string): GitCredential[];
+/** 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.
+ * @param text - raw file contents.
+ * @param path - file path (for the error message).
+ */
+export declare function parseCredentialFile(text: string, path?: string): GitCredential[];
+/**
+ * Serialize the credential set for the file.
+ * @param entries - stored credentials.
+ */
+export declare function serializeCredentialFile(entries: readonly GitCredential[]): 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.
+ */
+export declare function createCredentialStore(path: string): CredentialStore;

package/lib/credentials.js

@@ -0,0 +1,256 @@
+/**
+ * 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.
+ *
+ * Authentication rides `git -c http.https://<host>/.extraHeader=…` on the
+ * panel's own network commands: the user's global git config and credential
+ * helpers are left untouched. Only `https://` remotes receive the header;
+ * ssh and plain-http remotes are never sent a secret.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { resolveDshHome } from './settings.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.
+ */
+export const TOKEN_USERNAME = 'oauth2';
+/** A credential file the store could not read or understand. */
+export class CredentialStoreError extends Error {
+    path;
+    constructor(path, message) {
+        super(`credential file "${path}" ${message}`);
+        this.path = path;
+        this.name = 'CredentialStoreError';
+    }
+}
+/**
+ * Resolve the credential file location: `<dsh-home>/git-credentials.json`.
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam (blank = unset).
+ */
+export function credentialFilePath(home, envHome) {
+    return join(resolveDshHome(home, envHome), 'git-credentials.json');
+}
+/**
+ * Normalize a remote host typed or pasted by the user. Accepts a bare host
+ * (`github.com`), a host with a port (`git.example.com:8443`), a full remote
+ * URL (`https://github.com/org/repo.git`), an scp-like remote
+ * (`git@github.com:org/repo.git`) and a URL with userinfo — the host is the
+ * only part the credential needs. Lowercased, no scheme, path, userinfo or
+ * trailing slash.
+ * @param value - raw draft text.
+ * @returns the normalized host, or undefined when nothing usable is left.
+ */
+export function normalizeCredentialHost(value) {
+    let host = value.trim().toLowerCase();
+    // Scheme (`https://`) and everything after the authority (`/org/repo`).
+    host = host.replace(/^[a-z][a-z0-9+.-]*:\/\//, '');
+    const slash = host.search(/[/?#]/);
+    if (slash >= 0)
+        host = host.slice(0, slash);
+    // Userinfo (`user:pass@host`); scp-like `git@host:path` keeps the host part.
+    const at = host.lastIndexOf('@');
+    if (at >= 0)
+        host = host.slice(at + 1);
+    // scp-like `host:path` — keep the host before the colon, unless the colon
+    // introduces a numeric port.
+    const colon = host.indexOf(':');
+    if (colon >= 0 && !/^\d{1,5}$/.test(host.slice(colon + 1)))
+        host = host.slice(0, colon);
+    if (host.endsWith('.'))
+        host = host.slice(0, -1);
+    if (host === '')
+        return undefined;
+    // Hostname (single-label intranet hosts allowed) with an optional port.
+    if (!/^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?::\d{1,5})?$/.test(host))
+        return undefined;
+    return host;
+}
+/**
+ * Pre-flight check of a user-typed credential host.
+ * @param value - raw draft text.
+ */
+export function credentialHostIssue(value) {
+    if (value.trim() === '')
+        return 'empty';
+    return normalizeCredentialHost(value) === undefined ? 'invalid' : undefined;
+}
+/**
+ * Why a username is not usable yet (undefined = fine). A token credential may
+ * leave the username empty: vendors accept any non-empty Basic-auth name
+ * alongside a personal access token, so only password mode requires one.
+ * @param value - raw draft text.
+ * @param method - the method the draft targets (defaults to password mode).
+ */
+export function credentialUsernameIssue(value, method = 'password') {
+    if (value.trim() === '')
+        return method === 'token' ? undefined : 'empty';
+    if (/[\u0000-\u001f\u007f]/.test(value))
+        return 'illegal';
+    return undefined;
+}
+/**
+ * The Basic-auth username git actually sends for one entry.
+ * @param entry - the stored credential.
+ * @returns the stored username, or {@link TOKEN_USERNAME} for a token saved
+ * without one.
+ */
+export function basicUsername(entry) {
+    return entry.username.trim() === '' ? TOKEN_USERNAME : entry.username;
+}
+/** Why a secret is not usable yet (undefined = fine). */
+export function credentialSecretIssue(value) {
+    if (value.trim() === '')
+        return 'empty';
+    // A pasted multi-line blob (or a stray control character) would corrupt
+    // the Basic header; interior spaces stay legal — passwords may carry them.
+    if (/[\u0000-\u001f\u007f]/.test(value))
+        return 'illegal';
+    return undefined;
+}
+/**
+ * Mask a stored secret for the list route: the tail only, never the value.
+ * @param secret - the stored secret.
+ */
+export function maskSecret(secret) {
+    const tail = secret.slice(-4);
+    return secret.length <= 4 ? '****' : `****${tail}`;
+}
+/**
+ * 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 function authConfigArgs(entries) {
+    // Collapse duplicates by host, LAST entry winning: a hand-edited file with
+    // two rows for one host must hand git the row the list route shows last.
+    const byHost = new Map();
+    for (const entry of entries)
+        byHost.set(entry.host, entry);
+    const args = [];
+    for (const entry of byHost.values()) {
+        const basic = Buffer.from(`${basicUsername(entry)}:${entry.secret}`, 'utf8').toString('base64');
+        args.push('-c', `http.https://${entry.host}/.extraHeader=AUTHORIZATION: basic ${basic}`);
+    }
+    return args;
+}
+/**
+ * Insert or update one credential; the pair `(host, updatedAt)` changes,
+ * everything else is replaced. An existing host keeps its position.
+ * @param entries - current credentials.
+ * @param next - the entry to store (host already normalized).
+ * @returns a NEW sorted array.
+ */
+export function upsertCredential(entries, next) {
+    const rest = entries.filter(entry => entry.host !== next.host);
+    return sortCredentials([...rest, next]);
+}
+/**
+ * Drop one host's credential.
+ * @param entries - current credentials.
+ * @param host - normalized host to forget.
+ * @returns a NEW sorted array.
+ */
+export function removeCredential(entries, host) {
+    return entries.filter(entry => entry.host !== host);
+}
+/** Stable host order for the file and the UI. */
+export function sortCredentials(entries) {
+    return [...entries].sort((left, right) => left.host.localeCompare(right.host));
+}
+/**
+ * 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.
+ * @param text - raw file contents.
+ * @param path - file path (for the error message).
+ */
+export function parseCredentialFile(text, path = 'git-credentials.json') {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CredentialStoreError(path, `is not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CredentialStoreError(path, 'must contain a JSON object');
+    }
+    const raw = parsed.credentials;
+    if (!Array.isArray(raw))
+        throw new CredentialStoreError(path, 'has no "credentials" array');
+    const byHost = new Map();
+    for (const [index, item] of raw.entries()) {
+        if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+            throw new CredentialStoreError(path, `entry #${String(index + 1)} is not an object`);
+        }
+        const record = item;
+        const host = typeof record.host === 'string' ? normalizeCredentialHost(record.host) : undefined;
+        const username = typeof record.username === 'string' ? record.username : undefined;
+        const secret = typeof record.secret === 'string' ? record.secret : undefined;
+        const method = record.method;
+        if (host === undefined || username === undefined || secret === undefined || (method !== 'token' && method !== 'password')) {
+            throw new CredentialStoreError(path, `entry #${String(index + 1)} is missing a valid host/username/secret/method`);
+        }
+        const updatedAt = typeof record.updatedAt === 'number' && Number.isFinite(record.updatedAt) ? record.updatedAt : 0;
+        byHost.set(host, { host, username, secret, method, updatedAt });
+    }
+    return sortCredentials([...byHost.values()]);
+}
+/**
+ * Serialize the credential set for the file.
+ * @param entries - stored credentials.
+ */
+export function serializeCredentialFile(entries) {
+    const document = { version: 1, credentials: sortCredentials(entries) };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+/**
+ * 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.
+ */
+export function createCredentialStore(path) {
+    return {
+        path,
+        load: async () => {
+            let text;
+            try {
+                text = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return [];
+                throw new CredentialStoreError(path, `could not be read (${error instanceof Error ? error.message : String(error)})`);
+            }
+            if (text.trim() === '')
+                return [];
+            return parseCredentialFile(text, path);
+        },
+        save: async (entries) => {
+            const directory = dirname(path);
+            await mkdir(directory, { recursive: true });
+            // Write-then-rename keeps a crashed save from truncating the real file.
+            const temp = `${path}.${String(process.pid)}.${String(Date.now())}.tmp`;
+            try {
+                await writeFile(temp, serializeCredentialFile(entries), { encoding: 'utf8', mode: 0o600 });
+                await rename(temp, path);
+            }
+            catch (error) {
+                await rm(temp, { force: true }).catch(() => undefined);
+                throw new CredentialStoreError(path, `could not be written (${error instanceof Error ? error.message : String(error)})`);
+            }
+        },
+    };
+}

package/lib/git.d.ts

@@ -3,7 +3,7 @@
  * injectable `exec` seam (tests substitute it); every method is plain
  * argument assembly plus porcelain parsing, no ambient state.
  */
-import type { BranchEntry, WorktreeEntry, WorkspaceGitFacts } from './wire.js';
+import type { BranchEntry, RemoteEntry, WorktreeEntry, WorkspaceGitFacts } from './wire.js';
 /** One process result as the seam reports it. */
 export interface ExecResult {
     code: number;
@@ -253,8 +253,10 @@ export declare function accelArgs(prefix: string | undefined): readonly string[]
  * @param repoRoot - main worktree directory (fetch is repository-wide).
  * @param accelPrefix - optional cn-accelerate mirror prefix (see
  * {@link accelArgs}); only the READ half of the network commands gets it.
+ * @param authArgs - optional per-host credential `-c` pairs (see
+ * `credentials.ts`); prepended before the subcommand like the accel rewrite.
  */
-export declare function fetchAll(exec: Exec, repoRoot: string, accelPrefix?: string): Promise<void>;
+export declare function fetchAll(exec: Exec, repoRoot: string, accelPrefix?: string, authArgs?: readonly string[]): Promise<void>;
 /** Outcome of {@link updateBranch}: the branch touched and whether it moved. */
 export interface UpdateOutcome {
     branch: string;
@@ -276,7 +278,7 @@ export interface UpdateOutcome {
  * @returns the branch name and whether HEAD actually moved (false = the
  * upstream already contained it).
  */
-export declare function updateBranch(exec: Exec, cwd: string, accelPrefix?: string): Promise<UpdateOutcome>;
+export declare function updateBranch(exec: Exec, cwd: string, accelPrefix?: string, authArgs?: readonly string[]): Promise<UpdateOutcome>;
 /** Outcome of {@link pushBranch}: the branch touched and whether it moved. */
 export interface PushOutcome {
     branch: string;
@@ -300,7 +302,7 @@ export interface PushOutcome {
  * without an upstream can still be handed to `git push`, so Git's own
  * push-specific diagnostic is preserved; in that case `pushed` is false.
  */
-export declare function pushBranch(exec: Exec, cwd: string): Promise<PushOutcome>;
+export declare function pushBranch(exec: Exec, cwd: string, authArgs?: readonly string[]): Promise<PushOutcome>;
 /** Every LOCAL tag name of the repository, in git's own sort order. */
 export declare function listTagNames(exec: Exec, cwd: string): Promise<string[]>;
 /** Where a one-off push should go, or why no remote could be picked. */
@@ -351,9 +353,45 @@ export interface TagPushOutcome {
  * @param remote - the remote to publish to (see {@link resolvePushRemote}).
  * @returns the tag, the remote, and whether the push had to run.
  */
-export declare function pushTag(exec: Exec, cwd: string, name: string, remote: string): Promise<TagPushOutcome>;
+export declare function pushTag(exec: Exec, cwd: string, name: string, remote: string, authArgs?: readonly string[]): Promise<TagPushOutcome>;
 /** Guard for route inputs: a non-empty absolute directory path. */
 export declare function isAbsoluteDir(value: string): boolean;
+/**
+ * Every configured remote of the repository (`git remote -v`), with the fetch
+ * and push URLs git would actually use. A remote with only one side set
+ * mirrors that URL into both fields — git falls back to it the same way.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ */
+export declare function listRemotes(exec: Exec, cwd: string): Promise<RemoteEntry[]>;
+/**
+ * Register a new remote (`git remote add`). The name/URL were validated by
+ * the route; git still refuses a duplicate name — its stderr rides the
+ * GitError, mapped to 400 for the caller.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param name - the new remote name.
+ * @param url - its URL (fetch and push; a push URL is not set apart).
+ */
+export declare function addRemote(exec: Exec, cwd: string, name: string, url: string): Promise<void>;
+/**
+ * Re-point an existing remote's fetch AND push URL (`git remote set-url`).
+ * Deliberately both: a separate push URL would survive as a stale target the
+ * UI cannot show, so the panel keeps one address per remote.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param name - an existing remote name.
+ * @param url - the new URL.
+ */
+export declare function setRemoteUrl(exec: Exec, cwd: string, name: string, url: string): Promise<void>;
+/**
+ * Forget one remote (`git remote remove`): deletes its remote-tracking refs
+ * and its config section, never the objects the local branches share.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param name - an existing remote name.
+ */
+export declare function removeRemote(exec: Exec, cwd: string, name: string): Promise<void>;
 /** Pre-delete facts of one worktree directory, for the remove-confirm dialog. */
 export interface WorktreeInspect {
     /** Uncommitted-change file rows (`git status --porcelain` line count). */

package/lib/git.js

@@ -521,9 +521,11 @@ export function accelArgs(prefix) {
  * @param repoRoot - main worktree directory (fetch is repository-wide).
  * @param accelPrefix - optional cn-accelerate mirror prefix (see
  * {@link accelArgs}); only the READ half of the network commands gets it.
+ * @param authArgs - optional per-host credential `-c` pairs (see
+ * `credentials.ts`); prepended before the subcommand like the accel rewrite.
  */
-export async function fetchAll(exec, repoRoot, accelPrefix) {
-    await git(exec, repoRoot, [...accelArgs(accelPrefix), 'fetch', '--all', '--prune'], NETWORK_TIMEOUT_MS);
+export async function fetchAll(exec, repoRoot, accelPrefix, authArgs = []) {
+    await git(exec, repoRoot, [...accelArgs(accelPrefix), ...authArgs, 'fetch', '--all', '--prune'], NETWORK_TIMEOUT_MS);
 }
 /**
  * Update the CURRENT checkout: fetch every remote, then fast-forward the
@@ -541,8 +543,8 @@ export async function fetchAll(exec, repoRoot, accelPrefix) {
  * @returns the branch name and whether HEAD actually moved (false = the
  * upstream already contained it).
  */
-export async function updateBranch(exec, cwd, accelPrefix) {
-    await fetchAll(exec, cwd, accelPrefix);
+export async function updateBranch(exec, cwd, accelPrefix, authArgs = []) {
+    await fetchAll(exec, cwd, accelPrefix, authArgs);
     const before = (await git(exec, cwd, ['rev-parse', 'HEAD'])).trim();
     await git(exec, cwd, ['merge', '--ff-only', '@{u}']);
     const after = (await git(exec, cwd, ['rev-parse', 'HEAD'])).trim();
@@ -567,9 +569,9 @@ export async function updateBranch(exec, cwd, accelPrefix) {
  * without an upstream can still be handed to `git push`, so Git's own
  * push-specific diagnostic is preserved; in that case `pushed` is false.
  */
-export async function pushBranch(exec, cwd) {
+export async function pushBranch(exec, cwd, authArgs = []) {
     const before = await gitMaybe(exec, cwd, ['rev-parse', '@{u}']);
-    await git(exec, cwd, ['push'], NETWORK_TIMEOUT_MS);
+    await git(exec, cwd, [...authArgs, 'push'], NETWORK_TIMEOUT_MS);
     const after = await gitMaybe(exec, cwd, ['rev-parse', '@{u}']);
     const branch = (await gitMaybe(exec, cwd, ['branch', '--show-current']))?.trim() ?? '';
     return { branch, pushed: before !== undefined && after !== undefined && before.trim() !== after.trim() };
@@ -629,22 +631,94 @@ export async function resolvePushRemote(exec, cwd) {
  * @param remote - the remote to publish to (see {@link resolvePushRemote}).
  * @returns the tag, the remote, and whether the push had to run.
  */
-export async function pushTag(exec, cwd, name, remote) {
+export async function pushTag(exec, cwd, name, remote, authArgs = []) {
     const ref = `refs/tags/${name}`;
     const local = (await git(exec, cwd, ['rev-parse', '--verify', ref])).trim();
-    const listed = await gitMaybe(exec, cwd, ['ls-remote', '--refs', remote, ref], NETWORK_TIMEOUT_MS);
+    const listed = await gitMaybe(exec, cwd, [...authArgs, 'ls-remote', '--refs', remote, ref], NETWORK_TIMEOUT_MS);
     const present = (listed ?? '').split('\n')
         .map(line => line.trim().split(/\s+/)[0] ?? '')
         .includes(local);
     if (present)
         return { tag: name, remote, pushed: false };
-    await git(exec, cwd, ['push', remote, `${ref}:${ref}`], NETWORK_TIMEOUT_MS);
+    await git(exec, cwd, [...authArgs, 'push', remote, `${ref}:${ref}`], NETWORK_TIMEOUT_MS);
     return { tag: name, remote, pushed: true };
 }
 /** Guard for route inputs: a non-empty absolute directory path. */
 export function isAbsoluteDir(value) {
     return value.trim() !== '' && isAbsolute(value);
 }
+/**
+ * Every configured remote of the repository (`git remote -v`), with the fetch
+ * and push URLs git would actually use. A remote with only one side set
+ * mirrors that URL into both fields — git falls back to it the same way.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ */
+export async function listRemotes(exec, cwd) {
+    const text = await git(exec, cwd, ['remote', '-v']);
+    const byName = new Map();
+    for (const line of text.split('\n')) {
+        // `git remote -v` separates the name from `<url> (fetch|push)` with a tab;
+        // splitting there keeps a local-path URL with spaces intact.
+        const tab = line.indexOf('\t');
+        if (tab <= 0)
+            continue;
+        const name = line.slice(0, tab).trim();
+        const rest = line.slice(tab + 1).trim();
+        const match = /^(.*)\s+\((fetch|push)\)$/.exec(rest);
+        if (name === '' || match === null)
+            continue;
+        const url = (match[1] ?? '').trim();
+        const entry = byName.get(name) ?? {};
+        if (match[2] === 'fetch')
+            entry.fetchUrl = url;
+        else
+            entry.pushUrl = url;
+        byName.set(name, entry);
+    }
+    return [...byName.entries()]
+        .map(([name, urls]) => ({
+        name,
+        fetchUrl: urls.fetchUrl ?? urls.pushUrl ?? '',
+        pushUrl: urls.pushUrl ?? urls.fetchUrl ?? '',
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Register a new remote (`git remote add`). The name/URL were validated by
+ * the route; git still refuses a duplicate name — its stderr rides the
+ * GitError, mapped to 400 for the caller.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param name - the new remote name.
+ * @param url - its URL (fetch and push; a push URL is not set apart).
+ */
+export async function addRemote(exec, cwd, name, url) {
+    await git(exec, cwd, ['remote', 'add', name, url]);
+}
+/**
+ * Re-point an existing remote's fetch AND push URL (`git remote set-url`).
+ * Deliberately both: a separate push URL would survive as a stale target the
+ * UI cannot show, so the panel keeps one address per remote.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param name - an existing remote name.
+ * @param url - the new URL.
+ */
+export async function setRemoteUrl(exec, cwd, name, url) {
+    await git(exec, cwd, ['remote', 'set-url', name, url]);
+    await git(exec, cwd, ['remote', 'set-url', '--push', name, url]);
+}
+/**
+ * Forget one remote (`git remote remove`): deletes its remote-tracking refs
+ * and its config section, never the objects the local branches share.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param name - an existing remote name.
+ */
+export async function removeRemote(exec, cwd, name) {
+    await git(exec, cwd, ['remote', 'remove', name]);
+}
 /**
  * Inspect one worktree directory for removal: how many files carry
  * uncommitted changes (those ARE lost with the folder), and how many commits