swarm-mail 0.1.3 → 0.2.0

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

@@ -0,0 +1,139 @@
+/**
+ * Daemon Lifecycle Management for pglite-server
+ *
+ * Provides start/stop/health functionality for the pglite-server daemon process.
+ * Uses detached child_process for background operation with PID file tracking.
+ *
+ * ## Usage
+ * ```typescript
+ * import { startDaemon, stopDaemon, isDaemonRunning, healthCheck } from 'swarm-mail/daemon';
+ *
+ * // Start daemon
+ * const { pid, port } = await startDaemon({ port: 5433 });
+ *
+ * // Check health
+ * const healthy = await healthCheck({ port: 5433 });
+ *
+ * // Stop daemon
+ * await stopDaemon('/path/to/project');
+ * ```
+ */
+/**
+ * Daemon start options
+ */
+export interface DaemonOptions {
+    /** TCP port to bind (default: 5433) */
+    port?: number;
+    /** Host to bind (default: 127.0.0.1) */
+    host?: string;
+    /** Unix socket path (alternative to port/host) */
+    path?: string;
+    /** Database path (default: project .opencode/streams or ~/.opencode/streams) */
+    dbPath?: string;
+    /** Project path for PID file location (default: global ~/.opencode) */
+    projectPath?: string;
+}
+/**
+ * Daemon info returned by startDaemon
+ */
+export interface DaemonInfo {
+    /** Process ID */
+    pid: number;
+    /** TCP port (if using TCP) */
+    port?: number;
+    /** Unix socket path (if using socket) */
+    socketPath?: string;
+}
+/**
+ * Get PID file path for a project
+ *
+ * Stores PID file in $TMPDIR alongside the streams database.
+ * Path format: `$TMPDIR/opencode-<project-name>-<hash>/pglite-server.pid`
+ * Falls back to global `$TMPDIR/opencode-global/pglite-server.pid`
+ *
+ * @param projectPath - Optional project root path
+ * @returns Absolute path to PID file
+ */
+export declare function getPidFilePath(projectPath?: string): string;
+/**
+ * Check if daemon is running
+ *
+ * Checks both PID file existence and process liveness.
+ *
+ * @param projectPath - Optional project root path
+ * @returns true if daemon is running
+ *
+ * @example
+ * ```typescript
+ * if (!await isDaemonRunning()) {
+ *   await startDaemon();
+ * }
+ * ```
+ */
+export declare function isDaemonRunning(projectPath?: string): Promise<boolean>;
+/**
+ * Health check - verify daemon is responding
+ *
+ * Connects to the daemon and runs SELECT 1 query.
+ * Times out after 5 seconds.
+ *
+ * @param options - Connection options (port/host or path)
+ * @returns true if daemon is healthy
+ *
+ * @example
+ * ```typescript
+ * const healthy = await healthCheck({ port: 5433 });
+ * if (!healthy) {
+ *   console.error('Daemon not responding');
+ * }
+ * ```
+ */
+export declare function healthCheck(options: Pick<DaemonOptions, "port" | "host" | "path">): Promise<boolean>;
+/**
+ * Start pglite-server daemon
+ *
+ * Spawns pglite-server as a detached background process.
+ * Writes PID file and waits for server to be ready via health check.
+ *
+ * If daemon is already running, returns existing daemon info.
+ *
+ * @param options - Daemon configuration
+ * @returns Daemon info (PID and connection details)
+ * @throws Error if daemon fails to start
+ *
+ * @example
+ * ```typescript
+ * // Start with TCP port
+ * const { pid, port } = await startDaemon({ port: 5433 });
+ *
+ * // Start with Unix socket
+ * const { pid, socketPath } = await startDaemon({
+ *   path: '/tmp/swarm-mail-pglite.sock'
+ * });
+ *
+ * // Start with custom database path
+ * const { pid, port } = await startDaemon({
+ *   port: 5433,
+ *   dbPath: '/custom/path/to/db'
+ * });
+ * ```
+ */
+export declare function startDaemon(options?: DaemonOptions): Promise<DaemonInfo>;
+/**
+ * Stop pglite-server daemon
+ *
+ * Sends SIGTERM to the daemon process and waits for clean shutdown.
+ * Cleans up PID file after process exits.
+ *
+ * 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
+ * await stopDaemon('/path/to/project');
+ * ```
+ */
+export declare function stopDaemon(projectPath?: string): Promise<void>;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB3D;AAqGD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,GACrD,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAgErB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CpE"}

package/dist/index.d.ts

@@ -17,6 +17,11 @@
 export declare const SWARM_MAIL_VERSION = "0.1.0";
 export { createSwarmMailAdapter } from "./adapter";
 export type { DatabaseAdapter, SwarmMailAdapter, EventStoreAdapter, AgentAdapter, MessagingAdapter, ReservationAdapter, SchemaAdapter, ReadEventsOptions, InboxOptions, Message, Reservation, Conflict, } from "./types";
-export { getSwarmMail, createInMemorySwarmMail, closeSwarmMail, closeAllSwarmMail, getDatabasePath, PGlite, } from "./pglite";
+export { getSwarmMail, getSwarmMailSocket, createInMemorySwarmMail, closeSwarmMail, closeAllSwarmMail, getDatabasePath, getProjectTempDirName, hashProjectPath, PGlite, } from "./pglite";
+export { wrapPostgres, createSocketAdapter, } from "./socket-adapter";
+export type { SocketAdapterOptions } from "./socket-adapter";
 export * from "./streams";
+export * from "./beads";
+export { startDaemon, stopDaemon, isDaemonRunning, healthCheck, getPidFilePath, } from "./daemon";
+export type { DaemonOptions, DaemonInfo } from "./daemon";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAM1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,OAAO,EACP,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAMjB,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,MAAM,GACP,MAAM,UAAU,CAAC;AAMlB,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAM1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,OAAO,EACP,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAMjB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,MAAM,GACP,MAAM,UAAU,CAAC;AAMlB,OAAO,EACL,YAAY,EACZ,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAM7D,cAAc,WAAW,CAAC;AAM1B,cAAc,SAAS,CAAC;AAMxB,OAAO,EACL,WAAW,EACX,UAAU,EACV,eAAe,EACf,WAAW,EACX,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}