gutterpress 0.0.0

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

@@ -0,0 +1,225 @@
+/**
+ * Type/interface declarations for snapshot-first sync + conflict resolution
+ * (#15, ADR 0006 D5). Extracted from sync.ts so the orchestrator, transport and
+ * conflict-resolution modules share ONE definition of each result/option shape.
+ * Pure type surface — no runtime code.
+ */
+import type httpNode from "isomorphic-git/http/node";
+import type { HostCredential, TokenStore } from "./token-store.ts";
+/**
+ * isomorphic-git object cache, scoped to ONE operation (one function call)
+ * and released with it. NEVER share these across operations or hold them in
+ * module state: reading any object from a packfile makes isomorphic-git load
+ * the ENTIRE pack into the cache (measured ~1.3–3.8 GB RSS on a 2 GB repo),
+ * so a long-lived shared cache pins that memory for the life of the process —
+ * the root cause of the 0.5.0 "sync uses 2 GB" report.
+ */
+export type GitCache = Record<string, unknown>;
+/** How one conflicted file differs between the two copies. */
+export type ConflictKind = 
+/** Edited in both copies. */
+"both-edited"
+/** The author deleted it; the online copy edited it. */
+ | "you-deleted"
+/** The online copy deleted it; the author edited it. */
+ | "online-deleted";
+/** One file that changed in both the local and the online copy. */
+export interface ConflictFile {
+    path: string;
+    kind: ConflictKind;
+}
+/** Author's per-file decision for a conflicted file (ADR 0006 D5). */
+export interface ConflictResolution {
+    path: string;
+    choice: "mine" | "theirs" | "both";
+}
+/** Outcome of a sync (or conflict-resolution) attempt. */
+export type SyncOutcome = {
+    status: "synced";
+    message: string;
+    /** Snapshot taken of unsaved work before syncing, if any. */
+    snapshotId?: string;
+    /** True when online changes were merged into the local copy. */
+    mergedRemoteChanges: boolean;
+    /** True when pulling online changes changed the local working tree. */
+    filesChanged?: boolean;
+} | {
+    status: "up-to-date";
+    message: string;
+    snapshotId?: string;
+    filesChanged?: boolean;
+} | {
+    status: "conflict";
+    message: string;
+    files: ConflictFile[];
+    /** Local branch tip the conflict was computed against. */
+    localId: string;
+    /** Online tip the conflict was computed against. */
+    remoteId: string;
+    snapshotId?: string;
+} | {
+    status: "auth";
+    message: string;
+    snapshotId?: string;
+    filesChanged?: boolean;
+} | {
+    status: "offline";
+    message: string;
+    snapshotId?: string;
+    filesChanged?: boolean;
+} | {
+    status: "error";
+    message: string;
+    /**
+     * Stable machine-readable signal for the small set of known "the project
+     * isn't set up right" failures (no remote / SSH remote / no named
+     * branch) — set by conflict-resolution.ts's setupErrorMessage() check.
+     * Lets a host UI route to its connect/setup surface without
+     * string-matching `message` (which stays free to reword).
+     */
+    code?: "needs-connection-setup";
+    snapshotId?: string;
+    filesChanged?: boolean;
+};
+/**
+ * Outcome of a pull-only attempt ({@link pullChanges}): fetch + fast-forward/
+ * merge of the online changes, NEVER a push. Conflict semantics are identical
+ * to {@link syncProject} (abortOnConflict — the working tree is never left
+ * with conflict markers).
+ */
+export type PullOutcome = {
+    status: "pulled";
+    message: string;
+    /** Snapshot taken of unsaved work before pulling, if any. */
+    snapshotId?: string;
+    /**
+     * True when the pull created a combine (merge) commit — local commits
+     * existed alongside the online ones. False for a plain fast-forward.
+     */
+    merged: boolean;
+    /**
+     * True when the working tree CONTENT changed (the tip's tree differs
+     * from before) — the host should refresh its preview.
+     */
+    filesChanged: boolean;
+} | {
+    status: "up-to-date";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "conflict";
+    message: string;
+    files: ConflictFile[];
+    localId: string;
+    remoteId: string;
+    snapshotId?: string;
+} | {
+    status: "auth";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "offline";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "error";
+    message: string;
+    snapshotId?: string;
+};
+/**
+ * Outcome of a push-only attempt ({@link pushChanges}): snapshot-if-needed,
+ * then push — NEVER a merge. When the online copy has commits this computer
+ * doesn't have, the result is the typed `"pull-first"` status (the host shows
+ * a plain-language "get the latest changes first" message) — pushChanges
+ * never auto-merges.
+ */
+export type PushOutcome = {
+    status: "pushed";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "up-to-date";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "pull-first";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "auth";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "offline";
+    message: string;
+    snapshotId?: string;
+} | {
+    status: "error";
+    message: string;
+    snapshotId?: string;
+};
+export interface SyncProjectOptions {
+    projectDir: string;
+    /** Explicit credential; wins over the token store. */
+    credential?: HostCredential;
+    /** Host-keyed store used to resolve the credential for the remote's host. */
+    tokenStore?: TokenStore;
+    /** Snapshot message for unsaved work (defaults to a friendly one). */
+    message?: string;
+    authorName?: string;
+    authorEmail?: string;
+    /** Injectable git HTTP transport for tests. */
+    httpClient?: typeof httpNode;
+    /**
+     * Bounded retry policy for {@link syncProject}'s pull→push race loop. The
+     * loop is ALWAYS bounded (never infinite) and the snapshot-first guarantee
+     * holds on every path. Defaults to {@link DEFAULT_SYNC_RETRY}. `sleep` is
+     * injectable so tests can drive backoff deterministically.
+     */
+    retry?: SyncRetryOptions;
+    /**
+     * Optional path to a log file for debugging sync/recovery operations.
+     * When set, each step (snapshot, fetch, merge, push, conflict) is appended
+     * as a timestamped line. Never logs secrets.
+     */
+    logFile?: string;
+}
+/** Bounded retry policy for the sync race loop (BUG 6). */
+export interface SyncRetryOptions {
+    /** Max pull→push passes before giving up. Clamped to ≥ 1. Default 3. */
+    attempts?: number;
+    /** Delay between passes, in ms. Clamped to ≥ 0. Default 150. */
+    backoffMs?: number;
+    /** Injectable delay (tests only); defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface ResolveConflictsOptions {
+    projectDir: string;
+    resolutions: ConflictResolution[];
+    /** The `localId` from the conflict outcome. */
+    localId: string;
+    /** The `remoteId` from the conflict outcome. */
+    remoteId: string;
+    credential?: HostCredential;
+    tokenStore?: TokenStore;
+    authorName?: string;
+    authorEmail?: string;
+    httpClient?: typeof httpNode;
+    /**
+     * When true, the merge is allowed to combine two commits that share no
+     * common ancestor (unrelated histories). Set by the unrelated-histories
+     * recovery path; regular merge conflicts leave this false (the local and
+     * remote share a common base, so `allowUnrelatedHistories` is unnecessary).
+     */
+    allowUnrelatedHistories?: boolean;
+    /** Optional log file for debugging conflict resolution steps. */
+    logFile?: string;
+}
+/** Resolved project remote + credential used by every transport call. */
+export interface RemoteTransport {
+    remote: string;
+    /** Sanitized HTTPS URL (no embedded credentials). */
+    url: string;
+    host: string;
+    credential?: HostCredential;
+}

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

@@ -0,0 +1,45 @@
+import { conflictFilesFrom, onAuthFor } from "./transport.ts";
+import type { PullOutcome, PushOutcome, SyncOutcome, SyncProjectOptions, SyncRetryOptions } from "./sync-types.ts";
+export { onAuthFor, conflictFilesFrom };
+export { onlineCopyPath, resolveConflicts } from "./conflict-resolution.ts";
+export { SYNC_SNAPSHOT_MESSAGE } from "./sync-messages.ts";
+export type { ConflictFile, ConflictKind, ConflictResolution, PullOutcome, PushOutcome, ResolveConflictsOptions, SyncOutcome, SyncProjectOptions, SyncRetryOptions, } from "./sync-types.ts";
+/**
+ * Default sync retry budget (BUG 6): 3 bounded passes with a short backoff.
+ * A fast-moving remote can race the push once or twice without the user seeing
+ * the false "Someone else synced at the same moment" message; a remote that
+ * genuinely races EVERY pass still terminates with that friendly message and
+ * the work safely snapshotted.
+ */
+export declare const DEFAULT_SYNC_RETRY: Required<Omit<SyncRetryOptions, "sleep">>;
+/**
+ * Snapshot-first sync (ADR 0006 D5) — the composition of {@link pullChanges}
+ * then {@link pushChanges}. If someone pushes between our pull and our push,
+ * the push reports pull-first and the pair re-runs (their commits merge in on
+ * the next pass), with a short backoff between passes. The loop is ALWAYS
+ * bounded by `retry.attempts` (BUG 6 — a fast-moving remote no longer triggers
+ * a FALSE race message after only two attempts); a remote that genuinely races
+ * every pass surfaces a friendly "try again" rather than looping forever. The
+ * snapshot-first guarantee holds on every path (the work is saved locally
+ * before any network step). Never throws for expected outcomes — everything is
+ * reported through the {@link SyncOutcome} union.
+ */
+export declare function syncProject(options: SyncProjectOptions): Promise<SyncOutcome>;
+/**
+ * Pull-only operation (the History tab's "Pull"): snapshot-if-needed →
+ * fetch → fast-forward or clean merge of the online changes — NEVER a push.
+ *
+ * Same conflict semantics as {@link syncProject}: `abortOnConflict` keeps the
+ * working tree completely untouched and the conflict comes back as
+ * `{ status: "conflict", files }` for the per-file choices dialog. Serialized
+ * on the per-repo lock; one function-scoped object cache, released on return.
+ */
+export declare function pullChanges(options: SyncProjectOptions): Promise<PullOutcome>;
+/**
+ * Push-only operation (the History tab's "Push"): snapshot-if-needed → push.
+ * If the online copy has commits this computer doesn't have (non-fast-forward),
+ * it does NOT auto-merge — the typed `"pull-first"` result tells the host to
+ * show a plain-language "get the latest changes first" message. Serialized on
+ * the per-repo lock; one function-scoped object cache, released on return.
+ */
+export declare function pushChanges(options: SyncProjectOptions): Promise<PushOutcome>;

package/dist/lib/remote-auth/test-access.d.ts

@@ -0,0 +1,47 @@
+import httpNode from "isomorphic-git/http/node";
+import { type HostCredential } from "./token-store.ts";
+/** Why a remote-access probe failed, in machine-readable form. */
+export type RemoteAccessFailureReason = "auth" | "not-found" | "unreachable" | "ssh-unsupported" | "insecure-transport" | "tls" | "unknown";
+export type RemoteAccessResult = {
+    ok: true;
+    defaultBranch?: string;
+    refCount: number;
+} | {
+    ok: false;
+    reason: RemoteAccessFailureReason;
+    message: string;
+};
+export interface TestRemoteAccessOptions {
+    /** The remote URL to probe (HTTPS; SSH is classified, never contacted). */
+    url: string;
+    /** Credential for the remote's host, if one is stored. */
+    credential?: HostCredential;
+    /** Injectable git HTTP transport for tests. Defaults to the node client. */
+    httpClient?: typeof httpNode;
+    /** Probe timeout. The probe resolves `unreachable` when it elapses. */
+    timeoutMs?: number;
+}
+/**
+ * True for any remote URL gutterpress's HTTPS-only transport cannot use:
+ * `ssh://…` and the scp-like `git@host:owner/repo.git` shorthand.
+ */
+export declare function isSshRemoteUrl(url: string): boolean;
+/**
+ * Author-friendly messages per failure reason (no URLs, no tokens — and no
+ * literal scheme tokens like "http://": the desktop's Advanced Setup dialog
+ * redacts anything matching /https?:\/\/\S+/, which would garble the copy).
+ * Exported for the wording guard in test-access.test.ts.
+ */
+export declare const FAILURE_MESSAGES: Record<RemoteAccessFailureReason, string>;
+/** Map a raw transport error to a classified failure. Never echoes the URL. */
+export declare function classifyRemoteAccessError(e: unknown): RemoteAccessResult;
+/**
+ * Probe a remote with a single refs listing (the `git ls-remote` equivalent).
+ *
+ * - Never throws — every outcome is a classified {@link RemoteAccessResult}.
+ * - SSH URLs return `ssh-unsupported` with zero network traffic.
+ * - Credentials embedded in the URL are stripped and used for auth when no
+ *   explicit credential is supplied (ADR 0006 D7) — they never leak onward.
+ * - `defaultBranch` comes from the server's `HEAD` symref when advertised.
+ */
+export declare function testRemoteAccess(options: TestRemoteAccessOptions): Promise<RemoteAccessResult>;

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

@@ -0,0 +1,71 @@
+import type httpNode from "isomorphic-git/http/node";
+type HttpClient = typeof httpNode;
+export declare function pkt(data: string | Buffer): Buffer;
+export declare const FLUSH: Buffer<ArrayBuffer>;
+export declare function parsePktLines(body: Buffer): string[];
+/**
+ * isomorphic-git location options: a worktree repo (`dir`) or a bare repo
+ * (`gitdir`). Bare support exists so the server can serve a real `--bare`
+ * clone (used by the large-repo sync repro scripts).
+ */
+type RepoLoc = {
+    dir: string;
+} | {
+    gitdir: string;
+};
+export declare function createFixtureRepo(dir: string): Promise<{
+    head: string;
+    first: string;
+}>;
+/**
+ * Collect commit+tree+blob oids reachable from `commit`, to `depth` commits.
+ *
+ * `stopCommits` (the client's `have` lines) bounds the walk like a real
+ * upload-pack: commits the client already has are neither read nor included.
+ * `skipTrees` (the root trees of those have-commits) prunes tree recursion so
+ * a fetch of message-only commits on a multi-GB repo packs ONLY the new
+ * commit objects instead of re-walking the whole project tree.
+ */
+export declare function collectOids(repo: RepoLoc, commit: string, depth: number, opts?: {
+    stopCommits?: Set<string>;
+    skipTrees?: Set<string>;
+}): Promise<string[]>;
+export interface GitServer {
+    url: string;
+    /** Authorization headers the server saw, in order. */
+    authHeaders: Array<string | undefined>;
+    close(): Promise<void>;
+}
+export interface GitServerOptions {
+    requireAuth?: {
+        username: string;
+        password: string;
+    };
+    /** Answer every request with 404 (a host with no repo at that path). */
+    notFound?: boolean;
+}
+export declare function startGitServer(repoDir: string, opts?: GitServerOptions): Promise<GitServer>;
+export declare function tempDir(prefix: string): Promise<string>;
+/**
+ * An http client that delivers the git-upload-pack response but ERRORS the
+ * body instead of completing it — the shape a defaultGitHttp idle-timeout trip
+ * takes mid-pack. isomorphic-git 1.38.4 updates refs/remotes/<remote>/* from
+ * the ref advertisement BEFORE the packfile is collected/persisted, so this
+ * reproduces "refs moved, objects never landed" deterministically (the R15
+ * dangling-tracking-ref failure). Shared by the transport and recovery tests.
+ */
+export declare function packDroppingClient(inner: HttpClient): HttpClient;
+/**
+ * Binary-safe pkt-line command parser for a receive-pack request body:
+ * returns the `<old> <new> <ref>` commands and the byte offset where the raw
+ * packfile starts (right after the flush-pkt).
+ */
+export declare function parseReceivePackRequest(body: Buffer): {
+    commands: Array<{
+        oldOid: string;
+        newOid: string;
+        ref: string;
+    }>;
+    packfile: Buffer;
+};
+export {};

package/dist/lib/remote-auth/token-store.d.ts

@@ -0,0 +1,95 @@
+/** An opaque stored credential for one remote host. */
+export interface HostCredential {
+    /** Remote host the credential authenticates against, e.g. "github.com". */
+    host: string;
+    /** How the credential was acquired (drives re-auth UX, not transport). */
+    kind: "github-oauth" | "token";
+    /** The secret token value. NEVER log this. */
+    token: string;
+    /** Login/username associated with the token, when known. */
+    username?: string;
+    /** Optional human label ("GitHub — @octocat"). */
+    label?: string;
+    /** Epoch ms the credential was stored. */
+    createdAt: number;
+}
+/**
+ * Host-keyed credential vault contract (ADR 0006 D3 layer 2). Implementations
+ * are provided by the HOST APP (Electron safeStorage, CLI 0600 file); the lib
+ * only consumes this interface.
+ */
+export interface TokenStore {
+    get(host: string): Promise<HostCredential | null>;
+    set(host: string, credential: HostCredential): Promise<void>;
+    delete(host: string): Promise<void>;
+    /** All stored credentials (used by "connected accounts" UIs). */
+    list(): Promise<HostCredential[]>;
+}
+/** A credential with the token value masked — safe for logs/diagnostics. */
+export declare function redactCredential(cred: HostCredential): Omit<HostCredential, "token"> & {
+    token: string;
+};
+/**
+ * THE canonical credential-store key for a remote host — the ONE derivation
+ * every writer (GitHub device flow, generic connect, embedded-URL migration)
+ * and every reader (diagnose, transport) must share. Historically each site
+ * derived its own key (the device flow hardcoded `github.com`, the URL
+ * migration dropped `:port`, generic connect kept `www.`), so a credential
+ * stored by one flow could be invisible to the lookup of another — the
+ * "connected successfully but never syncable" defect class.
+ *
+ * Accepts a bare hostname ("Git.Example.com"), a host:port pair
+ * ("git.example.com:3000"), any URL on the host, or an scp-like SSH address
+ * ("git@host:owner/repo.git"). Returns `hostname[:port]` lower-cased with any
+ * leading `www.` stripped (so `www.github.com` remotes find the `github.com`
+ * device-flow credential). The port is kept ONLY when explicit and
+ * non-default — `new URL` already drops :443/:80 for https/http. Returns ""
+ * when nothing usable remains.
+ */
+export declare function credentialHostKey(hostOrUrl: string): string;
+/**
+ * Resolve the Gutterpress user config directory (where the CLI token store
+ * lives). There is no pre-existing lib config-dir mechanism to follow (the CLI
+ * config cascade is per-project manifest based), so this establishes the
+ * standard one: `$GUTTERPRESS_CONFIG_DIR` override → `%APPDATA%/gutterpress` on
+ * Windows → `$XDG_CONFIG_HOME/gutterpress` → `~/.config/gutterpress`.
+ */
+export declare function defaultConfigDir(): string;
+/**
+ * The CLI's {@link TokenStore}: a JSON file with `0600` permissions under the
+ * user config dir. Plaintext-at-rest by design (the `gh`/`npm` model) — the
+ * desktop uses an OS-keychain-backed store instead.
+ */
+export declare class FileTokenStore implements TokenStore {
+    readonly filePath: string;
+    private queue;
+    constructor(filePath?: string);
+    private read;
+    private write;
+    private enqueue;
+    get(host: string): Promise<HostCredential | null>;
+    set(host: string, credential: HostCredential): Promise<void>;
+    delete(host: string): Promise<void>;
+    list(): Promise<HostCredential[]>;
+}
+/** Result of {@link extractUrlCredential}. */
+export interface UrlCredentialExtraction {
+    /** The URL with any userinfo (user:token@) stripped. */
+    cleanUrl: string;
+    /** Credential recovered from the URL's userinfo, if any. */
+    credential?: HostCredential;
+}
+/**
+ * Detect a token embedded in a remote URL (`https://user:tok@host/…` — common
+ * in the wild), returning the sanitized URL plus the recovered credential so
+ * callers can migrate it into the {@link TokenStore}. The token value must
+ * never be echoed into logs or diagnostics — only the clean URL is safe to
+ * display. Non-HTTP(S) or unparseable URLs pass through unchanged.
+ */
+export declare function extractUrlCredential(url: string): UrlCredentialExtraction;
+/**
+ * Migrate any credential embedded in `url` into `store` (only when the store
+ * has no existing credential for that host — a stored credential is fresher
+ * than one fossilized in a clone URL) and return the sanitized URL.
+ */
+export declare function migrateUrlCredential(url: string, store: TokenStore): Promise<string>;

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

@@ -0,0 +1,105 @@
+import httpNode from "isomorphic-git/http/node";
+import { type HostCredential, type TokenStore } from "./token-store.ts";
+import type { ConflictFile, GitCache, RemoteTransport } from "./sync-types.ts";
+/**
+ * The git repo directory for a project dir. A project IS its git repo, so this
+ * walks up to the enclosing repo root (opening a subfolder syncs the whole
+ * repo — plain git, no per-book scoping). Anything unclassifiable is itself.
+ */
+export declare function repoDirFor(projectDir: string): Promise<string>;
+/**
+ * True when a stored credential may be transmitted to `url`: over https to
+ * anywhere, or over http ONLY to loopback (a local git daemon or the in-memory
+ * test server). Deep-analysis SECURITY fix: the protocol gates elsewhere accept
+ * http:// too, so without this a repo-scoped account token was sent as cleartext
+ * Basic auth to a remote http host — harvestable by anyone on the path. Loopback
+ * http carries no network exposure, so it stays allowed.
+ */
+export declare function isCredentialTransmissionSafe(url: string): boolean;
+export declare function onAuthFor(credential: HostCredential | undefined): {
+    onAuth?: undefined;
+} | {
+    onAuth: (url: string) => {
+        username: string;
+        password: string;
+    };
+};
+/**
+ * Resolve the project's tracked remote + credential. Throws friendly errors
+ * for the no-remote / SSH cases (the UI should have gated on diagnose, but
+ * the lib must stay safe to call directly).
+ */
+export declare function resolveTransport(dir: string, options: {
+    credential?: HostCredential;
+    tokenStore?: TokenStore;
+}): Promise<RemoteTransport>;
+/**
+ * The failure arms shared verbatim by {@link SyncOutcome}, {@link PullOutcome}
+ * and {@link PushOutcome} — so one classifier serves all three operations.
+ * Decoding delegates to the shared recovery classifier
+ * (classifyTransportFailure): auth_required → "auth", network_unavailable →
+ * "offline", insecure_transport → "error" with its dedicated message (NEVER
+ * "auth" — reconnecting can't fix an http:// address, and the auth recovery
+ * path deletes the stored credential), anything else → the generic "error" arm.
+ */
+export declare function failureOutcome(e: unknown, snapshotId?: string): {
+    status: "auth" | "offline" | "error";
+    message: string;
+    snapshotId?: string;
+};
+export declare function conflictFilesFrom(data: {
+    filepaths: string[];
+    bothModified: string[];
+    deleteByUs: string[];
+    deleteByTheirs: string[];
+}): ConflictFile[];
+/** Friendly setup-problem message for the expected gate errors, else null. */
+export declare function setupErrorMessage(e: unknown): string | null;
+/**
+ * Snapshot-first step shared by syncProject / pullChanges / pushChanges
+ * (ADR 0006 D5): commit any unsaved work in the WHOLE repo BEFORE any network
+ * or merge step, so a forced post-merge checkout can never discard it. The
+ * working-tree check runs lazily at action time on the caller's function-scoped
+ * object cache (released with the operation).
+ */
+export declare function snapshotBeforeAction(args: {
+    projectDir: string;
+    dir: string;
+    message?: string;
+    authorName?: string;
+    authorEmail?: string;
+    cache: GitCache;
+}): Promise<string | undefined>;
+export declare function currentBranchOrThrow(dir: string): Promise<string>;
+/**
+ * Run `fn` (a fetch that moves remote-tracking refs) with a rollback guard
+ * (deep-analysis R15): isomorphic-git updates refs/remotes/<remote>/* from
+ * the ref advertisement BEFORE collecting the packfile, so an abort
+ * mid-transfer (e.g. the defaultGitHttp idle timeout) leaves refs pointing
+ * at oids with no local object. Such a dangling ref poisons the next fetch —
+ * zero `have`s → the server streams the ENTIRE repository (the OOM
+ * fetchRemoteTip's `ref` choice exists to prevent) — and resolving it reports
+ * missing-object "corruption" on a never-corrupt repo.
+ *
+ * `listRefs` names the refs at risk; it runs again after a throw so refs
+ * CREATED by `fn` are covered too. If `fn` throws, every ref that moved to an
+ * oid whose object is MISSING locally is restored to its previous oid (or
+ * deleted if it didn't exist); refs whose objects DID land are kept — the
+ * pack made it. On success no ref is touched. Restoration is best-effort,
+ * per ref, and never masks `fn`'s error.
+ */
+export declare function guardRefs<T>(dir: string, listRefs: () => Promise<string[]>, cache: GitCache, fn: () => Promise<T>): Promise<T>;
+/** Single-ref form of {@link guardRefs} — guards one remote-tracking ref. */
+export declare function guardTrackingRef<T>(dir: string, ref: string, cache: GitCache, fn: () => Promise<T>): Promise<T>;
+/**
+ * Remote-wide form of {@link guardRefs} for a fetch that may move or create
+ * ANY refs/remotes/<remote>/* ref (e.g. `singleBranch: false`).
+ */
+export declare function guardRemoteRefs<T>(dir: string, remote: string, cache: GitCache, fn: () => Promise<T>): Promise<T>;
+/**
+ * Fetch the tracked branch's online tip. Returns `null` when the online
+ * repository has no such branch yet (a freshly created empty repo).
+ */
+export declare function fetchRemoteTip(dir: string, branch: string, transport: RemoteTransport, http: typeof httpNode, cache: GitCache): Promise<string | null>;
+/** First 8 chars of an oid for diagnostic log lines (null-safe). */
+export declare function short(oid: string | null | undefined): string;

package/dist/lib/slug.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared slug helper — turn a human name / URL into a safe, lowercase,
+ * hyphen-separated id usable as a folder or filename stem.
+ *
+ * One implementation, two historical call sites (DRY): the theme manager
+ * (`themes/<id>/`) and project scaffolding (project folder / output filename).
+ * They differed only in the empty-input fallback, so that is the single
+ * parameter — everything else (NFKD normalise, diacritic strip, collapse
+ * non-alphanumerics to single hyphens, trim edge hyphens) is identical.
+ *
+ * Bundle-safe (CLAUDE.md §1/§3): pure string work, no deps.
+ */
+/**
+ * Slugify `name`. When the input contains no usable characters the result is
+ * `fallback` (defaults to `""` — callers that need a placeholder pass one, e.g.
+ * theme ids pass `"theme"`).
+ */
+export declare function slugify(name: string, fallback?: string): string;
+/**
+ * Prettify a slug / filename stem into a display name: `-`/`_` runs become
+ * spaces and the first character is upper-cased ("stat-block" → "Stat block",
+ * "my_cool-theme" → "My cool theme"). The rough inverse of {@link slugify} used
+ * to label themes, snippets and custom templates that carry only a slug id.
+ *
+ * One implementation, several historical call sites (theme manager, snippets,
+ * project templates) — bundle-safe pure string work, no deps.
+ */
+export declare function prettify(slug: string): string;

package/dist/lib/snippets.d.ts

@@ -0,0 +1,39 @@
+/** Folder (relative to the project root) snippets live in. */
+export declare const SNIPPETS_DIR = "snippets";
+/** One snippet's metadata for the picker (no body — read lazily). */
+export interface SnippetEntry {
+    /** Display name (derived from the `.md` filename stem, prettified). */
+    name: string;
+    /** The on-disk filename, e.g. `callout.md`. Stable id for read/delete. */
+    fileName: string;
+    /** Distinct `{{variable}}` names parsed from the body, in first-seen order. */
+    variables: string[];
+}
+/**
+ * Parse the distinct `{{variable}}` placeholder names from a template, in the
+ * order they first appear. Whitespace inside the braces is ignored. Pure.
+ */
+export declare function extractVariables(template: string): string[];
+/**
+ * Replace every `{{name}}` placeholder with `values[name]`. A name with no
+ * provided value becomes the empty string (the caller prompts for values, so an
+ * unanswered field simply collapses). Non-placeholder braces are left intact.
+ * Pure.
+ */
+export declare function substituteVariables(template: string, values: Record<string, string>): string;
+/**
+ * List the project's snippets (newest filesystem order is not guaranteed; sort
+ * for the picker). Returns `[]` when the `snippets/` folder doesn't exist.
+ */
+export declare function listSnippets(projectDir: string): Promise<SnippetEntry[]>;
+/** Read one snippet's raw body. Refuses path traversal. */
+export declare function readSnippet(projectDir: string, fileName: string): Promise<string>;
+/**
+ * Save a snippet body under `snippets/<slug(name)>.md`, creating the folder when
+ * absent. Returns the stored entry (with its filename + parsed variables). The
+ * returned `name` echoes the author-supplied name, while `fileName` is the
+ * slugified storage name.
+ */
+export declare function saveSnippet(projectDir: string, name: string, body: string): Promise<SnippetEntry>;
+/** Delete a snippet by filename. Refuses path traversal. */
+export declare function deleteSnippet(projectDir: string, fileName: string): Promise<void>;