dsh-git-branch-manage 1.0.6 → 1.0.8

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,9 +302,96 @@ 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. */
+export type PushRemoteChoice = {
+    readonly ok: true;
+    readonly remote: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Pick the remote ONE tag push goes to, in fallback order: the checked-out
+ * branch's upstream remote, `remote.pushDefault`, then the only remote there
+ * is. Ambiguity is reported instead of guessed — a tag pushed to the wrong
+ * remote is a published mistake, not an inconvenience.
+ * @param exec - executor seam.
+ * @param cwd - directory whose checked-out branch supplies the upstream.
+ * @returns the remote name, or the caller-side reason none could be chosen.
+ */
+export declare function resolvePushRemote(exec: Exec, cwd: string): Promise<PushRemoteChoice>;
+/** Outcome of {@link pushTag}: the tag, where it went, and whether it moved. */
+export interface TagPushOutcome {
+    tag: string;
+    remote: string;
+    pushed: boolean;
+}
+/**
+ * Push ONE existing local tag to `remote` (`git push <remote>
+ * refs/tags/<name>:refs/tags/<name>`) — the publish step a tag needs and a
+ * branch push never performs: `git push` sends the current branch alone, so a
+ * tag made on an already-pushed commit is invisible to the remote.
+ *
+ * The tag must already exist locally (the route verifies it against
+ * {@link listTagNames}); a remote that already carries the SAME tag object is
+ * reported as `pushed: false` without running the push at all. The refspec
+ * always names both sides explicitly, so no configured push refspec (a mirror,
+ * a `push.default=upstream` branch) can widen what a menu click publishes, and
+ * tags are never deleted or overwritten: `--force` is deliberately absent, and
+ * a remote tag pointing somewhere else makes git refuse (mapped to 400).
+ *
+ * The cn-accelerate rewrite is never injected here (no {@link accelArgs}
+ * parameter exists, like {@link pushBranch}): a mirror has no `receive-pack` —
+ * and the pre-push probe must see the very remote the push targets, or the
+ * `pushed` flag would compare two different servers.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository (tag refs are shared).
+ * @param name - an existing local tag name.
+ * @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, 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). */