smart-context-mcp 1.18.1 → 1.20.0

package/src/index.js

@@ -4,8 +4,9 @@ import path from 'node:path';
 import ts from 'typescript';
 import { isBinaryBuffer } from './utils/fs.js';
 import { IGNORED_DIRS } from './config/ignored-paths.js';
+import { getParser } from './parsers/registry.js';
 
-const INDEX_VERSION = 6;
+const INDEX_VERSION = 7;
 
 const MAX_SIGNATURE_LEN = 200;
 const MAX_SNIPPET_LEN = 280;
@@ -231,31 +232,78 @@ const extractJsImportsExports = (sourceFile) => {
 // ---------------------------------------------------------------------------
 
 const PYTHON_SYMBOL_RE = /^(class|def|async\s+def)\s+(\w+)/;
+const PYTHON_TYPE_ALIAS_RE = /^(\w+)\s*:\s*(?:TypeAlias|"TypeAlias")\s*=/;
+const PYTHON_TYPEVAR_RE = /^(\w+)\s*=\s*(?:TypeVar|NewType|ParamSpec|TypeVarTuple)\s*\(/;
 
 const extractPySymbols = (content) => {
   const symbols = [];
   const lines = content.split('\n');
   let currentClass = null;
+  let currentClassIndent = -1;
+  let pendingDecorators = [];
 
   for (let i = 0; i < lines.length; i++) {
     const trimmed = lines[i].trimStart();
     const indent = lines[i].length - trimmed.length;
+
+    if (trimmed.startsWith('@')) {
+      pendingDecorators.push(trimmed.slice(1).split('(')[0].trim());
+      continue;
+    }
+
+    if (currentClass !== null && trimmed !== '' && indent <= currentClassIndent) {
+      currentClass = null;
+      currentClassIndent = -1;
+    }
+
+    const aliasMatch = PYTHON_TYPE_ALIAS_RE.exec(trimmed) ?? PYTHON_TYPEVAR_RE.exec(trimmed);
+    if (aliasMatch) {
+      symbols.push({
+        name: aliasMatch[1],
+        kind: 'type',
+        line: i + 1,
+        signature: trimSignature(trimmed),
+      });
+      pendingDecorators = [];
+      continue;
+    }
+
     const match = PYTHON_SYMBOL_RE.exec(trimmed);
-    if (!match) continue;
+    if (!match) {
+      if (trimmed !== '') pendingDecorators = [];
+      continue;
+    }
 
     const keyword = match[1].replace(/\s+/g, ' ');
     const name = match[2];
     const line = i + 1;
     const signature = trimSignature(trimmed.replace(/:$/, ''));
+    const decorators = pendingDecorators.length > 0 ? [...pendingDecorators] : undefined;
+    pendingDecorators = [];
 
     if (keyword === 'class') {
       currentClass = name;
-      symbols.push({ name, kind: 'class', line, signature });
-    } else if (indent > 0 && currentClass) {
-      symbols.push({ name, kind: 'method', line, parent: currentClass, signature });
+      currentClassIndent = indent;
+      symbols.push({ name, kind: 'class', line, signature, ...(decorators && { decorators }) });
+    } else if (currentClass !== null && indent > currentClassIndent) {
+      symbols.push({
+        name,
+        kind: keyword === 'async def' ? 'async-method' : 'method',
+        line,
+        parent: currentClass,
+        signature,
+        ...(decorators && { decorators }),
+      });
     } else {
       currentClass = null;
-      symbols.push({ name, kind: 'function', line, signature });
+      currentClassIndent = -1;
+      symbols.push({
+        name,
+        kind: keyword === 'async def' ? 'async-function' : 'function',
+        line,
+        signature,
+        ...(decorators && { decorators }),
+      });
     }
   }
 
@@ -277,8 +325,10 @@ const extractPyImports = (content) => {
 // Go extraction
 // ---------------------------------------------------------------------------
 
-const GO_FUNC_RE = /^func\s+(?:\([\w\s*]+\)\s+)?(\w+)\s*\(/;
-const GO_TYPE_RE = /^type\s+(\w+)\s+/;
+const GO_METHOD_RE = /^func\s+\(\s*\w+\s+\*?(\w+)\s*\)\s+(\w+)\s*\(/;
+const GO_FUNC_RE = /^func\s+(\w+)\s*\(/;
+const GO_TYPE_RE = /^type\s+(\w+)\s+(struct|interface|\w+)/;
+const GO_CONST_RE = /^(?:const|var)\s+(\w+)\s*(?:=|\s+\w)/;
 
 const extractGoSymbols = (content) => {
   const symbols = [];
@@ -286,6 +336,17 @@ const extractGoSymbols = (content) => {
 
   for (let i = 0; i < lines.length; i++) {
     const trimmed = lines[i].trimStart();
+    const methodMatch = GO_METHOD_RE.exec(trimmed);
+    if (methodMatch) {
+      symbols.push({
+        name: methodMatch[2],
+        kind: 'method',
+        line: i + 1,
+        parent: methodMatch[1],
+        signature: trimSignature(trimmed),
+      });
+      continue;
+    }
     const funcMatch = GO_FUNC_RE.exec(trimmed);
     if (funcMatch) {
       symbols.push({ name: funcMatch[1], kind: 'function', line: i + 1, signature: trimSignature(trimmed) });
@@ -293,7 +354,14 @@ const extractGoSymbols = (content) => {
     }
     const typeMatch = GO_TYPE_RE.exec(trimmed);
     if (typeMatch) {
-      symbols.push({ name: typeMatch[1], kind: 'type', line: i + 1, signature: trimSignature(trimmed) });
+      const kind = typeMatch[2] === 'interface' ? 'interface' : 'type';
+      symbols.push({ name: typeMatch[1], kind, line: i + 1, signature: trimSignature(trimmed) });
+      continue;
+    }
+    const constMatch = GO_CONST_RE.exec(trimmed);
+    if (constMatch) {
+      const kind = trimmed.startsWith('const') ? 'const' : 'var';
+      symbols.push({ name: constMatch[1], kind, line: i + 1, signature: trimSignature(trimmed) });
     }
   }
 
@@ -677,6 +745,20 @@ export const extractAdrSymbols = (content, fullPath) => {
 const extractFileInfo = (fullPath, content) => {
   const ext = path.extname(fullPath).toLowerCase();
 
+  const pluggable = getParser(ext);
+  if (pluggable) {
+    try {
+      const result = pluggable({ fullPath, content }) ?? {};
+      return {
+        symbols: enrichSymbolsWithSnippets(content, result.symbols ?? []),
+        imports: result.imports ?? [],
+        exports: result.exports ?? [],
+      };
+    } catch {
+      return { symbols: [], imports: [], exports: [] };
+    }
+  }
+
   let info;
 
   if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {

package/src/orchestration/base-orchestrator.js

@@ -16,6 +16,7 @@ import {
 export const DEFAULT_ORCHESTRATION_EVENT = 'session_end';
 export const DEFAULT_START_MAX_TOKENS = 350;
 export const DEFAULT_END_MAX_TOKENS = 350;
+const SIMPLE_TASK_SKIP_MAX_LENGTH = 40;
 
 const buildContextLines = (startResult) => {
   const context = buildOperationalContextLines(startResult, {
@@ -53,11 +54,31 @@ const buildFreshSessionUpdate = (prompt) => {
   };
 };
 
+const buildSimpleTaskStartResult = (prompt) => ({
+  phase: 'start',
+  skipSmartTurn: true,
+  continuity: {
+    state: 'simple_task_skip',
+    shouldReuseContext: false,
+    reason: 'Simple task heuristic skipped persisted continuity setup to avoid overhead.',
+  },
+  recommendedPath: {
+    phase: 'start',
+    mode: 'simple_task_skip',
+    nextTools: ['smart_read', 'smart_search'],
+    nextActions: [],
+    next: 'smart_read: Skip smart_turn for this simple task and use lightweight read/search directly.',
+  },
+  message: 'Simple task heuristic skipped smart_turn(start); use lightweight read/search flow unless the task grows.',
+  ...(prompt ? { promptPreview: truncate(prompt, MAX_FOCUS_LENGTH) } : {}),
+});
+
 const ensureIsolatedSession = async ({
   prompt,
   sessionId,
   startResult,
   startMaxTokens = DEFAULT_START_MAX_TOKENS,
+  tokenBudget,
   summaryTool = smartSummary,
   startTurn = smartTurn,
 }) => {
@@ -96,6 +117,7 @@ const ensureIsolatedSession = async ({
     prompt,
     ensureSession: false,
     maxTokens: startMaxTokens,
+    tokenBudget,
   });
 
   return {
@@ -112,11 +134,23 @@ export const resolveManagedStart = async ({
   ensureSession = true,
   allowIsolation = false,
   startMaxTokens = DEFAULT_START_MAX_TOKENS,
+  tokenBudget,
   startTurn = smartTurn,
   summaryTool = smartSummary,
   enableFastPath = true,
 }) => {
-  const simpleTask = enableFastPath && isSimpleTask(prompt);
+  const simpleTask = enableFastPath && isSimpleTask(prompt) && normalizeWhitespace(prompt).length <= SIMPLE_TASK_SKIP_MAX_LENGTH;
+
+  if (simpleTask && !preparedStartResult && !sessionId) {
+    const startResult = buildSimpleTaskStartResult(prompt);
+    return {
+      startResult,
+      isolated: false,
+      previousSessionId: null,
+      autoStarted: false,
+      fastPath: true,
+    };
+  }
 
   const startResult = preparedStartResult ?? await startTurn({
     phase: 'start',
@@ -124,6 +158,7 @@ export const resolveManagedStart = async ({
     prompt,
     ensureSession: simpleTask ? false : ensureSession,
     maxTokens: startMaxTokens,
+    tokenBudget,
   });
 
   if (!allowIsolation || simpleTask) {
@@ -141,6 +176,7 @@ export const resolveManagedStart = async ({
     sessionId,
     startResult,
     startMaxTokens,
+    tokenBudget,
     summaryTool,
     startTurn,
   });

package/src/parsers/registry.js

@@ -0,0 +1,26 @@
+const parsers = new Map();
+const importExtractors = new Map();
+
+export const registerParser = (extension, parser) => {
+  if (!extension || typeof parser !== 'function') return;
+  parsers.set(extension.toLowerCase(), parser);
+};
+
+export const registerImportExtractor = (extension, extractor) => {
+  if (!extension || typeof extractor !== 'function') return;
+  importExtractors.set(extension.toLowerCase(), extractor);
+};
+
+export const getParser = (extension) => parsers.get(extension?.toLowerCase()) ?? null;
+
+export const getImportExtractor = (extension) => importExtractors.get(extension?.toLowerCase()) ?? null;
+
+export const listRegisteredExtensions = () => ({
+  symbols: [...parsers.keys()],
+  imports: [...importExtractors.keys()],
+});
+
+export const clearRegistry = () => {
+  parsers.clear();
+  importExtractors.clear();
+};

package/src/playbooks/builtin/debug-flake.yaml

@@ -0,0 +1,17 @@
+name: debug-flake
+description: Recover last red test, gather curated debug context, list affected tests
+defaults: {}
+stopOnFail: false
+steps:
+  - tool: smart_test
+    label: lastFailure
+    args:
+      action: last_failure
+  - tool: smart_context
+    args:
+      task: "Debug last failing test"
+      intent: debug
+      maxTokens: 8000
+  - tool: smart_test
+    args:
+      action: affected

package/src/playbooks/builtin/doc-sync.yaml

@@ -0,0 +1,16 @@
+name: doc-sync
+description: Surface ADR/spec sections then build curated docs context
+defaults:
+  topic: "architecture"
+stopOnFail: false
+steps:
+  - tool: smart_search
+    args:
+      query: "{{args.topic}}"
+      kinds:
+        - adr
+        - adr-section
+  - tool: smart_context
+    args:
+      task: "Sync docs for {{args.topic}}"
+      intent: docs

package/src/playbooks/builtin/preflight-merge.yaml

@@ -0,0 +1,20 @@
+name: preflight-merge
+description: Review preflight + affected tests + milestone checkpoint
+defaults:
+  ref: HEAD
+stopOnFail: true
+steps:
+  - tool: smart_review
+    label: review
+    args:
+      ref: "{{args.ref}}"
+      includeBlame: false
+  - tool: smart_test
+    label: affected
+    args:
+      action: affected
+      diff: "{{args.ref}}"
+  - tool: smart_turn
+    args:
+      phase: end
+      event: milestone

package/src/playbooks/builtin/ramp-up.yaml

@@ -0,0 +1,14 @@
+name: ramp-up
+description: First contact with the project — status, doctor, and ADR overview
+defaults: {}
+stopOnFail: false
+steps:
+  - tool: smart_status
+    args: {}
+  - tool: smart_doctor
+    args: {}
+  - tool: smart_search
+    args:
+      query: "architecture decisions"
+      kinds:
+        - adr

package/src/playbooks/builtin/refactor-safe.yaml

@@ -0,0 +1,18 @@
+name: refactor-safe
+description: Curated context + outline reads + affected tests, ending with checkpoint
+defaults:
+  task: "Refactor target"
+stopOnFail: true
+steps:
+  - tool: smart_context
+    args:
+      task: "{{args.task}}"
+      intent: refactor
+      detail: balanced
+  - tool: smart_test
+    args:
+      action: affected
+  - tool: smart_turn
+    args:
+      phase: end
+      event: milestone

package/src/playbooks/loader.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { projectRoot } from '../utils/runtime-config.js';
+import { parseYamlMini } from './yaml-mini.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BUILTIN_DIR = path.join(__dirname, 'builtin');
+const PROJECT_DIR_NAME = '.devctx/playbooks';
+
+const SUPPORTED_EXT = new Set(['.yaml', '.yml', '.json']);
+const SAFE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+
+const listFilesIn = (dir) => {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && SUPPORTED_EXT.has(path.extname(entry.name).toLowerCase()))
+    .map((entry) => path.join(dir, entry.name));
+};
+
+const parseContent = (content, ext) => {
+  if (ext === '.json') return JSON.parse(content);
+  return parseYamlMini(content);
+};
+
+const nameFromFile = (file) => {
+  const base = path.basename(file).replace(/\.(ya?ml|json)$/i, '');
+  return base;
+};
+
+const validatePlaybook = (raw, sourceFile) => {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`Playbook ${sourceFile}: root must be a mapping`);
+  }
+  if (!raw.name || typeof raw.name !== 'string' || !SAFE_NAME_RE.test(raw.name)) {
+    throw new Error(`Playbook ${sourceFile}: missing/invalid 'name'`);
+  }
+  if (!Array.isArray(raw.steps) || raw.steps.length === 0) {
+    throw new Error(`Playbook ${raw.name}: 'steps' must be a non-empty array`);
+  }
+  for (const [i, step] of raw.steps.entries()) {
+    if (!step || typeof step !== 'object') {
+      throw new Error(`Playbook ${raw.name}: step ${i} must be an object`);
+    }
+    if (typeof step.tool !== 'string' || step.tool.length === 0) {
+      throw new Error(`Playbook ${raw.name}: step ${i} missing 'tool'`);
+    }
+    if (step.args !== undefined && step.args !== null && (typeof step.args !== 'object' || Array.isArray(step.args))) {
+      throw new Error(`Playbook ${raw.name}: step ${i} 'args' must be an object`);
+    }
+  }
+  return {
+    name: raw.name,
+    description: typeof raw.description === 'string' ? raw.description : '',
+    defaults: raw.defaults && typeof raw.defaults === 'object' && !Array.isArray(raw.defaults) ? raw.defaults : {},
+    stopOnFail: raw.stopOnFail !== false,
+    steps: raw.steps.map((step) => ({
+      tool: step.tool,
+      args: (step.args && typeof step.args === 'object' && !Array.isArray(step.args)) ? step.args : {},
+      when: typeof step.when === 'string' ? step.when : null,
+      label: typeof step.label === 'string' ? step.label : null,
+    })),
+    source: sourceFile,
+  };
+};
+
+const collectFromDir = (dir, source) => {
+  const out = new Map();
+  for (const file of listFilesIn(dir)) {
+    try {
+      const ext = path.extname(file).toLowerCase();
+      const raw = parseContent(fs.readFileSync(file, 'utf-8'), ext);
+      const playbook = validatePlaybook(raw, source);
+      if (playbook.name !== nameFromFile(file)) {
+        playbook.fileName = nameFromFile(file);
+      }
+      out.set(playbook.name, playbook);
+    } catch (err) {
+      out.set(`__error__${path.basename(file)}`, { error: err.message, source, file });
+    }
+  }
+  return out;
+};
+
+export const loadPlaybooks = ({ root = projectRoot } = {}) => {
+  const builtin = collectFromDir(BUILTIN_DIR, 'builtin');
+  const projectDir = path.join(root, PROJECT_DIR_NAME);
+  const project = collectFromDir(projectDir, 'project');
+
+  const merged = new Map(builtin);
+  for (const [name, pb] of project) merged.set(name, pb);
+
+  return {
+    playbooks: merged,
+    sources: {
+      builtinDir: BUILTIN_DIR,
+      projectDir,
+      projectExists: fs.existsSync(projectDir),
+    },
+  };
+};
+
+export const listPlaybookSummaries = ({ root = projectRoot } = {}) => {
+  const { playbooks, sources } = loadPlaybooks({ root });
+  const summaries = [];
+  const errors = [];
+  for (const [, value] of playbooks) {
+    if (value.error) {
+      errors.push({ file: value.file, error: value.error, source: value.source });
+      continue;
+    }
+    summaries.push({
+      name: value.name,
+      description: value.description,
+      source: value.source,
+      steps: value.steps.length,
+      defaults: value.defaults,
+    });
+  }
+  return { summaries, errors, sources };
+};
+
+export const _internal = { validatePlaybook, parseContent, nameFromFile };

package/src/playbooks/runner.js

@@ -0,0 +1,182 @@
+import { smartContext } from '../tools/smart-context.js';
+import { smartSearch } from '../tools/smart-search.js';
+import { smartRead } from '../tools/smart-read.js';
+import { smartReadBatch } from '../tools/smart-read-batch.js';
+import { smartTest } from '../tools/smart-test.js';
+import { smartReview } from '../tools/smart-review.js';
+import { smartShell } from '../tools/smart-shell.js';
+import { smartSummary } from '../tools/smart-summary.js';
+import { smartTurn } from '../tools/smart-turn.js';
+import { smartStatus } from '../tools/smart-status.js';
+import { smartDoctor } from '../tools/smart-doctor.js';
+import { smartMetrics } from '../tools/smart-metrics.js';
+
+const TOOL_REGISTRY = {
+  smart_context: smartContext,
+  smart_search: smartSearch,
+  smart_read: smartRead,
+  smart_read_batch: smartReadBatch,
+  smart_test: smartTest,
+  smart_review: smartReview,
+  smart_shell: smartShell,
+  smart_summary: smartSummary,
+  smart_turn: smartTurn,
+  smart_status: smartStatus,
+  smart_doctor: smartDoctor,
+  smart_metrics: smartMetrics,
+};
+
+const TEMPLATE_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\}\}/g;
+
+const resolvePath = (obj, dottedKey) => {
+  const segments = dottedKey.split('.');
+  let current = obj;
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined;
+    current = current[seg];
+  }
+  return current;
+};
+
+export const interpolate = (value, scope) => {
+  if (typeof value === 'string') {
+    const full = value.match(/^\{\{\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\}\}$/);
+    if (full) {
+      const resolved = resolvePath(scope, full[1]);
+      return resolved === undefined ? value : resolved;
+    }
+    return value.replace(TEMPLATE_RE, (match, key) => {
+      const resolved = resolvePath(scope, key);
+      if (resolved === undefined || resolved === null) return '';
+      if (typeof resolved === 'object') return JSON.stringify(resolved);
+      return String(resolved);
+    });
+  }
+  if (Array.isArray(value)) return value.map((item) => interpolate(item, scope));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = interpolate(v, scope);
+    return out;
+  }
+  return value;
+};
+
+const evaluateWhen = (whenExpr, scope) => {
+  if (!whenExpr) return true;
+  const expanded = interpolate(whenExpr, scope);
+  if (typeof expanded === 'boolean') return expanded;
+  if (expanded === null || expanded === undefined) return false;
+  if (typeof expanded === 'string') {
+    const lower = expanded.trim().toLowerCase();
+    if (lower === 'false' || lower === '0' || lower === '' || lower === 'no') return false;
+    return true;
+  }
+  return Boolean(expanded);
+};
+
+export const runPlaybook = async (playbook, args = {}, { dryRun = false, toolRegistry = TOOL_REGISTRY } = {}) => {
+  const scope = { args: { ...playbook.defaults, ...args } };
+  const steps = [];
+  const startedAt = Date.now();
+  let failed = false;
+
+  for (const [i, rawStep] of playbook.steps.entries()) {
+    const stepStart = Date.now();
+    const skipped = !evaluateWhen(rawStep.when, scope);
+
+    if (skipped) {
+      steps.push({
+        index: i,
+        tool: rawStep.tool,
+        label: rawStep.label,
+        args: rawStep.args,
+        ok: true,
+        skipped: true,
+        result: null,
+        elapsedMs: 0,
+      });
+      continue;
+    }
+
+    const tool = toolRegistry[rawStep.tool];
+    if (!tool) {
+      steps.push({
+        index: i,
+        tool: rawStep.tool,
+        label: rawStep.label,
+        args: rawStep.args,
+        ok: false,
+        skipped: false,
+        error: `Tool not allowed in playbooks: ${rawStep.tool}`,
+        elapsedMs: 0,
+      });
+      failed = true;
+      if (playbook.stopOnFail) break;
+      continue;
+    }
+
+    const resolvedArgs = interpolate(rawStep.args, scope);
+
+    if (dryRun) {
+      steps.push({
+        index: i,
+        tool: rawStep.tool,
+        label: rawStep.label,
+        args: resolvedArgs,
+        ok: true,
+        skipped: false,
+        dryRun: true,
+        elapsedMs: 0,
+      });
+      continue;
+    }
+
+    try {
+      const result = await tool(resolvedArgs);
+      const ok = result?.success !== false;
+      steps.push({
+        index: i,
+        tool: rawStep.tool,
+        label: rawStep.label,
+        args: resolvedArgs,
+        ok,
+        skipped: false,
+        result,
+        elapsedMs: Date.now() - stepStart,
+      });
+      if (!ok) {
+        failed = true;
+        if (playbook.stopOnFail) break;
+      }
+      scope[`step${i}`] = result;
+      if (rawStep.label) scope[rawStep.label] = result;
+    } catch (err) {
+      steps.push({
+        index: i,
+        tool: rawStep.tool,
+        label: rawStep.label,
+        args: resolvedArgs,
+        ok: false,
+        skipped: false,
+        error: err?.message ?? String(err),
+        elapsedMs: Date.now() - stepStart,
+      });
+      failed = true;
+      if (playbook.stopOnFail) break;
+    }
+  }
+
+  return {
+    name: playbook.name,
+    description: playbook.description,
+    success: !failed,
+    steps,
+    stepCount: playbook.steps.length,
+    executed: steps.filter((s) => !s.skipped && !s.dryRun).length,
+    skipped: steps.filter((s) => s.skipped).length,
+    totalElapsedMs: Date.now() - startedAt,
+    dryRun: !!dryRun,
+  };
+};
+
+export const _internal = { TOOL_REGISTRY, resolvePath, evaluateWhen };