smart-context-mcp 1.6.1 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",

package/scripts/task-runner.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 import { runTaskRunner } from '../src/task-runner.js';
+import { checkNodeVersion } from '../src/utils/runtime-check.js';
+
+const runtimeCheck = checkNodeVersion();
+if (!runtimeCheck.ok) {
+  console.error(`[smart-context-task] Runtime check failed: ${runtimeCheck.message}`);
+  console.error(`[smart-context-task] Current: ${runtimeCheck.current}, Required: ${runtimeCheck.minimum}+`);
+  process.exit(1);
+}
 
 const requireValue = (argv, index, flag) => {
   const value = argv[index + 1];

package/src/server.js

@@ -16,6 +16,7 @@ import { smartMetrics } from './tools/smart-metrics.js';
 import { smartTurn } from './tools/smart-turn.js';
 import { projectRoot, projectRootSource } from './utils/paths.js';
 import { setServerForStreaming } from './streaming.js';
+import { checkNodeVersion } from './utils/runtime-check.js';
 import { 
   getSymbolBlame, 
   getFileAuthorshipStats, 
@@ -44,6 +45,13 @@ export const asTextResult = (result) => ({
 });
 
 export const createDevctxServer = () => {
+  const runtimeCheck = checkNodeVersion();
+  if (!runtimeCheck.ok) {
+    console.error(`[devctx] Runtime check failed: ${runtimeCheck.message}`);
+    console.error(`[devctx] Current: ${runtimeCheck.current}, Required: ${runtimeCheck.minimum}+`);
+    process.exit(1);
+  }
+
   const server = new McpServer({
     name: 'devctx',
     version,

package/src/storage/sqlite.js

@@ -1103,6 +1103,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
   const payload = readJsonFile(filePath);
 
   if (!payload || typeof payload !== 'object') {
+    const sizeBytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
     return {
       type: 'session',
       path: filePath,
@@ -1110,6 +1111,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
       eligible: false,
       reason: 'invalid_json',
       sessionId: null,
+      sizeBytes,
     };
   }
 
@@ -1120,6 +1122,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
     WHERE session_id = ?
   `).get(sessionId);
   if (!sessionRow) {
+    const sizeBytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
     return {
       type: 'session',
       path: filePath,
@@ -1127,6 +1130,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
       eligible: false,
       reason: 'missing_in_sqlite',
       sessionId,
+      sizeBytes,
     };
   }
 
@@ -1134,6 +1138,8 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
   const sqliteUpdatedAt = toIsoString(sessionRow.updated_at);
   const eligible = getTimestamp(sqliteUpdatedAt) >= getTimestamp(fileUpdatedAt);
 
+  const sizeBytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+
   return {
     type: 'session',
     path: filePath,
@@ -1141,6 +1147,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
     eligible,
     reason: eligible ? 'imported_and_not_newer_than_sqlite' : 'legacy_file_newer_than_sqlite',
     sessionId,
+    sizeBytes,
     fileUpdatedAt,
     sqliteUpdatedAt,
   };
@@ -1153,34 +1160,40 @@ const buildActiveCleanupCandidate = (db, activeSessionFile) => {
 
   const payload = readJsonFile(activeSessionFile);
   if (!payload || typeof payload !== 'object') {
+    const sizeBytes = fs.statSync(activeSessionFile).size;
     return {
       type: 'active_session',
       path: activeSessionFile,
       eligible: false,
       reason: 'invalid_json',
       sessionId: null,
+      sizeBytes,
     };
   }
 
   const legacySessionId = typeof payload.sessionId === 'string' ? payload.sessionId : null;
   const activeRow = getActiveSessionRow(db);
   if (!legacySessionId) {
+    const sizeBytes = fs.statSync(activeSessionFile).size;
     return {
       type: 'active_session',
       path: activeSessionFile,
       eligible: true,
       reason: 'orphaned_legacy_file',
       sessionId: null,
+      sizeBytes,
     };
   }
 
   if (!activeRow) {
+    const sizeBytes = fs.statSync(activeSessionFile).size;
     return {
       type: 'active_session',
       path: activeSessionFile,
       eligible: true,
       reason: 'sqlite_has_no_active_session',
       sessionId: legacySessionId,
+      sizeBytes,
     };
   }
 
@@ -1189,12 +1202,15 @@ const buildActiveCleanupCandidate = (db, activeSessionFile) => {
   const eligible = activeRow.session_id === legacySessionId
     && getTimestamp(sqliteUpdatedAt) >= getTimestamp(fileUpdatedAt);
 
+  const sizeBytes = fs.existsSync(activeSessionFile) ? fs.statSync(activeSessionFile).size : 0;
+
   return {
     type: 'active_session',
     path: activeSessionFile,
     eligible,
     reason: eligible ? 'sqlite_active_session_matches' : 'sqlite_active_session_differs',
     sessionId: legacySessionId,
+    sizeBytes,
     fileUpdatedAt,
     sqliteUpdatedAt,
   };
@@ -1207,12 +1223,14 @@ const buildMetricsCleanupCandidate = (db, metricsFile) => {
 
   const { entries, invalidLines } = readMetricsEntries(metricsFile);
   if (invalidLines.length > 0) {
+    const sizeBytes = fs.statSync(metricsFile).size;
     return {
       type: 'metrics',
       path: metricsFile,
       eligible: false,
       reason: 'invalid_jsonl',
       entryCount: entries.length,
+      sizeBytes,
       invalidLines,
       missingEntries: [],
     };
@@ -1231,12 +1249,15 @@ const buildMetricsCleanupCandidate = (db, metricsFile) => {
     }
   }
 
+  const sizeBytes = fs.existsSync(metricsFile) ? fs.statSync(metricsFile).size : 0;
+
   return {
     type: 'metrics',
     path: metricsFile,
     eligible: missingEntries.length === 0,
     reason: missingEntries.length === 0 ? 'all_entries_imported' : 'sqlite_missing_entries',
     entryCount: entries.length,
+    sizeBytes,
     invalidLines,
     missingEntries,
   };

package/src/task-runner.js

@@ -1,6 +1,7 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { persistMetrics } from './metrics.js';
 import { countTokens } from './tokenCounter.js';
+import { projectRoot } from './utils/paths.js';
 import { TASK_RUNNER_QUALITY_ANALYTICS_KIND } from './analytics/product-quality.js';
 import { runHeadlessWrapper } from './orchestration/headless-wrapper.js';
 import { smartContext } from './tools/smart-context.js';
@@ -513,10 +514,57 @@ const runCleanupCommand = async ({
   });
 
   if (cleanupMode === 'legacy') {
-    const result = await smartSummary({
+    const dryRun = await smartSummary({
       action: 'cleanup_legacy',
-      apply,
+      apply: false,
     });
+
+    if (!apply) {
+      const eligibleFiles = [];
+
+      if (dryRun.sessions?.candidates) {
+        for (const session of dryRun.sessions.candidates) {
+          if (session.deletable) {
+            eligibleFiles.push({
+              relativePath: session.relativePath || session.path,
+              sizeBytes: session.sizeBytes || 0,
+            });
+          }
+        }
+      }
+
+      if (dryRun.metrics?.eligible && dryRun.metrics?.path) {
+        eligibleFiles.push({
+          relativePath: dryRun.metrics.path.replace(projectRoot + '/', ''),
+          sizeBytes: dryRun.metrics.sizeBytes || 0,
+        });
+      }
+
+      if (dryRun.activeSession?.eligible && dryRun.activeSession?.path) {
+        eligibleFiles.push({
+          relativePath: dryRun.activeSession.path.replace(projectRoot + '/', ''),
+          sizeBytes: dryRun.activeSession.sizeBytes || 0,
+        });
+      }
+
+      if (eligibleFiles.length > 0) {
+        console.log('\n📋 Legacy files eligible for cleanup:\n');
+        console.log('File                                      Size');
+        console.log('─'.repeat(60));
+        for (const file of eligibleFiles) {
+          const sizeKB = file.sizeBytes ? `${(file.sizeBytes / 1024).toFixed(1)}KB` : 'N/A';
+          console.log(`${file.relativePath.padEnd(42)} ${sizeKB}`);
+        }
+        const totalKB = eligibleFiles.reduce((sum, f) => sum + (f.sizeBytes || 0), 0) / 1024;
+        console.log('─'.repeat(60));
+        console.log(`Total: ${eligibleFiles.length} files, ${totalKB.toFixed(1)}KB\n`);
+        console.log('💡 To apply cleanup, run: smart-context-task cleanup --cleanup-mode legacy --apply\n');
+      } else {
+        console.log('\n✅ No legacy files eligible for cleanup.\n');
+      }
+    }
+
+    const result = apply ? await smartSummary({ action: 'cleanup_legacy', apply: true }) : dryRun;
     const payload = {
       command: 'cleanup',
       cleanupMode,

package/src/tools/smart-doctor.js

@@ -68,6 +68,76 @@ const readMaintenanceSnapshot = async ({ filePath, storageHealth }) => {
   try {
     return await withStateDbSnapshot((db) => {
       const count = (tableName) => db.prepare(`SELECT COUNT(*) AS count FROM ${tableName}`).get().count;
+      const retentionDays = Number(getMeta(db, 'state_compaction_retention_days') ?? DEFAULT_RETENTION_DAYS);
+      const activeSessionId = db.prepare('SELECT session_id FROM active_session WHERE scope = ?').get(ACTIVE_SESSION_SCOPE)?.session_id ?? null;
+      const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000).toISOString();
+      const hookTurnCutoff = new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString();
+      const staleSessionsQuery = activeSessionId
+        ? db.prepare(`
+          SELECT COUNT(*) AS count
+          FROM sessions
+          WHERE datetime(updated_at) < datetime(?)
+            AND session_id != ?
+        `)
+        : db.prepare(`
+          SELECT COUNT(*) AS count
+          FROM sessions
+          WHERE datetime(updated_at) < datetime(?)
+        `);
+      const staleSessions = activeSessionId
+        ? staleSessionsQuery.get(cutoff, activeSessionId).count
+        : staleSessionsQuery.get(cutoff).count;
+      const staleSessionEventsQuery = db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM (
+          SELECT
+            se.event_id,
+            se.created_at,
+            ROW_NUMBER() OVER (
+              PARTITION BY se.session_id
+              ORDER BY datetime(se.created_at) DESC, se.event_id DESC
+            ) AS row_num
+          FROM session_events se
+          JOIN sessions s ON s.session_id = se.session_id
+          WHERE datetime(s.updated_at) >= datetime(@cutoff)
+             OR s.session_id = @activeSessionId
+        )
+        WHERE row_num > @keepLatest
+          AND datetime(created_at) < datetime(@cutoff)
+      `);
+      const staleMetricsQuery = db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM (
+          SELECT
+            metric_id,
+            created_at,
+            ROW_NUMBER() OVER (
+              ORDER BY datetime(created_at) DESC, metric_id DESC
+            ) AS row_num
+          FROM metrics_events
+        )
+        WHERE row_num > @keepLatest
+          AND datetime(created_at) < datetime(@cutoff)
+      `);
+      const staleHookTurns = db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM hook_turn_state
+        WHERE datetime(updated_at) < datetime(?)
+      `).get(hookTurnCutoff).count;
+      const compactionEstimate = {
+        sessionsDeleted: staleSessions,
+        sessionEventsDeleted: staleSessionEventsQuery.get({
+          cutoff,
+          activeSessionId,
+          keepLatest: DEFAULT_KEEP_LATEST_EVENTS_PER_SESSION,
+        }).count,
+        metricsEventsDeleted: staleMetricsQuery.get({
+          cutoff,
+          keepLatest: DEFAULT_KEEP_LATEST_METRICS,
+        }).count,
+        hookTurnStateDeleted: staleHookTurns,
+      };
+      compactionEstimate.totalDeletes = Object.values(compactionEstimate).reduce((total, value) => total + value, 0);
 
       return {
         available: true,
@@ -78,14 +148,15 @@ const readMaintenanceSnapshot = async ({ filePath, storageHealth }) => {
           hookTurnState: count('hook_turn_state'),
           workflowMetrics: count('workflow_metrics'),
         },
-        activeSessionId: db.prepare('SELECT session_id FROM active_session WHERE scope = ?').get(ACTIVE_SESSION_SCOPE)?.session_id ?? null,
+        activeSessionId,
         schemaVersion: Number(getMeta(db, 'schema_version') ?? 0),
         lastCompactedAt: getMeta(db, 'state_compacted_at'),
-        retentionDays: Number(getMeta(db, 'state_compaction_retention_days') ?? DEFAULT_RETENTION_DAYS),
+        retentionDays,
         legacyImport: {
           sessions: Number(getMeta(db, 'legacy_sessions_import_count') ?? 0),
           metrics: Number(getMeta(db, 'legacy_metrics_import_count') ?? 0),
         },
+        compactionEstimate,
       };
     }, { filePath });
   } catch (error) {
@@ -227,21 +298,30 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
     retentionDays,
     schemaVersion,
     activeSessionId,
+    compactionEstimate = {
+      sessionsDeleted: 0,
+      sessionEventsDeleted: 0,
+      metricsEventsDeleted: 0,
+      hookTurnStateDeleted: 0,
+      totalDeletes: 0,
+    },
   } = maintenance;
   const daysSinceCompaction = daysSince(lastCompactedAt);
   const sessionEventThreshold = Math.max(SESSION_EVENTS_WARNING_FLOOR, counts.sessions * DEFAULT_KEEP_LATEST_EVENTS_PER_SESSION * 5);
   const needsCompaction = [];
+  const canReclaimRows = compactionEstimate.totalDeletes > 0;
 
   if (storageHealth.issue === 'oversized') {
     needsCompaction.push('database_size');
   }
 
-  if (!lastCompactedAt && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > METRICS_WARNING_FLOOR)) {
+  if (!lastCompactedAt && canReclaimRows && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > METRICS_WARNING_FLOOR)) {
     needsCompaction.push('never_compacted');
   }
 
   if (
     daysSinceCompaction !== null
+    && canReclaimRows
     && daysSinceCompaction > retentionDays
     && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > DEFAULT_KEEP_LATEST_METRICS)
   ) {
@@ -249,12 +329,19 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
   }
 
   if (needsCompaction.length > 0) {
+    const totalRows = compactionEstimate.totalDeletes;
+    const estimatedBytes = Math.round(storageHealth.sizeBytes * (totalRows / (counts.sessions + counts.sessionEvents + counts.metricsEvents + counts.hookTurnState)));
+    const pctReduction = Math.round((estimatedBytes / storageHealth.sizeBytes) * 100);
+    const impactSummary = totalRows > 0
+      ? `Estimated impact: ~${totalRows} rows, ~${(estimatedBytes / 1024 / 1024).toFixed(1)}MB (${pctReduction}% reduction)`
+      : 'Estimated impact: minimal (no rows to delete with current retention policy)';
+
     return buildCheck({
       id: 'compaction',
       status: 'warning',
       message: 'SQLite retention/compaction hygiene should be refreshed before the local state grows further.',
       recommendedActions: [
-        'Run smart_summary with action="compact" to prune old events and metrics.',
+        `Run smart_summary with action="compact" to prune old events and metrics. ${impactSummary}`,
         'Use vacuum=true if you expect large deletions and want to reclaim file size immediately.',
       ],
       details: {
@@ -264,6 +351,33 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
         schemaVersion,
         activeSessionId,
         counts,
+        compactionEstimate,
+        estimatedImpact: {
+          rowsToDelete: totalRows,
+          bytesReclaimed: estimatedBytes,
+          pctReduction,
+        },
+        lastCompactedAt,
+        daysSinceCompaction,
+        retentionDays,
+      },
+    });
+  }
+
+  if (!lastCompactedAt && !canReclaimRows && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > METRICS_WARNING_FLOOR)) {
+    return buildCheck({
+      id: 'compaction',
+      status: 'info',
+      message: 'SQLite state has never been compacted, but the current retention policy would not reclaim any rows yet.',
+      recommendedActions: [],
+      details: {
+        available: true,
+        recommended: false,
+        reason: 'baseline_not_initialized',
+        schemaVersion,
+        activeSessionId,
+        counts,
+        compactionEstimate,
         lastCompactedAt,
         daysSinceCompaction,
         retentionDays,
@@ -282,6 +396,7 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
       schemaVersion,
       activeSessionId,
       counts,
+      compactionEstimate,
       lastCompactedAt,
       daysSinceCompaction,
       retentionDays,

package/src/tools/smart-shell.js

@@ -10,7 +10,6 @@ import { recordDevctxOperation } from '../missed-opportunities.js';
 
 const execFile = promisify(execFileCallback);
 const isShellDisabled = () => process.env.DEVCTX_SHELL_DISABLED === 'true';
-const blockedPattern = /[|&;<>`\n\r$()]/;
 const allowedCommands = new Set(['pwd', 'ls', 'find', 'rg', 'git', 'npm', 'pnpm', 'yarn', 'bun']);
 const allowedGitSubcommands = new Set(['status', 'diff', 'show', 'log', 'branch', 'rev-parse', 'blame']);
 const allowedPackageManagerSubcommands = new Set(['test', 'run', 'lint', 'build', 'typecheck', 'check']);
@@ -20,8 +19,8 @@ const dangerousPatterns = [
   /sudo/i,
   /curl.*\|/i,
   /wget.*\|/i,
-  /eval/i,
-  /exec/i,
+  /(^|\s)eval(\s|$)/i,
+  /(^|\s)exec(\s|$)/i,
 ];
 const MAX_COMMAND_LENGTH = 500;
 
@@ -79,6 +78,45 @@ const tokenize = (command) => {
   return tokens;
 };
 
+const hasUnquotedShellOperators = (command) => {
+  let inQuote = null;
+  let prevWasEscape = false;
+
+  for (const char of command) {
+    if (prevWasEscape) {
+      prevWasEscape = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      prevWasEscape = true;
+      continue;
+    }
+
+    if (inQuote) {
+      if (char === inQuote) {
+        inQuote = null;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inQuote = char;
+      continue;
+    }
+
+    if (/[|&;<>`\n\r$]/.test(char)) {
+      return true;
+    }
+
+    if (char === '(' || char === ')') {
+      return true;
+    }
+  }
+
+  return false;
+};
+
 const validateCommand = (command, tokens) => {
   if (isShellDisabled()) {
     return 'Shell execution is disabled (DEVCTX_SHELL_DISABLED=true)';
@@ -92,8 +130,8 @@ const validateCommand = (command, tokens) => {
     return `Command too long (max ${MAX_COMMAND_LENGTH} chars)`;
   }
 
-  if (blockedPattern.test(command)) {
-    return 'Shell operators are not allowed (|, &, ;, <, >, `, $, (, ))';
+  if (hasUnquotedShellOperators(command)) {
+    return 'Shell operators are not allowed outside quotes (|, &, ;, <, >, `, $, (, ))';
   }
 
   for (const pattern of dangerousPatterns) {

package/src/utils/runtime-check.js

@@ -0,0 +1,52 @@
+const MINIMUM_NODE_VERSION = 22;
+const MINIMUM_NODE_VERSION_REASON = 'node:sqlite and node:test require Node 22+';
+
+const parseNodeVersion = (versionString) => {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(versionString);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    raw: versionString,
+  };
+};
+
+export const checkNodeVersion = (versionString = process.version) => {
+  const current = parseNodeVersion(versionString);
+
+  if (!current) {
+    return {
+      ok: false,
+      current: versionString,
+      minimum: MINIMUM_NODE_VERSION,
+      message: `Unable to parse Node version: ${versionString}`,
+      reason: MINIMUM_NODE_VERSION_REASON,
+    };
+  }
+
+  const ok = current.major >= MINIMUM_NODE_VERSION;
+
+  return {
+    ok,
+    current: current.raw,
+    minimum: MINIMUM_NODE_VERSION,
+    message: ok
+      ? `Node ${current.raw} meets minimum requirement (${MINIMUM_NODE_VERSION}+)`
+      : `Node ${current.raw} is below minimum requirement (${MINIMUM_NODE_VERSION}+). ${MINIMUM_NODE_VERSION_REASON}`,
+    reason: ok ? null : MINIMUM_NODE_VERSION_REASON,
+  };
+};
+
+export const assertNodeVersion = (versionString = process.version) => {
+  const check = checkNodeVersion(versionString);
+
+  if (!check.ok) {
+    throw new Error(check.message);
+  }
+
+  return check;
+};