@chemx/starter-kit 26.9.21-432 → 26.9.23-1269

package/cli/audit/prompts.js

@@ -296,7 +296,7 @@ export const buildHotspotsPrompt = (report, options = {}) => {
   lines.push('1. Pre-Split Pattern Discovery: Audit recurring UI layouts, state machines, and predicates across monoliths first; extract canonical shared capsules before slicing to prevent bespoke pattern duplication.');
   lines.push('2. Molecular Limits: Molecule capsules must strictly remain under 100 lines per file.');
   lines.push('3. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative Table of Contents assembling molecules via named slots.');
-  lines.push('4. Composable Return Contracts: Custom hooks/composables must strictly limit returns to 3 to 5 properties (State + Status + Actions).');
+  lines.push('4. Composable Return Contracts: Custom hooks/composables must classify returns into flat State, Status, and verb-prefixed Actions buckets (Directive 4.A).');
   lines.push('5. Type Co-location: Co-locate granular types/*.d.ts files inside each feature capsule (< 100 lines per type file) instead of creating type monoliths.');
   lines.push('6. Zero breaking changes to external component APIs, route exports, or existing props.');
   if (!isSubSection) {

package/cli/commands/cmd-project.js

@@ -0,0 +1,100 @@
+/**
+ * cmd-project.js: Persistent Coordinator and Projects CLI Handler
+ * Dispatches init, status, step, chat, pause, resume, and learnings
+ */
+
+import { openIndexDb } from '../search-db.js';
+import {
+  initProjectSession, getActiveProjectSession, getProjectSession,
+  postProjectMessage, getProjectMessages, updateProjectSession
+} from '../team/team-projects.js';
+import { queryRelevantLearnings, formatLearningsCard } from '../team/team-projects-memory.js';
+import { executeCoordinatorStep } from '../team/team-projects-coordinator.js';
+import { formatProjectStatusCard } from '../team/team-projects-format.js';
+import { listTasks } from '../team/team-db-tasks.js';
+
+export const runProjectCli = async (rawArgs = [], isCli = false, cwd = process.cwd()) => {
+  const db = openIndexDb(cwd);
+  if (!db) {
+    if (isCli) process.stderr.write('\x1b[31m✕ SQLite database unavailable.\x1b[0m\n');
+    return null;
+  }
+
+  const isJson = rawArgs.includes('--json');
+  const nonFlag = rawArgs.filter((a) => !a.startsWith('-'));
+  const subCommand = nonFlag[0] || 'status';
+  const restText = nonFlag.slice(1).join(' ');
+
+  if (subCommand === 'init' || subCommand === 'start') {
+    const goal = restText || 'Autonomous codebase optimization';
+    const session = initProjectSession(db, { goal, title: goal.slice(0, 40) });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(session, null, 2)}\n`);
+      else process.stdout.write(`\x1b[32m✔\x1b[0m Initialized project session #${session.id}: "${session.title}"\n`);
+    }
+    return session;
+  }
+
+  if (subCommand === 'step' || subCommand === 'turn') {
+    const res = executeCoordinatorStep(db, { cwd });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+      else process.stdout.write(`\x1b[36m⚡ [Turn ${res.turn || 0}]\x1b[0m ${res.action || res.status} - Status: ${res.status}\n`);
+    }
+    return res;
+  }
+
+  if (subCommand === 'chat' || subCommand === 'msg') {
+    const active = getActiveProjectSession(db);
+    if (!active) {
+      if (isCli) process.stderr.write('\x1b[31m✕ No active project. Run "chemx project init <goal>" first.\x1b[0m\n');
+      return { error: 'no_active_session' };
+    }
+    const msg = postProjectMessage(db, {
+      projectId: active.id,
+      turnIndex: active.current_turn,
+      authorId: '@user',
+      role: 'user',
+      message: restText || 'Status report'
+    });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(msg, null, 2)}\n`);
+      else process.stdout.write(`\x1b[32m✔\x1b[0m Sent message to coordinator: "${msg.message}"\n`);
+    }
+    return msg;
+  }
+
+  if (subCommand === 'learnings' || subCommand === 'memory') {
+    const learnings = queryRelevantLearnings(db, { limit: 10 });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(learnings, null, 2)}\n`);
+      else process.stdout.write(formatLearningsCard(learnings));
+    }
+    return learnings;
+  }
+
+  if (subCommand === 'pause' || subCommand === 'resume') {
+    const active = getActiveProjectSession(db);
+    if (!active) return null;
+    const newStatus = subCommand === 'pause' ? 'paused' : 'active';
+    const updated = updateProjectSession(db, active.id, { status: newStatus });
+    if (isCli) process.stdout.write(`\x1b[32m✔\x1b[0m Project #${active.id} status updated to: ${newStatus}\n`);
+    return updated;
+  }
+
+  // Default: status
+  const session = getActiveProjectSession(db);
+  const messages = session ? getProjectMessages(db, session.id, 5) : [];
+  const activeTasks = session ? listTasks(db, { status: 'in_progress' }) : [];
+  const learnings = queryRelevantLearnings(db, { limit: 5 });
+
+  if (isJson) {
+    const payload = { session, messages, activeTasks, learnings };
+    if (isCli) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return payload;
+  }
+
+  const card = formatProjectStatusCard({ session, messages, activeTasks, learnings });
+  if (isCli) process.stdout.write(card);
+  return { session, messages, activeTasks, learnings };
+};

package/cli/commands/cmd-router.js

@@ -23,6 +23,25 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       runTeamCli(rawArgs.slice(1), true);
       break;
     }
+    case 'project':
+    case 'coordinator': {
+      const { runProjectCli } = await import('./cmd-project.js');
+      await runProjectCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'tokens':
+    case 'telemetry': {
+      const { runTeamCli } = await import('../team/index.js');
+      runTeamCli(['tokens', ...rawArgs.slice(1)], true);
+      break;
+    }
+    case 'benchmark':
+    case 'ablation':
+    case 'memory': {
+      const { runTeamCli } = await import('../team/index.js');
+      runTeamCli(['benchmark', ...rawArgs.slice(1)], true);
+      break;
+    }
     case 'mcp':
     case 'mcp-server':
     case 'server': {
@@ -31,7 +50,8 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       break;
     }
     case 'read':
-    case 'view': {
+    case 'view':
+    case 'r': {
       const { runReaderCli } = await import('../reader.js');
       runReaderCli(rawArgs.slice(1), true);
       break;

package/cli/commands-schema.js

@@ -194,5 +194,19 @@ export const COMMANDS_SCHEMA = [
       'npx chemx pillars --preset=recommended',
       'npx chemx pillars --preset=minimal --dry-run'
     ]
+  },
+  {
+    name: 'ui',
+    aliases: ['dashboard', 'preview'],
+    usage: 'npx chemx ui [options]',
+    summary: 'Launch the Chemical X interactive web dashboard.',
+    description: 'Provides real-time Kanban task boards, agent rails, live SQLite Database Studio, and codebase AST tree exploration.',
+    flags: [
+      { flag: '--port=<N>', desc: 'Server port (default: 4173)' }
+    ],
+    examples: [
+      'npx chemx ui',
+      'npx chemx dashboard --port=3000'
+    ]
   }
 ];

package/cli/create.spec.js

@@ -63,7 +63,7 @@ describe('Scaffolding Entrypoint Invocations', () => {
     const result = spawnSync('node', [CREATE_BIN, '--help'], {
       encoding: 'utf-8',
       cwd: tmpBase,
-      timeout: 5000
+      timeout: 15000
     });
 
     assert.equal(result.status, 0, 'Should exit with code 0 on --help');
@@ -78,7 +78,7 @@ describe('Scaffolding Entrypoint Invocations', () => {
     const result = spawnSync('node', [CREATE_BIN, '--version'], {
       encoding: 'utf-8',
       cwd: tmpBase,
-      timeout: 5000
+      timeout: 15000
     });
 
     assert.equal(result.status, 0, 'Should exit with code 0 on --version');

package/cli/help.js

@@ -43,7 +43,7 @@ export const printHelp = () => {
   lines.push(
     `${BOLD}REACTIVE COMPOSABLE RULES${RESET}`,
     `  ${YELLOW}1.${RESET} Return plain objects with individual ref/computed. Never raw reactive().`,
-    `  ${YELLOW}2.${RESET} Strictly limit returns to State + Status + Actions (max 3-5 properties).`,
+    `  ${YELLOW}2.${RESET} Structure returns into flat State, Status, and verb Actions (HOOK_SHAPE_CONTRACT).`,
     `  ${YELLOW}3.${RESET} Clean up side-effects automatically onScopeDispose().`,
     '',
     `${BOLD}COMMUNITY & SUPPORT${RESET}`,

package/cli/index.js

@@ -45,7 +45,7 @@ const loadProjectConfig = () => {
 };
 
 // ---------------------------------------------------------------------------
-// Public API — lazy proxy exports (zero startup cost for consumers)
+// Public API: lazy proxy exports (zero startup cost for consumers)
 // ---------------------------------------------------------------------------
 
 export const runAudit = async (customDir = null, isCli = false) => {
@@ -77,7 +77,7 @@ export { handleError, withErrorCatcher, publishIssue };
 
 export const ALLOWED_COMMANDS = new Set([
   'search', 'q', 'query', 'find',
-  'read', 'view',
+  'read', 'view', 'r',
   'patch', 'edit',
   'write',
   'generate', 'g', 'gen', 'capsule', 'add',
@@ -85,7 +85,9 @@ export const ALLOWED_COMMANDS = new Set([
   'audit',
   'trend', 'trends',
   'verify', 'check:all',
-  'team', 'swarm', 'feed',
+  'team', 'swarm', 'feed', 'tokens', 'telemetry',
+  'project', 'coordinator',
+  'benchmark', 'ablation', 'memory',
   'pillars', 'rules', 'config:pillars',
   'mcp', 'mcp-server', 'server', 'install-mcp', 'setup-mcp',
   'build', 'run', 'wrap',
@@ -106,20 +108,28 @@ export const ALLOWED_COMMANDS = new Set([
 // main: thin orchestrator; real dispatch lives in cmd-router.js
 // ---------------------------------------------------------------------------
 
+const HELP_FLAGS = new Set(['help', '--help', '-h']);
+const VERSION_FLAGS = new Set(['version', '--version', '-v']);
+
 const main = async () => {
   const firstArg = rawArgs[0];
 
-  if (!firstArg || firstArg === 'help' || firstArg === '--help' || firstArg === '-h') {
+  const isHelpRequested = !firstArg || HELP_FLAGS.has(firstArg);
+  if (isHelpRequested) {
     printHelp();
     return;
   }
 
-  if (firstArg === 'version' || firstArg === '--version' || firstArg === '-v') {
+  const isVersionRequested = VERSION_FLAGS.has(firstArg);
+  if (isVersionRequested) {
     process.stdout.write(`create-chemx v${getPackageVersion()}\n`);
     return;
   }
 
-  if (!ALLOWED_COMMANDS.has(firstArg) && !isCapsulePrefix(firstArg)) {
+  const isAllowedCommand = ALLOWED_COMMANDS.has(firstArg);
+  const isCapsuleCmd = isCapsulePrefix(firstArg);
+  const isCommandValid = isAllowedCommand || isCapsuleCmd;
+  if (!isCommandValid) {
     process.stderr.write(`Unknown command "${firstArg}". Run --help for usage.\n`);
     process.exit(1);
   }

package/cli/installer-templates.js

@@ -99,7 +99,7 @@ fi
 
 if [ -n "\$AUDIT_BIN" ]; then
   printf "%s[Chemical X] Verifying architectural health (Min Grade: %s, Min Score: %s)...%s\\n" "\$C_BLUE" "\$MIN_GRADE" "\$MIN_SCORE" "\$C_RESET"
-  if ! \$AUDIT_BIN audit --min-grade="\$MIN_GRADE" --min-score="\$MIN_SCORE" --non-interactive < /dev/null; then
+  if ! \$AUDIT_BIN audit --git --min-grade="\$MIN_GRADE" --min-score="\$MIN_SCORE" --non-interactive < /dev/null; then
     printf "\\n%s%s[Chemical X] Commit Blocked: Architectural health verification failed%s\\n" "\$C_BOLD" "\$C_RED" "\$C_RESET"
     printf "%s💡 Tip: Want crystalline drop-in templates? Run 'npm create chemx' or sponsor at https://github.com/sponsors/Chemical-X-Protocol%s\\n\\n" "\$C_CYAN" "\$C_RESET"
     exit 1

package/cli/mcp/installer.js

@@ -48,10 +48,10 @@ export const resolveMcpServerCommand = (targetDir = '.') => {
   const hasScopedChemx = fs.existsSync(localScopedChemx);
   const hasInRepoStarterKit = fs.existsSync(inRepoStarterKit);
 
-  if (hasCreateChemx) {
+  if (hasInRepoStarterKit) {
     return {
       command: 'node',
-      args: ['./node_modules/create-chemx/cli/index.js', 'mcp']
+      args: ['./apps/chemical-x/starter-kit/cli/index.js', 'mcp']
     };
   }
 
@@ -62,16 +62,16 @@ export const resolveMcpServerCommand = (targetDir = '.') => {
     };
   }
 
-  if (hasInRepoStarterKit) {
+  if (hasCreateChemx) {
     return {
       command: 'node',
-      args: ['./apps/chemical-x/starter-kit/cli/index.js', 'mcp']
+      args: ['./node_modules/create-chemx/cli/index.js', 'mcp']
     };
   }
 
   return {
-    command: 'npx',
-    args: ['-y', 'chemx', 'mcp']
+    command: 'npm',
+    args: ['exec', '-y', '--', 'chemx', 'mcp']
   };
 };
 
@@ -173,7 +173,7 @@ export const installAntigravityMcpConfig = (targetDir = '.', options = {}) => {
 
   const serverDef = localStarter
     ? { command: process.execPath, args: [localStarter, 'mcp'] }
-    : { command: 'npx', args: ['-y', 'chemx', 'mcp'] };
+    : { command: 'npm', args: ['exec', '-y', '--', 'chemx', 'mcp'] };
 
   try {
     const existing = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf-8') : '';

package/cli/mcp/installer.spec.js

@@ -35,12 +35,12 @@ test('mergeMcpServerConfig: preserves existing servers while updating chemical-x
   assert.strictEqual(parsed.mcpServers['chemical-x'].command, 'npx');
 });
 
-test('resolveMcpServerCommand: falls back to npx when no local node_modules found', () => {
+test('resolveMcpServerCommand: falls back to npm exec when no local node_modules found', () => {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-cmd-test-'));
   try {
     const cmd = resolveMcpServerCommand(tmpDir);
-    assert.strictEqual(cmd.command, 'npx');
-    assert.deepStrictEqual(cmd.args, ['-y', 'chemx', 'mcp']);
+    assert.strictEqual(cmd.command, 'npm');
+    assert.deepStrictEqual(cmd.args, ['exec', '-y', '--', 'chemx', 'mcp']);
   } finally {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   }

package/cli/mcp/manifests.js

@@ -32,7 +32,8 @@ export const MASTER_MCP_TOOL = {
           'autofix',
           'generate',
           'patterns',
-          'issue'
+          'issue',
+          'project'
         ],
         description: 'The Chemical X subsystem action to execute.'
       },

package/cli/mcp/prompts.js

@@ -72,7 +72,7 @@ export const getMcpPrompt = async (name, args = {}) => {
         '2. Molecular Capsule Limit: Maximum 100 lines per molecule capsule file.',
         '3. Table-of-Contents Views: Top-level page views must be 10-20 line declarative templates assembling components via named slots.',
         '4. Two-Stage Atomic Booleans: Break complex multi-clause conditionals into atomic single-concept booleans.',
-        '5. Composable Return Contracts: Limit hook/composable returns to 3 to 5 properties (State + Status + Actions).',
+        '5. Composable Return Contracts: Classify hook/composable returns into flat State, Status, and verb-prefixed Actions buckets (HOOK_SHAPE_CONTRACT).',
         '6. Co-located Types: Co-locate granular types/*.d.ts inside each capsule (< 100 lines). Avoid type monoliths.',
         '7. Zero synthetic or mock data: Return live data or explicit empty states.',
         `8. Framework: Calibrate bindings for ${framework}.`,

package/cli/mcp/server.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { MCP_TOOLS, executeMcpTool } from './tools.js';
 import { MCP_RESOURCES, readMcpResource } from './resources.js';
 import { MCP_PROMPTS, getMcpPrompt } from './prompts.js';
+import { warmIndexDb } from '../search-db.js';
 
 export const SERVER_INFO = {
   name: 'chemical-x-mcp',
@@ -34,6 +35,7 @@ export const createMcpHandler = (options = {}) => {
       } else if (Array.isArray(params?.workspaceFolders) && params.workspaceFolders[0]?.uri?.startsWith('file://')) {
         cwd = new URL(params.workspaceFolders[0].uri).pathname;
       }
+      try { warmIndexDb(cwd); } catch {}
       return {
         jsonrpc: '2.0',
         id,

package/cli/mcp/tools-audit.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runAudit as executeAstAudit, auditFile } from '../audit.js';
+import {
+  buildMasterPrompt,
+  buildGradeFPrompt,
+  buildGradeDPrompt,
+  buildGradeCPrompt,
+  buildGradeBPrompt,
+  buildAiSlopPrompt,
+  buildHotspotsPrompt
+} from '../audit/prompts.js';
+import { syncSearchIndex, syncViolationsIndex, recordAuditSnapshot } from '../search.js';
+import { resolveTargetCwd } from './tools-search.js';
+
+export const handleAudit = (args = {}, cwd = process.cwd()) => {
+  const baseCwd = resolveTargetCwd(cwd);
+  const rawTarget = args.path || args.dir || (fs.existsSync(path.resolve(baseCwd, 'src')) ? 'src' : '.');
+  const resolvedTarget = path.isAbsolute(rawTarget) ? rawTarget : path.resolve(baseCwd, rawTarget);
+  const isFile = fs.existsSync(resolvedTarget) && fs.statSync(resolvedTarget).isFile();
+
+  if (isFile) {
+    const relPath = path.relative(baseCwd, resolvedTarget);
+    const violations = auditFile(resolvedTarget, relPath);
+    return {
+      type: 'file',
+      target: relPath,
+      violationCount: violations.length,
+      violations
+    };
+  }
+
+  const options = {
+    cwd: baseCwd,
+    model: args.model || 'blended',
+    outputFile: null
+  };
+
+  const report = executeAstAudit(resolvedTarget, options);
+
+  try {
+    const syncRes = syncSearchIndex(resolvedTarget, baseCwd);
+    if (syncRes?.db) {
+      syncViolationsIndex(syncRes.db, report.violations);
+      recordAuditSnapshot(syncRes.db, report);
+    }
+  } catch (syncError) {
+    process.stderr.write(`[chemx] Search index sync bypassed: ${syncError?.message || String(syncError)}\n`);
+  }
+
+  const isSevereViolation = (v) => v.severity === 'CRITICAL' || v.severity === 'HIGH';
+  const hasCriticalOrHigh = report.violations.some(isSevereViolation);
+  const isStrictFail = Boolean(args.strict) && report.violations.length > 0;
+  const isScoreFail = typeof args.minScore === 'number' && report.health.score < args.minScore;
+  const isPassing = !isStrictFail && !isScoreFail && !hasCriticalOrHigh;
+
+  return {
+    type: 'directory',
+    target: rawTarget,
+    health: report.health,
+    metrics: report.metrics,
+    aiSlop: report.aiSlop,
+    hotspots: report.hotspots,
+    totalViolations: report.totalViolations,
+    violations: report.violations,
+    contextAnalysis: report.contextAnalysis,
+    isPassing
+  };
+};
+
+export const handleGetRefactorPrompt = (args = {}, cwd = process.cwd()) => {
+  const targetDir = args.dir || (fs.existsSync(path.resolve(cwd, 'src')) ? 'src' : '.');
+  const scope = args.scope || 'master';
+  const report = executeAstAudit(targetDir, {});
+
+  const PROMPT_BUILDERS = {
+    'grade-f': buildGradeFPrompt,
+    'grade-d': buildGradeDPrompt,
+    'grade-c': buildGradeCPrompt,
+    'grade-b': buildGradeBPrompt,
+    'ai-slop': buildAiSlopPrompt,
+    'hotspots': buildHotspotsPrompt,
+    'master': buildMasterPrompt
+  };
+
+  const builder = Object.prototype.hasOwnProperty.call(PROMPT_BUILDERS, scope)
+    ? PROMPT_BUILDERS[scope]
+    : buildMasterPrompt;
+
+  return {
+    targetDir,
+    scope,
+    prompt: builder(report) || 'No violations found for the requested scope.'
+  };
+};

package/cli/mcp/tools-generate.js

@@ -0,0 +1,62 @@
+import { createCapsuleFiles } from '../generator.js';
+import { openIndexDb } from '../search-schema.js';
+import { fetchScoreTrends, formatTrendReport, renderSparkline } from '../trend.js';
+import { resolveTargetCwd } from './tools-search.js';
+
+export const handleGenerateCapsule = (args = {}, cwd = process.cwd()) => {
+  const { name, framework, tier = 'm', targetDir = null, lean = false, desc = '', description = '', dryRun = false } = args;
+
+  const hasName = Boolean(name && name.trim());
+  const hasValidFramework = Boolean(framework && ['react', 'vue', 'svelte'].includes(framework.toLowerCase()));
+  const canGenerate = hasName && hasValidFramework;
+
+  if (!canGenerate) {
+    throw new Error('chemx_generate_capsule requires "name" and "framework" (react, vue, svelte).');
+  }
+
+  const result = createCapsuleFiles({
+    name: name.trim(),
+    framework: framework.toLowerCase(),
+    tier: tier.toLowerCase(),
+    targetParent: targetDir,
+    isLean: Boolean(lean),
+    cwd,
+    desc: desc || description,
+    dryRun: Boolean(dryRun)
+  });
+
+  return {
+    success: true,
+    dryRun: result.dryRun,
+    capsuleName: result.capsuleName,
+    pascalName: result.pascalName,
+    framework: result.framework,
+    tier: result.tier,
+    targetDir: result.targetDir,
+    relativeDir: result.relativeDir,
+    filesCreated: result.filesCreated,
+    previews: result.previews
+  };
+};
+
+export const handleChemxTrend = async (args = {}, cwd = process.cwd()) => {
+  const targetCwd = resolveTargetCwd(args.cwd || cwd);
+  const db = openIndexDb(targetCwd);
+  const limit = args.limit || 10;
+  const snapshots = fetchScoreTrends(db, limit);
+  if (args.json) {
+    const scores = snapshots.map((s) => s.score);
+    const hasScores = snapshots.length > 0;
+    const latestScore = hasScores ? snapshots[snapshots.length - 1].score : null;
+    const hasDelta = snapshots.length >= 2;
+    const delta = hasDelta ? snapshots[snapshots.length - 1].score - snapshots[0].score : 0;
+    return {
+      count: snapshots.length,
+      sparkline: renderSparkline(scores),
+      latestScore,
+      delta,
+      snapshots
+    };
+  }
+  return formatTrendReport(snapshots);
+};

package/cli/mcp/tools-patch.js

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import { syncSingleFileIndex } from '../search.js';
+import { patchFile } from '../patcher.js';
+import { handleCheckCommand } from '../search-commands.js';
+
+export const isSevereViolation = (v) => {
+  const isCritical = v.severity === 'CRITICAL';
+  const isHigh = v.severity === 'HIGH';
+  return isCritical || isHigh;
+};
+
+export const formatPatchWarnings = (result) => {
+  const warnings = [];
+  const hasLineBudget = Boolean(result.lineBudget);
+  const isBudgetExceeded = hasLineBudget && !result.lineBudget.passed;
+  if (isBudgetExceeded) {
+    warnings.push(`[Directive 1.A] ${result.lineBudget.warning}`);
+  }
+
+  const violations = result.violations || [];
+  for (const v of violations) {
+    if (isSevereViolation(v)) {
+      warnings.push(`[${v.severity} - ${v.rule}] Line ${v.line}: ${v.hazard} -> ${v.directive || ''}`);
+    }
+  }
+
+  return warnings.length > 0 ? warnings : undefined;
+};
+
+export const handleChemxPatch = (args = {}, cwd = process.cwd()) => {
+  const hasPath = Boolean(args.path);
+  const hasTargetContent = args.targetContent !== undefined;
+  const hasReplacementContent = args.replacementContent !== undefined;
+  const hasRequiredArgs = hasPath && hasTargetContent && hasReplacementContent;
+
+  if (!hasRequiredArgs) {
+    throw new Error('chemx_patch requires "path", "targetContent", and "replacementContent" arguments.');
+  }
+
+  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  const result = patchFile(targetPath, {
+    targetContent: args.targetContent,
+    replacementContent: args.replacementContent,
+    allowMultiple: Boolean(args.allowMultiple),
+    cwd
+  });
+
+  try {
+    syncSingleFileIndex(targetPath, cwd);
+  } catch (err) {
+    if (process.env.CHEMX_DEBUG) {
+      process.stderr.write(`[patch-sync] Auto-index skipped for ${targetPath}: ${err.message}\n`);
+    }
+  }
+
+  return {
+    ...result,
+    warnings: formatPatchWarnings(result)
+  };
+};
+
+export const handleChemxCheck = (args = {}, cwd = process.cwd()) => {
+  if (args.path === 'RESTART_MCP') {
+    setTimeout(() => process.exit(0), 50);
+    return { restarting: true };
+  }
+  if (!args.path) {
+    throw new Error('chemx_check requires "path" argument.');
+  }
+  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  return handleCheckCommand(targetPath, { isJson: true, isCli: false });
+};

package/cli/mcp/tools-patterns.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runAudit as executeAstAudit } from '../audit.js';
+import { runAutofix } from '../audit/autofix.js';
+import { resolveTargetCwd } from './tools-search.js';
+
+export const handleQueryPatterns = (args = {}, cwd = process.cwd()) => {
+  const baseCwd = resolveTargetCwd(cwd);
+  const targetDir = args.dir || (fs.existsSync(path.resolve(baseCwd, 'src')) ? 'src' : '.');
+  const resolvedTarget = path.isAbsolute(targetDir) ? targetDir : path.resolve(baseCwd, targetDir);
+  const report = executeAstAudit(resolvedTarget, { cwd: baseCwd });
+  const rawPatterns = report.patterns || [];
+  const filterType = args.type || 'ALL';
+  const minOccurrences = typeof args.minOccurrences === 'number' ? args.minOccurrences : 2;
+  const isCompact = args.compact !== false;
+
+  const matchesType = (p) => filterType === 'ALL' || p.type === filterType;
+  const matchesCount = (p) => p.fileCount >= minOccurrences;
+
+  const candidates = rawPatterns
+    .filter((p) => matchesType(p) && matchesCount(p))
+    .map((p) => {
+      const base = {
+        id: p.id,
+        type: p.type,
+        label: p.label,
+        detail: p.detail,
+        suggestedCapsule: p.suggestedCapsule,
+        recommendation: p.recommendation,
+        fileCount: p.fileCount,
+        totalHits: p.totalHits,
+        impactScore: p.impactScore
+      };
+
+      if (isCompact) {
+        const sampleOccurrences = [];
+        const seenSampleFiles = new Set();
+        for (const occ of (p.occurrences || [])) {
+          if (!seenSampleFiles.has(occ.filePath)) {
+            seenSampleFiles.add(occ.filePath);
+            sampleOccurrences.push({ file: occ.filePath, line: occ.line });
+            if (sampleOccurrences.length >= 3) break;
+          }
+        }
+        return {
+          ...base,
+          files: p.uniqueFiles || Array.from(new Set((p.occurrences || []).map((o) => o.filePath))),
+          sampleOccurrences
+        };
+      }
+      return { ...base, occurrences: p.occurrences };
+    });
+
+  return {
+    scannedDir: targetDir,
+    totalCandidates: candidates.length,
+    compact: isCompact,
+    candidates
+  };
+};
+
+export const handleAutofix = (args = {}, cwd = process.cwd()) => {
+  const baseCwd = resolveTargetCwd(cwd);
+  const rawTarget = args.path || args.dir || (fs.existsSync(path.resolve(baseCwd, 'src')) ? 'src' : '.');
+  const targetDir = path.isAbsolute(rawTarget) ? rawTarget : path.resolve(baseCwd, rawTarget);
+  return runAutofix(targetDir, {
+    dryRun: Boolean(args.dryRun),
+    rules: args.rules,
+    cwd: baseCwd
+  });
+};