gutterpress 0.0.0

package/dist/lib/publish/types.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Publish provider contract (#35).
+ *
+ * A publish provider pushes a built artifact (PDF or static-site HTML) to a
+ * distribution platform — or, where the platform has no upload API
+ * (DriveThruRPG, Amazon KDP), stages a validated upload package and hands the
+ * author a checklist + the platform's upload URL ("guided" publishing).
+ *
+ * Architecture mirrors the remote-auth subsystem (ADR 0006):
+ *   - The lib NEVER touches OS keychains, the network, or child processes
+ *     directly through ambient globals — hosts inject a {@link TokenStore},
+ *     and tests inject {@link PublishDeps.fetch} / {@link PublishDeps.runCommand}.
+ *   - Credentials are keyed by provider host (e.g. "itch.io") in the same
+ *     TokenStore the Git remote features use: the CLI's 0600 file store, the
+ *     desktop's safeStorage-backed store.
+ *
+ * SECURITY INVARIANT: token values never appear in logs, error messages,
+ * spawned argv (process lists are world-readable — pass secrets via env), or
+ * host responses.
+ */
+import type { HostCredential, TokenStore } from "../remote-auth/token-store.ts";
+/**
+ * One author-editable, NON-SECRET settings field (stored in the manifest's
+ * `publish.<id>` section). Declared by each provider so settings UIs are
+ * fully data-driven — a new provider brings its own fields, no UI edits.
+ */
+export interface PublishConfigField {
+    /** Manifest key under `publish.<id>` (e.g. "target"). */
+    key: string;
+    /** Author-facing label ("Project (user/game)"). */
+    label: string;
+    placeholder?: string;
+}
+/** Stable provider identifiers: the `--provider` values AND the manifest
+ * `publish.<id>` keys — one spelling everywhere. */
+export type PublishProviderId = "itch" | "drivethrurpg" | "kdp" | "azure-swa" | "shopify";
+/**
+ * How the provider integrates:
+ *   - "api"    — real programmatic upload (itch.io, Azure SWA, Shopify)
+ *   - "guided" — no upload API exists; we validate + stage a package and open
+ *                the platform's upload page with a checklist (DTRPG, KDP)
+ */
+export type PublishProviderKind = "api" | "guided";
+/** Which build output the provider consumes. */
+export type PublishArtifactFormat = "pdf" | "html";
+/** Static, UI-facing description of a provider. */
+export interface PublishProviderInfo {
+    id: PublishProviderId;
+    /** Human name ("itch.io"). */
+    label: string;
+    kind: PublishProviderKind;
+    /** The artifact format this provider publishes. */
+    format: PublishArtifactFormat;
+    /** One-line author-facing description of what publishing here does. */
+    description: string;
+    /** The provider's author-editable manifest settings. */
+    configFields: PublishConfigField[];
+    /**
+     * Credential requirements. `host` keys the TokenStore entry; guided
+     * providers need no credential at all. `envVar` is the CI escape hatch —
+     * when set in the environment it wins over the stored credential.
+     */
+    credential: {
+        required: boolean;
+        host: string;
+        /** Environment variable honoured for headless/CI use. */
+        envVar?: string;
+        /** Where the author creates the key (shown in connect UIs). */
+        tokenUrl?: string;
+        /** Author-facing hint ("Paste an API key from …"). */
+        hint?: string;
+    };
+}
+/** The project being published (resolved from the manifest by the orchestrator). */
+export interface PublishProject {
+    projectDir: string;
+    title: string;
+    authors: string[];
+}
+/** The built artifact to publish. For "html" this is the export directory. */
+export interface PublishArtifact {
+    path: string;
+    format: PublishArtifactFormat;
+}
+/** Result of a spawned command (see {@link CommandRunner}). */
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Injectable child-process seam. The default implementation wraps
+ * `node:child_process.spawn`; tests substitute a fake. Secrets must only ever
+ * travel through `env`, never `args`.
+ */
+export type CommandRunner = (cmd: string, args: string[], options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    /** Called once per output line — drives live progress logs. */
+    onOutput?: (line: string) => void;
+    /**
+     * Idle-kill budget in ms (audit B2). If the child produces no output and
+     * has not exited within this window, it is SIGKILL'd and the run rejects
+     * with a timeout error, so a stalled upload can't hang publish forever.
+     * Omitted / undefined = the runner's default (defaultCommandRunner applies
+     * PUBLISH_IDLE_TIMEOUT_MS); 0 = explicitly no timeout.
+     */
+    timeoutMs?: number;
+}) => Promise<CommandResult>;
+/**
+ * Host-injected dependencies for every provider call. Everything with a side
+ * effect enters through here, which is what makes providers unit-testable.
+ */
+export interface PublishDeps {
+    tokenStore: TokenStore;
+    /** HTTP seam (itch.io check, Shopify, butler download). Defaults to global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Child-process seam (butler, swa). Defaults to node spawn. */
+    runCommand?: CommandRunner;
+    /** Environment (CI credential overrides). Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** User config dir override (butler tool cache). Defaults to defaultConfigDir(). */
+    configDir?: string;
+    /** Live progress line sink (CLI logger / desktop progress log). */
+    onProgress?: (message: string) => void;
+    /**
+     * The selected NAMED credential (account label) for this operation, when the
+     * user has more than one saved credential for the provider. The store is
+     * keyed by a compound `<host>#<account>` for named accounts (see
+     * {@link publishCredentialKey}); empty/undefined resolves the legacy
+     * bare-host entry, so existing single-credential setups keep working. The
+     * orchestrator sets this from the effective selection (book manifest →
+     * project/global default); providers read it transparently via
+     * {@link resolvePublishCredential}.
+     */
+    credentialAccount?: string;
+}
+/**
+ * The TokenStore key for a publishing provider credential. Named accounts use a
+ * compound `<host>#<account>` key so MULTIPLE credentials can coexist under one
+ * provider host (two itch.io accounts, two Shopify stores) in the same flat
+ * store — WITHOUT changing the TokenStore contract or disturbing git-sync,
+ * which keeps using bare host keys. An empty/absent account is the bare host
+ * (the legacy single-credential entry). The account segment is trimmed; host
+ * normalisation (lower-casing) is left to the store's `normalizeHost`.
+ */
+export declare function publishCredentialKey(host: string, account?: string | null): string;
+/** Everything a provider method needs for one operation. */
+export interface PublishRequest {
+    project: PublishProject;
+    /** The provider's manifest `publish.<id>` section (non-secret config). */
+    config: Record<string, unknown>;
+    artifact: PublishArtifact;
+    deps: PublishDeps;
+}
+/** A single preflight finding. `error` blocks publishing; others inform. */
+export interface PreflightIssue {
+    severity: "error" | "warning" | "info";
+    /** Stable machine id, e.g. "itch/target-missing". */
+    id: string;
+    message: string;
+}
+/** Redacted authentication status — NEVER carries the token value. */
+export interface PublishAuthStatus {
+    ok: boolean;
+    /** Where the accepted credential came from. */
+    source?: "env" | "store";
+    /** Friendly failure guidance when `ok` is false. */
+    message?: string;
+}
+/** A product/listing already on the platform (for update flows). */
+export interface PublishProduct {
+    id: string;
+    title: string;
+    url?: string;
+}
+/** Listing metadata for {@link PublishProvider.updateListing}. */
+export interface PublishListingMetadata {
+    title?: string;
+    description?: string;
+}
+/** What a publish produced. */
+export type PublishOutcome = {
+    kind: "published";
+    /** Where the published work lives (page URL / deploy URL). */
+    url?: string;
+    /** Human summary ("Pushed build 42 to dimm-city/ops-manual:pdf"). */
+    detail?: string;
+    /** Remaining manual steps, when the API covers only part of the flow. */
+    followUp?: string[];
+} | {
+    kind: "guided";
+    /** Directory containing the staged upload package. */
+    packageDir: string;
+    /** The platform upload page to open. */
+    openUrl: string;
+    /** Manual steps the author completes on the platform. */
+    checklist: string[];
+    detail?: string;
+};
+/**
+ * The publish provider contract (#35). `authenticate`/`listProducts`/
+ * `upload`/`updateListing` per the issue; guided providers implement
+ * `upload` as package staging and omit the listing operations.
+ */
+export interface PublishProvider {
+    readonly info: PublishProviderInfo;
+    /**
+     * Verify that a usable credential exists (env var or token store) and is
+     * accepted by the platform. Guided providers resolve `{ ok: true }`.
+     */
+    authenticate(req: PublishRequest): Promise<PublishAuthStatus>;
+    /** Provider-specific checks run before upload (config, artifact, specs). */
+    preflight(req: PublishRequest): Promise<PreflightIssue[]>;
+    /** Publish the artifact (or stage the guided package). */
+    upload(req: PublishRequest): Promise<PublishOutcome>;
+    /** Existing products/listings, for update flows. API providers only. */
+    listProducts?(req: PublishRequest): Promise<PublishProduct[]>;
+    /** Update an existing listing's metadata. API providers only. */
+    updateListing?(req: PublishRequest, productId: string, metadata: PublishListingMetadata): Promise<PublishProduct>;
+}
+/**
+ * Resolve the credential for a provider: the CI env var wins, then the token
+ * store. Returns null when neither is present. The returned credential is a
+ * secret — callers must never log or echo it.
+ */
+export declare function resolvePublishCredential(info: PublishProviderInfo, deps: PublishDeps, account?: string | undefined): Promise<{
+    credential: HostCredential;
+    source: "env" | "store";
+} | null>;
+/**
+ * Redacted connection status for a provider — the ONE definition of
+ * "connected" (env var or stored key) shared by the CLI's `--list` and the
+ * desktop's provider cards, so the two surfaces can never disagree.
+ */
+export declare function publishConnectionStatus(info: PublishProviderInfo, deps: PublishDeps, account?: string | undefined): Promise<{
+    connected: boolean;
+    source?: "env" | "store";
+}>;
+/** A saved credential for a provider, REDACTED (no token) — for a picker. */
+export interface PublishSavedAccount {
+    /**
+     * The account label (the compound-key `#<account>` segment). Empty string is
+     * the default (unnamed / bare-host) credential.
+     */
+    account: string;
+    /** Display name for the picker (the credential's label). */
+    label: string;
+    createdAt: number;
+}
+/**
+ * The saved credentials for a provider, redacted — one per named account plus
+ * the default (unnamed) entry, when present. Recovered from the store's flat
+ * {@link TokenStore.list} by matching the provider host; the account label is
+ * carried in each credential's `username` (see `connect.ts`), empty for the
+ * default entry. Never returns token values.
+ */
+export declare function listPublishAccounts(info: PublishProviderInfo, deps: PublishDeps): Promise<PublishSavedAccount[]>;

package/dist/lib/remote-auth/clone.d.ts

@@ -0,0 +1,87 @@
+import httpNode from "isomorphic-git/http/node";
+import { type HostCredential, type TokenStore } from "./token-store.ts";
+/** Coarse clone progress for host UIs. */
+export interface CloneProgressEvent {
+    /** Human-readable phase from the git transport (e.g. "Receiving objects"). */
+    phase: string;
+    loaded: number;
+    total?: number;
+}
+/**
+ * Provider provenance recorded next to a cloned project (ADR 0006 D4):
+ * metadata for the repo picker / re-auth UX, never consulted by the
+ * editing/preview/build paths.
+ */
+export interface ProjectProvenance {
+    provider: "github";
+    owner: string;
+    repo: string;
+    /**
+     * Legacy GitHub-App installation id. New clones never write it (the OAuth
+     * App model has no installations — ADR 0006 D1 amendment 2026-06-10); kept
+     * optional so provenance files written by 0.4.x betas still parse.
+     */
+    installationId?: string;
+}
+export interface CloneRepositoryOptions {
+    /** HTTPS clone URL. Tokens embedded in the URL are stripped (D7). */
+    url: string;
+    /** Absolute destination directory (created; must be absent or empty). */
+    dir: string;
+    /** Credential used for transport auth, if the remote needs one. */
+    credential?: HostCredential;
+    /** Branch to check out; the remote's default branch when omitted. */
+    branch?: string;
+    /**
+     * History depth. Defaults to a FULL clone (`undefined`).
+     *
+     * WHY full and not the ADR's `depth: 1` preference: the shallow-clone spike
+     * (clone.test.ts, "shallow clone spike") showed isomorphic-git CAN shallow
+     * clone and the existing source-provider ops (listHistory, snapshot) keep
+     * working on the shallow result — but `git.log` stops silently at the
+     * shallow boundary, so View History (#13) would show a single commit with no
+     * indication more history exists, and there is no deepen-on-demand surface
+     * yet. Until that lands, full clone is the honest default; pass `depth` to
+     * opt in to shallow (the plumbing is tested and works).
+     */
+    depth?: number;
+    /** Coarse progress callback for host UIs. */
+    onProgress?: (event: CloneProgressEvent) => void;
+    /** When provided, credentials embedded in `url` are migrated into it (D7). */
+    tokenStore?: TokenStore;
+    /** Provider provenance to record beside the clone (ADR 0006 D4). */
+    provenance?: ProjectProvenance;
+    /**
+     * Injectable git HTTP transport for tests (isomorphic-git's `http` client
+     * shape). Defaults to isomorphic-git's node client.
+     */
+    httpClient?: typeof httpNode;
+}
+export interface CloneRepositoryResult {
+    /** The directory the project was cloned into (same as options.dir). */
+    projectDir: string;
+    /** The checked-out branch. */
+    branch?: string;
+}
+export declare function provenancePath(projectDir: string): string;
+/** Read recorded provider provenance for a project, if any. Never throws. */
+export declare function readProjectProvenance(projectDir: string): Promise<ProjectProvenance | null>;
+/**
+ * Reduce a (possibly renderer-/user-supplied) project folder name to a single
+ * safe path segment: path separators become dashes and leading dots are
+ * stripped, so `path.join(parentDir, sanitizeCloneFolderName(name))` can never
+ * escape `parentDir` (no `..` segments, no absolute paths, no hidden dirs).
+ * Returns `""` when nothing usable remains — callers must reject that.
+ */
+export declare function sanitizeCloneFolderName(name: string): string;
+/**
+ * Clone a remote repository over smart HTTPS into `dir` (ADR 0006 D2).
+ *
+ * - HTTPS only (isomorphic-git has no SSH — ADR 0006 D6).
+ * - `singleBranch` always; `depth` opts into shallow (full by default — see
+ *   the WHY on {@link CloneRepositoryOptions.depth}).
+ * - Tokens embedded in the URL are stripped and (when a `tokenStore` is
+ *   given) migrated into the store; the token never reaches logs (D7).
+ * - Serialized through the same per-repo lock as snapshot/restore.
+ */
+export declare function cloneRepository(options: CloneRepositoryOptions): Promise<CloneRepositoryResult>;

package/dist/lib/remote-auth/conflict-resolution.d.ts

@@ -0,0 +1,29 @@
+import type { ResolveConflictsOptions, SyncOutcome } from "./sync-types.ts";
+/**
+ * `chapter-01.md` → `chapter-01 (online copy).md` (next to the original).
+ * `counter` ≥ 2 produces `chapter-01 (online copy 2).md`, … — used to avoid
+ * clobbering a pre-existing file with the same name.
+ */
+export declare function onlineCopyPath(filepath: string, counter?: number): string;
+/**
+ * Apply the author's per-file choices and sync the combined result
+ * (ADR 0006 D5). The merge commit has TWO PARENTS — the local branch tip and
+ * the online tip — so both histories remain intact and View History stays
+ * honest about what was combined.
+ *
+ * How each choice is applied WITHOUT conflict markers:
+ *
+ * - Files edited in both copies are settled inside the merge itself by a
+ *   custom `mergeDriver` that returns the chosen side's content ("Keep both
+ *   copies" keeps mine and writes the online version to
+ *   `<name> (online copy)<ext>` beforehand, committed on the local side so it
+ *   is part of the merge). Undecided files auto-merge with the same diff3
+ *   algorithm a plain merge uses.
+ * - Delete-involved conflicts never reach a merge driver, so they are settled
+ *   by equalizing the local side BEFORE the merge (making both sides agree so
+ *   the merge is clean) and, when the author chose the now-removed side, a
+ *   small follow-up commit AFTER the merge restores their choice. The merge
+ *   commit still carries both parents; the around-commits are visible,
+ *   honestly labeled steps in View History.
+ */
+export declare function resolveConflicts(options: ResolveConflictsOptions): Promise<SyncOutcome>;

package/dist/lib/remote-auth/diagnose.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Project remote diagnostics (#14, ADR 0006 D7).
+ *
+ * Pure-lib replacement for the issue's original shell diagnostics
+ * (`git status` / `git remote -v` / `git branch --show-current` — all
+ * forbidden by CLAUDE.md §7): folder classification reuses
+ * `detectProjectSource`, remote/branch come from the classification, and the
+ * stored-credential check goes through an injected {@link TokenStore}.
+ * Everything here is local reads — the only network diagnostic is the
+ * explicit, user-initiated `testRemoteAccess` probe (separate module).
+ *
+ * SECURITY INVARIANT (D7): `remoteUrl` is sanitized — credentials embedded in
+ * the clone URL never appear in the diagnosis (which the UI displays).
+ */
+import { type ProjectSource } from "../project-source.ts";
+import { type TokenStore } from "./token-store.ts";
+/** How the project's remote is addressed. "https" covers smart HTTP(S). */
+export type RemoteProtocol = "https" | "ssh" | "none";
+/** Recognized forge families, for per-provider guidance copy. */
+export type ForgeKind = "github" | "gitea" | "forgejo" | "gitlab" | "bitbucket" | "azure" | "generic";
+/**
+ * Machine-readable next-step hint the UI maps to author copy:
+ * - `local-only` — no remote; everything is on this computer.
+ * - `connect-github-to-sync` — HTTPS github.com remote, no stored credential.
+ * - `https-connect-server` — HTTPS non-GitHub remote, no stored credential.
+ * - `ready-to-sync` — HTTPS remote with a stored credential (sync lands
+ *   with #15's sync phase; the plumbing is in place).
+ * - `ssh-use-own-tools` — SSH remote: full local features, sync externally
+ *   (ADR 0006 D6). The UI layers the "switch to HTTPS" hint on recognized hosts.
+ */
+export type RemoteGuidanceId = "local-only" | "connect-github-to-sync" | "https-connect-server" | "ready-to-sync" | "ssh-use-own-tools";
+export interface ProjectRemoteDiagnosis {
+    /** The #12 classification, unchanged. */
+    classification: ProjectSource;
+    /** Sanitized remote URL (no embedded credentials), when one exists. */
+    remoteUrl?: string;
+    /** Host of the remote (hostname[:port], lower-case), when parseable. */
+    remoteHost?: string;
+    remoteProtocol: RemoteProtocol;
+    branch?: string;
+    /** A credential for `remoteHost` exists in the injected store. */
+    credentialPresent: boolean;
+    /** Forge family of the remote host; null when there is no remote. */
+    provider: ForgeKind | null;
+    /** Token-settings deep link for recognized non-GitHub forges. */
+    tokenSettingsUrl: string | null;
+    /**
+     * ADR 0006 D4: hasRemote && smart-HTTPS && credential stored. The sync
+     * flow (#15 D5) is live, so this is the real "offer the Sync action"
+     * gate, not a future-capability hint.
+     */
+    canSync: boolean;
+    guidance: RemoteGuidanceId;
+}
+/** Parse any git remote URL (https, ssh://, scp-like) to protocol + host. */
+export declare function parseRemoteOrigin(url: string): {
+    protocol: RemoteProtocol;
+    host?: string;
+};
+/** Classify a host into a forge family for guidance copy. Heuristic by name. */
+export declare function forgeKindForHost(host: string): ForgeKind;
+export interface DiagnoseProjectRemoteOptions {
+    /** Host-keyed credential store to check for a stored connection. */
+    tokenStore?: TokenStore;
+    /**
+     * Pre-classified source for `projectDir`, when the caller already ran
+     * detectProjectSource (e.g. buildRecoveryContext). Skips the redundant
+     * parent-dir walk; when omitted, classification runs here as before.
+     */
+    source?: ProjectSource;
+}
+/**
+ * Build the Advanced Setup environment status for an opened project folder.
+ * Local reads only; never throws (classification itself never throws, and a
+ * store failure degrades to `credentialPresent: false`).
+ */
+export declare function diagnoseProjectRemote(projectDir: string, options?: DiagnoseProjectRemoteOptions): Promise<ProjectRemoteDiagnosis>;

package/dist/lib/remote-auth/generic-auth.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Generic token auth provider (#14, ADR 0006 D3 layer 3).
+ *
+ * The universal floor for every smart-HTTPS Git host that is not github.com:
+ * the user pastes a host URL + (optional) username + access token collected by
+ * the Advanced Setup UI, and the credential is VERIFIED with a refs probe
+ * BEFORE it is saved — a bad paste fails immediately with friendly guidance,
+ * never later during a sync.
+ *
+ * The transport is identical for every forge (Gitea, Forgejo, GitLab,
+ * Bitbucket, Azure Repos, plain `git http-backend`), so a private Gitea works
+ * the day this lands. Per-forge sugar is limited to {@link knownForgeTokenUrl},
+ * the deep link to the host's token-settings page.
+ *
+ * SECURITY INVARIANT: token values never appear in error messages or logs.
+ */
+import type httpNode from "isomorphic-git/http/node";
+import type { HostCallbacks, RemoteAuthProvider } from "./github-auth.ts";
+import { type HostCredential } from "./token-store.ts";
+/** What the Advanced Setup UI collects for "Connect a Git server". */
+export interface GenericTokenConnectInput {
+    /** The server, as a hostname ("git.example.com") or any URL on it. */
+    host: string;
+    /**
+     * Login associated with the token. Optional — many forges (Gitea, GitLab)
+     * accept the token alone as Basic auth; when omitted the transport sends the
+     * token-as-username convention.
+     */
+    username?: string;
+    /** The access token pasted by the user. NEVER log this. */
+    token: string;
+    /**
+     * A repository HTTPS URL on the host to validate against. When provided the
+     * probe must fully succeed; when omitted the probe runs against the host
+     * root, which verifies reachability and catches rejected tokens (401) but
+     * cannot prove repo access (most forge roots are not Git endpoints, so a
+     * not-found answer there is expected and accepted).
+     */
+    repoUrl?: string;
+}
+/**
+ * The {@link RemoteAuthProvider} `connect` input for the generic provider:
+ * the UI-collected fields plus the standard host callbacks (`onUserCode` is
+ * part of the shared contract but unused — there is no device code in the
+ * token flow; pass a no-op, or use {@link connectGenericHost} directly).
+ */
+export interface GenericHostCallbacks extends HostCallbacks, GenericTokenConnectInput {
+}
+export interface GenericAuthOptions {
+    /** Injectable git HTTP transport for tests. */
+    httpClient?: typeof httpNode;
+    /** Probe timeout forwarded to {@link testRemoteAccess}. */
+    timeoutMs?: number;
+}
+/**
+ * Reduce user input ("https://git.example.com/some/repo", "Git.Example.com",
+ * "git.example.com:3000/x") to the normalized host the credential is keyed by.
+ * Delegates to {@link credentialHostKey} — the ONE canonical derivation shared
+ * by every credential writer and reader — so a host typed here always keys
+ * identically to the same host parsed out of a remote URL by diagnose or the
+ * sync transport. Returns "" when nothing usable remains.
+ */
+export declare function normalizeForgeHost(input: string): string;
+/**
+ * Deep link to the token-settings page for recognized forges; `null` for
+ * unknown hosts (the UI then shows generic "create an access token" guidance).
+ * github.com intentionally returns `null` — GitHub uses the managed device
+ * flow, never a pasted token.
+ */
+export declare function knownForgeTokenUrl(host: string): string | null;
+/**
+ * Validate-then-build a host credential from UI-collected input (the D3
+ * "Connect a Git server" flow). Throws a friendly error when validation
+ * fails; the caller stores the returned credential in its TokenStore.
+ *
+ * KNOWN LIMITATION (root probe): when `repoUrl` is omitted, the probe runs
+ * against `https://host/`, and most forge roots are not Git endpoints — they
+ * answer "not found" without ever evaluating the credential. That answer is
+ * accepted (it proves reachability and that the token was not actively
+ * rejected), which means **a wrong token can be accepted** in this mode. Only
+ * an explicit 401/403 rejects. Pass `repoUrl` whenever one is available to get
+ * a full end-to-end verification of the token against a real repository.
+ */
+export declare function connectGenericHost(input: GenericTokenConnectInput, options?: GenericAuthOptions): Promise<HostCredential>;
+/**
+ * {@link RemoteAuthProvider} wrapper for the generic token flow, so host apps
+ * can route any non-GitHub origin through the shared provider contract.
+ */
+export declare class GenericTokenAuthProvider implements RemoteAuthProvider {
+    private readonly options;
+    constructor(options?: GenericAuthOptions);
+    /** Handles any smart-HTTP(S) host that is not github.com (device flow). */
+    matches(origin: URL): boolean;
+    connect(callbacks: GenericHostCallbacks): Promise<HostCredential>;
+    /** Revalidate a stored credential: false only on a definitive rejection. */
+    validate(credential: HostCredential): Promise<boolean>;
+}

package/dist/lib/remote-auth/git-http.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Timeout wrapper for the isomorphic-git HTTP client (audit B1).
+ *
+ * Every git transport call in this subsystem (`git.fetch`/`git.push`/
+ * `git.clone`) is invoked with no timeout: if the TCP connection succeeds but
+ * the remote stalls, the call never resolves or rejects — sync/pull/push/clone
+ * hangs forever, and because the operation still holds the per-repo
+ * `withRepoLock` FIFO, every subsequent git op for that project wedges too.
+ *
+ * The REST calls in the same subsystem (github-repos.ts, github-auth.ts) already
+ * guard every fetch with `AbortSignal.timeout`; this brings the same discipline
+ * to the git transport, at the one place a default client is chosen.
+ *
+ * Design (review finding: a naive deadline on `request()` is WRONG for pushes):
+ * isomorphic-git passes upload bodies as an ARRAY of buffers, which the node
+ * client collects and sends with Content-Length — `request()` then resolves
+ * only when the response HEADERS arrive, i.e. after the ENTIRE pack upload.
+ * There is no per-chunk progress signal for uploads, so an idle deadline on the
+ * request phase of a push would be a TOTAL cap that kills legitimately slow
+ * large pushes. Therefore:
+ *
+ *  - Body-less requests (the info/refs discovery GET — the classic
+ *    "connected but silent" stall) get the short IDLE deadline.
+ *  - Requests WITH a body (push receive-pack / fetch negotiation POSTs) get a
+ *    LONG total backstop instead: generous enough that no realistic transfer
+ *    hits it, but bounded so a truly dead connection can never wedge the repo
+ *    lock forever.
+ *  - Every response-body chunk read re-arms the short idle deadline, so a
+ *    stall after headers is caught quickly on every request type while a
+ *    slow-but-progressing download streams for as long as it needs.
+ *
+ * One timer serves the whole request (re-armed via `refresh()`; no per-chunk
+ * allocation). On timeout the thrown error's message classifies as offline in
+ * recovery/classify.ts. Known limitation (documented, not fixable at this
+ * layer): isomorphic-git's client accepts no AbortSignal, so an abandoned
+ * timed-out transfer's socket is left to the OS/agent to reap.
+ *
+ * Test HTTP clients injected via `httpClient`/`ctx.httpClient` are NOT wrapped
+ * (they talk to in-memory fixtures that never stall); only the production
+ * default is.
+ */
+import httpNode from "isomorphic-git/http/node";
+/**
+ * Idle deadline for silent phases: the wait for response headers on body-less
+ * requests, and the gap between response-body chunks. A healthy transfer
+ * produces SOMETHING within a minute; total silence for 60s means the
+ * connection is dead, not slow.
+ */
+export declare const GIT_HTTP_IDLE_TIMEOUT_MS = 60000;
+/**
+ * Total backstop for requests that upload a LARGE body (a push pack), whose
+ * request phase exposes no progress signal (see header). 30 minutes
+ * accommodates a multi-GB initial push on a slow uplink while still
+ * guaranteeing the per-repo lock can never be wedged forever.
+ */
+export declare const GIT_HTTP_UPLOAD_TIMEOUT_MS: number;
+/**
+ * Bodies at or below this size are "not an upload": they transfer in seconds
+ * even on a very slow uplink (256 KiB ≈ 21s at 100 kbit/s), so the wait for
+ * response headers is server silence, governed by the short idle deadline. A
+ * pull's fetch-negotiation POST (want/have lines) is a few KB; push packs are
+ * MBs+ and get the long backstop.
+ */
+export declare const SMALL_BODY_MAX_BYTES: number;
+/**
+ * True when `body` is an array of sizable chunks totalling at most
+ * {@link SMALL_BODY_MAX_BYTES}. isomorphic-git always passes bodies as arrays
+ * of byte chunks, so small ones are sizable synchronously. Any chunk WITHOUT
+ * a numeric byteLength makes the body unsizable → NOT small, so it gets the
+ * long upload backstop rather than the idle deadline as a total cap (review
+ * finding: the old reduce counted unsizable chunks as 0 bytes — the exact
+ * opposite of that intent).
+ */
+export declare function isSmallBody(body: unknown): boolean;
+/**
+ * Return a client that behaves like `http` but rejects when the transfer goes
+ * silent (see the header for exactly which phases are guarded and why).
+ */
+export declare function withIdleTimeout(http: typeof httpNode, idleMs?: number, uploadMs?: number): typeof httpNode;
+/**
+ * The production default git HTTP client: `httpNode` with the timeout policy
+ * above. Use this in place of a bare `httpNode` wherever a caller did not
+ * inject its own `httpClient`.
+ */
+export declare const defaultGitHttp: typeof httpNode;