@toon-protocol/rig 2.0.1 → 2.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { c as GitObjectType, P as Publisher, F as FeeRates, b as PublishReceipt } from './publisher-CClD9OIZ.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-CClD9OIZ.js';
+import { c as GitObjectType, P as Publisher, F as FeeRates, b as PublishReceipt } from './publisher-CrwaNQrK.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-CrwaNQrK.js';
 import '@toon-protocol/core/nip34';
 
 /**
@@ -209,6 +209,18 @@ interface NostrEvent {
     content: string;
     sig: string;
 }
+/** NIP-01 subscription filter (only the fields rig's readers send). */
+interface NostrFilter {
+    ids?: string[];
+    kinds?: number[];
+    authors?: string[];
+    '#d'?: string[];
+    /** Repo address tag filter, e.g. `30617:<owner>:<repoId>` (#278 tracker). */
+    '#a'?: string[];
+    /** Event-reference tag filter (#278 tracker: statuses + comments). */
+    '#e'?: string[];
+    limit?: number;
+}
 /**
  * Minimal structural WebSocket type — satisfied by the WHATWG WebSocket
  * global (Node >= 22 / undici, browsers) and by the `ws` package.
@@ -270,6 +282,12 @@ interface RemoteState {
      */
     resolveMissing(shas: string[]): Promise<Map<string, string>>;
 }
+/**
+ * Query one relay: send a REQ, collect EVENTs until EOSE, then CLOSE.
+ * Mirrors rig's `queryRelay` (partial results on timeout / early close).
+ * Exported for reuse by the network-bootstrap discovery (kind:10032).
+ */
+declare function queryRelay(relayUrl: string, filter: NostrFilter, timeoutMs: number, webSocketFactory: WebSocketFactory): Promise<NostrEvent[]>;
 /**
  * Fetch the remote repository state from the relay(s).
  *
@@ -283,6 +301,251 @@ interface RemoteState {
  */
 declare function fetchRemoteState(options: FetchRemoteStateOptions): Promise<RemoteState>;
 
+/**
+ * The Git-from-TOON READ pipeline core (#278): download git object bodies
+ * from Arweave gateways, verify them against their SHA-1, and walk the
+ * object graph to prove a ref closure is complete.
+ *
+ * This is the CLI counterpart of rig-web's proven browser read path
+ * (`web/arweave-client.ts` + `web/git-objects.ts` + the commit walker) — the
+ * logic is mirrored, not imported, because the SPA package is not a library.
+ *
+ * Everything here is FREE (reads only: Arweave gateway GETs + the GraphQL
+ * Git-SHA resolver) and pure of git — materializing objects into a real
+ * repository lives in ./materialize.ts.
+ *
+ * INTEGRITY IS NON-NEGOTIABLE: an Arweave upload stores the object BODY
+ * (content after the envelope NUL). Re-wrapping the body as each of the four
+ * git object types and comparing the envelope SHA-1 against the expected SHA
+ * both AUTHENTICATES the bytes and DISCOVERS the object's type in one step —
+ * a body that matches under no type is rejected as corrupt/tampered, never
+ * written.
+ */
+
+/** A downloaded git object: SHA-verified body + the type that verified it. */
+interface FetchedObject {
+    /** Full 40-hex SHA-1 (verified against the body). */
+    sha: string;
+    type: GitObjectType;
+    /** Raw object body (content only, no envelope header). May be binary. */
+    body: Buffer;
+}
+/** WHATWG-fetch seam (injectable for tests). */
+type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+interface GatewayFetchOptions {
+    /** Ordered gateway base URLs (default: the shared preference list). */
+    gateways?: readonly string[];
+    /** fetch implementation (default: global fetch). */
+    fetchFn?: FetchLike;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+interface DownloadOptions extends GatewayFetchOptions {
+    /** Maximum concurrent gateway downloads (default {@link DEFAULT_CONCURRENCY}). */
+    concurrency?: number;
+    /** Progress callback, called once per finished object. */
+    onObject?: (done: number, total: number) => void;
+}
+/** Result of {@link downloadGitObjects}. */
+interface DownloadResult {
+    /** SHA → verified object, for every SHA that could be downloaded. */
+    objects: Map<string, FetchedObject>;
+    /** SHAs whose txId 404'd/errored on EVERY gateway (propagation lag). */
+    unavailable: {
+        sha: string;
+        txId: string;
+    }[];
+}
+/** Default parallel-download cap. */
+declare const DEFAULT_CONCURRENCY = 8;
+/**
+ * A downloaded body did not hash to its expected SHA under ANY git object
+ * type — corrupt or tampered content. The clone/fetch pipelines treat this
+ * as a hard failure: nothing is written.
+ */
+declare class ObjectIntegrityError extends Error {
+    /** The objects that failed verification. */
+    readonly objects: {
+        sha: string;
+        txId: string;
+    }[];
+    constructor(
+    /** The objects that failed verification. */
+    objects: {
+        sha: string;
+        txId: string;
+    }[]);
+}
+/**
+ * Verify a downloaded body against its expected SHA-1 by trying the four git
+ * envelope types. Returns the verified object, or null when no type matches
+ * (corrupt/tampered bytes).
+ */
+declare function verifyObjectBody(expectedSha: string, bytes: Uint8Array): FetchedObject | null;
+/**
+ * Fetch raw bytes for an Arweave tx id, trying each gateway in preference
+ * order. Returns null when every gateway fails (404 / error / timeout).
+ */
+declare function fetchTxBytes(txId: string, options?: GatewayFetchOptions): Promise<Uint8Array | null>;
+/**
+ * Download + verify a batch of git objects (sha → Arweave txId) with a
+ * concurrency cap and per-gateway fallback.
+ *
+ * Objects that 404 on every gateway are reported in `unavailable` (Arweave
+ * propagation lag — the caller decides whether that is fatal). Objects whose
+ * bytes fail SHA-1 verification throw {@link ObjectIntegrityError}: corrupt
+ * content is NEVER returned.
+ */
+declare function downloadGitObjects(entries: Iterable<[sha: string, txId: string]>, options?: DownloadOptions): Promise<DownloadResult>;
+/**
+ * SHAs an object references inside the SAME repository:
+ *   - commit → its tree + parents
+ *   - tree   → entry SHAs, EXCEPT gitlinks (mode 160000: submodule commits
+ *              live in another repository and are never present — git fsck
+ *              skips them too)
+ *   - tag    → the tagged object
+ *   - blob   → nothing
+ */
+declare function referencedShas(object: FetchedObject): string[];
+/** Result of {@link walkClosure}. */
+interface ClosureResult {
+    /** Every SHA reachable from the tips that lives in `objects`. */
+    reachable: Set<string>;
+    /** Reachable SHAs found NEITHER in `objects` nor in `presentLocally`. */
+    missing: string[];
+}
+/**
+ * Walk the object graph from the ref tips over the downloaded object set and
+ * report which reachable SHAs are missing. `presentLocally` marks SHAs that
+ * already exist in the destination repository — the walk does not descend
+ * into them (a consistent local repo carries its own closure; the same
+ * assumption `git fetch` makes).
+ */
+declare function walkClosure(tips: Iterable<string>, objects: ReadonlyMap<string, FetchedObject>, presentLocally?: ReadonlySet<string>): ClosureResult;
+
+/**
+ * The shared clone/fetch object-collection engine (#278).
+ *
+ * Given the remote's ref tips and its kind:30618 sha→Arweave-txId map, gather
+ * every object the refs need:
+ *
+ *   1. download the mapped objects the destination repo doesn't already have
+ *      (parallel, gateway fallback chain, SHA-verified — ./object-fetch.ts);
+ *   2. walk the object graph from the tips (./object-fetch.ts walkClosure) —
+ *      the local repository's objects count as present (git fetch's own
+ *      assumption: a consistent repo carries its own closure);
+ *   3. SHAs the map doesn't cover are resolved through the Arweave GraphQL
+ *      Git-SHA resolver (RemoteState.resolveMissing) and downloaded, looping
+ *      until the closure is complete or no progress can be made.
+ *
+ * The result separates FATAL gaps (reachable objects that could not be
+ * obtained — usually Arweave gateway propagation lag, 10–20 min for fresh
+ * pushes) from harmless ones (mapped-but-unreachable objects, e.g. history
+ * that was force-pushed away). Corrupt objects throw ObjectIntegrityError
+ * from the download layer and never surface here.
+ */
+
+/** A reachable object that could not be obtained. */
+interface MissingObject {
+    sha: string;
+    /** The txId that failed on every gateway, or null when no txId resolved. */
+    txId: string | null;
+}
+interface CollectRepoObjectsOptions extends DownloadOptions {
+    /** Ref tip SHAs (commits or annotated tags) the closure must reach. */
+    tips: string[];
+    /** kind:30618 `arweave` tag map: git SHA → Arweave txId. */
+    shaToTxId: ReadonlyMap<string, string>;
+    /** GraphQL fallback for SHAs the map doesn't cover (RemoteState.resolveMissing). */
+    resolveMissing: (shas: string[]) => Promise<Map<string, string>>;
+    /** SHAs already present in the destination repository (fetch delta). */
+    presentLocally?: ReadonlySet<string>;
+}
+interface CollectRepoObjectsResult {
+    /** Verified objects to write, keyed by SHA. */
+    objects: Map<string, FetchedObject>;
+    /** Reachable SHAs that could not be obtained — FATAL for clone/fetch. */
+    missing: MissingObject[];
+    /** Mapped-but-unreachable SHAs that failed to download — warn only. */
+    skippedUnavailable: {
+        sha: string;
+        txId: string;
+    }[];
+}
+/** Collect (download + verify + close over) the objects the ref tips need. */
+declare function collectRepoObjects(options: CollectRepoObjectsOptions): Promise<CollectRepoObjectsResult>;
+/**
+ * The honest propagation-lag error text: which SHAs are unobtainable and why
+ * retrying later is the expected remedy.
+ */
+declare function missingObjectsMessage(missing: MissingObject[], context: string): string;
+
+/**
+ * Materialize downloaded git objects into a REAL repository (#278).
+ *
+ * Objects are written through git's own plumbing — `git hash-object -w
+ * --stdin -t <type>` with the raw body on stdin — so git computes, validates
+ * (syntax checks for trees/commits/tags), stores (loose object + zlib), and
+ * RETURNS the SHA. The returned SHA is compared against the expected one:
+ * a second, independent integrity gate after ./object-fetch.ts's envelope
+ * verification. Refs land via `git update-ref`, HEAD via `git symbolic-ref`.
+ *
+ * Same injection posture as GitRepoReader: child processes use
+ * `execFile`/`spawn` with argument ARRAYS (never a shell), and refnames are
+ * validated with `git check-ref-format` semantics before use.
+ */
+
+/** A written object's SHA disagreed with what `git hash-object` computed. */
+declare class ObjectWriteMismatchError extends Error {
+    readonly expectedSha: string;
+    readonly writtenSha: string;
+    constructor(expectedSha: string, writtenSha: string);
+}
+/**
+ * Conservative refname validation (superset-safe subset of
+ * `git check-ref-format`): must start `refs/`, no component may start with
+ * `-` or `.`, no `..`, no control/space/git-special characters, no trailing
+ * `/`, `.`, or `.lock`. Rejecting odd-but-legal names is fine — these
+ * refnames come from relay events, and a hostile relay must not be able to
+ * smuggle options or path traversal into git invocations.
+ */
+declare function isSafeRefname(refname: string): boolean;
+/**
+ * Write one object via `git hash-object -w --stdin -t <type>` (binary-safe
+ * stdin) and verify the SHA git computed matches the expected one.
+ */
+declare function writeGitObject(repoPath: string, object: FetchedObject): Promise<void>;
+/** Write a batch of verified objects into the repository (sequential). */
+declare function writeGitObjects(repoPath: string, objects: Iterable<FetchedObject>): Promise<number>;
+/** `git update-ref <refname> <sha>` with refname/SHA validation. */
+declare function updateRef(repoPath: string, refname: string, sha: string): Promise<void>;
+/** Point HEAD at a branch via `git symbolic-ref HEAD <refname>`. */
+declare function setHeadSymref(repoPath: string, refname: string): Promise<void>;
+
+/**
+ * Minimal bech32 npub encoding/decoding for Nostr pubkeys (BIP-173 / NIP-19),
+ * dependency-free. Mirrors rig-web's proven `web/npub.ts` — the CLI must not
+ * import from the SPA package, so the ~100 lines live here too (#278: `rig
+ * clone` accepts `<owner-npub-or-hex>/<repo-id>` addresses).
+ */
+/** Encode a 64-char hex pubkey as an `npub1…` bech32 string. */
+declare function hexToNpub(hexPubkey: string): string;
+/**
+ * Decode an `npub1…` bech32 string back to a 64-char hex pubkey.
+ * Throws on malformed input (prefix, length, charset, checksum, padding).
+ */
+declare function npubToHex(npub: string): string;
+/**
+ * Normalize a repo-owner reference to a 64-char hex pubkey: accepts lowercase
+ * hex verbatim or an `npub1…` string. Throws a caller-facing error otherwise.
+ */
+declare function ownerToHex(owner: string): string;
+
 /**
  * Push planner/executor — the core of `rig push` (epic #222, ticket #226).
  *
@@ -665,6 +928,11 @@ interface GitPatchRequest {
     repoAddr: GitRepoAddr;
     /** Patch/PR title (`subject` tag). */
     title: string;
+    /**
+     * PR body/cover text (`description` tag). Kept OUT of the event content so
+     * `git am` still consumes the patch text verbatim (#280).
+     */
+    description?: string;
     /** Literal patch text. Mutually exclusive with `repoPath`+`range`. */
     patchText?: string;
     /** Local repository to run format-patch in. Requires `range`. */
@@ -739,4 +1007,4 @@ declare function serializeEventReceipt(kind: number, receipt: PublishReceipt): G
 /** 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 };
+export { type ClosureResult, type CollectRepoObjectsOptions, type CollectRepoObjectsResult, DEFAULT_CONCURRENCY, type DownloadOptions, type DownloadResult, type ExecutePushOptions, FeeRates, type FetchLike, type FetchRemoteStateOptions, type FetchedObject, type GatewayFetchOptions, 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, type MissingObject, NonFastForwardError, type NostrEvent, type NostrFilter, ObjectIntegrityError, type ObjectStat, type ObjectWithPath, ObjectWriteMismatchError, 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, collectRepoObjects, downloadGitObjects, executePush, fetchRemoteState, fetchTxBytes, hexToNpub, isSafeRefname, missingObjectsMessage, npubToHex, ownerToHex, planPush, queryRelay, referencedShas, serializeEventReceipt, serializeFeeEstimate, serializePushPlan, serializePushResult, setHeadSymref, updateRef, verifyObjectBody, walkClosure, writeGitObject, writeGitObjects };

package/dist/index.js

@@ -1,18 +1,33 @@
 import {
+  DEFAULT_CONCURRENCY,
   GitError,
   GitRepoReader,
   NonFastForwardError,
+  ObjectIntegrityError,
+  ObjectWriteMismatchError,
   OversizeObjectsError,
+  collectRepoObjects,
+  downloadGitObjects,
   executePush,
+  fetchTxBytes,
+  hexToNpub,
+  isSafeRefname,
+  missingObjectsMessage,
+  npubToHex,
+  ownerToHex,
   planPush,
+  referencedShas,
   serializeEventReceipt,
   serializeFeeEstimate,
   serializePushPlan,
-  serializePushResult
-} from "./chunk-LFGDLD6J.js";
-import {
-  fetchRemoteState
-} from "./chunk-G4W4MH6G.js";
+  serializePushResult,
+  setHeadSymref,
+  updateRef,
+  verifyObjectBody,
+  walkClosure,
+  writeGitObject,
+  writeGitObjects
+} from "./chunk-PS5QOT62.js";
 import {
   COMMENT_KIND,
   REPOSITORY_STATE_KIND,
@@ -21,8 +36,10 @@ import {
   buildPatch,
   buildRepoAnnouncement,
   buildRepoRefs,
-  buildStatus
-} from "./chunk-HPSOQP7Q.js";
+  buildStatus,
+  fetchRemoteState,
+  queryRelay
+} from "./chunk-JBB7HBQC.js";
 import {
   MAX_OBJECT_SIZE,
   createGitBlob,
@@ -33,10 +50,13 @@ import {
 } from "./chunk-X2CZPPDM.js";
 export {
   COMMENT_KIND,
+  DEFAULT_CONCURRENCY,
   GitError,
   GitRepoReader,
   MAX_OBJECT_SIZE,
   NonFastForwardError,
+  ObjectIntegrityError,
+  ObjectWriteMismatchError,
   OversizeObjectsError,
   REPOSITORY_STATE_KIND,
   buildComment,
@@ -45,17 +65,33 @@ export {
   buildRepoAnnouncement,
   buildRepoRefs,
   buildStatus,
+  collectRepoObjects,
   createGitBlob,
   createGitCommit,
   createGitTag,
   createGitTree,
+  downloadGitObjects,
   executePush,
   fetchRemoteState,
+  fetchTxBytes,
   hashGitObject,
+  hexToNpub,
+  isSafeRefname,
+  missingObjectsMessage,
+  npubToHex,
+  ownerToHex,
   planPush,
+  queryRelay,
+  referencedShas,
   serializeEventReceipt,
   serializeFeeEstimate,
   serializePushPlan,
-  serializePushResult
+  serializePushResult,
+  setHeadSymref,
+  updateRef,
+  verifyObjectBody,
+  walkClosure,
+  writeGitObject,
+  writeGitObjects
 };
 //# sourceMappingURL=index.js.map

package/dist/{publisher-CClD9OIZ.d.ts → publisher-CrwaNQrK.d.ts}

@@ -144,6 +144,13 @@ declare function buildComment(repoOwnerPubkey: string, repoId: string, issueOrPr
 /**
  * Build a kind:1617 patch event.
  *
+ * The PR body/description travels in a dedicated `description` tag, NEVER in
+ * `content` (#280): `content` is real `git format-patch` output that readers
+ * pipe straight into `git am`, and git's patch-format detection hard-fails on
+ * any leading prose (verified: "Patch format detection failed."). The tag
+ * route keeps `git am` consumption intact while `rig pr show` and the
+ * rig-web/views `parsePR` renderers surface the description.
+ *
  * @param repoOwnerPubkey - Pubkey of the repository owner
  * @param repoId - Repository identifier
  * @param title - Patch/PR title (subject tag)
@@ -151,11 +158,13 @@ declare function buildComment(repoOwnerPubkey: string, repoId: string, issueOrPr
  * @param branchTag - Branch name for the t tag
  * @param content - Real `git format-patch` text (NIP-34 patch body); defaults
  *                  to '' for callers that only reference commits by tag
+ * @param description - PR body/cover text (`description` tag) — kept out of
+ *                      `content` so `git am` still applies it
  */
 declare function buildPatch(repoOwnerPubkey: string, repoId: string, title: string, commits: {
     sha: string;
     parentSha: string;
-}[], branchTag?: string, content?: string): UnsignedEvent;
+}[], branchTag?: string, content?: string, description?: string): UnsignedEvent;
 /** Status kinds: 1630 open, 1631 applied/merged, 1632 closed, 1633 draft. */
 type StatusKind = typeof STATUS_OPEN_KIND | typeof STATUS_APPLIED_KIND | typeof STATUS_CLOSED_KIND | typeof STATUS_DRAFT_KIND;
 /**