swarm-mail 0.5.0 → 1.1.0

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"}

package/dist/beads/merge.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 3-Way Merge Driver for Beads JSONL
+ *
+ * Ported from steveyegge/beads internal/merge/merge.go (MIT License)
+ * Original by @neongreen: https://github.com/neongreen/mono/tree/main/beads-merge
+ *
+ * Features:
+ * - 3-way merge of JSONL bead files
+ * - Tombstone semantics (soft-delete wins over live, expired allows resurrection)
+ * - Field-level merge with updated_at tiebreaker
+ * - Deterministic conflict resolution (no manual intervention needed)
+ *
+ * ## Tombstone Rules
+ * - Tombstone always wins over live issue (unless expired)
+ * - Expired tombstones allow resurrection (live issue wins)
+ * - Two tombstones: later deleted_at wins
+ *
+ * ## Field Merge Rules
+ * - title/description: latest updated_at wins
+ * - status: closed wins over open, tombstone wins over all
+ * - priority: higher priority wins (lower number = more urgent)
+ * - notes: concatenate on conflict
+ * - dependencies: union (deduplicated)
+ *
+ * @module beads/merge
+ */
+import type { BeadExport } from "./jsonl.js";
+/** Default TTL for tombstones (30 days) */
+export declare const DEFAULT_TOMBSTONE_TTL_MS: number;
+/** Minimum TTL for tombstones (7 days) - safety limit */
+export declare const MIN_TOMBSTONE_TTL_MS: number;
+/** Clock skew grace period (1 hour) - added to TTL for distributed systems */
+export declare const CLOCK_SKEW_GRACE_MS: number;
+/** Tombstone status constant */
+export declare const STATUS_TOMBSTONE = "tombstone";
+/**
+ * Issue key for matching across base/left/right
+ *
+ * Uses ID + created_at + created_by for uniqueness (handles ID collisions)
+ */
+export interface IssueKey {
+    id: string;
+    createdAt: string;
+    createdBy?: string;
+}
+/**
+ * Merge result
+ */
+export interface MergeResult {
+    /** Successfully merged beads */
+    merged: BeadExport[];
+    /** Conflict markers (for manual resolution if needed) */
+    conflicts: string[];
+}
+/**
+ * Merge options
+ */
+export interface MergeOptions {
+    /** Custom tombstone TTL in milliseconds (default: 30 days) */
+    tombstoneTtlMs?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Check if a bead is a tombstone (soft-deleted)
+ */
+export declare function isTombstone(bead: BeadExport): boolean;
+/**
+ * Check if a tombstone has expired (resurrection allowed)
+ *
+ * @param bead - The bead to check
+ * @param ttlMs - TTL in milliseconds (default: 30 days)
+ * @returns true if tombstone is expired, false otherwise
+ */
+export declare function isExpiredTombstone(bead: BeadExport, ttlMs?: number): boolean;
+/**
+ * Perform 3-way merge of JSONL bead arrays
+ *
+ * @param base - Common ancestor (e.g., git merge-base)
+ * @param left - Local changes (e.g., HEAD)
+ * @param right - Remote changes (e.g., MERGE_HEAD)
+ * @param options - Merge options
+ * @returns Merged beads and any conflicts
+ */
+export declare function merge3Way(base: BeadExport[], left: BeadExport[], right: BeadExport[], options?: MergeOptions): MergeResult;
+/**
+ * Merge JSONL strings (convenience wrapper)
+ *
+ * @param baseJsonl - Base JSONL string
+ * @param leftJsonl - Left JSONL string
+ * @param rightJsonl - Right JSONL string
+ * @param options - Merge options
+ * @returns Merged JSONL string
+ */
+export declare function mergeJsonl(baseJsonl: string, leftJsonl: string, rightJsonl: string, options?: MergeOptions): {
+    jsonl: string;
+    conflicts: string[];
+};
+//# sourceMappingURL=merge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/beads/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,2CAA2C;AAC3C,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,QAA0B,CAAC;AAE5D,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAElD,gCAAgC;AAChC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAM5C;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,yDAAyD;IACzD,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA0BD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,MAAiC,GACvC,OAAO,CAyBT;AAwUD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,UAAU,EAAE,EAClB,IAAI,EAAE,UAAU,EAAE,EAClB,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,GAAE,YAAiB,GACzB,WAAW,CA0Jb;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,YAAiB,GACzB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAoBxC"}

package/dist/beads/migrations.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Beads Schema Migration (v6)
+ *
+ * Adds beads-specific tables to the shared PGLite database.
+ * This migration extends the existing swarm-mail schema.
+ *
+ * ## Migration Strategy
+ * - Migration v6 adds beads tables to existing swarm-mail schema (v1-v5)
+ * - Shares same PGLite database instance and migration system
+ * - Uses same schema_version table for tracking
+ *
+ * ## Tables Created
+ * - beads: Core bead records (parallel to steveyegge/beads issues table)
+ * - bead_dependencies: Dependency relationships between beads
+ * - bead_labels: String tags for categorization
+ * - bead_comments: Comments/notes on beads
+ * - blocked_beads_cache: Materialized view for fast blocked queries
+ * - dirty_beads: Tracks beads that need JSONL export
+ *
+ * ## Design Notes
+ * - Uses BIGINT for timestamps (Unix ms, like swarm-mail events)
+ * - Uses TEXT for IDs (like steveyegge/beads)
+ * - CASCADE deletes for referential integrity
+ * - Indexes for common query patterns
+ * - CHECK constraints for data integrity
+ *
+ * @module beads/migrations
+ */
+import type { Migration } from "../streams/migrations.js";
+/**
+ * Migration v6: Add beads tables
+ *
+ * This migration is designed to be appended to the existing migrations array
+ * in src/streams/migrations.ts.
+ */
+export declare const beadsMigration: Migration;
+/**
+ * Export as array for convenience
+ */
+export declare const beadsMigrations: Migration[];
+//# sourceMappingURL=migrations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/beads/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,SAoH5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,EAAqB,CAAC"}

package/dist/beads/operations.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bead Operations - High-level CRUD operations using BeadsAdapter
+ *
+ * Convenience functions that wrap BeadsAdapter with validation.
+ * Plugin tools should use these operations instead of calling adapter directly.
+ *
+ * ## Layering
+ * - BeadsAdapter: Low-level event sourcing operations
+ * - operations.ts: High-level validated CRUD (THIS FILE)
+ * - Plugin tools: Type-safe Zod-validated wrappers
+ */
+import type { BeadsAdapter, Bead, QueryBeadsOptions } from "../types/beads-adapter.js";
+import { type CreateBeadOptions, type UpdateBeadOptions } from "./validation.js";
+/**
+ * Create a new bead with validation
+ *
+ * @throws {Error} If validation fails
+ */
+export declare function createBead(adapter: BeadsAdapter, projectKey: string, options: CreateBeadOptions): Promise<Bead>;
+/**
+ * Get a bead by ID
+ *
+ * @returns Bead or null if not found
+ */
+export declare function getBead(adapter: BeadsAdapter, projectKey: string, beadId: string): Promise<Bead | null>;
+/**
+ * Update a bead with validation
+ *
+ * @throws {Error} If validation fails or bead not found
+ */
+export declare function updateBead(adapter: BeadsAdapter, projectKey: string, beadId: string, updates: UpdateBeadOptions): Promise<Bead>;
+/**
+ * Close a bead
+ *
+ * @throws {Error} If bead not found
+ */
+export declare function closeBead(adapter: BeadsAdapter, projectKey: string, beadId: string, reason: string, closedBy?: string): Promise<Bead>;
+/**
+ * Reopen a closed bead
+ *
+ * @throws {Error} If bead not found or invalid transition
+ */
+export declare function reopenBead(adapter: BeadsAdapter, projectKey: string, beadId: string, reopenedBy?: string): Promise<Bead>;
+/**
+ * Delete a bead (soft delete - creates tombstone)
+ *
+ * @throws {Error} If bead not found
+ */
+export declare function deleteBead(adapter: BeadsAdapter, projectKey: string, beadId: string, reason: string, deletedBy?: string): Promise<void>;
+/**
+ * Search beads by title
+ *
+ * Simple text search across bead titles with optional filters.
+ */
+export declare function searchBeads(adapter: BeadsAdapter, projectKey: string, query: string, filter?: QueryBeadsOptions): Promise<Bead[]>;
+//# sourceMappingURL=operations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/beads/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,IAAI,EACJ,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAEzB;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAEtB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,EAAE,CAAC,CAejB"}

package/dist/beads/projections.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Beads Projections Layer - Update and query materialized views
+ *
+ * Projections are the read-side of CQRS. They update denormalized
+ * materialized views when events are appended, and provide query methods.
+ *
+ * ## Architecture
+ * - Event store is source of truth (write side)
+ * - Projections are cached views (read side)
+ * - Events trigger projection updates
+ * - Queries read from projections (fast)
+ *
+ * ## Key projections:
+ * - beads table: Main bead records
+ * - bead_dependencies: Dependency relationships
+ * - bead_labels: String tags
+ * - bead_comments: Comments/notes
+ * - blocked_beads_cache: Cached blocker lookups
+ * - dirty_beads: Tracks changes for export
+ *
+ * @module beads/projections
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+import type { Bead, BeadComment, BeadDependency, QueryBeadsOptions } from "../types/beads-adapter.js";
+type BeadEvent = {
+    type: string;
+    project_key: string;
+    bead_id: string;
+    timestamp: number;
+    [key: string]: unknown;
+};
+/**
+ * Update projections based on an event
+ *
+ * This is called by the event store after appending an event.
+ * Routes to specific handlers based on event type.
+ */
+export declare function updateProjections(db: DatabaseAdapter, event: BeadEvent): Promise<void>;
+/**
+ * Get a bead by ID
+ */
+export declare function getBead(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<Bead | null>;
+/**
+ * Query beads with filters
+ */
+export declare function queryBeads(db: DatabaseAdapter, projectKey: string, options?: QueryBeadsOptions): Promise<Bead[]>;
+/**
+ * Get dependencies for a bead
+ */
+export declare function getDependencies(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<BeadDependency[]>;
+/**
+ * Get beads that depend on this bead
+ */
+export declare function getDependents(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<BeadDependency[]>;
+/**
+ * Check if bead is blocked
+ */
+export declare function isBlocked(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<boolean>;
+/**
+ * Get blockers for a bead
+ */
+export declare function getBlockers(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<string[]>;
+/**
+ * Get labels for a bead
+ */
+export declare function getLabels(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<string[]>;
+/**
+ * Get comments for a bead
+ */
+export declare function getComments(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<BeadComment[]>;
+/**
+ * Get next ready bead (unblocked, highest priority)
+ */
+export declare function getNextReadyBead(db: DatabaseAdapter, projectKey: string): Promise<Bead | null>;
+/**
+ * Get all in-progress beads
+ */
+export declare function getInProgressBeads(db: DatabaseAdapter, projectKey: string): Promise<Bead[]>;
+/**
+ * Get all blocked beads with their blockers
+ */
+export declare function getBlockedBeads(db: DatabaseAdapter, projectKey: string): Promise<Array<{
+    bead: Bead;
+    blockers: string[];
+}>>;
+/**
+ * Mark bead as dirty for JSONL export
+ */
+export declare function markBeadDirty(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<void>;
+/**
+ * Get all dirty beads
+ */
+export declare function getDirtyBeads(db: DatabaseAdapter, projectKey: string): Promise<string[]>;
+/**
+ * Clear dirty flag after export
+ */
+export declare function clearDirtyBead(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<void>;
+/**
+ * Clear all dirty flags
+ */
+export declare function clearAllDirtyBeads(db: DatabaseAdapter, projectKey: string): Promise<void>;
+export {};
+//# sourceMappingURL=projections.d.ts.map

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

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

package/dist/beads/queries.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Beads Query Functions
+ *
+ * High-level query functions for common bead operations:
+ * - Ready work (unblocked beads with sort policies)
+ * - Blocked issues with blockers
+ * - Epics eligible for closure
+ * - Stale issues
+ * - Statistics
+ *
+ * Based on steveyegge/beads query patterns.
+ *
+ * @module beads/queries
+ */
+import type { Bead, BeadStatus, BeadsAdapter } from "../types/beads-adapter.js";
+/**
+ * Sort policy for ready work queries
+ *
+ * - hybrid (default): Recent issues (<48h) by priority, older by age
+ * - priority: Always priority first, then creation date
+ * - oldest: Creation date ascending (backlog clearing)
+ */
+export type SortPolicy = "hybrid" | "priority" | "oldest";
+export interface ReadyWorkOptions {
+    limit?: number;
+    assignee?: string;
+    unassigned?: boolean;
+    labels?: string[];
+    sortPolicy?: SortPolicy;
+}
+export interface BlockedBead {
+    bead: Bead;
+    blockers: string[];
+}
+export interface EpicStatus {
+    epic_id: string;
+    title: string;
+    total_children: number;
+    closed_children: number;
+}
+export interface StaleOptions {
+    status?: BeadStatus;
+    limit?: number;
+}
+export interface Statistics {
+    total_beads: number;
+    open: number;
+    in_progress: number;
+    closed: number;
+    blocked: number;
+    ready: number;
+    by_type: Record<string, number>;
+}
+/**
+ * Get ready work (unblocked, prioritized)
+ *
+ * By default returns both 'open' and 'in_progress' beads so epics/tasks
+ * ready to close are visible (matching steveyegge/beads behavior).
+ */
+export declare function getReadyWork(adapter: BeadsAdapter, projectKey: string, options?: ReadyWorkOptions): Promise<Bead[]>;
+/**
+ * Get all blocked beads with their blockers
+ */
+export declare function getBlockedIssues(adapter: BeadsAdapter, projectKey: string): Promise<BlockedBead[]>;
+/**
+ * Get epics eligible for closure (all children closed)
+ */
+export declare function getEpicsEligibleForClosure(adapter: BeadsAdapter, projectKey: string): Promise<EpicStatus[]>;
+/**
+ * Get stale issues (not updated in N days)
+ */
+export declare function getStaleIssues(adapter: BeadsAdapter, projectKey: string, days: number, options?: StaleOptions): Promise<Bead[]>;
+/**
+ * Get aggregate statistics
+ */
+export declare function getStatistics(adapter: BeadsAdapter, projectKey: string): Promise<Statistics>;
+//# sourceMappingURL=queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/beads/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,EAAE,CAAC,CA2DjB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,EAAE,CAAC,CAmBxB;AAED;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,EAAE,CAAC,CA4BvB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,EAAE,CAAC,CAmCjB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CA4ErB"}

package/dist/beads/store.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Beads Event Store - Append-only event log for bead operations
+ *
+ * Integrates bead events (from opencode-swarm-plugin) into the shared
+ * swarm-mail event store. Follows same pattern as streams/store.ts but
+ * for bead-specific events.
+ *
+ * ## Architecture
+ * - Bead events stored in shared `events` table (same as agent/message events)
+ * - Events trigger updateProjections() to update materialized views
+ * - Events are NOT replayed for state (hybrid model - projections are source of truth)
+ * - Event log provides audit trail and debugging for swarm coordination
+ *
+ * ## Event Flow
+ * 1. appendBeadEvent() -> INSERT INTO events
+ * 2. updateProjections() -> UPDATE materialized views (beads, dependencies, labels, etc.)
+ * 3. Query operations read from projections (fast)
+ *
+ * @module beads/store
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+import type { BeadEvent } from "./events.js";
+/**
+ * Options for reading bead events
+ */
+export interface ReadBeadEventsOptions {
+    /** Filter by project key */
+    projectKey?: string;
+    /** Filter by bead ID */
+    beadId?: string;
+    /** Filter by event types */
+    types?: BeadEvent["type"][];
+    /** Events after this timestamp */
+    since?: number;
+    /** Events before this timestamp */
+    until?: number;
+    /** Events after this sequence number */
+    afterSequence?: number;
+    /** Maximum number of events to return */
+    limit?: number;
+    /** Skip this many events (pagination) */
+    offset?: number;
+}
+/**
+ * Append a bead event to the shared event store
+ *
+ * Events are stored in the same `events` table as agent/message events.
+ * Triggers updateProjections() to update materialized views.
+ *
+ * @param event - Bead event to append
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ * @returns Event with id and sequence number
+ */
+export declare function appendBeadEvent(event: BeadEvent, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<BeadEvent & {
+    id: number;
+    sequence: number;
+}>;
+/**
+ * Read bead events with optional filters
+ *
+ * Queries the shared events table for bead events (type starts with "bead_").
+ *
+ * @param options - Filter options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ * @returns Array of bead events with id and sequence
+ */
+export declare function readBeadEvents(options?: ReadBeadEventsOptions, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Array<BeadEvent & {
+    id: number;
+    sequence: number;
+}>>;
+/**
+ * Replay bead events to rebuild materialized views
+ *
+ * Useful for:
+ * - Recovering from projection corruption
+ * - Migrating to new schema
+ * - Debugging state issues
+ *
+ * Note: Unlike swarm-mail agent events, bead projections are NOT rebuilt
+ * from events in normal operation (hybrid CRUD + audit trail model).
+ * This function is for recovery/debugging only.
+ *
+ * @param options - Replay options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ * @returns Stats about replay operation
+ */
+export declare function replayBeadEvents(options?: {
+    projectKey?: string;
+    fromSequence?: number;
+    clearViews?: boolean;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<{
+    eventsReplayed: number;
+    duration: number;
+}>;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/beads/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA+B7C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;IAC5B,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,SAAS,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA2BvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE,qBAA0B,EACnC,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAoF9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;CACjB,EACN,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAyEvD"}

package/dist/beads/validation.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bead Validation - Port of steveyegge/beads internal/validation/bead.go
+ *
+ * Implements validation rules from steveyegge/beads internal/types/types.go Validate() method.
+ *
+ * ## Business Rules
+ * - Title required, max 500 chars
+ * - Priority 0-4 (0=critical, 4=low)
+ * - Valid status: open, in_progress, blocked, closed, tombstone
+ * - Valid type: bug, feature, task, epic, chore, message
+ * - closed_at only when status=closed
+ * - deleted_at required when status=tombstone
+ * - Status transitions enforce state machine
+ *
+ * ## Status Transition Rules
+ * - open -> in_progress, blocked, closed
+ * - in_progress -> open, blocked, closed
+ * - blocked -> open, in_progress, closed
+ * - closed -> open (reopen only)
+ * - tombstone -> (no transitions, permanent)
+ *
+ * Direct transitions to tombstone are prohibited - use delete operation instead.
+ */
+import type { BeadStatus, BeadType } from "../types/beads-adapter.js";
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export interface CreateBeadOptions {
+    title: string;
+    type: BeadType;
+    priority?: number;
+    description?: string;
+    parent_id?: string;
+    assignee?: string;
+    created_by?: string;
+}
+export interface UpdateBeadOptions {
+    title?: string;
+    description?: string;
+    priority?: number;
+    assignee?: string;
+}
+/**
+ * Validate bead creation options
+ *
+ * @param options - Bead creation options
+ * @returns Validation result with errors if invalid
+ */
+export declare function validateCreateBead(options: CreateBeadOptions): ValidationResult;
+/**
+ * Validate bead update options
+ *
+ * @param options - Bead update options
+ * @returns Validation result with errors if invalid
+ */
+export declare function validateUpdateBead(options: UpdateBeadOptions): ValidationResult;
+/**
+ * Validate status transition
+ *
+ * Enforces state machine rules:
+ * - open -> in_progress, blocked, closed
+ * - in_progress -> open, blocked, closed
+ * - blocked -> open, in_progress, closed
+ * - closed -> open (reopen only)
+ * - tombstone -> (no transitions, permanent)
+ *
+ * Direct transitions to tombstone are prohibited - use delete operation.
+ *
+ * @param currentStatus - Current bead status
+ * @param newStatus - Target status
+ * @returns Validation result with errors if invalid
+ */
+export declare function validateStatusTransition(currentStatus: BeadStatus, newStatus: BeadStatus): ValidationResult;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/beads/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,GACzB,gBAAgB,CAmClB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,GACzB,gBAAgB,CAyBlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,UAAU,EACzB,SAAS,EAAE,UAAU,GACpB,gBAAgB,CA+ClB"}

package/dist/daemon.d.ts

@@ -1,8 +1,8 @@
 /**
- * Daemon Lifecycle Management for pglite-server
+ * Daemon Lifecycle Management for PGLiteSocketServer
  *
- * Provides start/stop/health functionality for the pglite-server daemon process.
- * Uses detached child_process for background operation with PID file tracking.
+ * Provides start/stop/health functionality for in-process PGLiteSocketServer.
+ * Uses module-level state to track active server instance.
  *
  * ## Usage
  * ```typescript
@@ -90,9 +90,9 @@ export declare function isDaemonRunning(projectPath?: string): Promise<boolean>;
  */
 export declare function healthCheck(options: Pick<DaemonOptions, "port" | "host" | "path">): Promise<boolean>;
 /**
- * Start pglite-server daemon
+ * Start PGLiteSocketServer daemon in-process
  *
- * Spawns pglite-server as a detached background process.
+ * Creates PGlite instance and starts PGLiteSocketServer.
  * Writes PID file and waits for server to be ready via health check.
  *
  * If daemon is already running, returns existing daemon info.
@@ -120,15 +120,14 @@ export declare function healthCheck(options: Pick<DaemonOptions, "port" | "host"
  */
 export declare function startDaemon(options?: DaemonOptions): Promise<DaemonInfo>;
 /**
- * Stop pglite-server daemon
+ * Stop PGLiteSocketServer daemon
  *
- * Sends SIGTERM to the daemon process and waits for clean shutdown.
- * Cleans up PID file after process exits.
+ * Performs graceful shutdown: CHECKPOINT → server.stop() → db.close()
+ * Cleans up PID file and module-level state.
  *
  * If daemon is not running, this is a no-op (not an error).
  *
  * @param projectPath - Optional project root path
- * @throws Error if daemon doesn't stop within timeout
  *
  * @example
  * ```typescript