swarm-mail 0.1.2 → 0.1.4

package/README.md

@@ -30,6 +30,8 @@
 
 Event sourcing primitives for multi-agent coordination. Local-first, no external servers.
 
+**[🌐 swarmtools.ai](https://swarmtools.ai)** | **[📖 Full Documentation](https://swarmtools.ai/docs)**
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                     SWARM MAIL STACK                        │
@@ -190,6 +192,8 @@ Materialized views derived from events:
 
 ## API Reference
 
+For complete API documentation, see [swarmtools.ai/docs](https://swarmtools.ai/docs).
+
 ### SwarmMailAdapter
 
 ```typescript

package/dist/beads/adapter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Beads Adapter - Factory for creating BeadsAdapter instances
+ *
+ * This file implements the adapter pattern for beads event sourcing,
+ * enabling dependency injection of the database.
+ *
+ * ## Design Pattern
+ * - Accept DatabaseAdapter via factory parameter
+ * - Return BeadsAdapter interface
+ * - Delegate to store.ts for event operations
+ * - Delegate to projections.ts for queries
+ * - No direct database access (all via adapter)
+ *
+ * ## Usage
+ * ```typescript
+ * import { wrapPGlite } from '@opencode/swarm-mail/pglite';
+ * import { createBeadsAdapter } from '@opencode/swarm-mail/beads';
+ *
+ * const pglite = new PGlite('./streams.db');
+ * const db = wrapPGlite(pglite);
+ * const beads = createBeadsAdapter(db, '/path/to/project');
+ *
+ * // Use the adapter
+ * await beads.createBead(projectKey, { title: "Task", type: "task", priority: 2 });
+ * const bead = await beads.getBead(projectKey, "bd-123");
+ * ```
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+import type { BeadsAdapter } from "../types/beads-adapter.js";
+/**
+ * Create a BeadsAdapter instance
+ *
+ * @param db - DatabaseAdapter instance (PGLite, SQLite, PostgreSQL, etc.)
+ * @param projectKey - Project identifier (typically the project path)
+ * @returns BeadsAdapter interface
+ */
+export declare function createBeadsAdapter(db: DatabaseAdapter, projectKey: string): BeadsAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/beads/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/beads/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AA6B9D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,GACjB,YAAY,CAkiBd"}

package/dist/beads/blocked-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Blocked Beads Cache Management
+ *
+ * Convenience re-exports for blocked cache operations.
+ * The actual implementation is in dependencies.ts to avoid circular dependencies.
+ *
+ * ## Cache Strategy
+ * - blocked_beads_cache table stores bead_id → blocker_ids[]
+ * - Rebuilt when dependencies change or bead status changes
+ * - Enables fast "ready work" queries without recursive CTEs
+ *
+ * ## Performance
+ * - Cache rebuild: <50ms for typical projects
+ * - Ready work query: 25x faster with cache (752ms → 29ms on 10K beads)
+ *
+ * Reference: steveyegge/beads/internal/storage/sqlite/blocked_cache.go
+ *
+ * @module beads/blocked-cache
+ */
+export { rebuildBeadBlockedCache, rebuildAllBlockedCaches, invalidateBlockedCache, } from "./dependencies.js";
+//# sourceMappingURL=blocked-cache.d.ts.map

package/dist/beads/blocked-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocked-cache.d.ts","sourceRoot":"","sources":["../../src/beads/blocked-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/beads/comments.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Comment Operations
+ *
+ * Comment management with threading support.
+ * Comments can have parent_id for nested discussions.
+ *
+ * Reference: steveyegge/beads/internal/storage/sqlite/comments.go
+ *
+ * @module beads/comments
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+import type { BeadComment } from "../types/beads-adapter.js";
+/**
+ * Get a specific comment by ID
+ */
+export declare function getCommentById(db: DatabaseAdapter, commentId: number): Promise<BeadComment | null>;
+/**
+ * Get comment thread (comment + all replies)
+ */
+export declare function getCommentThread(db: DatabaseAdapter, rootCommentId: number): Promise<BeadComment[]>;
+//# sourceMappingURL=comments.d.ts.map

package/dist/beads/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/beads/comments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;GAEG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAM7B;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,eAAe,EACnB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CAgBxB"}

package/dist/beads/dependencies.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Dependency Graph Operations
+ *
+ * Provides dependency management with cycle detection and blocked bead tracking.
+ *
+ * ## Dependency Types
+ * - **blocks**: Hard dependency - target must be closed before source can start
+ * - **blocked-by**: Inverse of blocks (computed, not stored)
+ * - **related**: Soft relationship - doesn't affect ready state
+ * - **discovered-from**: Tracking relationship - found while working on another bead
+ *
+ * ## Cycle Prevention
+ * All dependency types are checked for cycles to maintain a DAG (Directed Acyclic Graph).
+ * This ensures:
+ * - Ready work calculation works correctly
+ * - Dependency traversal doesn't loop
+ * - Semantic clarity (no circular dependencies)
+ *
+ * Reference: steveyegge/beads/internal/storage/sqlite/dependencies.go
+ *
+ * @module beads/dependencies
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+/**
+ * Check if adding a dependency would create a cycle
+ *
+ * Uses recursive CTE to traverse from dependsOnId to see if we can reach beadId.
+ * If yes, adding "beadId depends on dependsOnId" would complete a cycle.
+ */
+export declare function wouldCreateCycle(db: DatabaseAdapter, beadId: string, dependsOnId: string): Promise<boolean>;
+/**
+ * Get all open blockers for a bead (including transitive)
+ *
+ * Returns bead IDs of all beads blocking this one that aren't closed.
+ * Only considers "blocks" relationship type.
+ */
+export declare function getOpenBlockers(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<string[]>;
+/**
+ * Rebuild blocked cache for a specific bead
+ *
+ * Finds all open blockers and updates the cache.
+ * If no open blockers, removes from cache (bead is unblocked).
+ */
+export declare function rebuildBeadBlockedCache(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<void>;
+/**
+ * Rebuild blocked cache for all beads in a project
+ *
+ * Used after bulk operations or status changes that affect blocking.
+ */
+export declare function rebuildAllBlockedCaches(db: DatabaseAdapter, projectKey: string): Promise<void>;
+/**
+ * Invalidate blocked cache when dependencies change
+ *
+ * Marks beads as needing cache rebuild.
+ * In this simple implementation, we just rebuild immediately.
+ */
+export declare function invalidateBlockedCache(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<void>;
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/beads/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/beads/dependencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAI5D;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBnB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/beads/events.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Bead Event Types - Minimal type definitions for swarm-mail
+ *
+ * These are simplified type definitions that match the bead-events from
+ * opencode-swarm-plugin but avoid cross-package TypeScript imports.
+ *
+ * The actual event schemas with Zod validation live in:
+ * packages/opencode-swarm-plugin/src/schemas/bead-events.ts
+ *
+ * This file provides just enough type information for the store to work.
+ */
+/**
+ * Base bead event (all events extend this)
+ */
+export interface BaseBeadEvent {
+    id?: number;
+    type: string;
+    project_key: string;
+    bead_id: string;
+    timestamp: number;
+    sequence?: number;
+}
+/**
+ * Union of all bead event types
+ *
+ * This matches the discriminated union in bead-events.ts but as pure TypeScript
+ */
+export type BeadEvent = BeadCreatedEvent | BeadUpdatedEvent | BeadStatusChangedEvent | BeadClosedEvent | BeadReopenedEvent | BeadDeletedEvent | BeadDependencyAddedEvent | BeadDependencyRemovedEvent | BeadLabelAddedEvent | BeadLabelRemovedEvent | BeadCommentAddedEvent | BeadCommentUpdatedEvent | BeadCommentDeletedEvent | BeadEpicChildAddedEvent | BeadEpicChildRemovedEvent | BeadEpicClosureEligibleEvent | BeadAssignedEvent | BeadWorkStartedEvent | BeadCompactedEvent;
+export interface BeadCreatedEvent extends BaseBeadEvent {
+    type: "bead_created";
+    title: string;
+    description?: string;
+    issue_type: "bug" | "feature" | "task" | "epic" | "chore";
+    priority: number;
+    parent_id?: string;
+    created_by?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface BeadUpdatedEvent extends BaseBeadEvent {
+    type: "bead_updated";
+    updated_by?: string;
+    changes: {
+        title?: {
+            old: string;
+            new: string;
+        };
+        description?: {
+            old: string;
+            new: string;
+        };
+        priority?: {
+            old: number;
+            new: number;
+        };
+    };
+}
+export interface BeadStatusChangedEvent extends BaseBeadEvent {
+    type: "bead_status_changed";
+    from_status: "open" | "in_progress" | "blocked" | "closed" | "tombstone";
+    to_status: "open" | "in_progress" | "blocked" | "closed" | "tombstone";
+    changed_by?: string;
+    reason?: string;
+}
+export interface BeadClosedEvent extends BaseBeadEvent {
+    type: "bead_closed";
+    reason: string;
+    closed_by?: string;
+    files_touched?: string[];
+    duration_ms?: number;
+}
+export interface BeadReopenedEvent extends BaseBeadEvent {
+    type: "bead_reopened";
+    reason?: string;
+    reopened_by?: string;
+}
+export interface BeadDeletedEvent extends BaseBeadEvent {
+    type: "bead_deleted";
+    reason?: string;
+    deleted_by?: string;
+}
+export interface BeadDependencyAddedEvent extends BaseBeadEvent {
+    type: "bead_dependency_added";
+    dependency: {
+        target: string;
+        type: "blocks" | "blocked-by" | "related" | "discovered-from";
+    };
+    added_by?: string;
+    reason?: string;
+}
+export interface BeadDependencyRemovedEvent extends BaseBeadEvent {
+    type: "bead_dependency_removed";
+    dependency: {
+        target: string;
+        type: "blocks" | "blocked-by" | "related" | "discovered-from";
+    };
+    removed_by?: string;
+    reason?: string;
+}
+export interface BeadLabelAddedEvent extends BaseBeadEvent {
+    type: "bead_label_added";
+    label: string;
+    added_by?: string;
+}
+export interface BeadLabelRemovedEvent extends BaseBeadEvent {
+    type: "bead_label_removed";
+    label: string;
+    removed_by?: string;
+}
+export interface BeadCommentAddedEvent extends BaseBeadEvent {
+    type: "bead_comment_added";
+    comment_id?: number;
+    author: string;
+    body: string;
+    parent_comment_id?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface BeadCommentUpdatedEvent extends BaseBeadEvent {
+    type: "bead_comment_updated";
+    comment_id: number;
+    old_body: string;
+    new_body: string;
+    updated_by: string;
+}
+export interface BeadCommentDeletedEvent extends BaseBeadEvent {
+    type: "bead_comment_deleted";
+    comment_id: number;
+    deleted_by: string;
+    reason?: string;
+}
+export interface BeadEpicChildAddedEvent extends BaseBeadEvent {
+    type: "bead_epic_child_added";
+    child_id: string;
+    child_index?: number;
+    added_by?: string;
+}
+export interface BeadEpicChildRemovedEvent extends BaseBeadEvent {
+    type: "bead_epic_child_removed";
+    child_id: string;
+    removed_by?: string;
+    reason?: string;
+}
+export interface BeadEpicClosureEligibleEvent extends BaseBeadEvent {
+    type: "bead_epic_closure_eligible";
+    child_ids: string[];
+    total_duration_ms?: number;
+    all_files_touched?: string[];
+}
+export interface BeadAssignedEvent extends BaseBeadEvent {
+    type: "bead_assigned";
+    agent_name: string;
+    task_description?: string;
+}
+export interface BeadWorkStartedEvent extends BaseBeadEvent {
+    type: "bead_work_started";
+    agent_name: string;
+    reserved_files?: string[];
+}
+export interface BeadCompactedEvent extends BaseBeadEvent {
+    type: "bead_compacted";
+    events_archived: number;
+    new_start_sequence: number;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/beads/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/beads/events.ts"],"names":[],"mappings":"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"}

package/dist/beads/flush-manager.d.ts

@@ -0,0 +1,71 @@
+/**
+ * FlushManager - Debounced JSONL export to file
+ *
+ * Automatically exports dirty beads to a JSONL file on a debounced timer.
+ * Prevents excessive writes while ensuring changes are persisted.
+ *
+ * Based on steveyegge/beads flush_manager.go
+ *
+ * @module beads/flush-manager
+ */
+import type { BeadsAdapter } from "../types/beads-adapter.js";
+export interface FlushManagerOptions {
+    adapter: BeadsAdapter;
+    projectKey: string;
+    outputPath: string;
+    debounceMs?: number;
+    onFlush?: (result: FlushResult) => void;
+}
+export interface FlushResult {
+    beadsExported: number;
+    bytesWritten: number;
+    duration: number;
+}
+/**
+ * FlushManager handles debounced export of dirty beads to JSONL
+ *
+ * Usage:
+ * ```ts
+ * const manager = new FlushManager({
+ *   adapter,
+ *   projectKey: "/path/to/project",
+ *   outputPath: ".beads/issues.jsonl",
+ *   debounceMs: 30000,
+ * });
+ *
+ * // Schedule flushes as beads change
+ * manager.scheduleFlush();
+ *
+ * // Clean up
+ * manager.stop();
+ * ```
+ */
+export declare class FlushManager {
+    private adapter;
+    private projectKey;
+    private outputPath;
+    private debounceMs;
+    private onFlush?;
+    private timer;
+    private flushing;
+    constructor(options: FlushManagerOptions);
+    /**
+     * Schedule a flush (debounced)
+     *
+     * If a flush is already scheduled, resets the timer.
+     */
+    scheduleFlush(): void;
+    /**
+     * Force immediate flush
+     *
+     * Exports all dirty beads to the output file.
+     */
+    flush(): Promise<FlushResult>;
+    /**
+     * Stop the flush manager
+     *
+     * Clears any pending timers. Does NOT flush pending changes.
+     */
+    stop(): void;
+}
+//# sourceMappingURL=flush-manager.d.ts.map

package/dist/beads/flush-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-manager.d.ts","sourceRoot":"","sources":["../../src/beads/flush-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAgC;IAChD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,mBAAmB;IAQxC;;;;OAIG;IACH,aAAa,IAAI,IAAI;IAcrB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IA8DnC;;;;OAIG;IACH,IAAI,IAAI,IAAI;CAMb"}

package/dist/beads/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Beads Module - Event-sourced issue tracking
+ *
+ * Exports:
+ * - BeadsAdapter interface and types
+ * - Migration definitions
+ * - Projection functions
+ * - Store operations (append, read, replay)
+ * - Event type definitions
+ *
+ * @module beads
+ */
+export type { Bead, BeadAdapter, BeadComment, BeadDependency, BeadLabel, BeadsAdapter, BeadsAdapterFactory, BeadsSchemaAdapter, BeadStatus, BeadType, CommentAdapter, CreateBeadOptions, DependencyAdapter, DependencyRelationship, EpicAdapter, LabelAdapter, QueryAdapter, QueryBeadsOptions, UpdateBeadOptions, } from "../types/beads-adapter.js";
+export type { BeadEvent, BaseBeadEvent, BeadCreatedEvent, BeadUpdatedEvent, BeadStatusChangedEvent, BeadClosedEvent, BeadReopenedEvent, BeadDeletedEvent, BeadDependencyAddedEvent, BeadDependencyRemovedEvent, BeadLabelAddedEvent, BeadLabelRemovedEvent, BeadCommentAddedEvent, BeadCommentUpdatedEvent, BeadCommentDeletedEvent, BeadEpicChildAddedEvent, BeadEpicChildRemovedEvent, BeadEpicClosureEligibleEvent, BeadAssignedEvent, BeadWorkStartedEvent, BeadCompactedEvent, } from "./events.js";
+export { createBeadsAdapter } from "./adapter.js";
+export { beadsMigration, beadsMigrations } from "./migrations.js";
+export { appendBeadEvent, readBeadEvents, replayBeadEvents, type ReadBeadEventsOptions, } from "./store.js";
+export { clearAllDirtyBeads, clearDirtyBead, getBead, getBlockedBeads, getBlockers, getComments, getDependencies, getDependents, getDirtyBeads, getInProgressBeads, getLabels, getNextReadyBead, isBlocked, markBeadDirty, queryBeads, updateProjections, } from "./projections.js";
+export { wouldCreateCycle, getOpenBlockers, rebuildBeadBlockedCache, rebuildAllBlockedCaches, invalidateBlockedCache, } from "./dependencies.js";
+export { getBeadsByLabel, getAllLabels, } from "./labels.js";
+export { getCommentById, getCommentThread, } from "./comments.js";
+export { exportToJSONL, exportDirtyBeads, importFromJSONL, parseJSONL, serializeToJSONL, computeContentHash, type BeadExport, type ExportOptions, type ImportOptions, type ImportResult, } from "./jsonl.js";
+export { FlushManager, type FlushManagerOptions, type FlushResult, } from "./flush-manager.js";
+export { merge3Way, mergeJsonl, isTombstone, isExpiredTombstone, DEFAULT_TOMBSTONE_TTL_MS, MIN_TOMBSTONE_TTL_MS, CLOCK_SKEW_GRACE_MS, STATUS_TOMBSTONE, type IssueKey, type MergeResult, type MergeOptions, } from "./merge.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/beads/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/beads/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,YAAY,EACV,IAAI,EACJ,WAAW,EACX,WAAW,EACX,cAAc,EACd,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,KAAK,qBAAqB,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,eAAe,EACf,WAAW,EACX,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,UAAU,EACV,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,SAAS,EACT,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC"}

package/dist/beads/jsonl.d.ts

@@ -0,0 +1,103 @@
+/**
+ * JSONL Export/Import for Beads
+ *
+ * Implements git sync via JSONL format compatible with steveyegge/beads.
+ * Features:
+ * - Full export to JSONL string
+ * - Incremental dirty bead export
+ * - Import with hash-based deduplication
+ * - Parse/serialize individual lines
+ *
+ * @module beads/jsonl
+ */
+import type { BeadsAdapter } from "../types/beads-adapter.js";
+/**
+ * JSONL export format matching steveyegge/beads
+ *
+ * One JSON object per line. Field names match the Go struct tags.
+ */
+export interface BeadExport {
+    id: string;
+    title: string;
+    description?: string;
+    status: "open" | "in_progress" | "blocked" | "closed" | "tombstone";
+    priority: number;
+    issue_type: "bug" | "feature" | "task" | "epic" | "chore";
+    created_at: string;
+    updated_at: string;
+    closed_at?: string;
+    assignee?: string;
+    parent_id?: string;
+    dependencies: Array<{
+        depends_on_id: string;
+        type: string;
+    }>;
+    labels: string[];
+    comments: Array<{
+        author: string;
+        text: string;
+    }>;
+}
+export interface ExportOptions {
+    includeDeleted?: boolean;
+    beadIds?: string[];
+}
+export interface ImportOptions {
+    dryRun?: boolean;
+    skipExisting?: boolean;
+}
+export interface ImportResult {
+    created: number;
+    updated: number;
+    skipped: number;
+    errors: Array<{
+        beadId: string;
+        error: string;
+    }>;
+}
+/**
+ * Serialize a bead to a JSONL line
+ */
+export declare function serializeToJSONL(bead: BeadExport): string;
+/**
+ * Parse JSONL string to bead exports
+ *
+ * Skips empty lines. Throws on invalid JSON.
+ */
+export declare function parseJSONL(jsonl: string): BeadExport[];
+/**
+ * Compute SHA-256 content hash for deduplication
+ *
+ * Uses canonical JSON encoding (sorted keys) for stability.
+ * Includes timestamps to detect any change.
+ */
+export declare function computeContentHash(bead: BeadExport): string;
+/**
+ * Export all beads to JSONL string
+ *
+ * By default excludes deleted beads (tombstones).
+ * Includes dependencies, labels, and comments.
+ */
+export declare function exportToJSONL(adapter: BeadsAdapter, projectKey: string, options?: ExportOptions): Promise<string>;
+/**
+ * Export only dirty beads (incremental)
+ *
+ * Returns JSONL and list of bead IDs that were exported.
+ */
+export declare function exportDirtyBeads(adapter: BeadsAdapter, projectKey: string): Promise<{
+    jsonl: string;
+    beadIds: string[];
+}>;
+/**
+ * Import beads from JSONL string
+ *
+ * Features:
+ * - Creates new beads
+ * - Updates existing beads
+ * - Hash-based deduplication (skips if content unchanged)
+ * - Imports dependencies, labels, comments
+ * - Dry run mode for preview
+ * - Skip existing mode
+ */
+export declare function importFromJSONL(adapter: BeadsAdapter, projectKey: string, jsonl: string, options?: ImportOptions): Promise<ImportResult>;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/beads/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/beads/jsonl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAa9D;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,KAAK,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CAyBtD;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAI3D;AAMD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA2EjB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAa/C;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAqBvB"}

package/dist/beads/labels.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Label Operations
+ *
+ * Simple label management for categorizing beads.
+ * Labels are string tags that can be queried for grouping and filtering.
+ *
+ * Reference: steveyegge/beads/internal/storage/sqlite/labels.go
+ *
+ * @module beads/labels
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+import type { Bead } from "../types/beads-adapter.js";
+/**
+ * Get all beads with a specific label
+ */
+export declare function getBeadsByLabel(db: DatabaseAdapter, projectKey: string, label: string): Promise<Bead[]>;
+/**
+ * Get all unique labels for a project
+ */
+export declare function getAllLabels(db: DatabaseAdapter, projectKey: string): Promise<string[]>;
+//# sourceMappingURL=labels.d.ts.map

package/dist/beads/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../src/beads/labels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AAEtD;;GAEG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,EAAE,CAAC,CASjB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CASnB"}