@toon-protocol/git 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,742 @@
+import { c as GitObjectType, P as Publisher, F as FeeRates, b as PublishReceipt } from './publisher-VEIEQHl6.js';
+export { C as COMMENT_KIND, d as GitObject, G as GitObjectUpload, M as MAX_OBJECT_SIZE, R as REPOSITORY_STATE_KIND, S as StatusKind, U as UnsignedEvent, a as UploadReceipt, e as buildComment, f as buildIssue, g as buildPatch, h as buildRepoAnnouncement, i as buildRepoRefs, j as buildStatus, k as createGitBlob, l as createGitCommit, m as createGitTag, n as createGitTree, o as hashGitObject } from './publisher-VEIEQHl6.js';
+import '@toon-protocol/core/nip34';
+
+/**
+ * GitRepoReader — read a local repository via `execFile` git plumbing.
+ *
+ * Real git gives perfect fidelity (packfiles, delta chains, exotic history)
+ * with zero new deps — no isomorphic-git. Everything here is read-only and
+ * injection-safe:
+ *
+ *  - child processes are spawned with `execFile`/`spawn` and argument
+ *    ARRAYS — never a shell, never string interpolation;
+ *  - every caller-supplied revision/range is validated against strict
+ *    regexes that (among other things) reject a leading `-`, so a value
+ *    like `--upload-pack=…` can never be parsed as an option;
+ *  - `--` terminators are appended where git supports them so nothing
+ *    user-supplied can be re-interpreted as a pathspec.
+ *
+ * Push planning/publishing live in follow-up tickets of epic
+ * toon-client#222 — this module only reads.
+ */
+
+/** A single ref from `git for-each-ref` (branches + tags). */
+interface GitRef {
+    /** Full refname, e.g. `refs/heads/main` or `refs/tags/v1.0.0`. */
+    refname: string;
+    /**
+     * SHA the ref points at. For annotated tags this is the TAG object's SHA
+     * (the peeled commit is in {@link peeledSha}); for branches and
+     * lightweight tags it is the commit SHA.
+     */
+    sha: string;
+    /** Type of the referenced object: `commit`, or `tag` for annotated tags. */
+    type: GitObjectType;
+    /** For annotated tags: the peeled (target) object SHA. */
+    peeledSha?: string;
+}
+/** Result of {@link GitRepoReader.listRefs}. */
+interface RepoRefs {
+    /**
+     * Full refname HEAD points at (e.g. `refs/heads/main`), or `undefined`
+     * when HEAD is detached.
+     */
+    head?: string;
+    refs: GitRef[];
+}
+/** One object streamed out of `git cat-file --batch`. */
+interface ReadGitObject {
+    /** Full 40-hex SHA-1. */
+    sha: string;
+    type: GitObjectType;
+    /** Raw object body (content only, no envelope header). May be binary. */
+    body: Buffer;
+}
+/** Result of {@link GitRepoReader.readObjects}. */
+interface ReadObjectsResult {
+    /** Objects found, in input order (minus missing ones). */
+    objects: ReadGitObject[];
+    /** Requested SHAs not present in the repository. */
+    missing: string[];
+}
+/** One object from `rev-list --objects`: SHA plus the path it was reached by. */
+interface ObjectWithPath {
+    /** Full 40-hex SHA-1. */
+    sha: string;
+    /**
+     * Path the object was first reached by (blobs and non-root trees);
+     * `undefined` for commits, root trees, and tag objects.
+     */
+    path?: string;
+}
+/** One object's metadata from `cat-file --batch-check`. */
+interface ObjectStat {
+    sha: string;
+    type: GitObjectType;
+    /** Object body size in bytes (content only, no envelope header). */
+    size: number;
+}
+/** Result of {@link GitRepoReader.statObjects}. */
+interface StatObjectsResult {
+    /** Stats found, in input order (minus missing ones). */
+    objects: ObjectStat[];
+    /** Requested SHAs not present in the repository. */
+    missing: string[];
+}
+/** Error from a git child process, carrying exit code and stderr. */
+declare class GitError extends Error {
+    /** Process exit code (undefined when the process failed to spawn). */
+    readonly exitCode: number | undefined;
+    /** Captured stderr, trimmed. */
+    readonly stderr: string;
+    constructor(message: string, 
+    /** Process exit code (undefined when the process failed to spawn). */
+    exitCode: number | undefined, 
+    /** Captured stderr, trimmed. */
+    stderr: string);
+}
+/**
+ * Read-only view of a local git repository via git plumbing commands.
+ *
+ * All methods throw {@link GitError} when the underlying git process fails
+ * unexpectedly, and plain `Error` when a caller-supplied argument fails
+ * validation (before any process is spawned).
+ */
+declare class GitRepoReader {
+    /** Absolute or relative path to the repository worktree (or .git dir). */
+    readonly repoPath: string;
+    constructor(
+    /** Absolute or relative path to the repository worktree (or .git dir). */
+    repoPath: string);
+    /** Run git with argument-array safety; resolves stdout as UTF-8. */
+    private git;
+    /**
+     * List all branches and tags plus the symbolic HEAD.
+     *
+     * Annotated tags report the tag object's SHA/type with the peeled target
+     * in `peeledSha`. A detached HEAD is tolerated (`head` is `undefined`).
+     */
+    listRefs(): Promise<RepoRefs>;
+    /**
+     * SHAs of every object reachable from `want` but not from `have`
+     * (`git rev-list --objects <want…> --not <have…>`), i.e. the push delta.
+     *
+     * Haves that don't exist locally (e.g. remote tips we never fetched) are
+     * filtered out first via one `cat-file --batch-check` pass — rev-list
+     * would otherwise die on them.
+     */
+    objectsBetween(want: string[], have: string[]): Promise<string[]>;
+    /**
+     * Like {@link objectsBetween} but keeps the path each object was reached
+     * by (`rev-list --objects` emits `<sha> <path>` for blobs and non-root
+     * trees) — used by push planning to report actionable oversize errors.
+     */
+    objectsBetweenWithPaths(want: string[], have: string[]): Promise<ObjectWithPath[]>;
+    /** Run git feeding `input` on stdin; resolves collected stdout bytes. */
+    private runWithStdin;
+    /** Of the given revisions, keep only those resolvable locally. */
+    private filterExisting;
+    /** One `cat-file --batch-check` pass; returns names reported missing. */
+    private batchCheck;
+    /**
+     * Object metadata (type + body size) for a batch of SHAs via one
+     * `cat-file --batch-check` pass — no bodies are read. Missing objects are
+     * reported, not thrown.
+     */
+    statObjects(shas: string[]): Promise<StatObjectsResult>;
+    /**
+     * Read raw object bodies via a single streaming `git cat-file --batch`
+     * child process. Bodies may be binary and are parsed size-driven across
+     * chunk boundaries. Missing objects are reported, not thrown.
+     */
+    readObjects(shas: string[]): Promise<ReadObjectsResult>;
+    /**
+     * `git merge-base --is-ancestor <a> <b>` — true when `a` is an ancestor
+     * of `b` (fast-forward check / force detection). Exit codes other than
+     * 0/1 (e.g. unknown revisions) throw.
+     */
+    isAncestor(a: string, b: string): Promise<boolean>;
+    /**
+     * `git format-patch --stdout <range>` — the full mbox-formatted patch
+     * series text (empty string when the range selects no commits).
+     */
+    formatPatch(range: string): Promise<string>;
+    /**
+     * Parent SHAs for a batch of commit SHAs via one
+     * `git rev-list --no-walk=unsorted --parents` pass. Root commits map to an
+     * empty array. Used to derive the kind:1617 `commit`/`parent-commit` tag
+     * pairs for exactly the commits a format-patch series carries.
+     */
+    commitParents(shas: string[]): Promise<Map<string, string[]>>;
+    /**
+     * Resolve a ref/revision to a full SHA via `git rev-parse --verify`.
+     * Throws {@link GitError} when the name doesn't resolve.
+     */
+    resolveRef(name: string): Promise<string>;
+}
+
+/**
+ * Remote repository state reader — the "what does the remote have?" half of
+ * `rig push` (epic #222, ticket #225).
+ *
+ * Queries relay(s) over NIP-01 WebSocket for the repository's NIP-34 state:
+ *   - kind:30618 (repository state): `r` tags → ref map, `HEAD` symref,
+ *     `arweave` tags → git SHA → Arweave txId hints.
+ *   - kind:30617 (repository announcement): presence = the repo exists on
+ *     TOON (first-push detection) + name/description/relays metadata.
+ *
+ * Both kinds are NIP-33 parameterized-replaceable: per relay only the latest
+ * event per (kind, author, d) survives, but we still pick the newest across
+ * relays (highest created_at, ties broken by lowest id per NIP-01).
+ *
+ * SHAs missing from the `arweave` tag map can be resolved via the shared
+ * Arweave GraphQL Git-SHA resolver (@toon-protocol/arweave — the same module
+ * the rig SPA uses) through {@link RemoteState.resolveMissing}.
+ *
+ * Relay payload encodings (mirrors rig's `web/relay-client.ts` decode logic):
+ * EVENT payloads arrive as an inline JSON object (standard NIP-01), as a
+ * double-JSON-encoded string (devnet relay quirk: a JSON string containing
+ * the event JSON), or as a TOON-encoded string. All three are tolerated.
+ */
+/** A signed Nostr event as seen on a relay (read side). */
+interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+/**
+ * Minimal structural WebSocket type — satisfied by the WHATWG WebSocket
+ * global (Node >= 22 / undici, browsers) and by the `ws` package.
+ */
+interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: string, listener: (event: never) => void): void;
+}
+/** Factory for WebSocket connections (injectable for tests / `ws` fallback). */
+type WebSocketFactory = (url: string) => WebSocketLike;
+interface FetchRemoteStateOptions {
+    /**
+     * Relay WebSocket URLs to query. Plural from day one (forward-compat with
+     * multi-relay routing); size 1 is typical today. Results are merged and the
+     * newest replaceable event across all relays wins.
+     */
+    relayUrls: string[];
+    /** Repository owner's pubkey (hex) — the author of 30617/30618. */
+    ownerPubkey: string;
+    /** Repository identifier (NIP-34 `d` tag). */
+    repoId: string;
+    /** Per-relay timeout in milliseconds (default 10000). On timeout the relay contributes whatever it sent so far. */
+    timeoutMs?: number;
+    /**
+     * Git-SHA → Arweave txId resolver used by {@link RemoteState.resolveMissing}.
+     * Defaults to the shared GraphQL resolver from @toon-protocol/arweave;
+     * injectable for tests.
+     */
+    resolveSha?: (sha: string, repo: string) => Promise<string | null>;
+    /** WebSocket constructor override (defaults to the global WebSocket). */
+    webSocketFactory?: WebSocketFactory;
+}
+/** Remote repository state assembled from relay events. */
+interface RemoteState {
+    /** True when a kind:30617 announcement exists (false ⇒ first push). */
+    announced: boolean;
+    /** Ref map from the latest kind:30618: refname → commit SHA. */
+    refs: Map<string, string>;
+    /** HEAD symref target (e.g. `refs/heads/main`), or null if unset. */
+    headSymref: string | null;
+    /** Git SHA → Arweave txId hints from the latest kind:30618 `arweave` tags. */
+    shaToTxId: Map<string, string>;
+    /** The latest kind:30618 event, or null if the repo has no state yet. */
+    refsEvent: NostrEvent | null;
+    /** The latest kind:30617 event, or null if the repo is unannounced. */
+    announceEvent: NostrEvent | null;
+    /** Repository name from the announcement `name` tag. */
+    name: string | null;
+    /** Announcement `description` tag (falls back to event content). */
+    description: string | null;
+    /** Relay URLs advertised in the announcement `relays` tag(s). */
+    relays: string[];
+    /**
+     * Resolve SHAs to Arweave txIds: served from the `arweave` tag map when
+     * present, otherwise via the GraphQL Git-SHA resolver. SHAs that resolve
+     * nowhere are omitted from the returned map.
+     */
+    resolveMissing(shas: string[]): Promise<Map<string, string>>;
+}
+/**
+ * Fetch the remote repository state from the relay(s).
+ *
+ * Sends one REQ per relay for kind:30617 + kind:30618 with
+ * `authors=[ownerPubkey]`, `#d=[repoId]`, collects until EOSE (or timeout),
+ * and reduces to the latest replaceable event per kind.
+ *
+ * Resolves as long as at least one relay answers; throws only when every
+ * relay fails. Events from other authors / repos are ignored (defense
+ * against misbehaving relays that over-return).
+ */
+declare function fetchRemoteState(options: FetchRemoteStateOptions): Promise<RemoteState>;
+
+/**
+ * Push planner/executor — the core of `rig push` (epic #222, ticket #226).
+ *
+ * `planPush` is network-free (relay/Arweave-wise — it only runs local git
+ * plumbing through GitRepoReader plus one injectable async resolver step):
+ * it classifies every ref update, computes the object delta against what the
+ * remote already stores, hard-errors on oversize objects, and prices the
+ * push. The returned {@link PushPlan} carries everything a confirm UI needs.
+ *
+ * `executePush` spends money: it uploads the planned objects through a
+ * {@link Publisher} (ref-tip objects last, so a crashed push never leads to
+ * a state where a discoverable tip's history is missing), then publishes ONE
+ * cumulative kind:30618 whose `arweave` tags are the MERGE of the remote's
+ * existing sha→txId map and the new uploads — kind:30618 is NIP-33
+ * replaceable, so dropping prior tags would orphan earlier hints — and whose
+ * `r` tags are the full new ref state. On a first push it publishes the
+ * kind:30617 announcement before the refs event.
+ *
+ * Resume safety: uploads are content-addressed (Git-SHA-tagged), so re-running
+ * `executePush` after a crash is safe — it consults the merged
+ * remote + planned sha→txId map before paying for any upload, and a re-plan
+ * with fresh remote state (whose `resolveMissing` finds the already-uploaded
+ * objects via GraphQL) skips them entirely.
+ */
+
+/** A ref update rejected because it is not a fast-forward. */
+interface RejectedRefUpdate {
+    refname: string;
+    localSha: string;
+    remoteSha: string;
+}
+/** Thrown by {@link planPush} when a non-fast-forward update lacks `force`. */
+declare class NonFastForwardError extends Error {
+    /** The refs that would need `--force` to update. */
+    readonly refs: RejectedRefUpdate[];
+    constructor(
+    /** The refs that would need `--force` to update. */
+    refs: RejectedRefUpdate[]);
+}
+/** One object exceeding {@link MAX_OBJECT_SIZE}. */
+interface OversizeObject {
+    sha: string;
+    type: GitObjectType;
+    /** Body size in bytes. */
+    size: number;
+    /** Path the object was reached by (blobs / non-root trees), if known. */
+    path?: string;
+}
+/**
+ * Thrown by {@link planPush} when any object in the delta exceeds the 95KB
+ * upload limit (hard error in v1 — the paid blob path is a follow-up spike).
+ */
+declare class OversizeObjectsError extends Error {
+    /** The offending objects with paths and sizes. */
+    readonly objects: OversizeObject[];
+    constructor(
+    /** The offending objects with paths and sizes. */
+    objects: OversizeObject[]);
+}
+/** How a ref moves relative to the remote. */
+type RefUpdateKind = 
+/** Ref does not exist on the remote yet. */
+'new'
+/** Remote tip is an ancestor of the local tip. */
+ | 'fast-forward'
+/** Non-fast-forward, allowed because `force` was set. */
+ | 'forced'
+/** Local and remote tips already match — nothing to push. */
+ | 'up-to-date';
+/** One planned ref update (deletions are out of scope in v1). */
+interface RefUpdate {
+    /** Full refname, e.g. `refs/heads/main`. */
+    refname: string;
+    /** Local tip SHA (tag object SHA for annotated tags). */
+    localSha: string;
+    /** Remote tip SHA, or null when the ref is new. */
+    remoteSha: string | null;
+    kind: RefUpdateKind;
+}
+/** One object scheduled for upload. */
+interface PlannedObject {
+    sha: string;
+    type: GitObjectType;
+    /** Body size in bytes (what the upload fee is charged on). */
+    size: number;
+    /** Path the object was reached by, if any (blobs / non-root trees). */
+    path?: string;
+    /** True when this SHA is the tip of a planned ref update (uploaded last). */
+    isRefTip: boolean;
+}
+/** Pre-push fee estimate — render this in the confirm table. */
+interface PushFeeEstimate {
+    /** Number of objects to upload. */
+    objectCount: number;
+    /** Total bytes across all planned object bodies. */
+    totalObjectBytes: number;
+    /** Σ size × uploadFeePerByte (smallest asset unit). */
+    uploadFee: bigint;
+    /** Number of events to publish (refs event + announcement on first push). */
+    eventCount: number;
+    /** eventCount × eventFee (smallest asset unit). */
+    eventFees: bigint;
+    /** uploadFee + eventFees. */
+    totalFee: bigint;
+}
+/** Everything `executePush` (and a confirm UI) needs. */
+interface PushPlan {
+    repoId: string;
+    /** Every considered ref with its classification (incl. up-to-date). */
+    refUpdates: RefUpdate[];
+    /**
+     * Full new ref state to publish as `r` tags: the remote's refs overlaid
+     * with the planned updates (refs not being pushed are preserved — v1
+     * never deletes). Ordered with the HEAD target first, which is what
+     * `buildRepoRefs` derives the HEAD symref tag from.
+     */
+    newRefs: Record<string, string>;
+    /** HEAD symref target for the new state (first key of {@link newRefs}). */
+    headSymref: string | null;
+    /**
+     * Objects to upload, dependency-safe order: ref-tip objects last so a
+     * crashed push never uploads a tip whose history is missing.
+     */
+    objects: PlannedObject[];
+    /**
+     * sha→txId hints known WITHOUT uploading: the remote's `arweave` tags
+     * plus anything `resolveMissing` found. Merged into the published
+     * kind:30618 so prior hints are never dropped.
+     */
+    knownShaToTxId: Map<string, string>;
+    /** True when no kind:30617 exists yet — executePush announces first. */
+    announceNeeded: boolean;
+    /** Announcement metadata used when {@link announceNeeded}. */
+    announcement: {
+        name: string;
+        description: string;
+    };
+    estimate: PushFeeEstimate;
+}
+interface PlanPushOptions {
+    repoReader: GitRepoReader;
+    remoteState: RemoteState;
+    /** Fee rates from `Publisher.getFeeRates()`. */
+    feeRates: FeeRates;
+    /** Repository identifier (NIP-34 `d` tag). */
+    repoId: string;
+    /**
+     * Full refnames to push (e.g. `['refs/heads/main']`). Defaults to every
+     * local branch and tag. Refs that don't exist locally are an error
+     * (deletions are out of scope in v1).
+     */
+    refs?: string[];
+    /** Allow non-fast-forward updates (default false → hard error). */
+    force?: boolean;
+    /** Repo name/description for the first-push announcement. */
+    announcement?: {
+        name?: string;
+        description?: string;
+    };
+    /**
+     * Async resolver for SHAs the remote's `arweave` tags don't cover —
+     * consulted before deciding to re-upload. Defaults to
+     * `remoteState.resolveMissing` (GraphQL fallback); injectable so the
+     * planner core stays testable without network.
+     */
+    resolveMissing?: (shas: string[]) => Promise<Map<string, string>>;
+}
+/**
+ * Classify ref updates, compute the object delta, enforce the size limit,
+ * and price the push. Throws {@link NonFastForwardError} /
+ * {@link OversizeObjectsError} (both carry structured data for UIs).
+ */
+declare function planPush(options: PlanPushOptions): Promise<PushPlan>;
+/** Result of one object-upload step. */
+interface UploadStepResult {
+    sha: string;
+    txId: string;
+    /** 0n when skipped (already uploaded — content-addressed resume). */
+    feePaid: bigint;
+    /** True when the object was already on Arweave and nothing was paid. */
+    skipped: boolean;
+}
+/** Result of the whole push. */
+interface PushResult {
+    /** Per-object results, in plan order. */
+    uploads: UploadStepResult[];
+    /** kind:30617 receipt, or null when the repo was already announced. */
+    announceReceipt: PublishReceipt | null;
+    /** kind:30618 (cumulative refs + arweave map) receipt. */
+    refsReceipt: PublishReceipt;
+    /**
+     * The full sha→txId map published in the refs event: remote hints +
+     * resolver finds + this push's uploads.
+     */
+    arweaveMap: Map<string, string>;
+    /** Total fees actually paid (uploads + events), smallest asset unit. */
+    totalFeePaid: bigint;
+}
+interface ExecutePushOptions {
+    plan: PushPlan;
+    publisher: Publisher;
+    /**
+     * Remote state — pass a FRESH fetch when resuming after a crash so its
+     * `shaToTxId` (and `announced`) reflect what the previous attempt already
+     * paid for.
+     */
+    remoteState: RemoteState;
+    repoReader: GitRepoReader;
+    /** Relay URLs to publish events to (plural from day one; size 1 today). */
+    relayUrls: string[];
+}
+/**
+ * Execute a {@link PushPlan}: upload objects (ref tips last), then publish
+ * the kind:30617 announcement (first push only) and ONE cumulative
+ * kind:30618 whose `arweave` tags merge every known sha→txId hint with the
+ * new uploads and whose `r` tags carry the full new ref state.
+ *
+ * Safe to re-run after a crash: SHAs already present in the merged
+ * remote + plan map are skipped without paying.
+ */
+declare function executePush(options: ExecutePushOptions): Promise<PushResult>;
+
+/**
+ * Wire shapes of the toon-clientd `/git/*` control routes (epic #222).
+ *
+ * These are the JSON request/response types the daemon serves (bigints as
+ * decimal strings, Maps as plain records) — defined HERE, in the dependency
+ * root, so both sides of the route can share them: the `rig` CLI (#229)
+ * consumes them as a plain-fetch client, and `@toon-protocol/client-mcp`
+ * (which depends on this package for the planner — the reverse import would
+ * be circular) can adopt them for its `control-api.ts` declarations. TYPES
+ * ONLY plus two pure serializers; no transport code lives here.
+ *
+ * Keep in byte-for-byte sync with
+ * `packages/client-mcp/src/control-api.ts` (`Git*` shapes) and
+ * `packages/client-mcp/src/daemon/routes.ts` (error envelopes: 409
+ * `non_fast_forward` carries `refs`, 413 `oversize_objects` carries
+ * `objects`, 503 `bootstrapping` / 402 `insufficient_gas` are retryable).
+ */
+
+/** One planned ref update (JSON-safe as-is). */
+type GitRefUpdate = RefUpdate;
+/** One object scheduled for upload (JSON-safe as-is). */
+type GitPlannedObject = PlannedObject;
+/**
+ * `POST /git/estimate` — plan a push (local git plumbing + remote-state read)
+ * and price it WITHOUT paying anything. The same body (plus `confirm`) drives
+ * `POST /git/push`.
+ */
+interface GitEstimateRequest {
+    /** Path to the local git repository (worktree or .git dir). Must exist. */
+    repoPath: string;
+    /** Repository identifier (NIP-34 `d` tag). The daemon identity is the owner. */
+    repoId: string;
+    /**
+     * Full refnames to push (e.g. `["refs/heads/main"]`). Default: every local
+     * branch and tag.
+     */
+    refspecs?: string[];
+    /** Allow non-fast-forward updates (default false → 409 `non_fast_forward`). */
+    force?: boolean;
+    /**
+     * Relay URLs to read remote state from and publish to. Plural from day one
+     * (forward-compat); defaults to the daemon's config-seeded relay.
+     */
+    relayUrls?: string[];
+    /** Repo name/description for the first-push kind:30617 announcement. */
+    announcement?: {
+        name?: string;
+        description?: string;
+    };
+}
+/** Pre-push fee table (all fees in base/micro units, decimal strings). */
+interface GitFeeEstimate {
+    objectCount: number;
+    totalObjectBytes: number;
+    /** Σ size × uploadFeePerByte. */
+    uploadFee: string;
+    /** Events to publish (refs event + announcement on first push). */
+    eventCount: number;
+    /** eventCount × per-event fee. */
+    eventFees: string;
+    /** uploadFee + eventFees. */
+    totalFee: string;
+}
+/** Serialized `PushPlan` — everything a confirm UI needs. */
+interface GitEstimateResponse {
+    repoId: string;
+    refUpdates: GitRefUpdate[];
+    /** Full new ref state to publish (HEAD target first). */
+    newRefs: Record<string, string>;
+    headSymref: string | null;
+    objects: GitPlannedObject[];
+    /** sha→txId hints known WITHOUT uploading (remote tags + resolver finds). */
+    knownShaToTxId: Record<string, string>;
+    /** True when no kind:30617 exists yet — the push announces first. */
+    announceNeeded: boolean;
+    announcement: {
+        name: string;
+        description: string;
+    };
+    estimate: GitFeeEstimate;
+}
+/**
+ * `POST /git/push` — plan + execute: upload the delta to Arweave and publish
+ * the cumulative kind:30618 (+ kind:30617 on first push). PERMANENT + PAID.
+ */
+interface GitPushRequest extends GitEstimateRequest {
+    /** Must be literally `true` — a push spends channel funds irreversibly. */
+    confirm: boolean;
+}
+/** One object-upload step result. */
+interface GitUploadStep {
+    sha: string;
+    txId: string;
+    /** '0' when skipped (already on Arweave — content-addressed resume). */
+    feePaid: string;
+    skipped: boolean;
+}
+/** Receipt for one published event. */
+interface GitPublishReceipt {
+    eventId: string;
+    feePaid: string;
+}
+/** Serialized `PushResult` — per-step receipts + total fees actually paid. */
+interface GitPushResponse {
+    repoId: string;
+    refUpdates: GitRefUpdate[];
+    /** Per-object results, in plan order. */
+    uploads: GitUploadStep[];
+    /** kind:30617 receipt, or null when the repo was already announced. */
+    announceReceipt: GitPublishReceipt | null;
+    /** kind:30618 (cumulative refs + arweave map) receipt. */
+    refsReceipt: GitPublishReceipt;
+    /** Full sha→txId map published in the refs event. */
+    arweaveMap: Record<string, string>;
+    /** Total fees actually paid (uploads + events), base units, decimal. */
+    totalFeePaid: string;
+    /** The pre-push estimate the push ran under (compare against totalFeePaid). */
+    estimate: GitFeeEstimate;
+}
+/** NIP-34 repository address: the owner+id pair behind `a` tags. */
+interface GitRepoAddr {
+    /** Repository owner's Nostr pubkey (64-char hex) — author of kind:30617/30618. */
+    ownerPubkey: string;
+    /** Repository identifier (NIP-34 `d` tag). */
+    repoId: string;
+}
+/** `POST /git/issue` — publish a kind:1621 issue against a repo. PAID. */
+interface GitIssueRequest {
+    repoAddr: GitRepoAddr;
+    /** Issue title (`subject` tag). */
+    title: string;
+    /** Issue body (Markdown content). */
+    body: string;
+    /** Labels (`t` tags). */
+    labels?: string[];
+}
+/** `POST /git/comment` — publish a kind:1622 comment on an issue/patch. PAID. */
+interface GitCommentRequest {
+    repoAddr: GitRepoAddr;
+    /** Event id of the issue or patch being commented on. */
+    rootEventId: string;
+    /** Comment body (Markdown content). */
+    body: string;
+    /**
+     * Pubkey of the TARGET event's author (NIP-34 `p` threading tag — not the
+     * comment author). Defaults to the repo owner.
+     */
+    parentAuthorPubkey?: string;
+    /** `e`-tag marker (default 'root': commenting directly on the issue/patch). */
+    marker?: 'root' | 'reply';
+}
+/**
+ * `POST /git/patch` — publish a kind:1617 patch. Supply EXACTLY ONE of
+ * `patchText` (literal `git format-patch` output) or `repoPath`+`range`
+ * (the daemon runs `git format-patch --stdout <range>` locally). PAID.
+ */
+interface GitPatchRequest {
+    repoAddr: GitRepoAddr;
+    /** Patch/PR title (`subject` tag). */
+    title: string;
+    /** Literal patch text. Mutually exclusive with `repoPath`+`range`. */
+    patchText?: string;
+    /** Local repository to run format-patch in. Requires `range`. */
+    repoPath?: string;
+    /** Revision range for format-patch (`<rev>`, `<rev>..<rev>`, `<rev>...<rev>`). */
+    range?: string;
+    /** Commit/parent pairs for `commit`/`parent-commit` tags. */
+    commits?: {
+        sha: string;
+        parentSha: string;
+    }[];
+    /** Branch name for the `t` tag. */
+    branch?: string;
+}
+type GitStatusValue = 'open' | 'applied' | 'closed' | 'draft';
+/** `POST /git/status` — publish a kind:1630-1633 status event. PAID. */
+interface GitStatusRequest {
+    repoAddr: GitRepoAddr;
+    /** Event id of the issue/patch whose status is being set. */
+    targetEventId: string;
+    /** open → 1630, applied → 1631, closed → 1632, draft → 1633. */
+    status: GitStatusValue;
+    /** Pubkey of the target event's author (`p` tag), when known. */
+    targetPubkey?: string;
+}
+/**
+ * Response of the single-event git publishes (issue/comment/patch/status):
+ * a publish receipt plus the NIP-34 kind that was published. Daemon
+ * responses extend the full `POST /publish` receipt, so the channel fields
+ * (`channelId`/`nonce`/…) are present there; they are optional here because
+ * the CLI's standalone path publishes through the embedded client and has
+ * no channel wire shape to report.
+ */
+interface GitEventResponse {
+    /** Event ID as accepted by the relay. */
+    eventId: string;
+    /** Fee actually paid for this publish, base units, decimal string. */
+    feePaid: string;
+    /** The NIP-34 kind that was published. */
+    kind: number;
+    /** Channel the claim was signed against (daemon responses). */
+    channelId?: string;
+    /** Channel nonce after this publish (daemon responses). */
+    nonce?: number;
+    /** FULFILL response data (base64), when the backend returned any. */
+    data?: string;
+    /** Spendable channel balance after this write, when known. */
+    channelBalanceAfter?: string;
+}
+/**
+ * Uniform error envelope of non-2xx control-route responses. Structured
+ * errors put extra fields at the top level: `non_fast_forward` (409) adds
+ * `refs`, `oversize_objects` (413) adds `objects`.
+ */
+interface GitErrorEnvelope {
+    error: string;
+    detail?: string;
+    /** True when the caller should retry (e.g. daemon still bootstrapping). */
+    retryable?: boolean;
+    [extra: string]: unknown;
+}
+/** Serialize a plan's fee estimate onto the wire (bigints → strings). */
+declare function serializeFeeEstimate(plan: PushPlan): GitFeeEstimate;
+/** Serialize a PushPlan onto the wire (bigints → strings, Maps → records). */
+declare function serializePushPlan(plan: PushPlan): GitEstimateResponse;
+/**
+ * Serialize a standalone {@link PublishReceipt} into the wire shape the
+ * daemon's single-event `/git/*` routes answer with, so `--json` consumers
+ * see one `GitEventResponse` shape regardless of publisher mode.
+ */
+declare function serializeEventReceipt(kind: number, receipt: PublishReceipt): GitEventResponse;
+/** Serialize a PushResult onto the wire (bigints → strings, Maps → records). */
+declare function serializePushResult(plan: PushPlan, result: PushResult): GitPushResponse;
+
+export { type ExecutePushOptions, FeeRates, type FetchRemoteStateOptions, type GitCommentRequest, GitError, type GitErrorEnvelope, type GitEstimateRequest, type GitEstimateResponse, type GitEventResponse, type GitFeeEstimate, type GitIssueRequest, GitObjectType, type GitPatchRequest, type GitPlannedObject, type GitPublishReceipt, type GitPushRequest, type GitPushResponse, type GitRef, type GitRefUpdate, type GitRepoAddr, GitRepoReader, type GitStatusRequest, type GitStatusValue, type GitUploadStep, NonFastForwardError, type NostrEvent, type ObjectStat, type ObjectWithPath, type OversizeObject, OversizeObjectsError, type PlanPushOptions, type PlannedObject, PublishReceipt, Publisher, type PushFeeEstimate, type PushPlan, type PushResult, type ReadGitObject, type ReadObjectsResult, type RefUpdate, type RefUpdateKind, type RejectedRefUpdate, type RemoteState, type RepoRefs, type StatObjectsResult, type UploadStepResult, type WebSocketFactory, type WebSocketLike, executePush, fetchRemoteState, planPush, serializeEventReceipt, serializeFeeEstimate, serializePushPlan, serializePushResult };