dsh-git-branch-manage 1.2.0 → 1.3.0

package/lib/network-ip.js

@@ -0,0 +1,206 @@
+/** Budget for ONE pinned probe; candidates run in parallel, so the race is bounded by this. */
+export const IP_PROBE_TIMEOUT_MS = 5_000;
+/** How long a winning channel is reused before the IPs are re-resolved. */
+export const IP_CACHE_TTL_MS = 600_000;
+/**
+ * Concurrent candidates. Probes run in parallel, so the wall clock is one
+ * timeout no matter how many run; this only bounds process count.
+ */
+export const MAX_IP_CANDIDATES = 6;
+/** Hosts this channel applies to. A mirror or an enterprise host has its own DNS. */
+const OPTIMIZABLE_HOSTS = ['github.com'];
+/** DNS-over-HTTPS resolvers, tried in order until one answers. */
+const DOH_URLS = [
+    host => `https://dns.alidns.com/resolve?name=${encodeURIComponent(host)}&type=A`,
+    host => `https://doh.pub/dns-query?name=${encodeURIComponent(host)}&type=A`,
+    host => `https://doh.360.cn/resolve?name=${encodeURIComponent(host)}&type=A`,
+];
+/**
+ * Hostnames whose answers widen the candidate pool for `github.com`.
+ *
+ * Measured on 2026-11-03: `dns.alidns.com` answered a single address for
+ * `github.com` (20.205.243.166) and `doh.pub` answered a different one
+ * (140.82.112.3) — one resolver gives one edge, and that edge may be dead.
+ * GitHub's edge fleet serves `api.`/`codeload.` from the same ranges, so their
+ * answers are extra tickets in the same lottery. Every candidate still has to
+ * answer a real `ls-remote` before it is used, so a wrong guess costs one
+ * parallel probe and nothing else.
+ */
+const SIBLING_SOURCES = ['api.github.com', 'codeload.github.com'];
+const cache = new Map();
+/** Drop every cached channel (tests, and a user-triggered re-probe). */
+export function resetIpChannelCache() {
+    cache.clear();
+}
+/**
+ * Pull the IPv4 answers out of one DoH JSON body. Anything malformed answers
+ * `[]` rather than throwing: a resolver hiccup must degrade to the direct
+ * channel, not fail the push before it starts.
+ */
+export function parseDohIps(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return [];
+    const answer = payload.Answer;
+    if (!Array.isArray(answer))
+        return [];
+    const ips = [];
+    for (const item of answer) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const record = item;
+        if (record.type !== 1 || typeof record.data !== 'string')
+            continue;
+        if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(record.data))
+            continue;
+        if (!record.data.split('.').every(part => Number(part) <= 255))
+            continue;
+        if (!ips.includes(record.data))
+            ips.push(record.data);
+    }
+    return ips;
+}
+/** Budget for one DoH query. Three resolvers are asked in parallel, so this bounds resolution. */
+export const DOH_TIMEOUT_MS = 3_000;
+/** One DoH question, or no answers (a blocked resolver is a normal state, not an error). */
+async function askResolver(url, fetchImpl) {
+    try {
+        const response = await fetchImpl(url, {
+            headers: { accept: 'application/dns-json' },
+            signal: AbortSignal.timeout(DOH_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return [];
+        return parseDohIps(await response.json());
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Ask every resolver about one host, in parallel, and union the answers.
+ *
+ * Sequential fallback was measured to be the wrong shape: the resolvers that
+ * are blocked here are blocked for the full timeout each, so a "fallback
+ * chain" spends three timeouts to learn what one parallel round trip tells.
+ * @param host - hostname to resolve.
+ * @param fetchImpl - fetch seam (tests inject a stub).
+ */
+export async function resolveHostIps(host, fetchImpl = fetch) {
+    const answers = await Promise.all(DOH_URLS.map(url => askResolver(url(host), fetchImpl)));
+    const ips = [];
+    for (const answer of answers) {
+        for (const ip of answer) {
+            if (!ips.includes(ip))
+                ips.push(ip);
+        }
+    }
+    return ips;
+}
+/**
+ * Candidates to race for one endpoint: the endpoint's own answers first, then
+ * the sibling services' answers (only for `github.com`), deduplicated and
+ * capped at {@link MAX_IP_CANDIDATES}. Everything runs in parallel, so the
+ * whole lookup is bounded by {@link DOH_TIMEOUT_MS}.
+ * @param host - endpoint hostname.
+ * @param fetchImpl - fetch seam.
+ */
+export async function candidateIpsFor(host, fetchImpl = fetch) {
+    const sources = host === 'github.com' ? [host, ...SIBLING_SOURCES] : [host];
+    const answers = await Promise.all(sources.map(source => resolveHostIps(source, fetchImpl)));
+    const ips = [];
+    for (const answer of answers) {
+        for (const ip of answer) {
+            if (!ips.includes(ip))
+                ips.push(ip);
+        }
+    }
+    return ips.slice(0, MAX_IP_CANDIDATES);
+}
+/** Whether this endpoint is one the pinned-IP channel may rewrite. */
+export function isOptimizableEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        return url.protocol === 'https:' && OPTIMIZABLE_HOSTS.includes(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The argv that pins `host:443` to one IP for a single command. `-c` goes
+ * before the subcommand, per git's global-option rule.
+ */
+export function pinArgs(host, ip) {
+    return ['-c', `http.curloptResolve=${host}:443:${ip}`];
+}
+/**
+ * Race up to {@link MAX_IP_CANDIDATES} pinned channels and answer the argv of
+ * the first that actually answers `ls-remote`. "First" means first to
+ * SUCCEED: all candidates start together and a slow-but-working IP can beat
+ * one that fails later.
+ * @param ips - candidates in resolver order.
+ * @param host - hostname being pinned.
+ * @param probe - one pinned probe (the caller supplies the budget + argv).
+ * @returns the winning `-c` argv, or undefined when every candidate failed.
+ */
+export async function racePinnedChannels(ips, host, probe) {
+    const candidates = ips.slice(0, MAX_IP_CANDIDATES);
+    const results = await Promise.all(candidates.map(async (ip) => {
+        const args = pinArgs(host, ip);
+        try {
+            await probe(args);
+            return args;
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    // Promise.all keeps resolver order, so a tie goes to the first answer.
+    return results.find(item => item !== undefined);
+}
+/**
+ * The channel a read/write may fall back to when the direct one fails in a
+ * retryable way. Wraps resolution + race + caching; answers undefined for
+ * endpoints outside {@link OPTIMIZABLE_HOSTS} or when nothing works.
+ * @param options.endpoint - the URL the command would use.
+ * @param options.probe - one pinned probe, built by {@link pinnedProbe}.
+ * @param options.now - clock seam for the cache.
+ * @param options.fetchImpl - DoH fetch seam.
+ */
+export async function pinnedChannelFor(options) {
+    const { endpoint, probe } = options;
+    if (!isOptimizableEndpoint(endpoint))
+        return undefined;
+    const host = new URL(endpoint).hostname;
+    const now = options.now ?? Date.now;
+    const cached = cache.get(endpoint);
+    if (cached !== undefined && now() - cached.at < IP_CACHE_TTL_MS)
+        return cached.args;
+    const ips = await candidateIpsFor(host, options.fetchImpl);
+    if (ips.length === 0)
+        return undefined;
+    const args = await racePinnedChannels(ips, host, probe);
+    if (args !== undefined)
+        cache.set(endpoint, { args, at: now() });
+    return args;
+}
+/**
+ * Build the probe the race runs: one pinned `ls-remote` at the probe budget,
+ * with terminal prompts disabled so a credentialed endpoint fails instead of
+ * hanging on an invisible dialog.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param endpoint - URL being probed.
+ * @param authArgs - per-host credential argv.
+ */
+export function pinnedProbe(exec, cwd, endpoint, authArgs = []) {
+    return async (args) => {
+        const result = await exec('git', [...args, ...authArgs, 'ls-remote', '--heads', endpoint], {
+            cwd,
+            timeoutMs: IP_PROBE_TIMEOUT_MS,
+            env: { GIT_TERMINAL_PROMPT: '0' },
+        });
+        if (result.code !== 0)
+            throw new Error(result.errorMessage ?? result.stderr ?? 'pinned probe failed');
+    };
+}

package/lib/network-probe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Channel diagnostics for the settings UI: one read of the endpoint per
+ * channel, so a user whose network is failing can see WHICH path reaches
+ * GitHub instead of guessing.
+ *
+ * A probe is the same judgement the write path makes (0041/0042), run on
+ * demand: the channel is good only when `ls-remote` exits 0. A TCP-level
+ * "reachable" proves nothing — measured on 2026-11-03, 7 of 8 GitHub edges
+ * accepted a connection and still failed the read.
+ *
+ * @module git-worktree/network-probe
+ */
+import type { Exec } from './git.js';
+import type { NetworkChannelId, NetworkChannelReport } from './wire.js';
+/**
+ * Probe one channel by reading the endpoint through it.
+ *
+ * Failures are returned as data: a dead channel must not hide the next one,
+ * and the caller renders every report side by side.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param channel - which channel this argv stands for.
+ * @param url - endpoint to read.
+ * @param channelArgs - the channel's argv prefix (empty for direct).
+ * @param authArgs - credential argv for this host.
+ * @returns the channel's verdict, failures included.
+ */
+export declare function channelReport(exec: Exec, cwd: string, channel: NetworkChannelId, url: string, channelArgs: readonly string[], authArgs?: readonly string[]): Promise<NetworkChannelReport>;

package/lib/network-probe.js

@@ -0,0 +1,47 @@
+/**
+ * Channel diagnostics for the settings UI: one read of the endpoint per
+ * channel, so a user whose network is failing can see WHICH path reaches
+ * GitHub instead of guessing.
+ *
+ * A probe is the same judgement the write path makes (0041/0042), run on
+ * demand: the channel is good only when `ls-remote` exits 0. A TCP-level
+ * "reachable" proves nothing — measured on 2026-11-03, 7 of 8 GitHub edges
+ * accepted a connection and still failed the read.
+ *
+ * @module git-worktree/network-probe
+ */
+import { PROBE_TIMEOUT_MS } from './network.js';
+const DETAIL_LIMIT = 300;
+/**
+ * Keep a failure readable in a toast: the first non-empty line, capped.
+ * @param text - raw stderr or error message.
+ */
+function firstLine(text) {
+    const line = text.split(/\r?\n/).find(item => item.trim() !== '') ?? '';
+    return line.length > DETAIL_LIMIT ? `${line.slice(0, DETAIL_LIMIT)}…` : line;
+}
+/**
+ * Probe one channel by reading the endpoint through it.
+ *
+ * Failures are returned as data: a dead channel must not hide the next one,
+ * and the caller renders every report side by side.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param channel - which channel this argv stands for.
+ * @param url - endpoint to read.
+ * @param channelArgs - the channel's argv prefix (empty for direct).
+ * @param authArgs - credential argv for this host.
+ * @returns the channel's verdict, failures included.
+ */
+export async function channelReport(exec, cwd, channel, url, channelArgs, authArgs = []) {
+    const started = Date.now();
+    const result = await exec('git', [...channelArgs, ...authArgs, 'ls-remote', '--heads', url], {
+        cwd,
+        timeoutMs: PROBE_TIMEOUT_MS,
+        env: { GIT_TERMINAL_PROMPT: '0' },
+    });
+    const elapsedMs = Date.now() - started;
+    if (result.code === 0)
+        return { channel, ok: true, elapsedMs };
+    return { channel, ok: false, elapsedMs, detail: firstLine(result.errorMessage ?? result.stderr) };
+}

package/lib/network-proxy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The third network channel: an explicit proxy, or the one Windows already
+ * has configured.
+ *
+ * Why the registry matters: git links libcurl, and libcurl does NOT read the
+ * WinINET/PAC settings that every browser on the machine honours. Measured on
+ * 2026-11-03 with a dead local proxy: `git ls-remote` failed with
+ * `Failed to connect to github.com:443 over proxy 127.0.0.1` the moment
+ * `-c http.proxy=…` was passed, i.e. git honours the argv and ignores the
+ * system setting entirely. A `gitport`-style tool bundles its own proxy; this
+ * plugin instead borrows the user's, and needs a way to find it.
+ */
+import type { Exec } from './git.js';
+import { proxyUrlError } from './normalize.js';
+/** A registry read is local and cheap; it must not become the slowest step. */
+export declare const SYSTEM_PROXY_TIMEOUT_MS = 3000;
+/** Re-exported so host callers keep one import site for the proxy rules. */
+export { proxyUrlError };
+/** The argv that routes one command through the proxy; `-c` precedes the subcommand. */
+export declare function proxyArgs(url: string): readonly string[];
+/**
+ * Parse the `ProxyServer` value WinINET stores, which is either `host:port` or
+ * a per-scheme list like `http=host:port;https=host:port`. The https entry
+ * wins; a plain value is used as is. Anything malformed answers undefined.
+ * @param raw - stdout of `reg query … /v ProxyServer`.
+ */
+export declare function parseProxyServer(raw: string): string | undefined;
+/**
+ * The system proxy Windows already has configured, when it is enabled and
+ * points somewhere usable; undefined otherwise (off Windows, disabled, empty,
+ * or unparseable). Read-only: nothing here changes the machine's settings.
+ * @param exec - executor seam.
+ * @param cwd - directory for the `reg` calls.
+ */
+export declare function systemProxyUrl(exec: Exec, cwd: string): Promise<string | undefined>;

package/lib/network-proxy.js

@@ -0,0 +1,55 @@
+import { proxyUrlError } from './normalize.js';
+/** A registry read is local and cheap; it must not become the slowest step. */
+export const SYSTEM_PROXY_TIMEOUT_MS = 3_000;
+const INTERNET_SETTINGS = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings';
+/** Re-exported so host callers keep one import site for the proxy rules. */
+export { proxyUrlError };
+/** The argv that routes one command through the proxy; `-c` precedes the subcommand. */
+export function proxyArgs(url) {
+    return ['-c', `http.proxy=${url}`];
+}
+/**
+ * Parse the `ProxyServer` value WinINET stores, which is either `host:port` or
+ * a per-scheme list like `http=host:port;https=host:port`. The https entry
+ * wins; a plain value is used as is. Anything malformed answers undefined.
+ * @param raw - stdout of `reg query … /v ProxyServer`.
+ */
+export function parseProxyServer(raw) {
+    const line = raw.split(/\r?\n/).find(item => /ProxyServer\s+REG_SZ/i.test(item));
+    if (line === undefined)
+        return undefined;
+    const value = line.replace(/^.*?ProxyServer\s+REG_SZ\s*/i, '').trim();
+    if (value === '')
+        return undefined;
+    if (!value.includes('='))
+        return value.includes(':') ? `http://${value}` : undefined;
+    const entries = value.split(';').map(item => item.trim()).filter(item => item !== '');
+    const https = entries.find(item => /^https=/i.test(item));
+    const chosen = https ?? entries.find(item => /^http=/i.test(item)) ?? entries[0];
+    const address = chosen?.replace(/^[a-z]+=/i, '').trim();
+    if (address === undefined || address === '' || !address.includes(':'))
+        return undefined;
+    const scheme = https === undefined ? 'http' : 'https';
+    return `${scheme}://${address}`;
+}
+/**
+ * The system proxy Windows already has configured, when it is enabled and
+ * points somewhere usable; undefined otherwise (off Windows, disabled, empty,
+ * or unparseable). Read-only: nothing here changes the machine's settings.
+ * @param exec - executor seam.
+ * @param cwd - directory for the `reg` calls.
+ */
+export async function systemProxyUrl(exec, cwd) {
+    if (process.platform !== 'win32')
+        return undefined;
+    const enabled = await exec('reg', ['query', INTERNET_SETTINGS, '/v', 'ProxyEnable'], { cwd, timeoutMs: SYSTEM_PROXY_TIMEOUT_MS });
+    if (enabled.code !== 0 || !/ProxyEnable\s+REG_DWORD\s+0x1\b/i.test(enabled.stdout))
+        return undefined;
+    const server = await exec('reg', ['query', INTERNET_SETTINGS, '/v', 'ProxyServer'], { cwd, timeoutMs: SYSTEM_PROXY_TIMEOUT_MS });
+    if (server.code !== 0)
+        return undefined;
+    const url = parseProxyServer(server.stdout);
+    if (url === undefined)
+        return undefined;
+    return proxyUrlError(url) === undefined ? url : undefined;
+}

package/lib/network-tool.js

@@ -18,7 +18,8 @@
  */
 import { isAbsolute } from 'node:path';
 import { basicUsername, createLocalCredentialStore, } from './credentials.js';
-import { childProcessExec, NETWORK_TIMEOUT_MS } from './git.js';
+import { childProcessExec } from './git.js';
+import { FETCH_TIMEOUT_MS } from './network.js';
 /** Model-facing tool name. */
 export const GIT_NETWORK_TOOL_NAME = 'git_network';
 /** The only git subcommands this tool will run. */
@@ -224,7 +225,7 @@ export function gitNetworkTool(deps) {
             // the same token serves this command and a plain shell `git push`.
             const result = await exec('git', request.args, {
                 cwd: request.repoPath,
-                timeoutMs: NETWORK_TIMEOUT_MS,
+                timeoutMs: FETCH_TIMEOUT_MS,
             });
             const stdout = cap(redactSecrets(result.stdout, entries));
             const stderrSource = result.stderr.trim() === '' && result.errorMessage !== undefined

package/lib/network.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Network policy for the host half: how long each remote operation may take,
+ * what a failed one actually means, and how a push that timed out is
+ * reconciled with the remote afterwards. Nothing here spawns a process — the
+ * budgets and the classifier are plain data so both the git wrapper and the
+ * routes can use them without a second seam.
+ */
+/**
+ * Budget for one reachability probe (`ls-remote`): a probe exists to fail
+ * FAST, so a dead host costs seconds, not the minutes a real transfer gets.
+ */
+export declare const PROBE_TIMEOUT_MS = 10000;
+/**
+ * Budget for the READ half of the network (fetch/update): a slow link with a
+ * real pack transfer outruns the local default, so this is deliberately wide.
+ */
+export declare const FETCH_TIMEOUT_MS = 300000;
+/**
+ * Budget for the WRITE half (push/push-tag). Wider than fetch: a push that
+ * is killed mid-transfer may already have updated the remote refs, and the
+ * caller pays for that ambiguity with a verification round-trip.
+ */
+export declare const PUSH_TIMEOUT_MS = 600000;
+/** Budget for the post-timeout reconciliation (`ls-remote` after a push). */
+export declare const VERIFY_TIMEOUT_MS = 10000;
+/** What a failed git network command most likely means. */
+export type GitFailureKind = 'timeout' | 'unreachable' | 'reset' | 'proxy' | 'tls' | 'credentials' | 'diverged' | 'protected' | 'unknown';
+/** Diagnosis of one failed remote command. */
+export interface GitFailure {
+    /** The shape of the failure; the UI may key wording off it later. */
+    kind: GitFailureKind;
+    /**
+     * Whether another network channel (a pinned IP, a proxy) could plausibly
+     * make the SAME command succeed. Credential, TLS, divergence and hook
+     * failures are about state, not reachability, so they never retry.
+     */
+    retryable: boolean;
+    /** One sentence the caller may append to the toast; undefined = say nothing. */
+    hint: string | undefined;
+}
+/**
+ * Classify one failed git network command from its diagnostic text.
+ * @param stderr - git's diagnostic (stderr, or the executor's fallback text).
+ * @param options - `timedOut` when the executor killed the process at its
+ * budget; that outranks the text, because a killed push carries no verdict.
+ * @returns the kind, whether another channel may help, and a one-line hint.
+ */
+export declare function classifyGitFailure(stderr: string, options?: {
+    timedOut?: boolean;
+}): GitFailure;
+/**
+ * Append a classified hint to git's own message, once: the raw diagnostic
+ * stays first so the user can still copy it into a bug report.
+ * @param message - the existing error text.
+ * @param failure - classifier output.
+ * @returns the message with the hint appended, unchanged when there is none.
+ */
+export declare function withHint(message: string, failure: GitFailure): string;

package/lib/network.js

@@ -0,0 +1,128 @@
+/**
+ * Network policy for the host half: how long each remote operation may take,
+ * what a failed one actually means, and how a push that timed out is
+ * reconciled with the remote afterwards. Nothing here spawns a process — the
+ * budgets and the classifier are plain data so both the git wrapper and the
+ * routes can use them without a second seam.
+ */
+/**
+ * Budget for one reachability probe (`ls-remote`): a probe exists to fail
+ * FAST, so a dead host costs seconds, not the minutes a real transfer gets.
+ */
+export const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * Budget for the READ half of the network (fetch/update): a slow link with a
+ * real pack transfer outruns the local default, so this is deliberately wide.
+ */
+export const FETCH_TIMEOUT_MS = 300_000;
+/**
+ * Budget for the WRITE half (push/push-tag). Wider than fetch: a push that
+ * is killed mid-transfer may already have updated the remote refs, and the
+ * caller pays for that ambiguity with a verification round-trip.
+ */
+export const PUSH_TIMEOUT_MS = 600_000;
+/** Budget for the post-timeout reconciliation (`ls-remote` after a push). */
+export const VERIFY_TIMEOUT_MS = 10_000;
+/** Patterns are matched in order: the first hit wins. */
+const RULES = [
+    {
+        kind: 'proxy',
+        retryable: false,
+        hint: 'The configured proxy refused or failed the CONNECT tunnel; check the proxy address or turn it off.',
+        test: text => /over proxy/i.test(text)
+            || /Proxy CONNECT aborted/i.test(text)
+            || /CONNECT tunnel failed/i.test(text)
+            || /Received HTTP code 407/i.test(text),
+    },
+    {
+        kind: 'credentials',
+        retryable: false,
+        hint: 'Git could not read usable credentials; sign in for this host in the credentials panel, then retry.',
+        test: text => /terminal prompts disabled/i.test(text)
+            || /could not read Username/i.test(text)
+            || /Authentication failed/i.test(text)
+            || /Permission denied \(publickey/i.test(text)
+            || /HTTP 40[13]\b/.test(text),
+    },
+    {
+        kind: 'unreachable',
+        retryable: true,
+        hint: 'The host could not be reached; retry, then pin an IP or use a proxy.',
+        test: text => /Could not resolve host/i.test(text)
+            || /Failed to connect/i.test(text)
+            || /Could not connect to server/i.test(text)
+            || /Connection refused/i.test(text)
+            || /Network is unreachable/i.test(text),
+    },
+    {
+        kind: 'reset',
+        retryable: true,
+        hint: 'The connection was reset mid-transfer; retry, then pin an IP or use a proxy.',
+        test: text => /Connection was reset/i.test(text)
+            || /Recv failure/i.test(text)
+            || /RPC failed/i.test(text)
+            || /early EOF/i.test(text)
+            || /remote end hung up unexpectedly/i.test(text)
+            || /unexpected disconnect/i.test(text),
+    },
+    {
+        kind: 'tls',
+        retryable: false,
+        hint: 'TLS negotiation failed; the network is intercepting the connection or the certificate is untrusted.',
+        test: text => /SSL certificate problem/i.test(text)
+            || /schannel/i.test(text)
+            || /SSL_ERROR/i.test(text)
+            || /tlsv1 alert/i.test(text),
+    },
+    {
+        kind: 'diverged',
+        retryable: false,
+        hint: 'The remote has commits you do not have; pull or rebase before pushing (the plugin never forces).',
+        test: text => /non-fast-forward/i.test(text)
+            || /fetch first/i.test(text)
+            || /Not possible to fast-forward/i.test(text)
+            || /\[rejected\]/i.test(text),
+    },
+    {
+        kind: 'protected',
+        retryable: false,
+        hint: 'A server-side rule refused the update (protected branch or hook); resolve it on the host, not in the network.',
+        test: text => /protected branch/i.test(text)
+            || /hook declined/i.test(text)
+            || /pre-receive hook/i.test(text),
+    },
+];
+/**
+ * Classify one failed git network command from its diagnostic text.
+ * @param stderr - git's diagnostic (stderr, or the executor's fallback text).
+ * @param options - `timedOut` when the executor killed the process at its
+ * budget; that outranks the text, because a killed push carries no verdict.
+ * @returns the kind, whether another channel may help, and a one-line hint.
+ */
+export function classifyGitFailure(stderr, options = {}) {
+    if (options.timedOut === true) {
+        return {
+            kind: 'timeout',
+            retryable: true,
+            hint: 'The command did not finish within its time budget; the remote may still be applying it — verify before retrying a push.',
+        };
+    }
+    const text = stderr.trim();
+    for (const rule of RULES) {
+        if (rule.test(text))
+            return { kind: rule.kind, retryable: rule.retryable, hint: rule.hint };
+    }
+    return { kind: 'unknown', retryable: false, hint: undefined };
+}
+/**
+ * Append a classified hint to git's own message, once: the raw diagnostic
+ * stays first so the user can still copy it into a bug report.
+ * @param message - the existing error text.
+ * @param failure - classifier output.
+ * @returns the message with the hint appended, unchanged when there is none.
+ */
+export function withHint(message, failure) {
+    if (failure.hint === undefined || message.includes(failure.hint))
+        return message;
+    return `${message}\n\n${failure.hint}`;
+}

package/lib/normalize.d.ts

@@ -75,8 +75,8 @@ export type AccelerateUrlIssue = 'empty' | 'invalid';
 export declare function accelerateUrlError(value: string): AccelerateUrlIssue | undefined;
 /**
  * Normalize an accepted accelerate URL: trim, and append the trailing `/`
- * the prefix concatenation requires (`https://gh-proxy.com/` + `o/r.git`
- * must stay one valid URL). Callers pass the result to `url.<base>.insteadOf`.
+ * the prefix concatenation requires (`https://gh-proxy.com/` + the complete
+ * `https://github.com/o/r.git` URL). accelArgs builds the Git rewrite base.
  * @param value - an accepted (non-empty, http(s), whitespace-free) URL.
  * @returns the prefix ending in `/`.
  */
@@ -105,3 +105,15 @@ export type RemoteUrlIssue = 'empty' | 'whitespace' | 'invalid';
  * @returns the issue kind, or undefined when acceptable.
  */
 export declare function remoteUrlIssue(url: string): RemoteUrlIssue | undefined;
+/** Schemes git's libcurl accepts for an HTTP(S) remote. */
+export declare const PROXY_SCHEMES: readonly string[];
+/**
+ * Why this proxy value cannot be used, or undefined when it can.
+ *
+ * Credentials are rejected on purpose: the value is stored in the plugin
+ * config and passed as one `-c` argument, so `user:pass@` would be readable
+ * in the settings UI and in any diagnostics (0043).
+ * @param value - candidate proxy URL.
+ * @returns the user-facing reason, or undefined.
+ */
+export declare function proxyUrlError(value: string): string | undefined;

package/lib/normalize.js

@@ -117,8 +117,8 @@ export function accelerateUrlError(value) {
 }
 /**
  * Normalize an accepted accelerate URL: trim, and append the trailing `/`
- * the prefix concatenation requires (`https://gh-proxy.com/` + `o/r.git`
- * must stay one valid URL). Callers pass the result to `url.<base>.insteadOf`.
+ * the prefix concatenation requires (`https://gh-proxy.com/` + the complete
+ * `https://github.com/o/r.git` URL). accelArgs builds the Git rewrite base.
  * @param value - an accepted (non-empty, http(s), whitespace-free) URL.
  * @returns the prefix ending in `/`.
  */
@@ -173,3 +173,39 @@ export function remoteUrlIssue(url) {
         return undefined;
     return 'invalid';
 }
+/** Schemes git's libcurl accepts for an HTTP(S) remote. */
+export const PROXY_SCHEMES = ['http', 'https', 'socks5', 'socks5h'];
+/**
+ * Why this proxy value cannot be used, or undefined when it can.
+ *
+ * Credentials are rejected on purpose: the value is stored in the plugin
+ * config and passed as one `-c` argument, so `user:pass@` would be readable
+ * in the settings UI and in any diagnostics (0043).
+ * @param value - candidate proxy URL.
+ * @returns the user-facing reason, or undefined.
+ */
+export function proxyUrlError(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return 'must be an absolute proxy URL such as http://127.0.0.1:7890';
+    }
+    if (!PROXY_SCHEMES.includes(url.protocol.replace(':', ''))) {
+        return `scheme must be one of ${PROXY_SCHEMES.join(', ')}`;
+    }
+    if (url.hostname === '')
+        return 'must name a proxy host';
+    if (url.port === '')
+        return 'must name a proxy port';
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        return 'proxy port must be 1-65535';
+    if (url.username !== '' || url.password !== '')
+        return 'credentials in the proxy URL are not supported';
+    if ((url.pathname !== '' && url.pathname !== '/') || url.search !== '' || url.hash !== '') {
+        return 'must not carry a path, query, or fragment';
+    }
+    return undefined;
+}