@claude-flow/plugin-gastown-bridge 0.1.2 → 0.1.4

package/dist/index-BzkAx4ho.d.ts

@@ -0,0 +1,785 @@
+import { EventEmitter } from 'events';
+import { c as ConvoyStatus, s as ConvoyProgress, C as Convoy } from './types-CMoOZXrm.js';
+import { B as BdBridge } from './bd-bridge-C9wTbkhi.js';
+
+/**
+ * Convoy Tracker
+ *
+ * Manages convoy lifecycle including creation, modification, progress
+ * tracking, and completion. Convoys are work-order groups that track
+ * related beads (issues) through their lifecycle.
+ *
+ * Features:
+ * - Create and manage convoy groups
+ * - Add/remove beads to convoys
+ * - Track progress and status changes
+ * - Event emission for status transitions
+ * - Integration with bd-bridge for bead operations
+ *
+ * @module gastown-bridge/convoy/tracker
+ */
+
+/**
+ * Convoy event types
+ */
+type ConvoyEventType = 'convoy:created' | 'convoy:started' | 'convoy:progressed' | 'convoy:completed' | 'convoy:cancelled' | 'convoy:paused' | 'convoy:resumed' | 'convoy:issue:added' | 'convoy:issue:removed' | 'convoy:issue:updated';
+/**
+ * Convoy event payload
+ */
+interface ConvoyEvent {
+    /** Event type */
+    type: ConvoyEventType;
+    /** Convoy ID */
+    convoyId: string;
+    /** Convoy name */
+    convoyName: string;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Previous status (for status change events) */
+    previousStatus?: ConvoyStatus;
+    /** Current status */
+    status: ConvoyStatus;
+    /** Progress at time of event */
+    progress: ConvoyProgress;
+    /** Issue IDs affected (for issue events) */
+    issues?: string[];
+    /** Cancellation reason (for cancelled events) */
+    reason?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Convoy tracker configuration
+ */
+interface ConvoyTrackerConfig {
+    /** BD bridge instance for bead operations */
+    bdBridge: BdBridge;
+    /** Auto-update progress on issue changes */
+    autoUpdateProgress?: boolean;
+    /** Progress update interval in milliseconds */
+    progressUpdateInterval?: number;
+    /** Enable persistent storage */
+    persistConvoys?: boolean;
+    /** Storage path for convoy data */
+    storagePath?: string;
+}
+/**
+ * Logger interface
+ */
+interface ConvoyLogger {
+    debug: (msg: string, meta?: Record<string, unknown>) => void;
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Convoy Tracker
+ *
+ * Manages convoy lifecycle and tracks progress of grouped work.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ConvoyTracker({
+ *   bdBridge: await createBdBridge().initialize(),
+ * });
+ *
+ * // Create a convoy
+ * const convoy = await tracker.create(
+ *   'Sprint 1',
+ *   ['gt-abc12', 'gt-def34', 'gt-ghi56'],
+ *   'First sprint tasks'
+ * );
+ *
+ * // Monitor progress
+ * tracker.on('convoy:progressed', (event) => {
+ *   console.log(`Progress: ${event.progress.closed}/${event.progress.total}`);
+ * });
+ *
+ * // Check status
+ * const status = await tracker.getStatus(convoy.id);
+ * ```
+ */
+declare class ConvoyTracker extends EventEmitter {
+    private bdBridge;
+    private convoys;
+    private logger;
+    private config;
+    private progressTimers;
+    constructor(config: ConvoyTrackerConfig, logger?: ConvoyLogger);
+    /**
+     * Create a new convoy
+     *
+     * @param name - Convoy name
+     * @param issues - Issue IDs to include
+     * @param description - Optional description
+     * @returns Created convoy
+     */
+    create(name: string, issues: string[], description?: string): Promise<Convoy>;
+    /**
+     * Add issues to an existing convoy
+     *
+     * @param convoyId - Convoy ID
+     * @param issues - Issue IDs to add
+     * @returns Updated convoy
+     */
+    addIssues(convoyId: string, issues: string[]): Promise<Convoy>;
+    /**
+     * Remove issues from a convoy
+     *
+     * @param convoyId - Convoy ID
+     * @param issues - Issue IDs to remove
+     * @returns Updated convoy
+     */
+    removeIssues(convoyId: string, issues: string[]): Promise<Convoy>;
+    /**
+     * Get convoy status
+     *
+     * @param convoyId - Convoy ID
+     * @returns Convoy with updated progress
+     */
+    getStatus(convoyId: string): Promise<Convoy>;
+    /**
+     * Mark convoy as complete
+     *
+     * @param convoyId - Convoy ID
+     * @returns Completed convoy
+     */
+    complete(convoyId: string): Promise<Convoy>;
+    /**
+     * Cancel a convoy
+     *
+     * @param convoyId - Convoy ID
+     * @param reason - Cancellation reason
+     * @returns Cancelled convoy
+     */
+    cancel(convoyId: string, reason?: string): Promise<Convoy>;
+    /**
+     * Pause a convoy
+     *
+     * @param convoyId - Convoy ID
+     * @returns Paused convoy
+     */
+    pause(convoyId: string): Promise<Convoy>;
+    /**
+     * Resume a paused convoy
+     *
+     * @param convoyId - Convoy ID
+     * @returns Resumed convoy
+     */
+    resume(convoyId: string): Promise<Convoy>;
+    /**
+     * List all convoys
+     *
+     * @param status - Optional status filter
+     * @returns Array of convoys
+     */
+    listConvoys(status?: ConvoyStatus): Convoy[];
+    /**
+     * Get convoy by ID
+     *
+     * @param convoyId - Convoy ID
+     * @returns Convoy or undefined
+     */
+    getConvoy(convoyId: string): Convoy | undefined;
+    /**
+     * Delete a convoy
+     *
+     * @param convoyId - Convoy ID
+     * @returns True if deleted
+     */
+    deleteConvoy(convoyId: string): boolean;
+    /**
+     * Calculate progress for a set of issues
+     */
+    private calculateProgress;
+    /**
+     * Verify issues exist
+     */
+    private verifyIssues;
+    /**
+     * Fetch beads by IDs
+     */
+    private fetchBeads;
+    /**
+     * Map CLI bead type to Gas Town status
+     */
+    private mapBeadStatus;
+    /**
+     * Start progress tracking timer
+     */
+    private startProgressTracking;
+    /**
+     * Stop progress tracking timer
+     */
+    private stopProgressTracking;
+    /**
+     * Emit convoy event
+     */
+    private emitConvoyEvent;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+/**
+ * Create a new convoy tracker instance
+ */
+declare function createConvoyTracker(config: ConvoyTrackerConfig, logger?: ConvoyLogger): ConvoyTracker;
+
+/**
+ * Lazy Loading Utilities for Gas Town Bridge Plugin
+ *
+ * Provides lazy initialization patterns to defer resource loading
+ * until first use, reducing initial memory footprint and startup time.
+ *
+ * Features:
+ * - Lazy WASM module loading
+ * - Deferred convoy observer initialization
+ * - Lazy bridge initialization
+ * - Resource cleanup on idle
+ *
+ * @module gastown-bridge/memory/lazy
+ */
+/**
+ * Lazy value state
+ */
+type LazyState = 'uninitialized' | 'initializing' | 'initialized' | 'error' | 'disposed';
+/**
+ * Lazy initialization options
+ */
+interface LazyOptions<T> {
+    /** Factory function to create the value */
+    factory: () => T | Promise<T>;
+    /** Optional cleanup function */
+    cleanup?: (value: T) => void | Promise<void>;
+    /** Auto-dispose after idle time (ms, 0 = never) */
+    idleTimeout?: number;
+    /** Error handler */
+    onError?: (error: Error) => void;
+    /** Name for debugging */
+    name?: string;
+}
+/**
+ * Lazy loader statistics
+ */
+interface LazyStats {
+    name: string;
+    state: LazyState;
+    initCount: number;
+    disposeCount: number;
+    errorCount: number;
+    lastInitTime?: Date;
+    lastAccessTime?: Date;
+    initDurationMs?: number;
+}
+/**
+ * Lazy value wrapper with automatic initialization
+ *
+ * @example
+ * ```typescript
+ * const lazyWasm = new Lazy({
+ *   name: 'wasm-module',
+ *   factory: async () => await loadWasmModule(),
+ *   cleanup: (wasm) => wasm.dispose(),
+ *   idleTimeout: 60000, // Auto-dispose after 1 minute of inactivity
+ * });
+ *
+ * // First access triggers initialization
+ * const wasm = await lazyWasm.get();
+ *
+ * // Check if initialized without triggering
+ * if (lazyWasm.isInitialized()) { ... }
+ *
+ * // Manual disposal
+ * await lazyWasm.dispose();
+ * ```
+ */
+declare class Lazy<T> {
+    private value?;
+    private state;
+    private initPromise?;
+    private idleTimer?;
+    private options;
+    private stats;
+    constructor(options: LazyOptions<T>);
+    /**
+     * Get the lazy value, initializing if necessary
+     */
+    get(): Promise<T>;
+    /**
+     * Get synchronously (throws if not initialized)
+     */
+    getSync(): T;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get current state
+     */
+    getState(): LazyState;
+    /**
+     * Initialize without returning value
+     */
+    initialize(): Promise<T>;
+    /**
+     * Dispose the lazy value
+     */
+    dispose(): Promise<void>;
+    /**
+     * Get statistics
+     */
+    getStats(): Readonly<LazyStats>;
+    private resetIdleTimer;
+    private clearIdleTimer;
+}
+/**
+ * Get or create a lazy singleton
+ */
+declare function getLazySingleton<T>(key: string, options: LazyOptions<T>): Lazy<T>;
+/**
+ * Dispose a lazy singleton
+ */
+declare function disposeLazySingleton(key: string): Promise<void>;
+/**
+ * Dispose all lazy singletons
+ */
+declare function disposeAllLazySingletons(): Promise<void>;
+/**
+ * Lazy module loader for dynamic imports
+ *
+ * @example
+ * ```typescript
+ * const wasmLoader = new LazyModule(() => import('./wasm-loader.js'));
+ * const { parseFormula } = await wasmLoader.get();
+ * ```
+ */
+declare class LazyModule<T> {
+    private lazy;
+    constructor(importer: () => Promise<T>, options?: Omit<LazyOptions<T>, 'factory'>);
+    /**
+     * Get the module
+     */
+    get(): Promise<T>;
+    /**
+     * Check if loaded
+     */
+    isLoaded(): boolean;
+    /**
+     * Dispose module
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Lazy bridge wrapper for Gas Town bridges
+ *
+ * Defers bridge initialization until first use.
+ */
+declare class LazyBridge<T extends {
+    initialize?: () => Promise<void>;
+}> {
+    private lazy;
+    constructor(factory: () => T | Promise<T>, options?: Omit<LazyOptions<T>, 'factory'>);
+    /**
+     * Get the bridge
+     */
+    get(): Promise<T>;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Dispose bridge
+     */
+    dispose(): Promise<void>;
+    /**
+     * Get stats
+     */
+    getStats(): LazyStats;
+}
+/**
+ * Lazy WASM module loader with caching
+ */
+declare class LazyWasm<T> {
+    private lazy;
+    private cached;
+    constructor(loader: () => Promise<T>, options?: {
+        name?: string;
+        idleTimeout?: number;
+        onError?: (error: Error) => void;
+    });
+    /**
+     * Get the WASM module
+     */
+    get(): Promise<T>;
+    /**
+     * Check if loaded
+     */
+    isLoaded(): boolean;
+    /**
+     * Clear cache (module will be reloaded on next access)
+     */
+    clearCache(): void;
+    /**
+     * Get stats
+     */
+    getStats(): LazyStats;
+}
+/**
+ * Lazy observer pattern for convoy watching
+ *
+ * Defers observer creation until first watch request.
+ */
+declare class LazyObserver<T> {
+    private lazy;
+    private watchCount;
+    constructor(factory: () => T | Promise<T>, options?: Omit<LazyOptions<T>, 'factory'>);
+    /**
+     * Start watching (initializes observer if needed)
+     */
+    watch(): Promise<T>;
+    /**
+     * Stop watching (disposes observer if no more watchers)
+     */
+    unwatch(): Promise<void>;
+    /**
+     * Get current watch count
+     */
+    getWatchCount(): number;
+    /**
+     * Check if active
+     */
+    isActive(): boolean;
+    /**
+     * Force dispose
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Create a lazy property getter
+ */
+declare function createLazyProperty<T>(factory: () => T | Promise<T>, options?: Omit<LazyOptions<T>, 'factory'>): {
+    get: () => Promise<T>;
+    isInitialized: () => boolean;
+};
+
+/**
+ * Convoy Observer
+ *
+ * Monitors convoy completion by observing issue state changes
+ * and detecting when all tracked issues are complete. Uses
+ * WASM-accelerated graph analysis for dependency resolution.
+ *
+ * Features:
+ * - Watch convoys for completion
+ * - Detect blocking issues
+ * - Identify ready-to-work issues
+ * - WASM-accelerated dependency graph analysis
+ * - Configurable polling intervals
+ *
+ * @module gastown-bridge/convoy/observer
+ */
+
+/**
+ * WASM graph module interface
+ */
+interface WasmGraphModule {
+    /** Check if dependency graph has cycles */
+    has_cycle(beadsJson: string): boolean;
+    /** Find nodes participating in cycles */
+    find_cycle_nodes(beadsJson: string): string;
+    /** Get beads with no unresolved dependencies */
+    get_ready_beads(beadsJson: string): string;
+    /** Compute execution levels for parallel processing */
+    compute_levels(beadsJson: string): string;
+    /** Topological sort of beads */
+    topo_sort(beadsJson: string): string;
+    /** Critical path analysis */
+    critical_path(beadsJson: string): string;
+}
+/**
+ * Completion callback signature
+ */
+type CompletionCallback = (convoy: Convoy, allComplete: boolean) => void;
+/**
+ * Observer watch handle
+ */
+interface WatchHandle {
+    /** Convoy ID being watched */
+    convoyId: string;
+    /** Stop watching */
+    stop(): void;
+    /** Check if still watching */
+    isActive(): boolean;
+}
+/**
+ * Observer configuration
+ */
+interface ConvoyObserverConfig {
+    /** BD bridge instance */
+    bdBridge: BdBridge;
+    /** Convoy tracker instance */
+    tracker: ConvoyTracker;
+    /** Optional WASM graph module */
+    wasmModule?: WasmGraphModule;
+    /** Initial polling interval in milliseconds */
+    pollInterval?: number;
+    /** Maximum poll attempts before giving up */
+    maxPollAttempts?: number;
+    /** Enable WASM acceleration (falls back to JS if unavailable) */
+    useWasm?: boolean;
+    /** Enable exponential backoff for polling */
+    useExponentialBackoff?: boolean;
+    /** Maximum backoff interval in milliseconds */
+    maxBackoffInterval?: number;
+    /** Backoff multiplier (default: 1.5) */
+    backoffMultiplier?: number;
+    /** Enable delta-based updates (only emit on changes) */
+    deltaUpdatesOnly?: boolean;
+    /** Debounce interval for progress updates in milliseconds */
+    progressDebounceMs?: number;
+}
+/**
+ * Blocker information
+ */
+interface BlockerInfo {
+    /** Issue ID that is blocked */
+    blockedIssue: string;
+    /** Issue IDs that are blocking */
+    blockers: string[];
+    /** True if blockers are from within the convoy */
+    internalBlockers: boolean;
+}
+/**
+ * Ready issue information
+ */
+interface ReadyIssueInfo {
+    /** Issue ID */
+    id: string;
+    /** Issue title */
+    title: string;
+    /** Priority */
+    priority: number;
+    /** Execution level (for parallel processing) */
+    level: number;
+}
+/**
+ * Completion check result
+ */
+interface CompletionCheckResult {
+    /** True if all issues are complete */
+    allComplete: boolean;
+    /** Progress statistics */
+    progress: ConvoyProgress;
+    /** Issues that are still open */
+    openIssues: string[];
+    /** Issues that are in progress */
+    inProgressIssues: string[];
+    /** Issues that are blocked */
+    blockedIssues: BlockerInfo[];
+    /** Issues ready to work on */
+    readyIssues: ReadyIssueInfo[];
+    /** True if there are dependency cycles */
+    hasCycles: boolean;
+    /** Issues involved in cycles */
+    cycleIssues: string[];
+}
+/**
+ * Logger interface
+ */
+interface ObserverLogger {
+    debug: (msg: string, meta?: Record<string, unknown>) => void;
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Convoy Observer
+ *
+ * Monitors convoys for completion and provides dependency analysis.
+ *
+ * @example
+ * ```typescript
+ * const observer = new ConvoyObserver({
+ *   bdBridge,
+ *   tracker,
+ *   pollInterval: 5000,
+ *   useWasm: true,
+ * });
+ *
+ * // Watch for completion
+ * const handle = observer.watch(convoyId, (convoy, complete) => {
+ *   if (complete) {
+ *     console.log('Convoy complete!');
+ *   }
+ * });
+ *
+ * // Check blockers
+ * const blockers = await observer.getBlockers(convoyId);
+ *
+ * // Get ready issues
+ * const ready = await observer.getReadyIssues(convoyId);
+ *
+ * // Stop watching
+ * handle.stop();
+ * ```
+ */
+declare class ConvoyObserver extends EventEmitter {
+    private bdBridge;
+    private tracker;
+    private wasmModule?;
+    private logger;
+    private config;
+    private watchers;
+    private readonly beadCache;
+    private readonly completionCache;
+    private readonly fetchDedup;
+    private readonly progressEmitters;
+    private pendingSubscriptions;
+    private subscriptionFlushTimer;
+    constructor(config: ConvoyObserverConfig, logger?: ObserverLogger);
+    /**
+     * Watch a convoy for completion
+     *
+     * @param convoyId - Convoy ID to watch
+     * @param callback - Called on each check with completion status
+     * @returns Watch handle to stop watching
+     */
+    watch(convoyId: string, callback: CompletionCallback): WatchHandle;
+    /**
+     * Batch subscribe to multiple convoys
+     * Subscriptions are batched and flushed together for efficiency
+     *
+     * @param convoyId - Convoy ID to watch
+     * @param callback - Callback for completion status
+     */
+    batchSubscribe(convoyId: string, callback: CompletionCallback): void;
+    /**
+     * Flush pending subscriptions
+     */
+    private flushSubscriptions;
+    /**
+     * Check if all issues in a convoy are complete
+     *
+     * @param convoyId - Convoy ID
+     * @returns Completion check result with detailed status
+     */
+    checkCompletion(convoyId: string): Promise<CompletionCheckResult>;
+    /**
+     * Get blockers for all issues in a convoy
+     *
+     * @param convoyId - Convoy ID
+     * @returns Array of blocker information
+     */
+    getBlockers(convoyId: string): Promise<BlockerInfo[]>;
+    /**
+     * Get issues ready to work on (no unresolved dependencies)
+     *
+     * @param convoyId - Convoy ID
+     * @returns Array of ready issue information
+     */
+    getReadyIssues(convoyId: string): Promise<ReadyIssueInfo[]>;
+    /**
+     * Get execution order for convoy issues
+     *
+     * @param convoyId - Convoy ID
+     * @returns Ordered array of issue IDs
+     */
+    getExecutionOrder(convoyId: string): Promise<string[]>;
+    /**
+     * Stop watching a convoy
+     */
+    stopWatching(convoyId: string): void;
+    /**
+     * Stop all watchers
+     */
+    stopAll(): void;
+    /**
+     * Set WASM module
+     */
+    setWasmModule(module: WasmGraphModule): void;
+    /**
+     * Check if WASM is available
+     */
+    isWasmAvailable(): boolean;
+    /**
+     * Poll convoy for completion with exponential backoff
+     */
+    private pollConvoyWithBackoff;
+    /**
+     * Legacy poll convoy method (without backoff)
+     * @deprecated Use pollConvoyWithBackoff instead
+     */
+    private pollConvoy;
+    /**
+     * Fetch beads by IDs with caching, batch deduplication, and object pooling.
+     * Uses PooledBead from memory module for reduced allocations.
+     */
+    private fetchBeads;
+    /**
+     * Map CLI bead type to Gas Town status
+     */
+    private mapBeadStatus;
+    /**
+     * Convert beads to WASM node format
+     */
+    private beadsToWasmNodes;
+    /**
+     * Analyze dependencies with WASM
+     */
+    private analyzeWithWasm;
+    /**
+     * Analyze dependencies with JavaScript (fallback)
+     */
+    private analyzeWithJS;
+    /**
+     * Detect cycles using DFS (JavaScript)
+     */
+    private detectCyclesJS;
+    /**
+     * Find nodes in cycles (JavaScript)
+     */
+    private findCycleNodesJS;
+    /**
+     * Topological sort using Kahn's algorithm (JavaScript)
+     */
+    private topoSortJS;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+/**
+ * Create a new convoy observer instance
+ */
+declare function createConvoyObserver(config: ConvoyObserverConfig, logger?: ObserverLogger): ConvoyObserver;
+/**
+ * Create a lazy-initialized convoy observer.
+ * The observer is only created when first accessed (via watch() or checkCompletion()).
+ * Useful for deferring initialization until convoy monitoring is actually needed.
+ *
+ * @example
+ * ```typescript
+ * const lazyObserver = createLazyConvoyObserver(config);
+ *
+ * // Observer is NOT created yet
+ * console.log(lazyObserver.getWatchCount()); // 0
+ *
+ * // First watch triggers observer creation
+ * const observer = await lazyObserver.watch();
+ * const handle = observer.watch(convoyId, callback);
+ *
+ * // When done, unwatch to potentially dispose
+ * await lazyObserver.unwatch();
+ * ```
+ */
+declare function createLazyConvoyObserver(config: ConvoyObserverConfig, logger?: ObserverLogger): LazyObserver<ConvoyObserver>;
+/**
+ * Get lazy observer statistics
+ */
+declare function getLazyObserverStats(lazyObserver: LazyObserver<ConvoyObserver>): {
+    isActive: boolean;
+    watchCount: number;
+};
+
+export { type BlockerInfo as B, ConvoyTracker as C, type LazyStats as L, type ObserverLogger as O, type ReadyIssueInfo as R, type WasmGraphModule as W, ConvoyObserver as a, type CompletionCallback as b, type CompletionCheckResult as c, type ConvoyEvent as d, type ConvoyEventType as e, type ConvoyLogger as f, type ConvoyObserverConfig as g, type ConvoyTrackerConfig as h, Lazy as i, LazyBridge as j, LazyModule as k, LazyObserver as l, type LazyOptions as m, type LazyState as n, LazyWasm as o, type WatchHandle as p, createConvoyObserver as q, createConvoyTracker as r, createLazyConvoyObserver as s, createLazyProperty as t, disposeAllLazySingletons as u, disposeLazySingleton as v, getLazyObserverStats as w, getLazySingleton as x };