dsh-git-branch-manage 1.0.7 → 1.0.8

package/lib/normalize.d.ts

@@ -81,3 +81,27 @@ export declare function accelerateUrlError(value: string): AccelerateUrlIssue |
  * @returns the prefix ending in `/`.
  */
 export declare function normalizeAccelerateUrl(value: string): string;
+/** Why a user-typed REMOTE name is not acceptable yet (null = fine). */
+export type RemoteNameIssue = 'empty' | 'leadingDash' | 'illegal';
+/**
+ * Pre-flight check of a remote name: non-empty; no leading `-` (git would
+ * parse it as a flag); letters, digits, `.`, `_` and `-` only (`/`, space and
+ * `~^:?*[\` are outside what a remote name can be typed as here); the lone
+ * `.`/`..` are rejected. Git stays the authority — a miss surfaces through
+ * the error envelope — this only feeds immediate form feedback.
+ * @param name - raw draft text.
+ * @returns the issue kind, or null when acceptable.
+ */
+export declare function remoteNameIssue(name: string): RemoteNameIssue | null;
+/** Why a user-typed REMOTE URL is not acceptable yet (undefined = fine). */
+export type RemoteUrlIssue = 'empty' | 'whitespace' | 'invalid';
+/**
+ * Pre-flight check of a remote URL. Accepted shapes: any `scheme://…` URL
+ * (`https://`, `ssh://`, `git://`, `file://`), an scp-like
+ * `user@host:path`, and an absolute local path (a legitimate `file` remote).
+ * Everything else — a bare word, a URL with stray whitespace, a value git
+ * would read as a flag — is rejected. Git validates the remote once added.
+ * @param url - raw draft text.
+ * @returns the issue kind, or undefined when acceptable.
+ */
+export declare function remoteUrlIssue(url: string): RemoteUrlIssue | undefined;

package/lib/normalize.js

@@ -126,3 +126,50 @@ export function normalizeAccelerateUrl(value) {
     const trimmed = value.trim();
     return trimmed.endsWith('/') ? trimmed : `${trimmed}/`;
 }
+/**
+ * Pre-flight check of a remote name: non-empty; no leading `-` (git would
+ * parse it as a flag); letters, digits, `.`, `_` and `-` only (`/`, space and
+ * `~^:?*[\` are outside what a remote name can be typed as here); the lone
+ * `.`/`..` are rejected. Git stays the authority — a miss surfaces through
+ * the error envelope — this only feeds immediate form feedback.
+ * @param name - raw draft text.
+ * @returns the issue kind, or null when acceptable.
+ */
+export function remoteNameIssue(name) {
+    if (name.trim() === '')
+        return 'empty';
+    if (name.startsWith('-'))
+        return 'leadingDash';
+    if (!/^[A-Za-z0-9._-]+$/.test(name))
+        return 'illegal';
+    if (name === '.' || name === '..')
+        return 'illegal';
+    return null;
+}
+/**
+ * Pre-flight check of a remote URL. Accepted shapes: any `scheme://…` URL
+ * (`https://`, `ssh://`, `git://`, `file://`), an scp-like
+ * `user@host:path`, and an absolute local path (a legitimate `file` remote).
+ * Everything else — a bare word, a URL with stray whitespace, a value git
+ * would read as a flag — is rejected. Git validates the remote once added.
+ * @param url - raw draft text.
+ * @returns the issue kind, or undefined when acceptable.
+ */
+export function remoteUrlIssue(url) {
+    const trimmed = url.trim();
+    if (trimmed === '')
+        return 'empty';
+    if (trimmed.startsWith('-'))
+        return 'invalid';
+    // Local-path remotes may contain spaces (`C:\my repo`), so the path shape
+    // is classified before the whitespace rule.
+    if (isAbsoluteConfigPath(trimmed))
+        return undefined;
+    if (/\s/.test(trimmed))
+        return 'whitespace';
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(trimmed))
+        return undefined;
+    if (/^[^\s@/]+@[^\s:/]+:\S+$/.test(trimmed))
+        return undefined;
+    return 'invalid';
+}

package/lib/oauth.d.ts

@@ -0,0 +1,109 @@
+/**
+ * GitHub OAuth device flow behind the credential dialog's site sign-in.
+ *
+ * A browser sign-in must never need a client SECRET (that would have to ship
+ * in the bundle) and must work from a machine that cannot accept inbound
+ * connections, so the plugin uses the OAuth 2.0 device authorization grant:
+ * the host asks GitHub for a one-time user code, the dialog opens the browser
+ * and shows that code, and the plugin polls the token endpoint until the user
+ * approves. The token that comes back is stored like a pasted personal access
+ * token (method `token`) and the user never sees a raw PAT workflow.
+ *
+ * Only hosts whose device flow this module knows are accepted; the caller
+ * decides which of them to offer in the UI.
+ *
+ * @module git-worktree/oauth
+ */
+/** The hosts whose device flow this module implements. The dialog imports the
+ * same list, so the offered buttons cannot drift from what the host supports. */
+export declare const DEVICE_FLOW_HOSTS: readonly string[];
+/**
+ * Fallback OAuth App client id. GitHub's device flow requires a client id but
+ * never a client secret; the shipped value is the public GitHub CLI app,
+ * which lets a stock `gh` install and this plugin sign in with the same app.
+ * Point `DSH_GITHUB_OAUTH_CLIENT_ID` at a dedicated OAuth App to use one.
+ */
+export declare const DEFAULT_OAUTH_CLIENT_ID = "178c6fc778ccc68e1d6a";
+/** Scopes one push needs: `repo` covers private repositories and write access. */
+export declare const OAUTH_SCOPE = "repo";
+/** One device-code grant, reduced to what the browser needs to show/open. */
+export interface DeviceCodeGrant {
+    /** Polling credential; never rendered. */
+    deviceCode: string;
+    /** The short code the user types on the verification page. */
+    userCode: string;
+    /** Verification page (without the code). */
+    verificationUri: string;
+    /** Verification page with the code pre-filled, when GitHub returns one. */
+    verificationUriComplete?: string;
+    /** Minimum seconds between polls. */
+    intervalSeconds: number;
+    /** Seconds until the grant expires. */
+    expiresInSeconds: number;
+}
+/** One poll answer: the finished token, or why there is no token yet. */
+export type DeviceFlowPoll = {
+    status: 'token';
+    token: string;
+} | {
+    status: 'pending';
+} | {
+    status: 'slow_down';
+}
+/** The transport broke (DNS, TLS, reset keep-alive connection): the grant is
+ * untouched, so a poll loop should retry instead of ending the sign-in. */
+ | {
+    status: 'network';
+    message: string;
+} | {
+    status: 'denied';
+    message: string;
+} | {
+    status: 'expired';
+    message: string;
+} | {
+    status: 'failed';
+    message: string;
+};
+/**
+ * The OAuth App client id to use: the environment override when set, else the
+ * shipped default.
+ * @param env - environment seam (`process.env` in production).
+ */
+export declare function deviceFlowClientId(env?: Readonly<Record<string, string | undefined>>): string;
+/** Whether browser sign-in is implemented for this (normalized) host. */
+export declare function isDeviceFlowHost(host: string): boolean;
+/**
+ * A request that never reached the host: DNS failure, TLS interference, or a
+ * reset pooled connection. Unlike an OAuth error answer this says nothing
+ * about the grant, so the poll loop may retry it.
+ */
+export declare class DeviceFlowTransportError extends Error {
+    /** The endpoint that could not be reached. */
+    readonly url: string;
+    /**
+     * @param url - the endpoint that could not be reached.
+     * @param cause - the underlying fetch failure.
+     */
+    constructor(url: string, cause: unknown);
+}
+/**
+ * Ask GitHub for a device code. The caller opens `verificationUriComplete`
+ * (or `verificationUri` plus the shown `userCode`) and then polls.
+ * @param fetchImpl - fetch seam (global fetch in production, a fake in tests).
+ * @param host - normalized host; must be a {@link DEVICE_FLOW_HOSTS} member.
+ * @param clientId - OAuth App client id, see {@link deviceFlowClientId}.
+ * @param timeoutMs - per-request budget for the device-code request.
+ */
+export declare function startDeviceFlow(fetchImpl: typeof fetch, host: string, clientId: string, timeoutMs?: number): Promise<DeviceCodeGrant>;
+/**
+ * Poll the token endpoint once for one grant. GitHub answers `400` with an
+ * `error` code until the user acts, so a pending grant is a normal answer,
+ * not a thrown failure; only transport problems throw.
+ * @param fetchImpl - fetch seam.
+ * @param host - normalized host.
+ * @param clientId - the same client id the grant was started with.
+ * @param deviceCode - the grant's `deviceCode`.
+ * @param timeoutMs - per-request budget for this poll.
+ */
+export declare function pollDeviceFlow(fetchImpl: typeof fetch, host: string, clientId: string, deviceCode: string, timeoutMs?: number): Promise<DeviceFlowPoll>;

package/lib/oauth.js

@@ -0,0 +1,182 @@
+/**
+ * GitHub OAuth device flow behind the credential dialog's site sign-in.
+ *
+ * A browser sign-in must never need a client SECRET (that would have to ship
+ * in the bundle) and must work from a machine that cannot accept inbound
+ * connections, so the plugin uses the OAuth 2.0 device authorization grant:
+ * the host asks GitHub for a one-time user code, the dialog opens the browser
+ * and shows that code, and the plugin polls the token endpoint until the user
+ * approves. The token that comes back is stored like a pasted personal access
+ * token (method `token`) and the user never sees a raw PAT workflow.
+ *
+ * Only hosts whose device flow this module knows are accepted; the caller
+ * decides which of them to offer in the UI.
+ *
+ * @module git-worktree/oauth
+ */
+import { BROWSER_SIGN_IN_HOSTS } from './wire.js';
+/** The hosts whose device flow this module implements. The dialog imports the
+ * same list, so the offered buttons cannot drift from what the host supports. */
+export const DEVICE_FLOW_HOSTS = BROWSER_SIGN_IN_HOSTS;
+/**
+ * Fallback OAuth App client id. GitHub's device flow requires a client id but
+ * never a client secret; the shipped value is the public GitHub CLI app,
+ * which lets a stock `gh` install and this plugin sign in with the same app.
+ * Point `DSH_GITHUB_OAUTH_CLIENT_ID` at a dedicated OAuth App to use one.
+ */
+export const DEFAULT_OAUTH_CLIENT_ID = '178c6fc778ccc68e1d6a';
+/** Scopes one push needs: `repo` covers private repositories and write access. */
+export const OAUTH_SCOPE = 'repo';
+/**
+ * The OAuth App client id to use: the environment override when set, else the
+ * shipped default.
+ * @param env - environment seam (`process.env` in production).
+ */
+export function deviceFlowClientId(env = process.env) {
+    const configured = env.DSH_GITHUB_OAUTH_CLIENT_ID?.trim();
+    return configured === undefined || configured === '' ? DEFAULT_OAUTH_CLIENT_ID : configured;
+}
+/** Whether browser sign-in is implemented for this (normalized) host. */
+export function isDeviceFlowHost(host) {
+    return DEVICE_FLOW_HOSTS.includes(host);
+}
+/** Read one non-empty string field from a parsed JSON object. */
+function readString(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/**
+ * A request that never reached the host: DNS failure, TLS interference, or a
+ * reset pooled connection. Unlike an OAuth error answer this says nothing
+ * about the grant, so the poll loop may retry it.
+ */
+export class DeviceFlowTransportError extends Error {
+    /** The endpoint that could not be reached. */
+    url;
+    /**
+     * @param url - the endpoint that could not be reached.
+     * @param cause - the underlying fetch failure.
+     */
+    constructor(url, cause) {
+        super(`${url} could not be reached (${cause instanceof Error ? cause.message : String(cause)})`);
+        this.name = 'DeviceFlowTransportError';
+        this.url = url;
+    }
+}
+/**
+ * POST one form-encoded body and parse the JSON answer. Network failures and
+ * unexpected non-2xx answers become one thrown Error; callers map it to a
+ * route failure. `allowErrorStatus` keeps the body of a documented OAuth
+ * error answer (the token endpoint reports a pending grant as `400`), which
+ * is an answer, not a transport failure.
+ */
+async function postForm(fetchImpl, url, fields, timeoutMs, allowErrorStatus = false) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body: new URLSearchParams(fields).toString(),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (error) {
+        throw new DeviceFlowTransportError(url, error);
+    }
+    let payload;
+    let parsed = false;
+    try {
+        payload = await response.json();
+        parsed = true;
+    }
+    catch {
+        parsed = false;
+    }
+    if (!parsed)
+        throw new Error(`${url} answered a non-JSON body`);
+    if (!response.ok && !allowErrorStatus)
+        throw new Error(`${url} answered HTTP ${String(response.status)}`);
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        throw new Error(`${url} answered an unexpected body`);
+    }
+    return payload;
+}
+/**
+ * Ask GitHub for a device code. The caller opens `verificationUriComplete`
+ * (or `verificationUri` plus the shown `userCode`) and then polls.
+ * @param fetchImpl - fetch seam (global fetch in production, a fake in tests).
+ * @param host - normalized host; must be a {@link DEVICE_FLOW_HOSTS} member.
+ * @param clientId - OAuth App client id, see {@link deviceFlowClientId}.
+ * @param timeoutMs - per-request budget for the device-code request.
+ */
+export async function startDeviceFlow(fetchImpl, host, clientId, timeoutMs = 15_000) {
+    const payload = await postForm(fetchImpl, `https://${host}/login/device/code`, { client_id: clientId, scope: OAUTH_SCOPE }, timeoutMs);
+    const deviceCode = readString(payload, 'device_code');
+    const userCode = readString(payload, 'user_code');
+    const verificationUri = readString(payload, 'verification_uri');
+    if (deviceCode === undefined || userCode === undefined || verificationUri === undefined) {
+        throw new Error(`${host} did not return a device code (is device flow enabled for the OAuth app?)`);
+    }
+    const interval = typeof payload.interval === 'number' && payload.interval > 0 ? payload.interval : 5;
+    const expiresIn = typeof payload.expires_in === 'number' && payload.expires_in > 0 ? payload.expires_in : 900;
+    const verificationUriComplete = readString(payload, 'verification_uri_complete');
+    return {
+        deviceCode,
+        userCode,
+        verificationUri,
+        ...(verificationUriComplete === undefined ? {} : { verificationUriComplete }),
+        intervalSeconds: interval,
+        expiresInSeconds: expiresIn,
+    };
+}
+/**
+ * Poll the token endpoint once for one grant. GitHub answers `400` with an
+ * `error` code until the user acts, so a pending grant is a normal answer,
+ * not a thrown failure; only transport problems throw.
+ * @param fetchImpl - fetch seam.
+ * @param host - normalized host.
+ * @param clientId - the same client id the grant was started with.
+ * @param deviceCode - the grant's `deviceCode`.
+ * @param timeoutMs - per-request budget for this poll.
+ */
+export async function pollDeviceFlow(fetchImpl, host, clientId, deviceCode, timeoutMs = 15_000) {
+    let payload;
+    try {
+        payload = await postForm(fetchImpl, `https://${host}/login/oauth/access_token`, {
+            client_id: clientId,
+            device_code: deviceCode,
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        }, timeoutMs, 
+        // A pending grant is a 400 with an OAuth error body, not a failure.
+        true);
+    }
+    catch (error) {
+        // A dropped connection says nothing about the grant: report it as a
+        // retryable answer so one blip cannot end a sign-in the user already
+        // approved in the browser. Any other failure (malformed body, HTTP 5xx)
+        // still throws and surfaces as a route error.
+        if (error instanceof DeviceFlowTransportError)
+            return { status: 'network', message: error.message };
+        throw error;
+    }
+    const token = readString(payload, 'access_token');
+    if (token !== undefined)
+        return { status: 'token', token };
+    const code = readString(payload, 'error') ?? 'unknown_error';
+    const description = readString(payload, 'error_description') ?? code;
+    switch (code) {
+        case 'authorization_pending':
+            return { status: 'pending' };
+        case 'slow_down':
+            return { status: 'slow_down' };
+        case 'expired_token':
+            return { status: 'expired', message: description };
+        case 'access_denied':
+            return { status: 'denied', message: description };
+        default:
+            return { status: 'failed', message: description };
+    }
+}

package/lib/routes.d.ts

@@ -3,8 +3,9 @@
  * shell (index.ts) owns req/res mechanics; everything testable lives here.
  */
 import { type CopyFilesSeams } from './copy-files.js';
+import { type CredentialStore } from './credentials.js';
 import { type DirExists, type ExcludeSeams, type Exec } from './git.js';
-import type { AiCommitMessageResult, ChangesResult, CommitFilesResult, CommitResult, CreateBranchResult, CreateTagResult, CreateWorktreeResult, EnsureDirectoryResult, FetchResult, GroupWorkspacesResult, InspectWorktreeResult, LogResult, PathExistsResult, PurgeDirectoryResult, PushTagResult, RemoveWorktreeResult, RepoStatus, RouteError, StageResult, SwitchResult, UpdateResult, WorktreesAllResult } from './wire.js';
+import type { AiCommitMessageResult, ChangesResult, CommitFilesResult, CommitResult, CreateBranchResult, CreateTagResult, CreateWorktreeResult, CredentialOAuthPollResult, CredentialOAuthStartResult, CredentialsResult, EnsureDirectoryResult, FetchResult, GroupWorkspacesResult, InspectWorktreeResult, LogResult, PathExistsResult, PurgeDirectoryResult, PushTagResult, RemoveWorktreeResult, RemotesResult, RepoStatus, RouteError, StageResult, SwitchResult, UpdateResult, WorktreesAllResult } from './wire.js';
 /** Everything the handlers need from the host half. */
 export interface RouteDeps {
     exec: Exec;
@@ -28,6 +29,8 @@ export interface RouteDeps {
     excludeSeams?: ExcludeSeams;
     /** Post-create file copy seams (tests substitute). */
     copyFilesSeams?: CopyFilesSeams;
+    /** HTTP seam for the browser sign-in routes (absent = global fetch). */
+    fetchImpl?: typeof fetch;
     /** Directory probe seam over fs.stat (true = exists AND is a directory);
      * tests substitute. */
     statDirectory?: (path: string) => Promise<boolean>;
@@ -38,6 +41,9 @@ export interface RouteDeps {
     listDir?: (path: string) => Promise<string[]>;
     /** Recursive force rm seam (fs.rm with retries); tests substitute. */
     rmRecursive?: (path: string) => Promise<void>;
+    /** Global per-host credential store. Absent = the fs-backed store at the
+     * resolved dsh home; tests substitute an in-memory one. */
+    credentialsStore?: CredentialStore;
 }
 /** Real fs-backed one-level directory listing (names only). Plain FILES are
  * filtered out — the storage root can carry strays (a legacy settings.json
@@ -50,7 +56,7 @@ export declare function fsMkdirRecursive(path: string): Promise<void>;
 /** One route outcome: HTTP status plus the JSON body. */
 export interface RouteOutcome {
     status: number;
-    body: RepoStatus | CreateWorktreeResult | SwitchResult | CreateBranchResult | FetchResult | UpdateResult | GroupWorkspacesResult | InspectWorktreeResult | RemoveWorktreeResult | PathExistsResult | EnsureDirectoryResult | WorktreesAllResult | PurgeDirectoryResult | ChangesResult | StageResult | CommitResult | LogResult | CommitFilesResult | CreateTagResult | PushTagResult | AiCommitMessageResult | RouteError;
+    body: RepoStatus | CreateWorktreeResult | SwitchResult | CreateBranchResult | FetchResult | UpdateResult | GroupWorkspacesResult | InspectWorktreeResult | RemoveWorktreeResult | PathExistsResult | EnsureDirectoryResult | WorktreesAllResult | PurgeDirectoryResult | ChangesResult | StageResult | CommitResult | LogResult | CommitFilesResult | CreateTagResult | PushTagResult | AiCommitMessageResult | CredentialsResult | CredentialOAuthStartResult | CredentialOAuthPollResult | RemotesResult | RouteError;
 }
 /**
  * POST /group — git belonging facts for a batch of workspace directories.
@@ -351,3 +357,62 @@ export interface LlmStreamRuntime {
  * @param body - parsed request body: `{ repoPath, provider, model, effort?, hint? }`.
  */
 export declare function handleAiCommitMessage(deps: RouteDeps, llm: LlmStreamRuntime, body: unknown): Promise<RouteOutcome>;
+/**
+ * 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 declare function handleCredentials(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * 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 declare function handleCredentialsSave(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * 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 declare function handleCredentialsDelete(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * 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 declare function handleCredentialsOAuthStart(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * 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 declare function handleCredentialsOAuthPoll(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * 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 declare function handleRemotes(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * 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 declare function handleRemote(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;