sqlew 4.0.4 → 4.1.0

package/dist/watcher/base-watcher.js

@@ -0,0 +1,130 @@
+/**
+ * Base Watcher - Common file watching functionality
+ *
+ * Provides shared infrastructure for file watchers:
+ * - chokidar v4 initialization
+ * - WSL detection and handling
+ * - Debounce management
+ * - Start/stop lifecycle
+ *
+ * @since v4.1.0
+ */
+import chokidar from 'chokidar';
+import { execSync } from 'child_process';
+import { debugLog } from '../utils/debug-logger.js';
+/**
+ * Abstract base class for file watchers
+ */
+export class BaseWatcher {
+    watcher = null;
+    isRunning = false;
+    debounceTimers = new Map();
+    debounceMs;
+    watcherName;
+    constructor(name, debounceMs = 2000) {
+        this.watcherName = name;
+        this.debounceMs = debounceMs;
+    }
+    /**
+     * Detect if running on WSL (Windows Subsystem for Linux)
+     */
+    isWSL() {
+        if (process.platform !== 'linux') {
+            return false;
+        }
+        try {
+            const result = execSync('uname -r', {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            return (result.toLowerCase().includes('microsoft') ||
+                result.toLowerCase().includes('wsl'));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Initialize chokidar watcher with common options
+     */
+    initializeWatcher(options) {
+        const isWSL = this.isWSL();
+        if (isWSL) {
+            debugLog('INFO', `${this.watcherName}: WSL detected`);
+        }
+        const watcherConfig = {
+            persistent: true,
+            ignoreInitial: options.ignoreInitial ?? true,
+            awaitWriteFinish: {
+                stabilityThreshold: options.debounceMs ?? this.debounceMs,
+                pollInterval: 100,
+            },
+            usePolling: options.usePolling ?? false,
+            interval: options.pollInterval ?? 100,
+        };
+        if (options.ignored && watcherConfig) {
+            watcherConfig.ignored = options.ignored;
+        }
+        return chokidar.watch(options.paths, watcherConfig);
+    }
+    /**
+     * Debounced handler - calls handler after debounce period
+     */
+    debounce(key, handler) {
+        // Clear existing timer for this key
+        const existingTimer = this.debounceTimers.get(key);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+        // Set new timer
+        const timer = setTimeout(async () => {
+            this.debounceTimers.delete(key);
+            try {
+                await handler();
+            }
+            catch (error) {
+                debugLog('ERROR', `${this.watcherName}: Error in debounced handler`, {
+                    error,
+                });
+            }
+        }, this.debounceMs);
+        this.debounceTimers.set(key, timer);
+    }
+    /**
+     * Stop the watcher
+     */
+    async stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        try {
+            // Clear all debounce timers
+            this.debounceTimers.forEach((timer) => clearTimeout(timer));
+            this.debounceTimers.clear();
+            // Close watcher
+            if (this.watcher) {
+                await this.watcher.close();
+                this.watcher = null;
+            }
+            this.isRunning = false;
+            debugLog('INFO', `${this.watcherName}: Stopped`);
+        }
+        catch (error) {
+            debugLog('ERROR', `${this.watcherName}: Error stopping`, { error });
+            throw error;
+        }
+    }
+    /**
+     * Check if watcher is running
+     */
+    getIsRunning() {
+        return this.isRunning;
+    }
+    /**
+     * Get watcher name for logging
+     */
+    getName() {
+        return this.watcherName;
+    }
+}
+//# sourceMappingURL=base-watcher.js.map

package/dist/watcher/base-watcher.js.map

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

package/dist/watcher/index.d.ts

@@ -2,7 +2,10 @@
  * Watcher module exports
  * Provides file watching and test execution functionality
  */
+export { BaseWatcher } from './base-watcher.js';
+export type { WatcherOptions } from './base-watcher.js';
 export { FileWatcher } from './file-watcher.js';
+export { QueueWatcher, startQueueWatcher, stopQueueWatcher } from './queue-watcher.js';
 export { executeAcceptanceCriteria } from './test-executor.js';
 export type { CheckResult } from './test-executor.js';
 export { GitIgnoreParser, createGitIgnoreParser, BUILT_IN_IGNORE_PATTERNS } from './gitignore-parser.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/watcher/index.js

@@ -2,7 +2,9 @@
  * Watcher module exports
  * Provides file watching and test execution functionality
  */
+export { BaseWatcher } from './base-watcher.js';
 export { FileWatcher } from './file-watcher.js';
+export { QueueWatcher, startQueueWatcher, stopQueueWatcher } from './queue-watcher.js';
 export { executeAcceptanceCriteria } from './test-executor.js';
 export { GitIgnoreParser, createGitIgnoreParser, BUILT_IN_IGNORE_PATTERNS } from './gitignore-parser.js';
 //# sourceMappingURL=index.js.map

package/dist/watcher/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/watcher/queue-watcher.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Queue Watcher - Monitors hook queue file for changes
+ *
+ * Watches `.sqlew/queue/pending.json` and processes queued decisions
+ * when hooks write to the queue file.
+ *
+ * Flow:
+ * 1. Hook writes to queue file (fast, <100ms)
+ * 2. QueueWatcher detects change
+ * 3. processHookQueue() registers decisions in DB
+ *
+ * @since v4.1.0
+ */
+import { BaseWatcher } from './base-watcher.js';
+/**
+ * QueueWatcher - Singleton for monitoring hook queue
+ */
+export declare class QueueWatcher extends BaseWatcher {
+    private static instance;
+    private projectRoot;
+    private processing;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(projectRoot?: string): QueueWatcher;
+    /**
+     * Reset singleton (for testing)
+     */
+    static reset(): void;
+    /**
+     * Start watching the queue file
+     */
+    start(): Promise<void>;
+    /**
+     * Handle queue file change
+     */
+    private handleQueueChange;
+    /**
+     * Process queue if items exist
+     */
+    private processQueueIfNeeded;
+    /**
+     * Process a single queue item
+     */
+    private processItem;
+    /**
+     * Get watcher status
+     */
+    getStatus(): {
+        running: boolean;
+        projectRoot: string;
+    };
+}
+/**
+ * Start the queue watcher
+ * Called from MCP server setup after DB initialization
+ */
+export declare function startQueueWatcher(projectRoot: string): Promise<void>;
+/**
+ * Stop the queue watcher
+ */
+export declare function stopQueueWatcher(): Promise<void>;
+//# sourceMappingURL=queue-watcher.d.ts.map

package/dist/watcher/queue-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-watcher.d.ts","sourceRoot":"","sources":["../../src/watcher/queue-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOhD;;GAEG;AACH,qBAAa,YAAa,SAAQ,WAAW;IAC3C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA6B;IACpD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAkB;IAEpC,OAAO;IAKP;;OAEG;WACW,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY;IAU7D;;OAEG;WACW,KAAK,IAAI,IAAI;IAO3B;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4CnC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;OAEG;YACW,oBAAoB;IAuBlC;;OAEG;YACW,WAAW;IAwBzB;;OAEG;IACI,SAAS,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;CAM9D;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOtD"}

package/dist/watcher/queue-watcher.js

@@ -0,0 +1,187 @@
+/**
+ * Queue Watcher - Monitors hook queue file for changes
+ *
+ * Watches `.sqlew/queue/pending.json` and processes queued decisions
+ * when hooks write to the queue file.
+ *
+ * Flow:
+ * 1. Hook writes to queue file (fast, <100ms)
+ * 2. QueueWatcher detects change
+ * 3. processHookQueue() registers decisions in DB
+ *
+ * @since v4.1.0
+ */
+import { dirname } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import { BaseWatcher } from './base-watcher.js';
+import { getQueuePath, hasQueueItems, processQueue } from '../utils/hook-queue.js';
+import { quickSetDecision } from '../tools/context/actions/quick-set.js';
+import { setDecision } from '../tools/context/actions/set.js';
+import { debugLog } from '../utils/debug-logger.js';
+/**
+ * QueueWatcher - Singleton for monitoring hook queue
+ */
+export class QueueWatcher extends BaseWatcher {
+    static instance = null;
+    projectRoot;
+    processing = false;
+    constructor(projectRoot) {
+        super('QueueWatcher', 500); // 500ms debounce for queue changes
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Get singleton instance
+     */
+    static getInstance(projectRoot) {
+        if (!QueueWatcher.instance) {
+            if (!projectRoot) {
+                throw new Error('QueueWatcher: projectRoot required for first initialization');
+            }
+            QueueWatcher.instance = new QueueWatcher(projectRoot);
+        }
+        return QueueWatcher.instance;
+    }
+    /**
+     * Reset singleton (for testing)
+     */
+    static reset() {
+        if (QueueWatcher.instance) {
+            QueueWatcher.instance.stop().catch(() => { });
+        }
+        QueueWatcher.instance = null;
+    }
+    /**
+     * Start watching the queue file
+     */
+    async start() {
+        if (this.isRunning) {
+            debugLog('WARN', `${this.watcherName}: Already running`);
+            return;
+        }
+        try {
+            const queuePath = getQueuePath(this.projectRoot);
+            const queueDir = dirname(queuePath);
+            // Ensure queue directory exists
+            if (!existsSync(queueDir)) {
+                mkdirSync(queueDir, { recursive: true });
+            }
+            // Watch the queue directory (not just file, to catch file creation)
+            this.watcher = this.initializeWatcher({
+                paths: queueDir,
+                debounceMs: this.debounceMs,
+                ignoreInitial: false, // Process existing queue on startup
+            });
+            // Handle file changes
+            this.watcher.on('add', (path) => this.handleQueueChange(path));
+            this.watcher.on('change', (path) => this.handleQueueChange(path));
+            this.watcher.on('error', (error) => {
+                debugLog('ERROR', `${this.watcherName}: Watch error`, { error });
+            });
+            this.isRunning = true;
+            debugLog('INFO', `${this.watcherName}: Started`, {
+                projectRoot: this.projectRoot,
+                queueDir,
+            });
+            // Process any existing queue items on startup
+            await this.processQueueIfNeeded();
+        }
+        catch (error) {
+            debugLog('ERROR', `${this.watcherName}: Failed to start`, { error });
+            throw error;
+        }
+    }
+    /**
+     * Handle queue file change
+     */
+    handleQueueChange(path) {
+        // Only process pending.json
+        if (!path.endsWith('pending.json')) {
+            return;
+        }
+        debugLog('INFO', `${this.watcherName}: Queue file changed`);
+        // Debounce to avoid processing during rapid writes
+        this.debounce('queue-process', async () => {
+            await this.processQueueIfNeeded();
+        });
+    }
+    /**
+     * Process queue if items exist
+     */
+    async processQueueIfNeeded() {
+        // Prevent concurrent processing
+        if (this.processing) {
+            return;
+        }
+        if (!hasQueueItems(this.projectRoot)) {
+            return;
+        }
+        this.processing = true;
+        try {
+            const count = await processQueue(this.projectRoot, this.processItem.bind(this));
+            if (count > 0) {
+                debugLog('INFO', `${this.watcherName}: Processed ${count} queue items`);
+            }
+        }
+        catch (error) {
+            debugLog('ERROR', `${this.watcherName}: Error processing queue`, { error });
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+    /**
+     * Process a single queue item
+     */
+    async processItem(item) {
+        const { action, data } = item;
+        debugLog('INFO', `${this.watcherName}: Processing ${action}`, { key: data.key });
+        if (action === 'create') {
+            await quickSetDecision({
+                key: data.key,
+                value: data.value,
+                status: data.status,
+                layer: data.layer,
+                tags: data.tags,
+            });
+        }
+        else if (action === 'update') {
+            await setDecision({
+                key: data.key,
+                value: data.value || `Updated: ${data.key}`,
+                status: data.status,
+                layer: data.layer,
+                tags: data.tags,
+            });
+        }
+    }
+    /**
+     * Get watcher status
+     */
+    getStatus() {
+        return {
+            running: this.isRunning,
+            projectRoot: this.projectRoot,
+        };
+    }
+}
+/**
+ * Start the queue watcher
+ * Called from MCP server setup after DB initialization
+ */
+export async function startQueueWatcher(projectRoot) {
+    const watcher = QueueWatcher.getInstance(projectRoot);
+    await watcher.start();
+}
+/**
+ * Stop the queue watcher
+ */
+export async function stopQueueWatcher() {
+    try {
+        const watcher = QueueWatcher.getInstance();
+        await watcher.stop();
+    }
+    catch {
+        // Instance not initialized, nothing to stop
+    }
+}
+//# sourceMappingURL=queue-watcher.js.map

package/dist/watcher/queue-watcher.js.map

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

package/docs/ADR_CONCEPTS.md

@@ -0,0 +1,140 @@
+# ADR (Architecture Decision Record) Concepts
+
+**Architecture Decision Records (ADR)** document the architectural decisions made on a project, including context, consequences, and alternatives considered. sqlew extends this proven pattern to AI agents.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    subgraph Claude Code
+        A[Plan Mode] -->|Create Plan| B[User Approval]
+        B -->|ExitPlanMode| C[Hook Triggered]
+    end
+
+    subgraph sqlew
+        C -->|Enqueue| D[Queue File]
+        D -->|QueueWatcher| E[(SQL Database)]
+    end
+
+    subgraph Next Session
+        F[AI Agent] -->|Query| E
+        E -->|Past Decisions| F
+    end
+```
+
+**Zero-effort knowledge accumulation:**
+1. You plan your work normally in Claude Code
+2. Hooks automatically capture decisions
+3. Next session, AI queries past decisions via SQL
+
+## Core ADR Concepts in sqlew
+
+**Decisions** capture architectural choices with full context:
+- **What** was decided (the decision itself)
+- **Why** it was chosen (rationale, trade-offs)
+- **What else** was considered (alternatives rejected)
+- **Impact** on the system (consequences, affected components)
+
+**Constraints** define architectural principles and rules:
+- **Performance requirements** (response time limits, throughput goals)
+- **Technology choices** ("must use PostgreSQL", "avoid microservices")
+- **Coding standards** ("async/await only", "no any types")
+- **Security policies** (authentication patterns, data handling rules)
+
+**Implementation tracking** connects decisions to reality:
+- **File tracking** shows which code was affected by decisions
+- **Status evolution** tracks decision lifecycle (draft → active → deprecated)
+- **Auto-capture via Hooks** records decisions automatically from Plan Mode
+
+```mermaid
+erDiagram
+    DECISION ||--o{ TAG : has
+    DECISION ||--o{ FILE : affects
+    DECISION {
+        string key
+        string value
+        string layer
+        string status
+        timestamp updated
+    }
+    CONSTRAINT ||--o{ TAG : has
+    CONSTRAINT {
+        string text
+        string category
+        int priority
+    }
+    TAG {
+        string name
+    }
+    FILE {
+        string path
+        string action
+    }
+```
+
+## Why SQL for ADR?
+
+Traditional text-based ADR forces AI to:
+- Read complete files even for simple queries
+- Parse unstructured text to find relationships
+- Manually detect duplicate or conflicting decisions
+
+sqlew's **SQL-backed ADR repository** enables AI to:
+- Query by layer, tags, status in milliseconds (2-50ms)
+- Join decisions with constraints and files
+- Leverage similarity algorithms to prevent duplicates
+- Scale to thousands of decisions without context explosion
+
+**Token efficiency**: 60-75% reduction compared to reading Markdown ADRs
+
+## Why RDBMS + MCP for ADR?
+
+**RDBMS (Relational Database)** provides efficient structured queries:
+- **Indexed searches** – Find decisions by tags/layers in milliseconds, not seconds
+- **JOIN operations** – Query related decisions and constraints in a single operation
+- **Transaction support** – ACID guarantees ensure data integrity across concurrent AI agents
+- **Scalability** – Handle thousands of ADRs without performance degradation
+
+**MCP (Model Context Protocol)** enables seamless AI integration:
+- **Direct tool access** – AI agents call ADR operations as native functions
+- **Token efficiency** – Retrieve only required data, avoiding full-file reads
+- **Type safety** – Structured parameters prevent errors and guide correct usage
+- **Cross-session persistence** – ADRs survive beyond individual chat sessions
+
+**Together**: AI agents gain SQL-powered ADR capabilities without managing databases directly.
+
+## Traditional vs sqlew ADR
+
+| Traditional ADR (Markdown) | sqlew ADR (SQL) |
+|---------------------------|-----------------|
+| Read entire files | Query specific decisions |
+| Manual duplicate checking | Automatic similarity detection |
+| Text parsing required | Structured, typed data |
+| Linear token scaling | Constant-time lookups |
+| File-based organization | Relational queries with JOINs |
+
+## Key Benefits for AI-Driven Development
+
+### 📚 Persistent Architectural Memory
+- **Zero context loss** – AI agents remember every architectural decision across sessions
+- **Rationale preservation** – Never forget WHY a decision was made, not just WHAT
+- **Alternative tracking** – Document rejected options to prevent circular debates
+- **Evolution history** – See how decisions changed over time with full version history
+
+### 🛡️ Prevent Architectural Drift
+- **Constraint enforcement** – Define architectural rules once, AI follows them forever
+- **Pattern consistency** – AI generates code matching established patterns automatically
+- **Anti-pattern prevention** – Document "what NOT to do" as enforceable constraints
+- **Regression prevention** – AI won't reintroduce previously rejected approaches
+
+### 🔍 Intelligent Decision Discovery
+- **Three-tier duplicate detection** – Gentle nudge (35-44), hard block (45-59), or auto-update (60+) based on similarity score
+- **Similarity detection** – AI identifies duplicate or related decisions before creating new ones
+- **Context-aware search** – Query by layer, tags, or relationships to find relevant decisions
+- **Impact analysis** – Trace which files are affected by each decision
+- **Conflict detection** – Find decisions that contradict or supersede each other
+
+### ⚡ Extreme Efficiency
+- **60-75% token reduction** – Query only relevant decisions instead of reading all ADRs
+- **Millisecond queries** – 2-50ms response times even with thousands of decisions
+- **Scalable architecture** – Perform well with large decision histories