gutterpress 0.9.0-alpha.1 → 0.10.0-alpha.3

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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,68 +0,0 @@
-/**
- * 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";
-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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,35 +0,0 @@
-/**
- * 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/resolution-plan.d.ts

@@ -1,64 +0,0 @@
-/**
- * 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>;