smart-context-mcp 1.1.0 → 1.3.0

package/src/tools/smart-shell.js

@@ -4,13 +4,26 @@ import { rgPath } from '@vscode/ripgrep';
 import { buildMetrics, persistMetrics } from '../metrics.js';
 import { projectRoot } from '../utils/paths.js';
 import { pickRelevantLines, truncate, uniqueLines } from '../utils/text.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
 
 const execFile = promisify(execFileCallback);
-const blockedPattern = /[|&;<>`\n\r]/;
+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']);
+const allowedGitSubcommands = new Set(['status', 'diff', 'show', 'log', 'branch', 'rev-parse', 'blame']);
 const allowedPackageManagerSubcommands = new Set(['test', 'run', 'lint', 'build', 'typecheck', 'check']);
-const safeRunScriptPattern = /^(test|lint|build|typecheck|check|smoke|verify)(:|$)/;
+const safeRunScriptPattern = /^(test|lint|build|typecheck|check|smoke|verify|eval)(:|$)/;
+const dangerousPatterns = [
+  /rm\s+-rf/i,
+  /sudo/i,
+  /curl.*\|/i,
+  /wget.*\|/i,
+  /eval/i,
+  /exec/i,
+];
+const MAX_COMMAND_LENGTH = 500;
 
 const tokenize = (command) => {
   const tokens = [];
@@ -67,12 +80,26 @@ const tokenize = (command) => {
 };
 
 const validateCommand = (command, tokens) => {
+  if (isShellDisabled()) {
+    return 'Shell execution is disabled (DEVCTX_SHELL_DISABLED=true)';
+  }
+
   if (!command.trim()) {
     return 'Command is empty';
   }
 
-  if (blockedPattern.test(command) || command.includes('$(')) {
-    return 'Shell operators are not allowed';
+  if (command.length > MAX_COMMAND_LENGTH) {
+    return `Command too long (max ${MAX_COMMAND_LENGTH} chars)`;
+  }
+
+  if (blockedPattern.test(command)) {
+    return 'Shell operators are not allowed (|, &, ;, <, >, `, $, (, ))';
+  }
+
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(command)) {
+      return `Dangerous pattern detected: ${pattern.source}`;
+    }
   }
 
   if (tokens.length === 0) {
@@ -82,11 +109,11 @@ const validateCommand = (command, tokens) => {
   const [baseCommand, subcommand, thirdToken] = tokens;
 
   if (!allowedCommands.has(baseCommand)) {
-    return `Command not allowed: ${baseCommand}`;
+    return `Command not allowed: ${baseCommand}. Allowed: ${[...allowedCommands].join(', ')}`;
   }
 
   if (baseCommand === 'git' && !allowedGitSubcommands.has(subcommand)) {
-    return `Git subcommand not allowed: ${subcommand ?? '(missing)'}`;
+    return `Git subcommand not allowed: ${subcommand ?? '(missing)'}. Allowed: ${[...allowedGitSubcommands].join(', ')}`;
   }
 
   if (baseCommand === 'find') {
@@ -99,11 +126,11 @@ const validateCommand = (command, tokens) => {
 
   if (['npm', 'pnpm', 'yarn', 'bun'].includes(baseCommand)) {
     if (!subcommand || !allowedPackageManagerSubcommands.has(subcommand)) {
-      return `Package manager subcommand not allowed: ${subcommand ?? '(missing)'}`;
+      return `Package manager subcommand not allowed: ${subcommand ?? '(missing)'}. Allowed: ${[...allowedPackageManagerSubcommands].join(', ')}`;
     }
 
     if (subcommand === 'run' && (!thirdToken || !safeRunScriptPattern.test(thirdToken))) {
-      return `Package manager script not allowed: ${thirdToken ?? '(missing)'}`;
+      return `Package manager script not allowed: ${thirdToken ?? '(missing)'}. Allowed pattern: ${safeRunScriptPattern.source}`;
     }
   }
 
@@ -197,6 +224,32 @@ export const smartShell = async ({ command }) => {
   });
 
   await persistMetrics(metrics);
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_shell',
+    savedTokens: metrics.savedTokens,
+    target: command,
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  const outputLines = rawText.split('\n').length;
+  let reason = DECISION_REASONS.COMMAND_OUTPUT;
+  if (shouldPrioritizeRelevant && relevant) {
+    reason = DECISION_REASONS.RELEVANT_LINES;
+  }
+  
+  recordDecision({
+    tool: 'smart_shell',
+    action: `execute "${command}"`,
+    reason,
+    alternative: 'Shell (uncompressed output)',
+    expectedBenefit: EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens),
+    context: `${outputLines} lines → ${compressedText.split('\n').length} lines (relevant only)`,
+  });
 
   const result = {
     command,

package/src/tools/smart-summary.js

@@ -1,6 +1,9 @@
 import { countTokens } from '../tokenCounter.js';
 import { persistMetrics } from '../metrics.js';
 import { enforceRepoSafety, getRepoSafety } from '../repo-safety.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
 import {
   ACTIVE_SESSION_SCOPE,
   SQLITE_SCHEMA_VERSION,
@@ -1212,6 +1215,23 @@ export const smartSummary = async ({
           ...summaryMetrics,
           latencyMs: Date.now() - startTime,
         });
+        
+        recordToolUsage({
+          tool: 'smart_summary',
+          savedTokens: summaryMetrics.savedTokens || 0,
+          target: targetSessionId,
+        });
+        
+        recordDevctxOperation();
+        
+        recordDecision({
+          tool: 'smart_summary',
+          action: `get checkpoint "${targetSessionId}"`,
+          reason: DECISION_REASONS.RESUME,
+          alternative: 'Start from scratch (lose context)',
+          expectedBenefit: EXPECTED_BENEFITS.SESSION_RECOVERY,
+          context: `Recovered ${compressed.goal ? 'goal' : 'state'}, ${compressed.status || 'unknown'} status`,
+        });
       }
 
       return addRepoSafety({
@@ -1356,14 +1376,21 @@ export const smartSummary = async ({
         const { compressed, tokens, truncated, omitted, compressionLevel } = compressSummary(currentSession, maxTokens);
         const rawTokens = countTokens(JSON.stringify(currentSession));
 
+        const metrics = buildSummaryMetrics(rawTokens, tokens);
         persistMetrics({
           tool: 'smart_summary',
           action,
           sessionId: targetSessionId,
-          ...buildSummaryMetrics(rawTokens, tokens),
+          ...metrics,
           latencyMs: Date.now() - startTime,
           skipped: true,
         });
+        
+        recordToolUsage({
+          tool: 'smart_summary',
+          savedTokens: metrics.savedTokens || 0,
+          target: targetSessionId,
+        });
 
         return addRepoSafety({
           action,
@@ -1386,15 +1413,24 @@ export const smartSummary = async ({
         const { compressed, tokens, truncated, omitted, compressionLevel } = compressSummary(currentSession, maxTokens);
         const rawTokens = countTokens(JSON.stringify(currentSession));
 
+        const metrics2 = buildSummaryMetrics(rawTokens, tokens);
         persistMetrics({
           tool: 'smart_summary',
           action,
           sessionId: targetSessionId,
-          ...buildSummaryMetrics(rawTokens, tokens),
+          ...metrics2,
           latencyMs: Date.now() - startTime,
           skipped: true,
           checkpointEvent: checkpointDecision.event,
         });
+        
+        recordToolUsage({
+          tool: 'smart_summary',
+          savedTokens: metrics2.savedTokens || 0,
+          target: targetSessionId,
+        });
+        
+        recordDevctxOperation();
 
         return addRepoSafety({
           action,
@@ -1455,6 +1491,14 @@ export const smartSummary = async ({
         latencyMs: Date.now() - startTime,
         ...(action === 'checkpoint' ? { checkpointEvent: checkpointDecision.event } : {}),
       });
+      
+      recordToolUsage({
+        tool: 'smart_summary',
+        savedTokens: summaryMetrics.savedTokens || 0,
+        target: targetSessionId,
+      });
+      
+      recordDevctxOperation();
 
       return addRepoSafety({
         action,

package/src/tools/smart-turn.js

@@ -205,6 +205,7 @@ const startTurn = async ({
       })
     : null;
 
+
   return {
     phase: 'start',
     promptPreview: truncate(prompt, MAX_PROMPT_PREVIEW),

package/src/usage-feedback.js

@@ -0,0 +1,179 @@
+/**
+ * Usage feedback system - tracks devctx tool usage in current session
+ * and provides visible feedback to users about what tools were used and tokens saved.
+ * 
+ * Enable with environment variable: DEVCTX_SHOW_USAGE=true
+ * 
+ * Auto-enabled for first 10 tool calls (onboarding mode), then auto-disables.
+ * User can explicitly enable/disable at any time.
+ */
+
+const sessionUsage = {
+  tools: new Map(), // toolName -> { count, savedTokens }
+  totalSavedTokens: 0,
+  enabled: false,
+  totalToolCalls: 0,
+  onboardingMode: true,
+  ONBOARDING_THRESHOLD: 10, // Auto-disable after 10 tool calls
+};
+
+/**
+ * Check if usage feedback is enabled
+ * 
+ * Priority:
+ * 1. Explicit env var (DEVCTX_SHOW_USAGE=true/false)
+ * 2. Onboarding mode (first 10 tool calls)
+ * 3. Default: disabled
+ */
+export const isFeedbackEnabled = () => {
+  const envValue = process.env.DEVCTX_SHOW_USAGE?.toLowerCase();
+  
+  // Explicit enable
+  if (envValue === 'true' || envValue === '1' || envValue === 'yes') {
+    sessionUsage.enabled = true;
+    sessionUsage.onboardingMode = false;
+    return true;
+  }
+  
+  // Explicit disable
+  if (envValue === 'false' || envValue === '0' || envValue === 'no') {
+    sessionUsage.enabled = false;
+    sessionUsage.onboardingMode = false;
+    return false;
+  }
+  
+  // Onboarding mode: auto-enable for first N tool calls
+  if (sessionUsage.onboardingMode && sessionUsage.totalToolCalls < sessionUsage.ONBOARDING_THRESHOLD) {
+    sessionUsage.enabled = true;
+    return true;
+  }
+  
+  // After onboarding threshold, auto-disable
+  if (sessionUsage.onboardingMode && sessionUsage.totalToolCalls >= sessionUsage.ONBOARDING_THRESHOLD) {
+    sessionUsage.enabled = false;
+    sessionUsage.onboardingMode = false;
+  }
+  
+  return sessionUsage.enabled;
+};
+
+/**
+ * Record tool usage for feedback
+ */
+export const recordToolUsage = ({ tool, savedTokens = 0, target = null }) => {
+  // Increment total tool calls (for onboarding mode)
+  sessionUsage.totalToolCalls += 1;
+  
+  if (!isFeedbackEnabled()) return;
+  
+  const current = sessionUsage.tools.get(tool) || { count: 0, savedTokens: 0, targets: [] };
+  current.count += 1;
+  current.savedTokens += savedTokens;
+  if (target) current.targets.push(target);
+  
+  sessionUsage.tools.set(tool, current);
+  sessionUsage.totalSavedTokens += savedTokens;
+};
+
+/**
+ * Get current session usage stats
+ */
+export const getSessionUsage = () => {
+  return {
+    tools: Array.from(sessionUsage.tools.entries()).map(([tool, stats]) => ({
+      tool,
+      count: stats.count,
+      savedTokens: stats.savedTokens,
+      targets: stats.targets.slice(-3), // Last 3 targets only
+    })),
+    totalSavedTokens: sessionUsage.totalSavedTokens,
+  };
+};
+
+/**
+ * Format usage feedback as markdown
+ */
+export const formatUsageFeedback = () => {
+  if (!isFeedbackEnabled()) return '';
+  
+  const usage = getSessionUsage();
+  if (usage.tools.length === 0) return '';
+  
+  const lines = [];
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('📊 **devctx usage this session:**');
+  
+  // Sort by count descending
+  const sorted = usage.tools.sort((a, b) => b.count - a.count);
+  
+  for (const { tool, count, savedTokens, targets } of sorted) {
+    const countStr = count === 1 ? '1 call' : `${count} calls`;
+    const tokensStr = savedTokens > 0 ? ` | ~${formatTokens(savedTokens)} saved` : '';
+    
+    if (targets.length > 0) {
+      const targetsPreview = targets.length === 1 
+        ? ` (${truncateTarget(targets[0])})`
+        : ` (${targets.length} files)`;
+      lines.push(`- **${tool}**: ${countStr}${tokensStr}${targetsPreview}`);
+    } else {
+      lines.push(`- **${tool}**: ${countStr}${tokensStr}`);
+    }
+  }
+  
+  if (usage.totalSavedTokens > 0) {
+    lines.push('');
+    lines.push(`**Total saved:** ~${formatTokens(usage.totalSavedTokens)}`);
+  }
+  
+  lines.push('');
+  
+  // Show onboarding message if in onboarding mode
+  if (sessionUsage.onboardingMode && sessionUsage.totalToolCalls < sessionUsage.ONBOARDING_THRESHOLD) {
+    const remaining = sessionUsage.ONBOARDING_THRESHOLD - sessionUsage.totalToolCalls;
+    lines.push(`*Onboarding mode: showing for ${remaining} more tool calls. To keep: \`export DEVCTX_SHOW_USAGE=true\`*`);
+  } else {
+    lines.push('*To disable this message: `export DEVCTX_SHOW_USAGE=false`*');
+  }
+  
+  return lines.join('\n');
+};
+
+/**
+ * Reset session usage (for testing or manual reset)
+ */
+export const resetSessionUsage = () => {
+  sessionUsage.tools.clear();
+  sessionUsage.totalSavedTokens = 0;
+  sessionUsage.totalToolCalls = 0;
+  sessionUsage.onboardingMode = true;
+};
+
+/**
+ * Format token count for display
+ */
+const formatTokens = (tokens) => {
+  if (tokens >= 1000000) {
+    return `${(tokens / 1000000).toFixed(1)}M tokens`;
+  }
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}K tokens`;
+  }
+  return `${tokens} tokens`;
+};
+
+/**
+ * Truncate target path for display
+ */
+const truncateTarget = (target) => {
+  if (!target) return '';
+  if (target.length <= 40) return target;
+  
+  // Try to show filename
+  const parts = target.split('/');
+  const filename = parts[parts.length - 1];
+  if (filename.length <= 40) return `.../${filename}`;
+  
+  return target.slice(0, 37) + '...';
+};

package/src/workflow-tracker-stub.js

@@ -0,0 +1,53 @@
+// Stub for workflow tracking (to be implemented in future version)
+// This avoids SQLite issues in tests while keeping the API available
+
+export const detectWorkflowType = () => null;
+export const getWorkflowBaseline = () => 0;
+export const startWorkflow = () => null;
+export const endWorkflow = () => null;
+export const getWorkflowMetrics = () => [];
+export const getWorkflowSummaryByType = () => [];
+export const autoTrackWorkflow = () => null;
+
+export const WORKFLOW_DEFINITIONS = {
+  debugging: {
+    name: 'Debugging',
+    description: 'Error-first, symbol-focused debugging workflow',
+    typicalTools: ['smart_turn', 'smart_search', 'smart_read', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 150000,
+    pattern: /debug|error|bug|fix|fail/i,
+  },
+  'code-review': {
+    name: 'Code Review',
+    description: 'Diff-aware, API-focused code review workflow',
+    typicalTools: ['smart_turn', 'smart_context', 'smart_read', 'git_blame', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 200000,
+    pattern: /review|pr|pull.?request|approve/i,
+  },
+  refactoring: {
+    name: 'Refactoring',
+    description: 'Graph-aware, test-verified refactoring workflow',
+    typicalTools: ['smart_turn', 'smart_context', 'smart_read', 'git_blame', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 180000,
+    pattern: /refactor|extract|rename|move|restructure/i,
+  },
+  testing: {
+    name: 'Testing',
+    description: 'Coverage-aware, TDD-friendly testing workflow',
+    typicalTools: ['smart_turn', 'smart_search', 'smart_read', 'smart_context', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 120000,
+    pattern: /test|spec|coverage|tdd/i,
+  },
+  architecture: {
+    name: 'Architecture Exploration',
+    description: 'Index-first, minimal-detail architecture exploration',
+    typicalTools: ['smart_turn', 'smart_context', 'smart_search', 'smart_read', 'cross_project'],
+    minTools: 3,
+    baselineTokens: 300000,
+    pattern: /architect|explore|understand|structure|design/i,
+  },
+};