gutterpress 0.0.0

package/dist/lib/remote-auth/recovery/recover-network.d.ts

@@ -0,0 +1,34 @@
+/**
+ * recover-network.ts — Offline: keep local work, schedule retry.
+ *
+ * WHY this module exists: when gutterpress can't reach the server (ECONNREFUSED,
+ * ETIMEDOUT, or any other network error), the right behavior is:
+ *
+ *   1. Snapshot any unsaved work locally so nothing is lost (sync.ts already
+ *      does this as its first step — "snapshot-first" invariant from ADR 0006 D5).
+ *   2. Tell the host to retry later with an exponential backoff delay.
+ *   3. Do NOT create a backup zip (risk is "none" — no data is at risk).
+ *   4. Do NOT ask the user for confirmation (no repair is being attempted).
+ *   5. Do NOT force-push, do NOT touch the remote.
+ *
+ * This is a THIN WRAPPER around syncProject from sync.ts. The snapshot step,
+ * the network call, and the "offline" classification all live there. The only
+ * delta this module adds is translating SyncOutcome { status: "offline" } →
+ * RecoveryResult { status: "retry_later", retryAfterMs }.
+ *
+ * Backoff: fixed 30 s delay before the next automated retry.
+ */
+import type { RecoveryContext, RecoveryResult } from "./types.ts";
+/**
+ * Handle a `network_unavailable` classification:
+ *
+ * - Delegates entirely to `syncProject` (which snapshots unsaved work first,
+ *   then attempts fetch + merge + push through the injectable httpClient).
+ * - When the outcome is `offline`, returns `retry_later` with a sane backoff.
+ * - When the outcome is anything else (e.g. the network recovered mid-call),
+ *   passes the outcome through as a `recovered` result so the host can refresh.
+ *
+ * The `error` argument is accepted per the dispatcher contract but is not
+ * needed here: syncProject already re-classifies the live error internally.
+ */
+export declare function recover(ctx: RecoveryContext, _error?: unknown): Promise<RecoveryResult>;

package/dist/lib/remote-auth/recovery/recover-non-fast-forward.d.ts

@@ -0,0 +1,27 @@
+/**
+ * recover-non-fast-forward.ts — thin wrapper over syncProject.
+ *
+ * WHY this exists: when a push is rejected because the online copy has commits
+ * this computer doesn't have, the correct fix is pull-then-push — which is
+ * exactly what syncProject already does. This handler just calls syncProject
+ * and maps its typed SyncOutcome to the RecoveryResult contract.
+ *
+ * NO backup is created (policy.createBackup = false for non_fast_forward):
+ * syncProject takes its own snapshot before touching anything (ADR 0006 D5),
+ * so the user's work is safe without an additional zip.
+ *
+ * NO force-push is ever used: syncProject/pullChanges/pushChanges use only
+ * the normal git.push(), which the server rejects when a force-push would be
+ * needed. The safety invariant is proved by gitSpy in the test.
+ *
+ * Outcome mapping:
+ *   SyncOutcome.status   → RecoveryResult.status
+ *   'synced'             → 'recovered'
+ *   'up-to-date'         → 'recovered'  (local commits all landed; nothing new)
+ *   'conflict'           → 'needs_user' (let the user choose per file)
+ *   'auth'               → 'needs_user' (guidance: reconnect)
+ *   'offline'            → 'retry_later'
+ *   'error'              → 'failed_no_changes_made'
+ */
+import type { RecoverFn } from "./types.ts";
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-stale-lock.d.ts

@@ -0,0 +1,76 @@
+/**
+ * recover-stale-lock.ts — remove stale .git lock files left by a crash.
+ *
+ * WHY: When a write operation is interrupted (power loss, forced kill, crash)
+ * the version-tracking system leaves a lock file behind. Every subsequent
+ * operation fails until the lock is removed. This handler automates that
+ * cleanup with a conservative age check and a user confirmation gate.
+ *
+ * A crash does NOT only leave `.git/index.lock`. Depending on what was being
+ * written when the process died, git can leave any of:
+ *   - index.lock          (staging the index)
+ *   - HEAD.lock           (moving HEAD)
+ *   - config.lock         (writing config)
+ *   - packed-refs.lock    (repacking refs)
+ *   - refs/**\/<name>.lock (updating a single ref, e.g. refs/heads/main.lock)
+ * If the stuck lock is any of these and we only ever looked at index.lock, the
+ * repo would stay unusable forever. So this handler scans the known top-level
+ * lock files PLUS a shallow scan of `.git/refs/**` for `*.lock` files.
+ *
+ * Decision logic (applied to the WHOLE candidate set, not just index.lock):
+ *   NO lock at all → the race was already won; return retry_later (safe to
+ *     retry the original operation immediately).
+ *   ANY lock is FRESH (age < STALE_THRESHOLD_MS) → a live process may still
+ *     hold the repo. Deleting a lock another process holds would corrupt an
+ *     in-flight write, so we delete NOTHING and return retry_later — even if
+ *     other locks in the set are stale. One fresh lock blocks the whole sweep.
+ *   ALL locks are STALE (age ≥ STALE_THRESHOLD_MS) → request user confirmation
+ *     once, then remove every stale lock; return recovered.
+ *
+ * Why "any fresh → retry_later" (and not "remove the stale ones"): the locks
+ * in the set may belong to the SAME interrupted-or-live operation. We cannot
+ * tell a crashed lock from a live one except by age, so the safe rule is: if
+ * the youngest lock could still be held, leave them all alone for now.
+ *
+ * Safety invariants:
+ *   - Never force-pushes (this repair is entirely local).
+ *   - No backup zip (policy.createBackup = false for stale_lock; a lock file
+ *     is trivially recreatable and contains no user data).
+ *   - Confirmation required (policy.requireConfirmation = true).
+ *   - Fault hook ctx.faults?.before("remove_index_lock") fires once, just
+ *     before the FIRST unlink, so tests can assert the fail-safe path. If it
+ *     throws, nothing is removed.
+ *   - Only locks proven stale are removed; a fresh lock is never touched.
+ *   - User content files are never touched.
+ *
+ * Author-facing copy lives in manual-guidance.ts (stale_lock case). No git
+ * words, no file paths, no tokens in any user-visible string — the copy here
+ * says "leftover lock" / "temporary lock", never "lock file"/"index"/"ref".
+ */
+import type { RecoveryContext, RecoveryResult } from "./types.ts";
+/**
+ * Known top-level lock files git may leave directly under `.git/`. These are
+ * scanned in addition to a shallow walk of `.git/refs/**` for `*.lock` files.
+ * Exported (with findLockCandidates) as the SINGLE lock-discovery
+ * implementation — inspect.ts's health probe consumes the same scan, so
+ * health and handler can never disagree about which locks exist.
+ */
+export declare const TOP_LEVEL_LOCK_NAMES: readonly ["index.lock", "HEAD.lock", "config.lock", "packed-refs.lock"];
+export interface LockCandidate {
+    /** Absolute path to the lock file. */
+    path: string;
+    /** Age in ms relative to `now` (now - mtime). */
+    ageMs: number;
+}
+/**
+ * Gather every candidate lock file (top-level + refs/**) with its age.
+ * Locks that vanish between discovery and stat are simply dropped (a racing
+ * delete is fine to ignore). Never throws.
+ */
+export declare function findLockCandidates(gitDir: string, now: number): Promise<LockCandidate[]>;
+/**
+ * Attempt to recover from stale .git lock files (index.lock and friends).
+ *
+ * Implements the RecoverFn contract from types.ts.
+ */
+export declare function recover(ctx: RecoveryContext, _error?: unknown): Promise<RecoveryResult>;

package/dist/lib/remote-auth/recovery/recover-unrelated-histories.d.ts

@@ -0,0 +1,44 @@
+/**
+ * recover-unrelated-histories.ts — Combine local and remote when they share
+ * no history.
+ *
+ * WHY this is needed:
+ *   If a user's local project and the configured online project were created
+ *   independently — with no shared starting point — a normal merge cannot
+ *   combine them. This handler creates a backup, asks the user to confirm,
+ *   then performs the combination locally:
+ *
+ *   1. Fetches the remote tip.
+ *   2. Merges the remote into the local branch with
+ *      `allowUnrelatedHistories: true`.
+ *   3. On clean merge → combined successfully.
+ *   4. On file conflicts → surfaces `needs_user` with the conflict file list
+ *      and the local/remote OIDs, so the host can show the per-file version
+ *      chooser and call `resolveConflicts({ allowUnrelatedHistories: true })`
+ *      with the user's choices ("keep mine", "keep theirs", "keep both").
+ *
+ *   The per-file resolution (merge driver, binary safety, "keep both" →
+ *   "(online copy)" rename, delete-conflict equalization, push) is handled
+ *   entirely by `sync.ts:resolveConflicts` — this handler just sets up the
+ *   merge and surfaces the conflict, exactly like `recover-merge-conflict.ts`
+ *   and `recover-binary-conflict.ts`.
+ *
+ * Safety invariants:
+ *   - NEVER pushes to the remote (mayChangeRemote:false in policy). The push
+ *     happens later in `resolveConflicts` AFTER the user makes their choices.
+ *   - Remote is fetched but never written to.
+ *   - Backup zip created and verified BEFORE any repair.
+ *   - backup_create fault → failed_no_changes_made, no further writes.
+ *   - mid-repair fault → failed_backup_available, backup readable.
+ *   - User DENY → blocked, local + remote unchanged, backup still readable.
+ *   - No remoteUrl → blocked with guidance.
+ *   - Merge conflict → branch unchanged (abortOnConflict:true is the default);
+ *     local commits preserved on the branch and in the backup zip. The
+ *     conflict file list + OIDs are threaded through so the host can call
+ *     `resolveConflicts` after the user decides.
+ *
+ * Fault injection points:
+ *   after_backup_before_repair, fetch, merge
+ */
+import type { RecoverFn } from "./types.ts";
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-wrong-remote.d.ts

@@ -0,0 +1,35 @@
+/**
+ * recover-wrong-remote.ts — Wrong remote / missing destination.
+ *
+ * WHAT: When the project's configured online destination is unreachable,
+ * returns 404, or the destination section (path) does not exist on the
+ * server, syncing cannot proceed. This handler:
+ *   1. Uses diagnoseProjectRemote + parseRemoteOrigin (CLAUDE.md §7 mandated
+ *      reuses) to obtain the project's remote URL, host, and protocol facts.
+ *   2. Probes the remote using isomorphic-git listServerRefs via httpClient
+ *      (no system git binary) to detect whether the configured destination
+ *      is actually present on the server.
+ *   3. Returns status "blocked" with reconnect/choose-destination guidance.
+ *      The supportDetails reflect whether the destination was found or absent,
+ *      so the guidance can distinguish "destination missing" from "wrong address".
+ *   4. NEVER creates a destination on the server automatically.
+ *   5. NEVER pushes to the remote.
+ *   6. Leaves all local files and remote state completely unchanged.
+ *
+ * Policy: createBackup:false — pure block, no repair attempted.
+ *   requireConfirmation:false — confirmation gate is never called.
+ *
+ * WHY this is always "blocked": the handler is invoked ONLY after the
+ * classifier has determined the remote or destination is wrong. There is no
+ * safe automated fix — the author must update the project settings.
+ */
+import type { RecoverFn } from "./types.ts";
+/**
+ * Block sync and return author-facing reconnect guidance.
+ * Never pushes, never modifies local files or remote state.
+ *
+ * Uses diagnoseProjectRemote to get remote/protocol facts, and
+ * listServerRefs to detect whether the configured destination exists
+ * on the server — all read-only operations.
+ */
+export declare const recover: RecoverFn;

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

@@ -0,0 +1,235 @@
+/**
+ * Shared types and dispatcher contract for the sync-recovery subsystem.
+ *
+ * Every recover-<x>.ts handler imports from here. This module contains ZERO
+ * logic — it is a pure type surface. The dispatcher (dispatch.ts) maps a
+ * SyncErrorKind to its handler and is wired in the Integrate phase.
+ *
+ * Author-facing copy rules: no git words, no tokens, no internal paths visible
+ * to users. Every user-visible string lives in manual-guidance.ts.
+ */
+import type httpNode from "isomorphic-git/http/node";
+import type { ProjectSource } from "../../project-source.ts";
+import type { ConflictFile } from "../sync.ts";
+import type { HostCredential, TokenStore } from "../token-store.ts";
+/**
+ * Every failure mode the recovery subsystem can handle. The classifier
+ * (classify.ts) maps a thrown error + repo health facts to one of these.
+ */
+export type SyncErrorKind = "non_fast_forward" | "merge_conflict" | "binary_conflict" | "auth_required" | "network_unavailable" | "insecure_transport" | "detached_head" | "stale_lock" | "corrupt_index" | "missing_git_dir" | "missing_or_corrupt_objects" | "unrelated_histories" | "wrong_remote_or_branch" | "interrupted_rebase" | "interrupted_cherry_pick" | "interrupted_merge" | "unknown";
+/**
+ * Machine token for the primary CTA in the guidance dialog. The host switches
+ * on this to route the button to the right flow. The human-readable label the
+ * button shows lives in `ManualGuidance.recommendedAction` (never this token).
+ */
+export type RecoveryActionKey = "sync" | "reconnect" | "resolve_conflict" | "restore_repo" | "check_connection";
+/**
+ * How much irreversible change a repair makes. The confirmation gate shows
+ * a plain-language summary appropriate to the risk level.
+ */
+export type RecoveryRisk = "none" | "low" | "medium" | "high";
+/**
+ * Jargon-free guidance the host shows when a repair is blocked or fails.
+ * No git words, no tokens, no internal paths.
+ */
+export interface ManualGuidance {
+    /** One-sentence plain-language summary of what went wrong. */
+    userSummary: string;
+    /** The single most important action the user should take next. */
+    recommendedNextStep: string;
+    /** Action label for the primary button in the UI. */
+    recommendedAction: string;
+    /** Machine token the host switches on to route the primary button's action. */
+    recommendedActionKey: RecoveryActionKey;
+    /** Optional secondary steps (shown as a list). */
+    safeNextSteps?: string[];
+    /** Details for a support ticket — may contain technical info. */
+    supportDetails?: string;
+    /** Path to the backup zip, when one was created before the failure. */
+    backupZipPath?: string;
+}
+/** The backup zip created before a risky repair. */
+export interface RecoveryBackup {
+    /** Absolute path to the zip file under os.tmpdir()/print-sync-recovery/. */
+    zipPath: string;
+    /** ISO timestamp the backup was created. */
+    createdAt: string;
+    /** Files included in the backup (relative paths). */
+    entries: string[];
+}
+/**
+ * What a confirmation gate shows the user before a risky repair.
+ * The UI must render this information — never silently start a risky repair.
+ */
+export interface RepairConfirmation {
+    repair: SyncErrorKind;
+    risk: RecoveryRisk;
+    /** Plain-language summary of what the repair will do. */
+    summary: string;
+    /** Path to the backup zip (already created and verified). */
+    backupZipPath: string;
+    willChangeLocalFiles: boolean;
+    willChangeGitMetadata: boolean;
+    willChangeRemote: boolean;
+    /** True when the backup alone is enough to undo the repair. */
+    canBeUndoneFromBackup: boolean;
+}
+/** Gate the host must satisfy: show the user what will happen and ask. */
+export interface ConfirmationGate {
+    confirmRepair(req: RepairConfirmation): Promise<boolean>;
+}
+/**
+ * Outcome of a recovery attempt. Each status maps to a host-side action:
+ * - recovered        → refresh the project; show a success toast.
+ * - retry_later      → schedule a retry after retryAfterMs; show a soft message.
+ * - needs_user       → show the conflict chooser / reconnect dialog.
+ * - blocked          → show guidance and a "what do I do?" panel.
+ * - failed_no_changes_made → show guidance; nothing was changed locally or remotely.
+ * - failed_backup_available → show guidance + "open backup folder" button.
+ */
+export type RecoveryResult = {
+    status: "recovered";
+    message: string;
+    backupZipPath?: string;
+} | {
+    status: "retry_later";
+    message: string;
+    retryAfterMs: number;
+} | {
+    status: "needs_user";
+    message: string;
+    guidance: ManualGuidance;
+    files?: ConflictFile[];
+    backupZipPath?: string;
+    /**
+     * Conflict tip OIDs threaded through to the host so it can call
+     * resolveConflicts with the correct local/remote versions after the user
+     * chooses. Present on the per-file conflict-chooser paths only.
+     */
+    localId?: string;
+    remoteId?: string;
+} | {
+    status: "blocked";
+    message: string;
+    guidance: ManualGuidance;
+    backupZipPath?: string;
+} | {
+    status: "failed_no_changes_made";
+    message: string;
+    guidance: ManualGuidance;
+} | {
+    status: "failed_backup_available";
+    message: string;
+    backupZipPath: string;
+    guidance: ManualGuidance;
+};
+/**
+ * Preflight health snapshot of a local repo. Populated by inspectRepo()
+ * (inspect.ts) before any recovery decision is made.
+ */
+export interface RepoHealth {
+    /** True when .git/ exists and looks like a valid git dir. */
+    hasGitDir: boolean;
+    /** Current branch name, or undefined when HEAD is detached. */
+    currentBranch?: string;
+    /** True when HEAD is detached (no named branch). */
+    isDetachedHead: boolean;
+    /**
+     * True when HEAD (or the ref store) could not even be READ — distinct from
+     * a clean detached HEAD, where HEAD resolves fine but points at a commit
+     * instead of a branch. This means the repo's ref store or HEAD file is
+     * missing/corrupt, and routes to `missing_or_corrupt_objects` instead of
+     * `detached_head` (see classifyFromHealth).
+     */
+    headUnreadable: boolean;
+    /**
+     * True when a leftover git lock file exists (a previous operation may have
+     * died). Detects any of index.lock, HEAD.lock, config.lock, packed-refs.lock,
+     * or a per-ref refs/**\/*.lock — the same set the stale-lock handler scans.
+     */
+    hasStaleLock: boolean;
+    /** How old the YOUNGEST detected lock file is in milliseconds, when present. */
+    lockAgeMs?: number;
+    /** True when a MERGE_HEAD file exists (interrupted merge). */
+    hasInterruptedMerge: boolean;
+    /** True when a rebase-in-progress directory exists. */
+    hasInterruptedRebase: boolean;
+    /** True when CHERRY_PICK_HEAD exists. */
+    hasInterruptedCherryPick: boolean;
+    /** True when the working tree has uncommitted changes. */
+    hasLocalChanges: boolean;
+}
+/**
+ * Named fault injection points every risky repair MUST call via
+ * `ctx.faults?.before(point)`. Throwing from this hook simulates a failure
+ * at that exact point so failsafe invariants can be asserted.
+ */
+export type FaultPoint = "backup_create" | "backup_verify" | "after_backup_before_repair" | "fetch" | "merge" | "checkout_branch" | "abort_interrupted_operation" | "remove_operation_state" | "create_recovery_branch" | "commit_recovery_snapshot" | "remove_index_lock" | "remove_index" | "rebuild_index" | "clone_temp_repo" | "replace_git_dir" | "push" | "write_conflict_snapshot";
+export interface FaultInjector {
+    before(point: FaultPoint): Promise<void>;
+}
+/**
+ * Everything a recover-<x>.ts handler needs. Extends SyncProjectOptions with
+ * the repo-level facts that the dispatcher resolves once and passes down.
+ */
+export interface RecoveryContext {
+    /** The project directory the user opened (may be a repo subfolder). */
+    projectDir: string;
+    /** Absolute path to the git repository root. */
+    repoDir: string;
+    /**
+     * The projectDir's classification, resolved ONCE by buildRecoveryContext and
+     * threaded to every consumer (inspectRepo, diagnoseProjectRemote) so the
+     * recovery path never re-walks parent dirs to re-classify the same folder.
+     * `null` records that classification failed; omitted means "not resolved" —
+     * consumers classify themselves in both cases.
+     */
+    source?: ProjectSource | null;
+    /** Current branch name (may be empty on detached HEAD). */
+    branch: string;
+    /** Sanitized HTTPS remote URL (no embedded credentials). */
+    remoteUrl?: string;
+    /** Short identifier for the repo used in backup paths. */
+    repoSlug: string;
+    /** Resolved credential for the remote host. */
+    credential?: HostCredential;
+    /** Host-keyed credential store (for clearing stale tokens). */
+    tokenStore?: TokenStore;
+    /** Injectable HTTP transport (real or test mock). */
+    httpClient?: typeof httpNode;
+    /** The user's display name for snapshot commits. */
+    authorName?: string;
+    /** The user's email for snapshot commits. Paired with `authorName` — a
+     *  recovery commit must carry the SAME identity a normal snapshot does. */
+    authorEmail?: string;
+    /** Gate the host must satisfy before a risky repair starts. */
+    confirmation: ConfirmationGate;
+    /** Fault injection hooks (tests only — omit in production). */
+    faults?: FaultInjector;
+    /** Clock override (tests only). Returns epoch ms. */
+    now?: () => number;
+    /**
+     * Optional path to a log file for debugging. When set, each recovery step
+     * (backup, fetch, merge, checkout, etc.) is appended as a timestamped line.
+     * Never logs secrets — only repo slug, branch, short OIDs, outcome status.
+     */
+    logFile?: string;
+}
+/**
+ * The signature every recover-<x>.ts module MUST export.
+ * The dispatcher (dispatch.ts) maps SyncErrorKind → RecoverFn.
+ */
+export type RecoverFn = (ctx: RecoveryContext, error?: unknown) => Promise<RecoveryResult>;
+/**
+ * Optional per-kind precondition probe a recover-<x>.ts module MAY export as
+ * `stillApplies`. The dispatcher calls it — for serializeRepo:true kinds only,
+ * INSIDE withRepoLock, immediately before invoking the handler body — to catch
+ * the case where the condition that justified this kind was already resolved
+ * (externally, or by a previous attempt) between classification and dispatch.
+ * Returning false means there is nothing left to repair; the dispatcher
+ * returns a benign no-op RecoveryResult without running the handler at all.
+ * Must be read-only and throw-free from the caller's perspective (probes
+ * should catch their own errors and resolve `true` — "assume it still
+ * applies" — rather than reject, so a probe failure never blocks recovery).
+ */
+export type StillAppliesFn = (ctx: RecoveryContext) => Promise<boolean>;

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

@@ -0,0 +1,64 @@
+/**
+ * Pure per-file resolution PLAN builder for {@link resolveConflicts} (#15,
+ * ADR 0006 D5). Given the author's per-file choices and the two commit tips,
+ * it decides — for EACH conflicted file — what the merge driver should return
+ * ("mine"/"theirs"), what to write/delete on the LOCAL side before the merge
+ * (delete-conflict equalization + "(online copy)" files), what to restore
+ * after the merge, and which decided files need a raw-bytes binary fix.
+ *
+ * It is intentionally free of git/fs coupling: the only IO it needs — reading
+ * a file's blob from a commit, and picking a collision-free "(online copy)"
+ * name — is injected via {@link ResolutionPlanDeps}, so the whole decision
+ * table is unit-testable with plain fakes. sync.ts owns the git side-effects
+ * of ACTUALLY writing/deleting/merging/pushing; this module owns only the
+ * decisions.
+ */
+/** Author's per-file decision for a conflicted file (mirror of sync.ts). */
+export interface ResolutionInput {
+    path: string;
+    choice: "mine" | "theirs" | "both";
+}
+/** A file to write with exact bytes (never decoded through a string). */
+export interface PlanWrite {
+    path: string;
+    content: Uint8Array;
+}
+/**
+ * The decisions {@link resolveConflicts} executes, in order:
+ *
+ * - `driverChoice` — the side the custom mergeDriver returns per decided file.
+ * - `preWrites` / `preDeletes` — applied on the LOCAL side BEFORE the merge
+ *   ("(online copy)" files + delete-conflict equalization) so the merge is
+ *   clean and both parents stay honest.
+ * - `postWrites` / `postDeletes` — applied AFTER the merge to restore the
+ *   author's chosen side for delete-involved files equalized the other way.
+ * - `postBinaryFixes` — decided files overwritten with raw git-object bytes
+ *   after checkout, guarding against UTF-8 round-trip corruption of binaries
+ *   in the string-based merge driver (a no-op for text files).
+ */
+export interface ResolutionPlan {
+    driverChoice: Map<string, "mine" | "theirs">;
+    preWrites: PlanWrite[];
+    preDeletes: string[];
+    postWrites: PlanWrite[];
+    postDeletes: string[];
+    postBinaryFixes: PlanWrite[];
+}
+/** Injected IO the plan builder needs (kept out of this pure module). */
+export interface ResolutionPlanDeps {
+    /** Read a file's blob from a commit oid, or null when absent in that tree. */
+    readBlob: (oid: string, filepath: string) => Promise<Uint8Array | null>;
+    /**
+     * First "(online copy)" name for `filepath` that collides with nothing in
+     * the working dir or in either side's tree (given by `oids`).
+     */
+    uniqueOnlineCopyPath: (filepath: string, oids: string[]) => Promise<string>;
+}
+/**
+ * Build the per-file plan. "mine" is read from `localTip` (the CURRENT local
+ * tip, so edits made after the conflict was reported count as the author's
+ * version); "theirs" is read from `remoteId` (the online tip). Files present
+ * on BOTH sides are settled inside the merge by the driver; delete-involved
+ * files are equalized before the merge and restored after.
+ */
+export declare function buildResolutionPlan(resolutions: ResolutionInput[], localTip: string, remoteId: string, deps: ResolutionPlanDeps): Promise<ResolutionPlan>;

package/dist/lib/remote-auth/sync-messages.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Author-language copy for sync / pull / push / conflict-resolution (never raw
+ * git words). Extracted from sync.ts so the transport, conflict-resolution and
+ * orchestrator modules share ONE source of these strings — their exact wording
+ * is part of the observable contract (the host renders them verbatim).
+ */
+export declare const MSG_UP_TO_DATE = "Everything is in sync.";
+export declare const MSG_UP_TO_DATE_PULLED = "Everything is in sync. The latest online changes were downloaded to this computer.";
+export declare const MSG_SYNCED = "Your changes are online.";
+export declare const MSG_SYNCED_MERGED = "Your changes are online, combined with changes from the online copy.";
+export declare const MSG_OFFLINE = "Your changes are saved on this computer. gutterpress couldn't reach the online repository \u2014 try syncing again when you're back online.";
+export declare const MSG_AUTH = "The online repository didn't accept the saved connection. Reconnect and try again.";
+export declare const MSG_INSECURE_TRANSPORT = "This project's online address isn't secure, so the saved connection wasn't sent \u2014 connections are never sent over an insecure address. Switch the address to a secure one (starting with https), or to a local loopback address for a server on this computer, to sync.";
+export declare const MSG_RACE = "Someone else synced changes at the same moment. Your work is saved on this computer \u2014 please try Sync again.";
+export declare const MSG_CONFLICT = "Your copy and the online copy both changed. Choose which version to keep for each file \u2014 a safety snapshot of your work was taken first.";
+export declare const MSG_NO_REMOTE = "This project isn't connected to an online repository yet.";
+export declare const MSG_SSH_REMOTE = "This project's online address uses SSH (git@\u2026), which gutterpress can't sync to. Switch it to the web (HTTPS) address to sync from here.";
+export declare const MSG_NO_BRANCH = "This project's version history isn't on a named branch, so it can't be synced right now.";
+export declare const MSG_PULLED = "The latest online changes were downloaded to this computer.";
+export declare const MSG_PULLED_MERGED = "The latest online changes were combined with your changes on this computer.";
+export declare const MSG_PULL_UP_TO_DATE = "You already have the latest online changes.";
+export declare const MSG_PUSH_UP_TO_DATE = "There's nothing new to send \u2014 everything is already online.";
+export declare const MSG_PULL_FIRST = "The online copy has changes you don't have yet. Get the latest changes first, then send yours.";
+export declare const MSG_EXPIRED_CHOICES = "Those combine choices have expired. Please run Sync again.";
+/** Message recorded on the automatic pre-sync snapshot (D5 invariant). */
+export declare const SYNC_SNAPSHOT_MESSAGE = "Snapshot before syncing";