sqlew 3.2.5 → 3.6.0

package/dist/utils/cleanup.js

@@ -1,79 +1,86 @@
 /**
  * Programmatic cleanup utilities for old messages and file changes
  * Replaces the automatic triggers with weekend-aware logic
+ *
+ * CONVERTED: Using Knex.js with DatabaseAdapter (async/await)
  */
 import { calculateMessageCutoff, calculateFileChangeCutoff } from './retention.js';
 /**
  * Perform automatic cleanup of old data
  * Deletes old messages, file changes, and activity logs based on m_config settings
  *
- * @param db - Database instance
+ * @param adapter - Database adapter instance
+ * @param trx - Optional transaction
  * @returns Object with counts of deleted records
  */
-export function performAutoCleanup(db) {
-    const messageCutoff = calculateMessageCutoff(db);
-    const fileChangeCutoff = calculateFileChangeCutoff(db);
-    const messagesDeleted = cleanupMessages(db, messageCutoff);
-    const fileChangesDeleted = cleanupFileChanges(db, fileChangeCutoff);
+export async function performAutoCleanup(adapter, trx) {
+    const messageCutoff = await calculateMessageCutoff(adapter);
+    const fileChangeCutoff = await calculateFileChangeCutoff(adapter);
+    const messagesDeleted = await cleanupMessages(adapter, messageCutoff, trx);
+    const fileChangesDeleted = await cleanupFileChanges(adapter, fileChangeCutoff, trx);
     // Activity log uses same retention as messages (constraint #4)
-    const activityLogsDeleted = cleanupActivityLogs(db, messageCutoff);
+    const activityLogsDeleted = await cleanupActivityLogs(adapter, messageCutoff, trx);
     return { messagesDeleted, fileChangesDeleted, activityLogsDeleted };
 }
 /**
  * Delete old messages before the cutoff timestamp
  *
- * @param db - Database instance
+ * @param adapter - Database adapter instance
  * @param cutoffTimestamp - Unix timestamp (seconds) for cutoff
+ * @param trx - Optional transaction
  * @returns Number of messages deleted
  */
-export function cleanupMessages(db, cutoffTimestamp) {
-    const result = db.prepare('DELETE FROM t_agent_messages WHERE ts < ?').run(cutoffTimestamp);
-    return result.changes;
+export async function cleanupMessages(adapter, cutoffTimestamp, trx) {
+    const knex = trx || adapter.getKnex();
+    return await knex('t_agent_messages').where('ts', '<', cutoffTimestamp).delete();
 }
 /**
  * Delete old file changes before the cutoff timestamp
  *
- * @param db - Database instance
+ * @param adapter - Database adapter instance
  * @param cutoffTimestamp - Unix timestamp (seconds) for cutoff
+ * @param trx - Optional transaction
  * @returns Number of file changes deleted
  */
-export function cleanupFileChanges(db, cutoffTimestamp) {
-    const result = db.prepare('DELETE FROM t_file_changes WHERE ts < ?').run(cutoffTimestamp);
-    return result.changes;
+export async function cleanupFileChanges(adapter, cutoffTimestamp, trx) {
+    const knex = trx || adapter.getKnex();
+    return await knex('t_file_changes').where('ts', '<', cutoffTimestamp).delete();
 }
 /**
  * Delete old activity logs before the cutoff timestamp
  * Activity logs use the same retention as messages (constraint #4)
  *
- * @param db - Database instance
+ * @param adapter - Database adapter instance
  * @param cutoffTimestamp - Unix timestamp (seconds) for cutoff
+ * @param trx - Optional transaction
  * @returns Number of activity logs deleted
  */
-export function cleanupActivityLogs(db, cutoffTimestamp) {
-    const result = db.prepare('DELETE FROM t_activity_log WHERE ts < ?').run(cutoffTimestamp);
-    return result.changes;
+export async function cleanupActivityLogs(adapter, cutoffTimestamp, trx) {
+    const knex = trx || adapter.getKnex();
+    return await knex('t_activity_log').where('ts', '<', cutoffTimestamp).delete();
 }
 /**
  * Cleanup with custom retention periods (overrides config)
  *
- * @param db - Database instance
+ * @param adapter - Database adapter instance
  * @param messageHours - Message retention in hours (optional)
  * @param fileChangeDays - File change retention in days (optional)
+ * @param trx - Optional transaction
  * @returns Object with counts of deleted records
  */
-export function cleanupWithCustomRetention(db, messageHours, fileChangeDays) {
+export async function cleanupWithCustomRetention(adapter, messageHours, fileChangeDays, trx) {
     let messagesDeleted = 0;
     let fileChangesDeleted = 0;
     let activityLogsDeleted = 0;
     if (messageHours !== undefined) {
         const messageCutoff = Math.floor(Date.now() / 1000) - (messageHours * 3600);
-        messagesDeleted = cleanupMessages(db, messageCutoff);
+        messagesDeleted = await cleanupMessages(adapter, messageCutoff, trx);
         // Activity log uses same retention as messages (constraint #4)
-        activityLogsDeleted = cleanupActivityLogs(db, messageCutoff);
+        activityLogsDeleted = await cleanupActivityLogs(adapter, messageCutoff, trx);
     }
     if (fileChangeDays !== undefined) {
         const fileChangeCutoff = Math.floor(Date.now() / 1000) - (fileChangeDays * 86400);
-        fileChangesDeleted = cleanupFileChanges(db, fileChangeCutoff);
+        fileChangesDeleted = await cleanupFileChanges(adapter, fileChangeCutoff, trx);
     }
     return { messagesDeleted, fileChangesDeleted, activityLogsDeleted };
 }

package/dist/utils/cleanup.js.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../src/utils/cleanup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAY;IAC7C,MAAM,aAAa,GAAG,sBAAsB,CAAC,EAAE,CAAC,CAAC;IACjD,MAAM,gBAAgB,GAAG,yBAAyB,CAAC,EAAE,CAAC,CAAC;IAEvD,MAAM,eAAe,GAAG,eAAe,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;IAC3D,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;IACpE,+DAA+D;IAC/D,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;IAEnE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,EAAY,EAAE,eAAuB;IACnE,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,2CAA2C,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC5F,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAY,EAAE,eAAuB;IACtE,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,yCAAyC,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAY,EAAE,eAAuB;IACvE,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,yCAAyC,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,EAAY,EACZ,YAAqB,EACrB,cAAuB;IAEvB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAC3B,IAAI,mBAAmB,GAAG,CAAC,CAAC;IAE5B,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;QAC5E,eAAe,GAAG,eAAe,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;QACrD,+DAA+D;QAC/D,mBAAmB,GAAG,mBAAmB,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,GAAG,KAAK,CAAC,CAAC;QAClF,kBAAkB,GAAG,kBAAkB,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAC;AACtE,CAAC"}
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../src/utils/cleanup.ts"],"names":[],"mappings":"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"}

package/dist/utils/debug-logger.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Debug Logger for MCP Shared Context Server
+ *
+ * Enables debug logging when specified via CLI arg, environment variable, or config file.
+ * Priority: CLI arg > Environment variable > Config file
+ *
+ * Usage:
+ *   node dist/index.js --debug-log=/path/to/debug.log
+ *   SQLEW_DEBUG=/path/to/debug.log node dist/index.js
+ *   OR set debug.log_path in .sqlew/config.toml
+ */
+/**
+ * Initialize debug logger
+ * @param debugLogPath - Log path (already resolved with priority: CLI > env > config)
+ */
+export declare function initDebugLogger(debugLogPath?: string): void;
+/**
+ * Write debug log entry
+ * @param level - Log level (INFO, WARN, ERROR, DEBUG)
+ * @param message - Log message
+ * @param data - Optional data to log
+ */
+export declare function debugLog(level: 'INFO' | 'WARN' | 'ERROR' | 'DEBUG', message: string, data?: any): void;
+/**
+ * Log MCP tool call
+ */
+export declare function debugLogToolCall(toolName: string, action: string, params: any): void;
+/**
+ * Log MCP tool response
+ */
+export declare function debugLogToolResponse(toolName: string, action: string, success: boolean, result?: any, error?: any): void;
+/**
+ * Log error with stack trace
+ */
+export declare function debugLogError(context: string, error: any): void;
+/**
+ * Close debug logger
+ */
+export declare function closeDebugLogger(): void;
+/**
+ * Check if debug logging is enabled
+ */
+export declare function isDebugEnabled(): boolean;
+//# sourceMappingURL=debug-logger.d.ts.map

package/dist/utils/debug-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-logger.d.ts","sourceRoot":"","sources":["../../src/utils/debug-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAmC3D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAoBtG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAEpF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,GAAG,IAAI,CAMxH;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAK/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAQvC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC"}

package/dist/utils/debug-logger.js

@@ -0,0 +1,116 @@
+/**
+ * Debug Logger for MCP Shared Context Server
+ *
+ * Enables debug logging when specified via CLI arg, environment variable, or config file.
+ * Priority: CLI arg > Environment variable > Config file
+ *
+ * Usage:
+ *   node dist/index.js --debug-log=/path/to/debug.log
+ *   SQLEW_DEBUG=/path/to/debug.log node dist/index.js
+ *   OR set debug.log_path in .sqlew/config.toml
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+let debugEnabled = false;
+let debugStream = null;
+let currentLogPath = null;
+/**
+ * Initialize debug logger
+ * @param debugLogPath - Log path (already resolved with priority: CLI > env > config)
+ */
+export function initDebugLogger(debugLogPath) {
+    if (!debugLogPath) {
+        return;
+    }
+    currentLogPath = debugLogPath;
+    try {
+        // Ensure directory exists
+        const logDir = path.dirname(debugLogPath);
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        // Create write stream (append mode)
+        debugStream = fs.createWriteStream(debugLogPath, { flags: 'a' });
+        debugEnabled = true;
+        // Detect source (for logging purposes)
+        const cliArg = process.argv.find(arg => arg.startsWith('--debug-log'));
+        const envVar = process.env.SQLEW_DEBUG;
+        const source = cliArg ? 'CLI Argument' : envVar ? 'Environment Variable' : 'Config File';
+        const sourceDetail = cliArg ? '--debug-log' : envVar ? 'SQLEW_DEBUG' : 'debug.log_path';
+        debugLog('INFO', '='.repeat(80));
+        debugLog('INFO', `MCP Shared Context Server Debug Log Started`);
+        debugLog('INFO', `Timestamp: ${new Date().toISOString()}`);
+        debugLog('INFO', `Process ID: ${process.pid}`);
+        debugLog('INFO', `Debug Log Path: ${debugLogPath}`);
+        debugLog('INFO', `Source: ${source} (${sourceDetail})`);
+        debugLog('INFO', '='.repeat(80));
+    }
+    catch (error) {
+        console.error(`Failed to initialize debug logger: ${error}`);
+        debugEnabled = false;
+    }
+}
+/**
+ * Write debug log entry
+ * @param level - Log level (INFO, WARN, ERROR, DEBUG)
+ * @param message - Log message
+ * @param data - Optional data to log
+ */
+export function debugLog(level, message, data) {
+    if (!debugEnabled || !debugStream) {
+        return;
+    }
+    const timestamp = new Date().toISOString();
+    let logEntry = `[${timestamp}] [${level}] ${message}`;
+    try {
+        if (data !== undefined) {
+            const dataStr = typeof data === 'string'
+                ? data
+                : JSON.stringify(data);
+            logEntry += ` | Data: ${dataStr}`;
+        }
+        debugStream.write(logEntry + '\n');
+    }
+    catch (error) {
+        console.error(`Failed to write debug log: ${error}`);
+    }
+}
+/**
+ * Log MCP tool call
+ */
+export function debugLogToolCall(toolName, action, params) {
+    debugLog('DEBUG', `Tool Call: ${toolName}.${action}`, { params });
+}
+/**
+ * Log MCP tool response
+ */
+export function debugLogToolResponse(toolName, action, success, result, error) {
+    debugLog(success ? 'DEBUG' : 'ERROR', `Tool Response: ${toolName}.${action} ${success ? 'SUCCESS' : 'FAILED'}`, success ? result : error);
+}
+/**
+ * Log error with stack trace
+ */
+export function debugLogError(context, error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    debugLog('ERROR', `${context}: ${errorMessage}`, { stack });
+}
+/**
+ * Close debug logger
+ */
+export function closeDebugLogger() {
+    if (debugStream) {
+        debugLog('INFO', 'MCP Shared Context Server Debug Log Ended');
+        debugLog('INFO', '='.repeat(80));
+        debugStream.end();
+        debugStream = null;
+        debugEnabled = false;
+    }
+}
+/**
+ * Check if debug logging is enabled
+ */
+export function isDebugEnabled() {
+    return debugEnabled;
+}
+//# sourceMappingURL=debug-logger.js.map

package/dist/utils/debug-logger.js.map

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

package/dist/utils/file-pruning.d.ts

@@ -0,0 +1,69 @@
+/**
+ * File pruning utilities for v3.5.0 Auto-Pruning feature
+ * Automatically removes non-existent watched files with audit trail
+ */
+import { Database } from '../types.js';
+/**
+ * Prune non-existent files from a task's watch list
+ * Records pruned files to audit table for project archaeology
+ *
+ * Quality gate enforcement:
+ * - If ALL watched files are non-existent → throw error (prevents zero-work completion)
+ * - If SOME watched files are non-existent → prune them and continue
+ *
+ * @param db - Database instance
+ * @param taskId - Task ID to prune files for
+ * @param projectRoot - Project root directory (default: process.cwd())
+ * @returns Object with pruned count and remaining count
+ * @throws Error if ALL files are non-existent (safety check)
+ */
+export declare function pruneNonExistentFiles(db: Database, taskId: number, projectRoot?: string): {
+    prunedCount: number;
+    remainingCount: number;
+    prunedPaths: string[];
+};
+/**
+ * Get pruned files for a task
+ *
+ * @param db - Database instance
+ * @param taskId - Task ID
+ * @param limit - Maximum number of records (default: 100)
+ * @returns Array of pruned file records
+ */
+export declare function getPrunedFiles(db: Database, taskId: number, limit?: number): Array<{
+    id: number;
+    file_path: string;
+    pruned_at: string;
+    linked_decision: string | null;
+}>;
+/**
+ * Link a pruned file to a decision (for WHY reasoning)
+ *
+ * @param db - Database instance
+ * @param prunedFileId - Pruned file record ID
+ * @param decisionKey - Decision key to link
+ * @throws Error if pruned file or decision not found
+ */
+export declare function linkPrunedFileToDecision(db: Database, prunedFileId: number, decisionKey: string): void;
+/**
+ * Get all pruned files across all tasks (for audit purposes)
+ *
+ * @param db - Database instance
+ * @param filters - Optional filters
+ * @returns Array of pruned file records with task info
+ */
+export declare function getAllPrunedFiles(db: Database, filters?: {
+    taskId?: number;
+    linkedDecision?: string;
+    since?: number;
+    limit?: number;
+    offset?: number;
+}): Array<{
+    id: number;
+    task_id: number;
+    task_title: string;
+    file_path: string;
+    pruned_at: string;
+    linked_decision: string | null;
+}>;
+//# sourceMappingURL=file-pruning.d.ts.map

package/dist/utils/file-pruning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-pruning.d.ts","sourceRoot":"","sources":["../../src/utils/file-pruning.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAsB,GAClC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAoExE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAY,GAClB,KAAK,CAAC;IACP,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC,CAoBD;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,QAAQ,EACZ,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,IAAI,CAiCN;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,QAAQ,EACZ,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,KAAK,CAAC;IACP,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC,CAoDD"}

package/dist/utils/file-pruning.js

@@ -0,0 +1,185 @@
+/**
+ * File pruning utilities for v3.5.0 Auto-Pruning feature
+ * Automatically removes non-existent watched files with audit trail
+ */
+import { existsSync } from 'fs';
+import { join } from 'path';
+/**
+ * Prune non-existent files from a task's watch list
+ * Records pruned files to audit table for project archaeology
+ *
+ * Quality gate enforcement:
+ * - If ALL watched files are non-existent → throw error (prevents zero-work completion)
+ * - If SOME watched files are non-existent → prune them and continue
+ *
+ * @param db - Database instance
+ * @param taskId - Task ID to prune files for
+ * @param projectRoot - Project root directory (default: process.cwd())
+ * @returns Object with pruned count and remaining count
+ * @throws Error if ALL files are non-existent (safety check)
+ */
+export function pruneNonExistentFiles(db, taskId, projectRoot = process.cwd()) {
+    // 1. Get all watched files for this task
+    const watchedFiles = db.prepare(`
+    SELECT f.id as file_id, f.path
+    FROM t_task_file_links tfl
+    JOIN m_files f ON tfl.file_id = f.id
+    WHERE tfl.task_id = ?
+  `).all(taskId);
+    if (watchedFiles.length === 0) {
+        // No watched files - nothing to prune
+        return { prunedCount: 0, remainingCount: 0, prunedPaths: [] };
+    }
+    // 2. Check which files exist on filesystem
+    const existingFiles = [];
+    const nonExistentFiles = [];
+    for (const file of watchedFiles) {
+        const fullPath = join(projectRoot, file.path);
+        if (existsSync(fullPath)) {
+            existingFiles.push(file);
+        }
+        else {
+            nonExistentFiles.push(file);
+        }
+    }
+    // 3. Safety check: If ALL files are non-existent, block the operation
+    if (nonExistentFiles.length === watchedFiles.length) {
+        throw new Error(`Cannot prune files for task #${taskId}: ALL ${watchedFiles.length} watched files are non-existent. ` +
+            `This indicates no work was done. Please verify watched files or mark task as invalid.`);
+    }
+    // 4. If no files need pruning, return early
+    if (nonExistentFiles.length === 0) {
+        return {
+            prunedCount: 0,
+            remainingCount: watchedFiles.length,
+            prunedPaths: [],
+        };
+    }
+    // 5. Prune non-existent files in a transaction
+    db.transaction(() => {
+        const insertPruned = db.prepare(`
+      INSERT INTO t_task_pruned_files (task_id, file_path, pruned_ts)
+      VALUES (?, ?, unixepoch())
+    `);
+        const deleteLink = db.prepare(`
+      DELETE FROM t_task_file_links
+      WHERE task_id = ? AND file_id = ?
+    `);
+        // Record each pruned file to audit table and remove link
+        for (const file of nonExistentFiles) {
+            insertPruned.run(taskId, file.path);
+            deleteLink.run(taskId, file.file_id);
+        }
+    })();
+    return {
+        prunedCount: nonExistentFiles.length,
+        remainingCount: existingFiles.length,
+        prunedPaths: nonExistentFiles.map(f => f.path),
+    };
+}
+/**
+ * Get pruned files for a task
+ *
+ * @param db - Database instance
+ * @param taskId - Task ID
+ * @param limit - Maximum number of records (default: 100)
+ * @returns Array of pruned file records
+ */
+export function getPrunedFiles(db, taskId, limit = 100) {
+    const rows = db.prepare(`
+    SELECT
+      tpf.id,
+      tpf.file_path,
+      datetime(tpf.pruned_ts, 'unixepoch') as pruned_at,
+      k.key as linked_decision
+    FROM t_task_pruned_files tpf
+    LEFT JOIN m_context_keys k ON tpf.linked_decision_key_id = k.id
+    WHERE tpf.task_id = ?
+    ORDER BY tpf.pruned_ts DESC
+    LIMIT ?
+  `).all(taskId, limit);
+    return rows;
+}
+/**
+ * Link a pruned file to a decision (for WHY reasoning)
+ *
+ * @param db - Database instance
+ * @param prunedFileId - Pruned file record ID
+ * @param decisionKey - Decision key to link
+ * @throws Error if pruned file or decision not found
+ */
+export function linkPrunedFileToDecision(db, prunedFileId, decisionKey) {
+    // 1. Get decision key_id
+    const decision = db.prepare(`
+    SELECT k.id as key_id
+    FROM m_context_keys k
+    WHERE k.key = ? AND EXISTS (
+      SELECT 1 FROM t_decisions d WHERE d.key_id = k.id
+    )
+  `).get(decisionKey);
+    if (!decision) {
+        throw new Error(`Decision not found: ${decisionKey}`);
+    }
+    // 2. Check if pruned file exists
+    const prunedFile = db.prepare(`
+    SELECT id FROM t_task_pruned_files WHERE id = ?
+  `).get(prunedFileId);
+    if (!prunedFile) {
+        throw new Error(`Pruned file record not found: ${prunedFileId}`);
+    }
+    // 3. Update the link
+    const result = db.prepare(`
+    UPDATE t_task_pruned_files
+    SET linked_decision_key_id = ?
+    WHERE id = ?
+  `).run(decision.key_id, prunedFileId);
+    if (result.changes === 0) {
+        throw new Error(`Failed to link pruned file #${prunedFileId} to decision ${decisionKey}`);
+    }
+}
+/**
+ * Get all pruned files across all tasks (for audit purposes)
+ *
+ * @param db - Database instance
+ * @param filters - Optional filters
+ * @returns Array of pruned file records with task info
+ */
+export function getAllPrunedFiles(db, filters) {
+    let query = `
+    SELECT
+      tpf.id,
+      tpf.task_id,
+      t.title as task_title,
+      tpf.file_path,
+      datetime(tpf.pruned_ts, 'unixepoch') as pruned_at,
+      k.key as linked_decision
+    FROM t_task_pruned_files tpf
+    JOIN t_tasks t ON tpf.task_id = t.id
+    LEFT JOIN m_context_keys k ON tpf.linked_decision_key_id = k.id
+    WHERE 1=1
+  `;
+    const params = [];
+    if (filters?.taskId !== undefined) {
+        query += ' AND tpf.task_id = ?';
+        params.push(filters.taskId);
+    }
+    if (filters?.linkedDecision) {
+        query += ' AND k.key = ?';
+        params.push(filters.linkedDecision);
+    }
+    if (filters?.since !== undefined) {
+        query += ' AND tpf.pruned_ts >= ?';
+        params.push(filters.since);
+    }
+    query += ' ORDER BY tpf.pruned_ts DESC';
+    if (filters?.limit) {
+        query += ' LIMIT ?';
+        params.push(filters.limit);
+    }
+    if (filters?.offset) {
+        query += ' OFFSET ?';
+        params.push(filters.offset);
+    }
+    return db.prepare(query).all(...params);
+}
+//# sourceMappingURL=file-pruning.js.map

package/dist/utils/file-pruning.js.map

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

package/dist/utils/help-tracking.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Help Action Usage Tracking
+ *
+ * Lightweight logging system to track help/example action invocations
+ * for understanding usage patterns and optimizing documentation.
+ *
+ * Data collected:
+ * - tool_name: Which MCP tool invoked help/example
+ * - action_name: "help" or "example"
+ * - timestamp: When the action was invoked
+ * - token_count: Estimated tokens in request + response
+ *
+ * Storage: Temporary log file in .sqlew/tmp/help-usage.log
+ * Format: JSON lines (one JSON object per line for easy parsing)
+ * Retention: Manual cleanup after 1-2 week analysis period
+ */
+/**
+ * Help action invocation record
+ */
+export interface HelpUsageRecord {
+    tool_name: string;
+    action_name: 'help' | 'example';
+    timestamp: string;
+    token_count: number;
+    context?: string;
+}
+/**
+ * Log a help action invocation
+ * Appends JSON line to log file for analysis
+ *
+ * @param record - Help usage record to log
+ */
+export declare function logHelpUsage(record: HelpUsageRecord): void;
+/**
+ * Estimate token count for help/example action
+ * Rough estimation based on response length
+ *
+ * @param toolName - Name of the MCP tool
+ * @param actionName - "help" or "example"
+ * @param responseLength - Length of response text
+ * @returns Estimated token count (request + response)
+ */
+export declare function estimateHelpTokens(toolName: string, actionName: 'help' | 'example', responseLength: number): number;
+/**
+ * Track help action and return the help content
+ * Convenience wrapper that logs and returns content
+ *
+ * @param toolName - Name of the MCP tool
+ * @param actionName - "help" or "example"
+ * @param content - Help content to return
+ * @param context - Optional context about what triggered help
+ * @returns The help content (pass-through)
+ */
+export declare function trackAndReturnHelp(toolName: string, actionName: 'help' | 'example', content: string, context?: string): string;
+//# sourceMappingURL=help-tracking.d.ts.map

package/dist/utils/help-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-tracking.d.ts","sourceRoot":"","sources":["../../src/utils/help-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAW1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,cAAc,EAAE,MAAM,GACrB,MAAM,CAQR;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAYR"}