gutterpress 0.0.0

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

@@ -0,0 +1,69 @@
+import type { HostCredential } from "./token-store.ts";
+/** What the host UI needs to show the user during the device flow. */
+export interface DeviceCodeInfo {
+    /** The code the user types at the verification page, e.g. "ABCD-1234". */
+    userCode: string;
+    /** Where the user enters the code (https://github.com/login/device). */
+    verificationUri: string;
+    /** Seconds until the device code expires. */
+    expiresIn: number;
+    /** Minimum seconds between token polls. */
+    interval: number;
+}
+/** Host-supplied callbacks for the interactive connect flow (ADR 0006 D3). */
+export interface HostCallbacks {
+    /** Called once with the code/URL so the UI can display them. */
+    onUserCode(info: DeviceCodeInfo): void;
+    /** Optional cancellation (user closed the dialog). */
+    signal?: AbortSignal;
+}
+/**
+ * Per-host auth-acquisition plugin contract (ADR 0006 D3 layer 3). github.com
+ * gets the device flow below; every other host gets the generic token flow
+ * (#14, not in this change).
+ */
+export interface RemoteAuthProvider {
+    /** Does this provider handle the given remote host? */
+    matches(origin: URL): boolean;
+    /** Interactive flow producing a credential for the host. */
+    connect(callbacks: HostCallbacks): Promise<HostCredential>;
+    /** Cheap revalidation for stored credentials. */
+    validate(credential: HostCredential): Promise<boolean>;
+}
+/**
+ * Client id resolution: explicit option → env var → registered default.
+ * Empty/whitespace-only values at any layer are treated as unset (the packaged
+ * desktop bakes `process.env.GUTTERPRESS_GITHUB_CLIENT_ID` in via a vite `define`,
+ * which yields `""` when the secret is missing at build time).
+ */
+export declare function resolveGitHubClientId(explicit?: string): string;
+export declare const GITHUB_HOST = "github.com";
+/** Author-friendly message for connectivity failures (ADR 0006 D7). */
+export declare const OFFLINE_MESSAGE = "Couldn't reach GitHub. Check your connection and try again.";
+export interface GitHubAuthProviderOptions {
+    /** Explicit client id (overrides env + default). */
+    clientId?: string;
+    /** Injectable fetch for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable sleep for tests (so polling tests run instantly). */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/** GitHub device-flow {@link RemoteAuthProvider} (ADR 0006 D1). */
+export declare class GitHubAuthProvider implements RemoteAuthProvider {
+    private readonly clientId;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(options?: GitHubAuthProviderOptions);
+    matches(origin: URL): boolean;
+    connect(callbacks: HostCallbacks): Promise<HostCredential>;
+    /**
+     * Cheap credential revalidation against `GET /user`. Returns `false` on any
+     * non-200 (401 revoked/expired, 403 forbidden/rate-limit-blocked, …);
+     * network failures are treated as "can't tell" → `true`.
+     */
+    validate(credential: HostCredential): Promise<boolean>;
+    /** Best-effort login lookup after auth — failure is non-fatal. */
+    private fetchUsername;
+}
+/** Standard headers for api.github.com calls. */
+export declare function githubApiHeaders(token: string): Record<string, string>;

package/dist/lib/remote-auth/github-repos.d.ts

@@ -0,0 +1,64 @@
+/**
+ * GitHub repo discovery (#15, ADR 0006 D3 layer 4).
+ *
+ * Plain `fetch` against the GitHub REST API — deliberately no `@octokit`
+ * dependency. Lists every repository the user can access (`GET /user/repos`,
+ * the OAuth `repo`-scope model — ADR 0006 D1 amendment 2026-06-10), the
+ * branches of a chosen repository, and (via the Git Trees API) the gutterpress
+ * book projects inside a repo. The two REST listings paginate; the Git Trees
+ * call is a single request that handles the API's `truncated` flag instead. All
+ * three time out explicitly and map failures to author-friendly messages
+ * (401 → "reconnect").
+ */
+import type { HostCredential } from "./token-store.ts";
+/** One repository the user can open from GitHub. */
+export interface RemoteRepository {
+    owner: string;
+    name: string;
+    fullName: string;
+    private: boolean;
+    defaultBranch: string;
+    htmlUrl: string;
+}
+/** One branch of a remote repository. */
+export interface RemoteBranch {
+    name: string;
+}
+export interface GitHubApiOptions {
+    /** Injectable fetch for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/** "Reconnect" message for revoked/expired tokens (ADR 0006 D7). */
+export declare const RECONNECT_MESSAGE = "Your GitHub connection has expired. Reconnect GitHub and try again.";
+/**
+ * List every repository the user can access — own, collaborator, and org
+ * member — via `GET /user/repos` (paginated). The OAuth `repo` scope makes
+ * the full set visible with zero install/selection steps (ADR 0006 D1
+ * amendment). `sort=pushed` puts recently-active books first; callers must
+ * PRESERVE this order (the picker renders it as "most recent first").
+ */
+export declare function listGitHubRepositories(credential: HostCredential, options?: GitHubApiOptions): Promise<RemoteRepository[]>;
+/** One Gutterpress book found inside a repository. */
+export interface RepoBook {
+    /**
+     * Folder of the book relative to the repository root, forward-slash form.
+     * Empty string when the manifest sits at the repository root.
+     */
+    path: string;
+    /** Display name: the folder's basename, or the repo name for the root. */
+    name: string;
+}
+/**
+ * Find the Gutterpress books inside a repository branch: every directory that
+ * contains a recognized manifest (from `MANIFEST_FILENAMES`) — the repository
+ * root counts, with `path: ""`. Uses one
+ * `GET /repos/{owner}/{repo}/git/trees/{branch}
+ * ?recursive=1` call; when GitHub truncates the recursive listing (very large
+ * repositories) it falls back to scanning the root + each top-level directory
+ * with non-recursive tree calls, so the result stays correct for the common
+ * "books are top-level folders" layout. Results are sorted by path, root
+ * first.
+ */
+export declare function listRepoBooks(credential: HostCredential, owner: string, repo: string, branch: string, options?: GitHubApiOptions): Promise<RepoBook[]>;
+/** List a repository's branches via `GET /repos/{owner}/{repo}/branches`. */
+export declare function listGitHubBranches(credential: HostCredential, owner: string, repo: string, options?: GitHubApiOptions): Promise<RemoteBranch[]>;

package/dist/lib/remote-auth/operation-log.d.ts

@@ -0,0 +1,66 @@
+/**
+ * operation-log.ts — structured file logger for git / sync / recovery / snapshot
+ * operations.
+ *
+ * WHY this exists: when a sync or recovery operation fails, the user needs a
+ * debuggable log file that records what was attempted, what steps ran, and
+ * what went wrong — without having to reproduce the failure with verbose
+ * console output enabled. The log is written incrementally (append mode) so
+ * it survives even if the process crashes mid-operation.
+ *
+ * SECURITY INVARIANT: this logger NEVER writes secrets, tokens, credentials,
+ * or full remote URLs with embedded auth. Callers must pass only sanitized
+ * data (repo slug, branch name, short OIDs, error codes, outcome status).
+ *
+ * The logger is injectable: callers pass a `logFile` path and get a file
+ * logger; omit it and a no-op logger is used (backward compatible — existing
+ * callers that don't pass `logFile` see zero behavior change).
+ *
+ * LOG FORMAT (one line per entry, plain text for easy grep/tail):
+ *   [ISO-timestamp] LEVEL  operation: step=<step> key=value ... | <message>
+ *
+ * Example:
+ *   [2026-06-19T12:34:56.789Z] INFO  recovery: kind=unrelated_histories repo=my-book branch=main | starting recovery
+ *   [2026-06-19T12:34:56.890Z] INFO  recovery: step=backup | backup created at /tmp/print-sync-recovery/my-book/...zip
+ *   [2026-06-19T12:34:57.789Z] WARN  recovery: step=merge | merge conflicted files=manifest.yaml,notes.md
+ *   [2026-06-19T12:34:57.890Z] INFO  recovery: result=needs_user | surfaced 2 conflicted files to user
+ *
+ * Cross-platform: uses `node:fs` appendFileSync + `node:path`. The caller
+ * is responsible for providing a valid directory (the logger creates the
+ * file but NOT the parent directory — that's the caller's job, e.g. the
+ * desktop ensures `userData/logs/` exists before passing the path).
+ *
+ * Compatible with `bun build --compile`: no runtime package.json reads, no
+ * computed-path dynamic imports, no native bindings — just `fs.appendFileSync`.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface OperationLogger {
+    debug(step: string, message: string, data?: LogData): void;
+    info(step: string, message: string, data?: LogData): void;
+    warn(step: string, message: string, data?: LogData): void;
+    error(step: string, message: string, data?: LogData): void;
+}
+/** Structured key-value fields appended after the step. No secrets. */
+export type LogData = Record<string, string | number | boolean | string[] | undefined>;
+/**
+ * Create a file-backed operation logger. Each call appends one line to
+ * `logFile` (created if it doesn't exist; the parent directory is created
+ * if missing). Writes are synchronous so the log survives a process crash
+ * mid-operation.
+ *
+ * @param logFile  Absolute path to the log file.
+ * @param minLevel Minimum level to write (default: "debug" — write everything).
+ * @param operation  Operation name shown in each line (e.g. "sync", "recovery").
+ */
+export declare function createFileLogger(logFile: string, operation: string, minLevel?: LogLevel): OperationLogger;
+/**
+ * Resolve a logger from an optional `logFile` path. Returns a no-op logger
+ * when `logFile` is undefined or empty (backward compatible — callers that
+ * don't pass `logFile` see zero behavior change and zero file I/O).
+ */
+export declare function resolveLogger(logFile: string | undefined, operation: string): OperationLogger;
+/**
+ * Shorten a 40-char OID to the first 7 characters for compact log lines.
+ * Same convention as `git log --oneline`.
+ */
+export declare function shortOid(oid: string): string;

package/dist/lib/remote-auth/recovery/abort-interrupted-operation.d.ts

@@ -0,0 +1,103 @@
+/**
+ * abort-interrupted-operation.ts — shared skeleton for aborting an unfinished
+ * git operation (merge / cherry-pick / rebase) left on disk.
+ *
+ * WHY (DRY): recover-interrupted-merge, recover-interrupted-cherry-pick, and
+ * recover-interrupted-rebase were ~90% identical — same TOCTOU guard, same
+ * backup gate, same hadLocalChanges capture, same fault-injection ordering,
+ * same force-checkout + marker cleanup + re-verify. The ONLY real differences
+ * are: which marker files signal the state, which files to remove, and how to
+ * resolve the ref to restore (merge/cherry-pick reset the current branch; a
+ * rebase may rewind a named branch to a recorded pre-rebase commit OR restore a
+ * detached HEAD). Those three differences are captured in `AbortConfig`; the
+ * invariant ordering lives here, once.
+ *
+ * Abort algorithm (pure isomorphic-git + node:fs — never the system git binary):
+ *   1. TOCTOU precondition: if NONE of `markerFiles` exist, the operation was
+ *      already finished/aborted externally and there is nothing to abort. This
+ *      is now enforced by the DISPATCHER (dispatch.ts), which calls each
+ *      kind's exported `stillApplies` — built from `anyMarkerPresent` below —
+ *      INSIDE withRepoLock, before this function is ever invoked. There used
+ *      to be a duplicate hand-rolled copy of this same check at the top of
+ *      this function; it is deleted, not kept alongside the dispatcher probe,
+ *      because — unlike recover-missing-git-dir.ts — this function has no
+ *      SECOND re-check later (no re-check after the backup/confirm wait), so
+ *      the one check and the dispatcher probe cover the exact same window: the
+ *      dispatcher probe runs immediately before this function's synchronous
+ *      entry, with no work in between, just as the deleted local check did.
+ *   2. withBackupGate (backup → confirm → risky → failsafe). Inside the callback:
+ *   3. Capture whether the working tree had in-progress edits (best-effort).
+ *   4. Resolve the restore target via `resolveTarget` (default:
+ *      ctx.branch → git.currentBranch → "HEAD"). resolveTarget MAY throw (e.g.
+ *      the rebase cannot find its pre-op commit) — that surfaces as
+ *      failed_backup_available since the backup is already safe.
+ *   5. Optionally rewind a named branch ref to a recorded commit, then
+ *      force-checkout the target (resets index + worktree).
+ *   6. Remove the transient `cleanupFiles` inside .git.
+ *   7. Verify every `markerFiles` entry is gone; if not → THROW.
+ *
+ * Inside the risky callback we call ONLY raw git.* / node:fs — never a
+ * lock-wrapped lib function — so the dispatcher's per-repo FIFO queue can't
+ * deadlock. Re-verification uses direct fs.existsSync, not inspectRepo. All
+ * removed paths live INSIDE the repo's own .git and are captured in the verified
+ * backup — never user content.
+ *
+ * Fault injection points (ctx.faults?.before()):
+ *   after_backup_before_repair   — start of the destructive section
+ *   abort_interrupted_operation  — start of the abort proper
+ *   checkout_branch              — before the force checkout
+ *   remove_operation_state       — before deleting the on-disk state files
+ */
+import type { RecoveryContext, RecoveryResult, SyncErrorKind } from "./types.ts";
+/**
+ * True when any of `markerFiles` (gitDir-relative) still exists. Shared by
+ * each interrupted-* handler's exported `stillApplies` (the dispatcher's
+ * precondition probe, see types.ts `StillAppliesFn`) so there is ONE
+ * implementation of "is this abort still needed", not three copies.
+ */
+export declare function anyMarkerPresent(ctx: RecoveryContext, markerFiles: string[]): boolean;
+/** Arguments handed to a config's `resolveTarget`. */
+export interface AbortResolveArgs {
+    ctx: RecoveryContext;
+    /** The git repository root (ctx.repoDir). */
+    dir: string;
+    /** The resolved `.git` directory for `dir`. */
+    gitDir: string;
+}
+/** Which ref to restore and (optionally) which branch ref to rewind first. */
+export interface AbortTargetPlan {
+    /** The ref to force-checkout (a branch name, a commit sha, or "HEAD"). */
+    checkoutRef: string;
+    /**
+     * When set, `refs/heads/<writeRefBranch>` is force-written to `writeRefValue`
+     * BEFORE the checkout (used to rewind a named branch to a pre-op commit). Omit
+     * to leave all refs untouched (merge/cherry-pick and detached-HEAD rebase).
+     */
+    writeRefBranch?: string;
+    writeRefValue?: string;
+}
+/** The per-operation differences the shared skeleton parameterizes. */
+export interface AbortConfig {
+    /** Recovery kind — drives policy (backup/confirm) and guidance copy. */
+    kind: SyncErrorKind;
+    /**
+     * gitDir-relative marker paths whose presence signals the interrupted state.
+     * If NONE exist the abort is a benign no-op; after the abort ALL must be gone.
+     */
+    markerFiles: string[];
+    /** gitDir-relative paths removed during the abort (force; missing is fine). */
+    cleanupFiles: string[];
+    /**
+     * Resolve which ref to restore. Defaults to
+     * ctx.branch → git.currentBranch → "HEAD". MAY throw to abort the repair
+     * (the verified backup makes that safe → failed_backup_available).
+     */
+    resolveTarget?: (args: AbortResolveArgs) => Promise<AbortTargetPlan>;
+    /** Build the success message; `hadLocalChanges` reports whether edits were reset. */
+    successMessage: (hadLocalChanges: boolean) => string;
+}
+/**
+ * Abort an interrupted git operation per `config`. See the module header for the
+ * full algorithm and safety invariants.
+ */
+export declare function abortInterruptedOperation(ctx: RecoveryContext, config: AbortConfig): Promise<RecoveryResult>;

package/dist/lib/remote-auth/recovery/backup.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Temp-dir zip backup creation and verification for the sync-recovery subsystem.
+ *
+ * Creates a STORE-method (no compression) ZIP of the project's user files plus
+ * .git/, writing it to:
+ *   <os.tmpdir()>/print-sync-recovery/<repo-slug>/<ISO-timestamp>-<reason>.zip
+ *
+ * The backup root is `os.tmpdir()` (NOT a hardcoded "/tmp") so it is correct on
+ * Windows/macOS/Linux — the desktop ships on all three (CLAUDE.md §8). A literal
+ * "/tmp" would make every risky-repair backup throw on Windows.
+ *
+ * The ZIP bytes are produced by fflate's streaming Zip/ZipPassThrough (STORE
+ * method — no compression), replacing the previous hand-rolled writer (#86).
+ * fflate is pure JS with zero dependencies, no runtime package.json/data
+ * reads, and no computed-path dynamic imports, so it bundles cleanly under
+ * bun build --compile (CLAUDE.md §1/§3). It is already a dependency (publish
+ * providers use its unzipSync).
+ *
+ * Verification (assertZipReadable): deliberately NOT fflate. It validates
+ * EVERY central-directory entry's signature and bounds (not just the first)
+ * via positioned reads of the EOCD + central directory only — never the file
+ * data — so it stays memory-safe on multi-GB backups while still catching
+ * corruption in any later entry. fflate's unzip needs the whole archive in
+ * memory, so it cannot back this check; the small positioned-read parser
+ * stays.
+ *
+ * Retention: createRecoveryZip prunes stale backups (best-effort, never throws)
+ * before writing a new one — see pruneOldBackups — so old backups do not fill
+ * the disk over time.
+ *
+ * Exclusions: node_modules/, .print-sync/cache/, and **.git/config**. The git
+ * config file is deliberately dropped from the backup because it can carry an
+ * embedded credential (e.g. a tokenized remote URL) and is reconstructable on
+ * recovery (the remote is reconfigured from the stored connection). All other
+ * .git/ contents (objects, refs, HEAD) ARE included so recovery still works.
+ * Inclusions: all user-visible files + .git/ (minus config, for full recovery)
+ */
+import type { RecoveryBackup, RecoveryContext } from "./types.ts";
+/**
+ * Root directory for all sync-recovery backups.
+ *
+ * Computed from `os.tmpdir()` (NOT hardcoded "/tmp") so it resolves to a real
+ * temp dir on Windows, macOS, and Linux. A literal "/tmp" does not exist on
+ * Windows and would make every risky-repair backup throw there (CLAUDE.md §8).
+ */
+export declare const BACKUP_ROOT: string;
+export interface PruneOldBackupsOptions {
+    /** Backup root to prune under. Defaults to {@link BACKUP_ROOT}. */
+    root?: string;
+    /** Restrict pruning to a single repo-slug subfolder. */
+    slug?: string;
+    /** Remove zips with an mtime older than this many ms. Default 7 days. */
+    ttlMs?: number;
+    /** After TTL pruning, keep at most this many newest zips per slug. */
+    maxPerSlug?: number;
+    /** Clock override (tests). Returns epoch ms. */
+    now?: () => number;
+}
+/**
+ * Remove stale recovery backups so they do not accumulate forever and fill the
+ * disk (BUG 2). Two independent policies are applied per repo-slug folder:
+ *   1. TTL — delete any zip whose mtime is older than `ttlMs` (default 7 days).
+ *   2. Cap — keep only the newest `maxPerSlug` zips (default 20), delete the rest.
+ *
+ * BEST-EFFORT and SILENT: this never throws and never blocks backup creation.
+ * Any unreadable dir, racing delete, or stat failure is ignored — a failure to
+ * prune must never prevent the user's work from being backed up.
+ */
+export declare function pruneOldBackups(opts?: PruneOldBackupsOptions): Promise<void>;
+/**
+ * Create a temp-dir zip backup of the project directory (user files + .git/,
+ * minus .git/config). Calls ctx.faults?.before("backup_create") then
+ * ctx.faults?.before("backup_verify") so tests can inject failures at each step.
+ *
+ * Returns a RecoveryBackup describing the zip, or throws on failure.
+ */
+export declare function createRecoveryZip(ctx: Pick<RecoveryContext, "repoDir" | "repoSlug" | "faults" | "now">, reason: string): Promise<RecoveryBackup>;
+export interface ZipEntryInfo {
+    name: string;
+    size: number;
+    /** The extracted file content. */
+    data: Uint8Array;
+}
+/**
+ * Extract every entry of a ZIP buffer (fflate unzipSync). Returns [] for a
+ * buffer that is not a parseable zip — matching the old hand-rolled parser's
+ * "no EOCD found" behavior that some assertions rely on.
+ */
+export declare function parseZipEntries(buf: Buffer): ZipEntryInfo[];
+/**
+ * Assert that a zip file at `zipPath` is readable and parseable.
+ * Throws with a descriptive error if not.
+ *
+ * Validates EVERY central-directory entry — each entry's CD signature
+ * (0x02014b50) and that its variable-length fields stay within the central
+ * directory bounds. A zip whose FIRST entry is intact but whose LATER entries
+ * are corrupt is rejected (BUG 4): checking only entry 0 let truncated/garbled
+ * tails slip through.
+ *
+ * MEMORY-SAFE: reads only the end-of-central-directory record (file tail) and
+ * the central directory via positioned reads — NEVER the file data. A multi-GB
+ * backup is verified without reading it back into memory.
+ */
+export declare function assertZipReadable(zipPath: string): Promise<void>;
+/**
+ * Return the list of entries inside a zip file (as ZipEntryInfo objects).
+ *
+ * @internal TEST-ONLY: reads the WHOLE zip into memory to expose entry content.
+ * NEVER call this in a production path — a large backup would OOM. Production
+ * verification uses {@link assertZipReadable} (positioned reads, memory-safe).
+ * Used by tests to assert which files were backed up and inspect content.
+ */
+export declare function zipEntries(zipPath: string): Promise<ZipEntryInfo[]>;

package/dist/lib/remote-auth/recovery/classify.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Error-to-kind classifier for the sync-recovery subsystem — the SINGLE
+ * source of truth for git error classification.
+ *
+ * Maps a thrown error (from isomorphic-git or sync.ts) plus an optional
+ * RepoHealth preflight to a SyncErrorKind. The building blocks
+ * (isPushRejected, isMergeConflictError, classifyTransportFailure) are
+ * exported and consumed by sync.ts — there is exactly ONE implementation of
+ * each decoder, not parallel copies "kept in sync by spec".
+ *
+ * classifyFromHealth() is the health-only classifier used by preflight
+ * callers (no thrown error yet — e.g. the desktop at project-open): it returns
+ * null for a healthy repo so the caller can skip recovery entirely.
+ *
+ * This module is pure — no I/O, no side effects.
+ */
+import type { RepoHealth, SyncErrorKind } from "./types.ts";
+/**
+ * Minimum age before a leftover git lock counts as STALE for a preflight
+ * classification. recover-stale-lock.ts imports this same constant as its
+ * act-or-retry threshold, so preflight and handler can never disagree: a lock
+ * young enough to pass preflight is exactly a lock the handler would defer
+ * with retry_later ("a live process may still hold it").
+ */
+export declare const STALE_LOCK_MIN_AGE_MS: number;
+/**
+ * Thrown by syncProject's structural preflight when the repo must be repaired
+ * before any sync work can safely run. The `code` string is the STABLE
+ * contract hosts may match on across the dynamic-import boundary (where
+ * `instanceof` is unreliable); `kind` names the repair to dispatch.
+ */
+export declare class RepoNeedsRecoveryError extends Error {
+    readonly kind: SyncErrorKind;
+    readonly code = "RepoNeedsRecovery";
+    constructor(kind: SyncErrorKind);
+}
+/** Type guard for {@link RepoNeedsRecoveryError} (matches on the stable code). */
+export declare function isRepoNeedsRecoveryError(e: unknown): e is RepoNeedsRecoveryError;
+/**
+ * Thrown by transport.ts's onAuth when a stored credential EXISTS but the
+ * remote URL fails isCredentialTransmissionSafe (non-loopback http). Loud and
+ * typed on purpose: the old behavior (silently withholding the credential)
+ * surfaced as a 401 → "auth" → "reconnect" loop, and recover-auth then deleted
+ * the credential for the whole host. The `code` string is the STABLE contract
+ * (matchable across dynamic-import boundaries where `instanceof` fails).
+ */
+export declare class InsecureTransportError extends Error {
+    readonly code = "InsecureTransport";
+    constructor();
+}
+/** Type guard for {@link InsecureTransportError} (matches on the stable code). */
+export declare function isInsecureTransportError(e: unknown): e is InsecureTransportError;
+export declare function isPushRejected(e: unknown): boolean;
+/** Type guard exposing MergeConflictError's per-file payload (used by sync.ts). */
+export declare function isMergeConflictError(e: unknown): e is {
+    data: {
+        filepaths: string[];
+        bothModified: string[];
+        deleteByUs: string[];
+        deleteByTheirs: string[];
+    };
+};
+export declare function classifyTransportFailure(e: unknown): "auth_required" | "network_unavailable" | "insecure_transport" | null;
+/**
+ * Classify a structural repo condition from a RepoHealth snapshot alone.
+ * Used by preflight callers (no thrown error — e.g. project-open), and by
+ * classifyGitError's structural step so there is ONE ordering, not two.
+ *
+ * Returns null for a healthy repo (nothing to recover).
+ *
+ * ORDERING: interrupted-operation checks MUST precede the detached-head check
+ * (an in-progress rebase usually detaches HEAD — the abort repair must win over
+ * the rescue-branch repair), and specific interrupted-op repairs precede the
+ * generic stale-lock cleanup.
+ *
+ * `minLockAgeMs` gates the stale-lock classification: at preflight (the
+ * default, STALE_LOCK_MIN_AGE_MS) a younger lock is treated as healthy because
+ * a live process may still hold it — the same rule recover-stale-lock.ts
+ * applies before acting. Error-path callers pass 0: a lock that just made a
+ * sync THROW is worth routing regardless of age (the handler still re-checks
+ * and returns retry_later while it is fresh).
+ */
+export declare function classifyFromHealth(health: RepoHealth, opts?: {
+    minLockAgeMs?: number;
+}): SyncErrorKind | null;
+/**
+ * Map a thrown error plus optional repo-health facts to a SyncErrorKind.
+ *
+ * Called by the recovery dispatcher BEFORE invoking the per-kind handler.
+ *
+ * ORDERING (BUG 1 — transient transport beats structural health):
+ *   1. missing_git_dir — when there is genuinely no repo, a transport error is
+ *      meaningless (nothing to talk to a remote ABOUT), so the missing-repo
+ *      guidance must win even over an auth/network error.
+ *   2. Clearly transient/transport errors (auth, network) — these are decoded
+ *      from the THROWN ERROR and win over the remaining structural health
+ *      flags (detached HEAD, stale lock). Rationale: you cannot repair repo
+ *      STRUCTURE while you are offline or signed out, and the scary
+ *      backup+rescue-branch+confirm repair is the wrong first response to a
+ *      blip — the friendly "reconnect" / "try later" is correct. Once the user
+ *      is back online, the next sync re-runs preflight (no thrown error) and
+ *      the structural kind surfaces then (step 3).
+ *   3. Structural health flags (detached HEAD, stale lock) — applied when the
+ *      failure is NOT a transient transport error (e.g. a preflight with no
+ *      error, or a non-transport error).
+ *   4. Remaining error-code/message heuristics (conflicts, corrupt index,
+ *      unrelated histories, missing objects/ref-store, wrong remote/branch).
+ */
+export declare function classifyGitError(err: unknown, health?: RepoHealth): SyncErrorKind;

package/dist/lib/remote-auth/recovery/context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * buildRecoveryContext — the ONE place a RecoveryContext is resolved from a
+ * project directory. Both hosts consume it (the desktop's recovery bridge and
+ * `gutterpress repair`); each supplies only its own ConfirmationGate (dialog vs
+ * terminal prompt). Keeping the resolution here means repo-root, branch,
+ * credential, and slug rules can never drift between hosts.
+ *
+ * Resolution rules (each learned the hard way — see the audit trail):
+ *  - repoDir: the project's OWN repo root via detectProjectSource. NEVER
+ *    findEnclosingRepoDir — it is ancestor-only (skips the project's own
+ *    .git), so a project that IS its own repo root would resolve to a parent
+ *    repo (e.g. ~/.git) and the backup step would zip the entire home
+ *    directory.
+ *  - branch: remote diagnosis first, then the locally detected branch
+ *    (local-only repos on non-"main" branches), then "main".
+ *  - credential: resolved from the token store by remote hostname; stays in
+ *    the calling process — never serialized to a UI layer.
+ *  - repoSlug: last path segment, sanitized for backup file naming.
+ */
+import { detectProjectSource } from "../../project-source.ts";
+import { diagnoseProjectRemote } from "../diagnose.ts";
+import { type TokenStore } from "../token-store.ts";
+import type { ConfirmationGate, RecoveryContext } from "./types.ts";
+export interface BuildRecoveryContextOptions {
+    /** The directory the user opened (may be a subfolder of its repo). */
+    projectDir: string;
+    /** Host-specific approval gate (dialog, terminal prompt, …). */
+    confirmation: ConfirmationGate;
+    /** Credential store for the remote host, when the host has one. */
+    tokenStore?: TokenStore;
+    /** Display name for snapshot commits created during recovery. */
+    authorName?: string;
+    /** Email for snapshot commits created during recovery. */
+    authorEmail?: string;
+    /** Operation-log file shared with the sync path. */
+    logFile?: string;
+    /**
+     * Classification override (tests only — omit in production). Injected the
+     * same way as RecoveryContext's `now`/`faults`: bun's mock.module leaks
+     * across test files, so cross-cutting modules are never module-mocked.
+     */
+    classify?: typeof detectProjectSource;
+    /** Diagnosis override (tests only — omit in production). See `classify`. */
+    diagnose?: typeof diagnoseProjectRemote;
+}
+/** Resolve everything a recovery handler needs from a project directory. */
+export declare function buildRecoveryContext(options: BuildRecoveryContextOptions): Promise<RecoveryContext>;

package/dist/lib/remote-auth/recovery/dispatch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Recovery dispatcher — INTEGRATE PHASE.
+ *
+ * Maps each SyncErrorKind to its recover-<x>.ts handler.
+ * Also exports the index barrel for the recovery subsystem public surface.
+ *
+ * The dispatcher is the single call-site for all recovery attempts. Callers
+ * (e.g. a guardedSync wrapper) obtain a SyncErrorKind from classifyGitError(),
+ * build a RecoveryContext, and call recover(kind, ctx, error).
+ *
+ * Handler lookup is a plain switch — no dynamic import, no registry object —
+ * so TypeScript can verify exhaustiveness at compile time and bun build
+ * --compile can tree-shake unused handlers.
+ */
+import type { RecoveryContext, RecoveryResult, SyncErrorKind } from "./types.ts";
+/**
+ * Dispatch a recovery attempt.
+ *
+ * @param kind   - The SyncErrorKind from classifyGitError().
+ * @param ctx    - Full RecoveryContext (repoDir, branch, remoteUrl, etc.).
+ * @param error  - The original thrown error, if available.
+ * @returns      RecoveryResult describing what happened.
+ */
+export declare function recover(kind: SyncErrorKind, ctx: RecoveryContext, error?: unknown): Promise<RecoveryResult>;
+export type { RecoverFn, RecoveryContext, RecoveryResult, SyncErrorKind, RecoveryRisk, ManualGuidance, RepoHealth, RecoveryBackup, RepairConfirmation, ConfirmationGate, FaultInjector, FaultPoint, } from "./types.ts";
+export { classifyGitError, classifyFromHealth, RepoNeedsRecoveryError, isRepoNeedsRecoveryError, } from "./classify.ts";
+export { inspectRepo, preflightStructuralReason, buildPreflightDiagnostics, verifyRepoReadable, isUnbornRepo, } from "./inspect.ts";
+export { buildRecoveryContext } from "./context.ts";
+export type { BuildRecoveryContextOptions } from "./context.ts";
+export { recoveryPolicy, policyFor, detachedHeadWithLocalChangesPolicy } from "./policy.ts";
+export { createRecoveryZip, assertZipReadable, zipEntries } from "./backup.ts";
+export { makeManualGuidance } from "./manual-guidance.ts";
+export { failSafeNoRepair, withBackupGate } from "./failsafe.ts";

package/dist/lib/remote-auth/recovery/failsafe.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Fail-safe wrapper and no-op fallback for the sync-recovery subsystem.
+ *
+ * withBackupGate() enforces the invariant ordering every risky repair must
+ * follow:
+ *   1. Look up the policy for the kind.
+ *   2. If createBackup → createRecoveryZip; on failure → failSafe
+ *      "failed_no_changes_made" with NO subsequent writes.
+ *   3. If requireConfirmation → confirmRepair; DENIED → "blocked" no-op.
+ *   4. Run the risky repair callback.
+ *   5. If the risky callback throws AFTER a backup → failSafe
+ *      "failed_backup_available" (backup is readable, remote is unchanged).
+ *
+ * failSafeNoRepair() is the terminal no-op: returns
+ *   - "failed_backup_available" when a backup zip path is supplied
+ *   - "failed_no_changes_made" otherwise
+ * Both branches include ManualGuidance so the host can show useful copy.
+ */
+import type { RecoveryContext, RecoveryResult, SyncErrorKind } from "./types.ts";
+/**
+ * Terminal no-op: no repair was attempted (or the repair failed after a
+ * backup was created). Returns a RecoveryResult with the appropriate status.
+ */
+export declare function failSafeNoRepair(ctx: Pick<RecoveryContext, "repoSlug" | "remoteUrl">, kind: SyncErrorKind, backupZipPath?: string, error?: unknown): RecoveryResult;
+/**
+ * Enforce the invariant ordering for risky repairs:
+ *   policy → backup → confirmation → risky → failsafe on throw.
+ *
+ * The `risky` callback receives the backup zip path (or undefined) and
+ * must call ctx.faults?.before("after_backup_before_repair") at the start
+ * of its destructive section.
+ */
+export declare function withBackupGate(ctx: RecoveryContext, kind: SyncErrorKind, risky: (backupZipPath: string | undefined) => Promise<RecoveryResult>, error?: unknown): Promise<RecoveryResult>;