smart-context-mcp 1.0.2 → 1.0.4

package/scripts/init-clients.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -118,13 +119,32 @@ const writeFile = (filePath, content, dryRun) => {
   console.log(`updated ${filePath}`);
 };
 
+const runGit = (args, cwd) => {
+  try {
+    const stdout = execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return {
+      ok: true,
+      stdout: stdout.trim(),
+    };
+  } catch {
+    return {
+      ok: false,
+      stdout: '',
+    };
+  }
+};
+
 const getServerConfig = ({ name, command, args, cwd }) => ({
   name,
   config: {
     command,
     args,
     env: {
-      MCP_PROJECT_ROOT: cwd,
+      DEVCTX_PROJECT_ROOT: cwd,
     },
   },
 });
@@ -159,6 +179,61 @@ const updateClaudeConfig = (targetDir, serverConfig, dryRun) => {
   writeFile(filePath, `${JSON.stringify(current, null, 2)}\n`, dryRun);
 };
 
+const buildClaudeHookCommand = (targetDir, eventName) => {
+  const scriptPath = normalizeCommandPath(path.relative(targetDir, path.join(devctxDir, 'scripts', 'claude-hook.js')));
+  return `"${process.execPath}" "${scriptPath}" --event ${eventName} --project-root "$CLAUDE_PROJECT_DIR"`;
+};
+
+const getClaudeHookMatcher = (eventName) => {
+  if (eventName === 'SessionStart') {
+    return 'startup|resume|clear|compact';
+  }
+
+  if (eventName === 'PostToolUse') {
+    return 'Write|Edit|MultiEdit|mcp__.*__smart_turn|mcp__.*__smart_summary';
+  }
+
+  return '*';
+};
+
+const upsertClaudeHook = (settings, eventName, matcher, command) => {
+  settings.hooks ??= {};
+  settings.hooks[eventName] = Array.isArray(settings.hooks[eventName]) ? settings.hooks[eventName] : [];
+
+  const normalizedMatcher = matcher ?? '*';
+  const existingGroup = settings.hooks[eventName].find((group) => (group.matcher ?? '*') === normalizedMatcher);
+
+  if (existingGroup) {
+    existingGroup.hooks = Array.isArray(existingGroup.hooks) ? existingGroup.hooks : [];
+    const alreadyPresent = existingGroup.hooks.some((hook) => hook?.type === 'command' && hook?.command === command);
+    if (!alreadyPresent) {
+      existingGroup.hooks.push({ type: 'command', command });
+    }
+    return;
+  }
+
+  settings.hooks[eventName].push({
+    matcher: normalizedMatcher,
+    hooks: [{ type: 'command', command }],
+  });
+};
+
+const updateClaudeHooksConfig = (targetDir, dryRun) => {
+  const filePath = path.join(targetDir, '.claude', 'settings.json');
+  const current = readJson(filePath, {});
+
+  ['SessionStart', 'UserPromptSubmit', 'PostToolUse', 'Stop'].forEach((eventName) => {
+    upsertClaudeHook(
+      current,
+      eventName,
+      getClaudeHookMatcher(eventName),
+      buildClaudeHookCommand(targetDir, eventName),
+    );
+  });
+
+  writeFile(filePath, `${JSON.stringify(current, null, 2)}\n`, dryRun);
+};
+
 const updateQwenConfig = (targetDir, serverConfig, dryRun) => {
   const filePath = path.join(targetDir, '.qwen', 'settings.json');
   const current = readJson(filePath, {});
@@ -241,6 +316,18 @@ const upsertTomlSection = (content, header, bodyLines) => {
   return `${preserved}\n\n${section}\n`;
 };
 
+const upsertSentinelSection = (content, startMarker, endMarker, section) => {
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    return content.slice(0, startIdx) + section + content.slice(endIdx + endMarker.length);
+  }
+
+  const trimmed = content.trimEnd();
+  return trimmed.length === 0 ? `${section}\n` : `${trimmed}\n\n${section}\n`;
+};
+
 const updateCodexConfig = (targetDir, serverConfig, dryRun) => {
   const filePath = path.join(targetDir, '.codex', 'config.toml');
   const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
@@ -249,12 +336,53 @@ const updateCodexConfig = (targetDir, serverConfig, dryRun) => {
   writeFile(filePath, nextContent, dryRun);
 };
 
+const HOOK_SECTION_START = '# devctx:start';
+const HOOK_SECTION_END = '# devctx:end';
+
+const buildPreCommitHookSection = (targetDir) => {
+  const scriptPath = normalizeCommandPath(path.relative(targetDir, path.join(devctxDir, 'scripts', 'check-repo-safety.js')));
+  return `${HOOK_SECTION_START}
+# Prevent committing project-local devctx state.
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+"${process.execPath}" "${scriptPath}" --project-root "$repo_root"
+status=$?
+if [ "$status" -ne 0 ]; then
+  echo "devctx: commit blocked by repo safety checks." >&2
+  exit "$status"
+fi
+${HOOK_SECTION_END}`;
+};
+
+const updatePreCommitHook = (targetDir, dryRun) => {
+  const hookPathResult = runGit(['rev-parse', '--git-path', 'hooks/pre-commit'], targetDir);
+  if (!hookPathResult.ok || !hookPathResult.stdout) {
+    console.log(`skipped git hook installation for ${targetDir} (not a git repository)`);
+    return;
+  }
+
+  const filePath = path.resolve(targetDir, hookPathResult.stdout);
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const nextBody = upsertSentinelSection(current, HOOK_SECTION_START, HOOK_SECTION_END, buildPreCommitHookSection(targetDir));
+  const nextContent = nextBody.startsWith('#!') ? nextBody : `#!/bin/sh\n\n${nextBody}`;
+  writeFile(filePath, nextContent, dryRun);
+
+  if (!dryRun) {
+    fs.chmodSync(filePath, 0o755);
+  }
+};
+
 // ---------------------------------------------------------------------------
 // Agent rules — instruct agents to prefer devctx tools over built-in ones
 // ---------------------------------------------------------------------------
 
-const agentRuleBody = `Always prefer devctx MCP tools over built-in file reading, code search, and diagnostics.
+const agentRuleBody = `Always prefer devctx MCP tools over built-in file reading, code search, diagnostics, and context recovery.
 
+- For every non-trivial user prompt, start with smart_turn phase=start before exploring the codebase. Pass the current user prompt and ensureSession=true for a meaningful new task.
+- Treat smart_turn phase=start as the default entrypoint for context recovery instead of manually deciding whether to call smart_summary(get).
+- Inspect repoSafety from smart_turn or smart_summary responses. If .devctx/state.sqlite is tracked or staged, mutating context writes are blocked until git hygiene is fixed.
+- If smart_turn phase=start reports ambiguous_resume, choose the recommended session explicitly with smart_summary sessionId="auto" before continuing.
+- After meaningful milestones, end the turn with smart_turn phase=end and the appropriate event (milestone, decision, blocker, task_complete, session_end) so persistence stays event-driven.
+- Before ending work, persist the latest nextStep with smart_turn phase=end and event=session_end.
 - Use smart_read outline or signatures before full (~90% token savings).
 - Use smart_read symbol (string or array) to extract specific functions/classes before editing.
 - Use smart_read range for specific lines when you know the location.
@@ -262,14 +390,15 @@ const agentRuleBody = `Always prefer devctx MCP tools over built-in file reading
 - Use smart_search instead of grep/ripgrep — it groups, ranks, and filters automatically.
 - Pass intent to smart_search to get task-aware ranking (implementation/debug/tests/config/docs/explore).
 - Use smart_shell for diagnostics: git status, ls, find, pwd, test output.
+- Use smart_metrics to report token savings or recent devctx usage instead of reading metrics files manually.
 
 By task:
-- Debugging: smart_search with intent=debug → read signatures → inspect symbol → smart_shell for tests/errors.
-- Review: smart_search with intent=implementation → read outline/signatures, focus on changed symbols, minimal changes.
-- Refactor: smart_search with intent=implementation → signatures for public API, preserve behavior, small edits, verify with tests.
-- Tests: smart_search with intent=tests → find existing tests, read symbol of function under test.
+- Debugging: smart_turn(start) → smart_search with intent=debug → read signatures → inspect symbol → smart_shell for tests/errors → smart_turn(end event=milestone or blocker).
+- Review: smart_turn(start) → smart_search with intent=implementation → read outline/signatures, focus on changed symbols, minimal changes → smart_turn(end event=milestone).
+- Refactor: smart_turn(start) → smart_search with intent=implementation → signatures for public API, preserve behavior, small edits, verify with tests → smart_turn(end event=milestone).
+- Tests: smart_turn(start) → smart_search with intent=tests → find existing tests, read symbol of function under test → smart_turn(end event=milestone).
 - Config: smart_search with intent=config → find settings, env vars, infrastructure files.
-- Architecture: smart_search with intent=explore → directory structure, outlines of key modules and API boundaries.`;
+- Architecture: smart_turn(start) → smart_search with intent=explore → directory structure, outlines of key modules and API boundaries → smart_turn(end event=task_switch or milestone).`;
 
 const cursorRuleContent = `---
 description: Prefer devctx MCP tools for file reading, code search, and diagnostics
@@ -352,6 +481,7 @@ const main = () => {
 
   const clientSet = new Set(options.clients);
   ensureGitignoreEntry(targetDir, options.dryRun);
+  updatePreCommitHook(targetDir, options.dryRun);
 
   if (clientSet.has('cursor')) {
     updateCursorConfig(targetDir, serverConfig, options.dryRun);
@@ -369,6 +499,7 @@ const main = () => {
 
   if (clientSet.has('claude')) {
     updateClaudeConfig(targetDir, serverConfig, options.dryRun);
+    updateClaudeHooksConfig(targetDir, options.dryRun);
     updateClaudeMd(targetDir, options.dryRun);
   }
 

package/scripts/report-metrics.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import fs from 'node:fs';
 import path from 'node:path';
-import { getLegacyMetricsFilePath, getMetricsFilePath } from '../src/metrics.js';
+import { fileURLToPath } from 'node:url';
+import { smartMetrics } from '../src/tools/smart-metrics.js';
 
 const requireValue = (argv, index, flag) => {
   const value = argv[index + 1];
@@ -11,7 +11,7 @@ const requireValue = (argv, index, flag) => {
   return value;
 };
 
-const parseArgs = (argv) => {
+export const parseArgs = (argv) => {
   const options = {
     file: null,
     json: false,
@@ -44,110 +44,24 @@ const parseArgs = (argv) => {
   return options;
 };
 
-const unique = (items) => [...new Set(items.filter(Boolean))];
-
-const resolveMetricsInput = (options) => {
-  if (options.file) {
-    return { filePath: options.file, source: 'explicit' };
-  }
-
-  const defaultPath = getMetricsFilePath();
-  const legacyPath = getLegacyMetricsFilePath();
-  const candidates = unique([defaultPath, legacyPath]);
-  const existing = candidates.find((filePath) => fs.existsSync(filePath));
-
-  if (existing) {
-    return {
-      filePath: existing,
-      source: existing === legacyPath ? 'legacy' : 'default',
-    };
-  }
-
-  return { filePath: defaultPath, source: 'default' };
-};
-
-const readEntries = (filePath) => {
-  if (!fs.existsSync(filePath)) {
-    throw new Error(`No metrics file found at ${filePath}`);
-  }
-
-  const lines = fs.readFileSync(filePath, 'utf8')
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean);
-
-  const entries = [];
-  const invalidLines = [];
+const formatNumber = (value) => new Intl.NumberFormat('en-US').format(value);
 
-  lines.forEach((line, index) => {
-    try {
-      entries.push(JSON.parse(line));
-    } catch {
-      invalidLines.push(index + 1);
-    }
+export const createReport = async (options) => {
+  const result = await smartMetrics({
+    file: options.file,
+    tool: options.tool,
+    window: 'all',
+    latest: 100,
   });
-
-  return { entries, invalidLines };
-};
-
-const getCompressedTokens = (entry) => Number(entry.compressedTokens ?? entry.finalTokens ?? 0);
-
-const getSavedTokens = (entry, compressedTokens) => {
-  if (entry.savedTokens !== undefined) {
-    return Number(entry.savedTokens ?? 0);
-  }
-
-  return Math.max(0, Number(entry.rawTokens ?? 0) - compressedTokens);
-};
-
-const aggregate = (entries) => {
-  const byTool = new Map();
-  let rawTokens = 0;
-  let compressedTokens = 0;
-  let savedTokens = 0;
-
-  for (const entry of entries) {
-    const tool = entry.tool ?? 'unknown';
-    const compressedTokensForEntry = getCompressedTokens(entry);
-    const savedTokensForEntry = getSavedTokens(entry, compressedTokensForEntry);
-    const current = byTool.get(tool) ?? {
-      tool,
-      count: 0,
-      rawTokens: 0,
-      compressedTokens: 0,
-      savedTokens: 0,
-    };
-
-    current.count += 1;
-    current.rawTokens += Number(entry.rawTokens ?? 0);
-    current.compressedTokens += compressedTokensForEntry;
-    current.savedTokens += savedTokensForEntry;
-    byTool.set(tool, current);
-
-    rawTokens += Number(entry.rawTokens ?? 0);
-    compressedTokens += compressedTokensForEntry;
-    savedTokens += savedTokensForEntry;
-  }
-
-  const tools = [...byTool.values()]
-    .map((item) => ({
-      ...item,
-      savingsPct: item.rawTokens > 0 ? +((item.savedTokens / item.rawTokens) * 100).toFixed(2) : 0,
-    }))
-    .sort((a, b) => b.savedTokens - a.savedTokens || b.count - a.count || a.tool.localeCompare(b.tool));
-
   return {
-    count: entries.length,
-    rawTokens,
-    compressedTokens,
-    savedTokens,
-    savingsPct: rawTokens > 0 ? +((savedTokens / rawTokens) * 100).toFixed(2) : 0,
-    tools,
+    filePath: result.filePath,
+    source: result.source,
+    toolFilter: options.tool,
+    invalidLines: result.invalidLines,
+    summary: result.summary,
   };
 };
 
-const formatNumber = (value) => new Intl.NumberFormat('en-US').format(value);
-
 const printHuman = (report) => {
   console.log('');
   console.log('devctx metrics report');
@@ -176,20 +90,9 @@ const printHuman = (report) => {
   }
 };
 
-const main = () => {
+export const main = async () => {
   const options = parseArgs(process.argv.slice(2));
-  const resolved = resolveMetricsInput(options);
-  const { entries, invalidLines } = readEntries(resolved.filePath);
-  const filteredEntries = options.tool ? entries.filter((entry) => entry.tool === options.tool) : entries;
-  const summary = aggregate(filteredEntries);
-
-  const report = {
-    filePath: resolved.filePath,
-    source: resolved.source,
-    toolFilter: options.tool,
-    invalidLines,
-    summary,
-  };
+  const report = await createReport(options);
 
   if (options.json) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -199,9 +102,11 @@ const main = () => {
   printHuman(report);
 };
 
-try {
-  main();
-} catch (error) {
-  console.error(error.message);
-  process.exit(1);
+const isDirectExecution = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectExecution) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
 }