@happyvertical/repos 0.85.4 → 0.86.0

package/AGENT.md

@@ -27,7 +27,7 @@ pnpm --filter @happyvertical/repos clean
 ## Ecosystem Relationships
 - Provides: Standardized repository interface for GitHub, GitLab, Bitbucket, and Azure DevOps
 - Implements: none
-- Requires: @happyvertical/graphql, js-yaml
+- Requires: @happyvertical/graphql, js-yaml, nostr-tools
 - Stability: stable (Primary package surface is described as implemented and production-oriented.)
 <!-- END AGENT:GENERATED -->
 

package/README.md

@@ -123,6 +123,27 @@ an observation. The exported `createGitHubWebhookFixture()` helper creates exact
 deterministic bytes and signatures for duplicate, redelivery, delayed, and
 out-of-order integration scenarios.
 
+### Buzz forge relay
+
+`BuzzRelayClient` polls configured Buzz/Nostr relays and normalizes supported
+forge kinds into provider-neutral `ForgeEventEnvelope` values. Production
+events are verified with `nostr-tools` before normalization; the
+`allowUnverifiedFixtures` option is solely for deterministic test fixtures.
+When `channelIds` is set, accepted events must have a matching `channel` or
+`h` tag. Kind-7 approvals need pull-request metadata or their referenced
+kind-1617 patch; pass a kind-39002 members event and `roleFloor` to enforce
+channel roles.
+
+```typescript
+import { BuzzRelayClient } from '@happyvertical/repos';
+
+const buzz = new BuzzRelayClient({
+  relays: ['https://relay.example/buzz'],
+  channelIds: ['channel-hv'],
+});
+const events = await buzz.pollOnce();
+```
+
 ### Errors and provider metadata
 
 New forge APIs throw `ForgeError`, which exposes `code`, `provider`, `status`,

package/dist/index.d.ts

@@ -4,6 +4,119 @@ export declare interface Branch {
     protected: boolean;
 }
 
+export declare const BUZZ_FIXTURE_PUBKEYS: {
+    readonly owner: "2ad53df8aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa4f05";
+    readonly attestor: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+    readonly reactor: "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc";
+};
+
+/**
+ * Buzz/Nostr forge event kinds verified live against desktop-v0.5.3 (ADR-002).
+ * Kind numbers are load-bearing and must match the deployed relay.
+ */
+export declare const BUZZ_FORGE_KINDS: {
+    readonly repositoryAnnouncement: 30617;
+    readonly refUpdate: 30618;
+    readonly patch: 1617;
+    readonly statusOpen: 1630;
+    readonly statusApplied: 1631;
+    readonly statusClosed: 1632;
+    readonly statusDraft: 1633;
+    readonly reaction: 7;
+    readonly channelMembers: 39002;
+};
+
+/** Channel role floor used when validating kind:7 approvals (ADR-002). */
+export declare type BuzzChannelRole = 'owner' | 'admin' | 'member' | 'guest' | 'bot';
+
+declare interface BuzzFixtureOptions {
+    /** Override event id after computing the NIP-01 digest (duplicate/replay cases). */
+    id?: string;
+    pubkey?: string;
+    created_at?: number;
+    tags?: readonly (readonly string[])[];
+    content?: string;
+    sig?: string;
+}
+
+export declare type BuzzForgeKind = (typeof BUZZ_FORGE_KINDS)[keyof typeof BUZZ_FORGE_KINDS];
+
+/**
+ * Minimal buzz relay client: HTTP REQ polling plus an injectable event source
+ * for tests and WebSocket adapters.
+ *
+ * The client never mutates process-global state. Each subscribe/poll call is
+ * scoped to the constructed options.
+ */
+export declare class BuzzRelayClient {
+    private readonly relays;
+    private readonly kinds;
+    private readonly channelIds;
+    private readonly fetchImpl;
+    private readonly pollIntervalMs;
+    private readonly seenIds;
+    constructor(options: BuzzRelayClientOptions);
+    /**
+     * Poll every configured relay once with a NIP-01-style HTTP REQ body and
+     * return newly observed, verified envelopes (deduped by event id).
+     */
+    pollOnce(options?: {
+        since?: number;
+        allowUnverifiedFixtures?: boolean;
+        membersEvent?: NostrForgeEvent;
+        referencedPatchEvent?: NostrForgeEvent;
+    }): Promise<ForgeEventEnvelope[]>;
+    /**
+     * Poll on an interval until `close()` is called. Useful for long-running
+     * Aedile adapters. Returns a subscription handle.
+     */
+    subscribe(onEvent: (envelope: ForgeEventEnvelope) => void | Promise<void>, options?: {
+        since?: number;
+        allowUnverifiedFixtures?: boolean;
+        membersEvent?: NostrForgeEvent;
+        referencedPatchEvent?: NostrForgeEvent;
+        onError?: (error: unknown) => void;
+    }): BuzzRelaySubscription;
+    /**
+     * Normalize a pre-fetched event list (tests / custom transports) without
+     * contacting a relay. Applies the same kind/channel filters and id dedupe.
+     */
+    ingestEvents(events: readonly NostrForgeEvent[], options?: {
+        allowUnverifiedFixtures?: boolean;
+        membersEvent?: NostrForgeEvent;
+        referencedPatchEvent?: NostrForgeEvent;
+        verify?: boolean;
+    }): ForgeEventEnvelope[];
+    /** Forget delivered ids (operator replay). */
+    resetSeen(): void;
+    private fetchEvents;
+}
+
+export declare interface BuzzRelayClientOptions {
+    /** WebSocket or HTTP relay endpoints. */
+    relays: readonly string[];
+    /** Optional filter limiting which kinds are accepted. */
+    kinds?: readonly number[];
+    /** Bound channel ids watched for forge activity. */
+    channelIds?: readonly string[];
+    /** Fetch implementation override for tests. */
+    fetch?: typeof fetch;
+    /** Poll interval in ms when using HTTP REQ polling. Default 5000. */
+    pollIntervalMs?: number;
+}
+
+export declare interface BuzzRelaySubscription {
+    close(): void;
+}
+
+export declare interface BuzzRoleResolution {
+    pubkey: string;
+    role: BuzzChannelRole;
+}
+
+/** Extract a channel id from common buzz tags when present. */
+export declare function channelIdFromEvent(event: NostrForgeEvent): string | undefined;
+
 /** Normalized provider check run. */
 export declare interface CheckRun {
     id: string;
@@ -47,6 +160,37 @@ export declare interface CommitStatus {
     raw?: unknown;
 }
 
+/**
+ * Compute the NIP-01 event id for a Nostr event (sha256 of serialized fields).
+ * Used by fixtures and verification when the caller supplies an unsigned skeleton.
+ */
+export declare function computeNostrEventId(event: Omit<NostrForgeEvent, 'id' | 'sig'>): string;
+
+export declare function createApprovalFixture(options?: BuzzFixtureOptions & {
+    content?: string;
+    headSha?: string;
+    targetEventId?: string;
+}): NostrForgeEvent;
+
+/**
+ * Deterministic sequences for convergence suites (duplicate / delayed /
+ * out-of-order / replay). Each sequence is an ordered list of Nostr events;
+ * consumers may reshuffle delivery while asserting identical projection state.
+ */
+export declare function createBuzzConvergenceSequences(): {
+    canonical: NostrForgeEvent[];
+    duplicate: NostrForgeEvent[];
+    delayed: NostrForgeEvent[];
+    outOfOrder: NostrForgeEvent[];
+    replay: NostrForgeEvent[];
+};
+
+/**
+ * Build a deterministic unsigned-then-id-bound Nostr event for tests.
+ * Signature bytes are placeholders; pair with `allowUnverifiedFixtures: true`.
+ */
+export declare function createBuzzFixtureEvent(kind: number, options?: BuzzFixtureOptions): NostrForgeEvent;
+
 /** Input for publishing a provider check run. */
 export declare interface CreateCheckRunInput {
     name: string;
@@ -115,6 +259,19 @@ export declare interface CreateIssueInput {
     assignees?: string[];
 }
 
+export declare function createMembersFixture(options?: BuzzFixtureOptions & {
+    members?: readonly {
+        pubkey: string;
+        role: string;
+    }[];
+}): NostrForgeEvent;
+
+export declare function createPatchFixture(options?: BuzzFixtureOptions & {
+    headSha?: string;
+    number?: number;
+    repoId?: string;
+}): NostrForgeEvent;
+
 export declare interface CreatePRInput {
     title: string;
     body?: string;
@@ -123,6 +280,27 @@ export declare interface CreatePRInput {
     draft?: boolean;
 }
 
+export declare function createRefUpdateFixture(options?: BuzzFixtureOptions & {
+    ref?: string;
+    head?: string;
+    previous?: string;
+    repoId?: string;
+    owner?: string;
+}): NostrForgeEvent;
+
+export declare function createRepositoryAnnouncementFixture(options?: BuzzFixtureOptions & {
+    owner?: string;
+    repoId?: string;
+    channelId?: string;
+}): NostrForgeEvent;
+
+export declare function createStatusFixture(options?: BuzzFixtureOptions & {
+    kind?: typeof BUZZ_FORGE_KINDS.statusOpen | typeof BUZZ_FORGE_KINDS.statusApplied | typeof BUZZ_FORGE_KINDS.statusClosed | typeof BUZZ_FORGE_KINDS.statusDraft;
+    context?: string;
+    headSha?: string;
+    conclusion?: string;
+}): NostrForgeEvent;
+
 /**
  * Detect which template an issue was created from based on labels
  *
@@ -884,6 +1062,17 @@ export declare function loadIssueTemplate(yamlPath: string): Promise<IssueTempla
 
 export declare type MergeMethod = 'merge' | 'squash' | 'rebase';
 
+/**
+ * Normalize one already-verified Nostr forge event into a provider-neutral
+ * envelope. Signature verification is the caller's responsibility (or use
+ * {@link verifyAndNormalizeBuzzEvent}).
+ */
+export declare function normalizeBuzzEvent(event: NostrForgeEvent, receivedAt?: Date, options?: {
+    roleFloor?: BuzzChannelRole;
+    membersEvent?: NostrForgeEvent;
+    referencedPatchEvent?: NostrForgeEvent;
+}): ForgeEventEnvelope;
+
 /**
  * Normalizes one already-verified GitHub payload.
  * @param deliveryId Stable provider delivery identity.
@@ -894,6 +1083,17 @@ export declare type MergeMethod = 'merge' | 'squash' | 'rebase';
  */
 export declare function normalizeGitHubWebhook(deliveryId: string, event: string, raw: unknown, receivedAt?: Date): ForgeEventEnvelope;
 
+/** Minimal Nostr event shape consumed by the buzz forge adapter. */
+export declare interface NostrForgeEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: readonly (readonly string[])[];
+    content: string;
+    sig: string;
+}
+
 /**
  * Parse an issue body into field values
  *
@@ -1027,6 +1227,15 @@ export declare enum RepositoryErrorCode {
     UNKNOWN = "UNKNOWN"
 }
 
+/**
+ * Resolve a reactor's channel role from a kind:39002 members list.
+ * Returns null when the pubkey is absent from the membership event.
+ */
+export declare function resolveBuzzChannelRole(membersEvent: NostrForgeEvent, pubkey: string): BuzzRoleResolution | null;
+
+/** True when the reactor's role rank is at or above the configured floor. */
+export declare function roleMeetsFloor(role: BuzzChannelRole, floor: BuzzChannelRole): boolean;
+
 export declare interface SearchFilters {
     state?: 'open' | 'closed' | 'all';
     labels?: string[];
@@ -1088,4 +1297,26 @@ export declare interface User {
     url?: string;
 }
 
+/**
+ * Verify then normalize a buzz forge event. Rejects invalid signatures without
+ * producing an observation.
+ */
+export declare function verifyAndNormalizeBuzzEvent(event: NostrForgeEvent, receivedAt?: Date, options?: {
+    roleFloor?: BuzzChannelRole;
+    membersEvent?: NostrForgeEvent;
+    referencedPatchEvent?: NostrForgeEvent;
+    allowUnverifiedFixtures?: boolean;
+}): ForgeEventEnvelope;
+
+/**
+ * Structural signature verification for Nostr events.
+ *
+ * When `nostr-tools` is available it performs full Schnorr verification.
+ * Otherwise it fails closed unless `allowUnverifiedFixtures` is set (tests
+ * that inject pre-trusted fixture events with matching id digests).
+ */
+export declare function verifyNostrEventSignature(event: NostrForgeEvent, options?: {
+    allowUnverifiedFixtures?: boolean;
+}): void;
+
 export { }