@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/mcp/context.js

@@ -0,0 +1,81 @@
+// The one project-root resolver for MCP calls and wrappers.
+// Order: explicit projectRoot > MCP roots > server dir > CHEMX_PROJECT_ROOT
+// > boot dir with a .chemx/.chemxrc marker. Anything else is refused, never guessed.
+// A target path never picks the root (that let any package.json ancestor, even $HOME, become one).
+import fs from 'node:fs';
+import path from 'node:path';
+import { LOADED_VERSION } from './server-info.js';
+import { findChemxDir } from '../audit/chemx-dir.js';
+
+const CHEMX_MARKERS = ['.chemxrc', '.chemxrc.json', '.chemx'];
+const PROJECT_MARKERS = [...CHEMX_MARKERS, 'package.json', '.git'];
+
+const hasAnyMarker = (dir, markers) => markers.some((m) => fs.existsSync(path.join(dir, m)));
+
+export const isExistingDir = (p) => typeof p === 'string' && path.isAbsolute(p) && fs.existsSync(p) && fs.statSync(p).isDirectory();
+
+export const hasChemxMarker = (dir) => hasAnyMarker(dir, CHEMX_MARKERS);
+
+export const looksLikeProject = (dir) => hasAnyMarker(dir, PROJECT_MARKERS);
+
+export const isInsideDir = (root, target) => {
+  const rel = path.relative(root, target);
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+
+// realpath of the nearest existing ancestor plus the not-yet-existing tail, so a symlink is followed.
+const realResolve = (target) => {
+  const tail = [];
+  let current = target;
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    const isFilesystemRoot = parent === current;
+    if (isFilesystemRoot) return target;
+    tail.unshift(path.basename(current));
+    current = parent;
+  }
+  return path.join(fs.realpathSync(current), ...tail);
+};
+
+// Inside both lexically and after following symlinks: a link in the root cannot carry a path out of it.
+export const resolveInsideRoot = (root, requested) => {
+  const resolved = path.resolve(root, requested);
+  const isInside = isInsideDir(root, resolved) && isInsideDir(realResolve(root), realResolve(resolved));
+  return { requested, resolved, isInside };
+};
+
+const parseAllowedRoots =(env) => (env.CHEMX_MCP_ALLOWED_ROOTS || '').split(path.delimiter).filter((p) => path.isAbsolute(p));
+
+// When the client sent MCP roots or the server was started with a dir, projectRoot may only narrow them.
+const locateProjectRoot = (projectRoot, declaredRoots) => {
+  const isUsableRoot = isExistingDir(projectRoot) && looksLikeProject(projectRoot);
+  if (!isUsableRoot) return { ok: false, error: `projectRoot "${projectRoot}" must be an absolute path to an existing project directory (.chemxrc, .chemx, package.json or .git).` };
+  const isBounded = declaredRoots.length === 0 || declaredRoots.some((root) => resolveInsideRoot(root, projectRoot).isInside);
+  if (!isBounded) return { ok: false, error: `projectRoot "${projectRoot}" is outside the declared roots (${declaredRoots.join(', ')}).` };
+  return { ok: true, root: projectRoot, rootSource: 'projectRoot' };
+};
+
+const locateRoot = ({ projectRoot, mcpRoots, serverRoot, envRoot, bootDir }) => {
+  const hasProjectRoot = !(projectRoot === undefined || projectRoot === null);
+  if (hasProjectRoot) return locateProjectRoot(projectRoot, [...mcpRoots, serverRoot].filter(Boolean));
+  const hasMcpRoots = mcpRoots.length > 0;
+  if (hasMcpRoots) return { ok: true, root: mcpRoots[0], rootSource: 'mcpRoots' };
+  if (serverRoot) return { ok: true, root: serverRoot, rootSource: 'declared' };
+  if (envRoot) return { ok: true, root: envRoot, rootSource: 'env' };
+  if (bootDir) return { ok: true, root: bootDir, rootSource: 'boot' };
+  return { ok: false, error: 'No project root: pass projectRoot, start the server with a directory, set CHEMX_PROJECT_ROOT, or start it inside a project with .chemxrc/.chemx.' };
+};
+
+export const resolveContext = ({ cwd = null, projectRoot = null, mcpRoots = [], serverRoot = null, env = process.env } = {}) => {
+  const envRoot = isExistingDir(env.CHEMX_PROJECT_ROOT) ? env.CHEMX_PROJECT_ROOT : null;
+  const bootDir = cwd && hasChemxMarker(cwd) ? cwd : null;
+  const located = locateRoot({ projectRoot, mcpRoots, serverRoot, envRoot, bootDir });
+  const hasLocateFailed = !located.ok;
+  if (hasLocateFailed) return located;
+  const allowedRoots = parseAllowedRoots(env);
+  const isPinned = allowedRoots.length > 0;
+  const isAllowed = !isPinned || allowedRoots.some((allowed) => isInsideDir(allowed, located.root));
+  if (!isAllowed) return { ok: false, error: `Root "${located.root}" is outside CHEMX_MCP_ALLOWED_ROOTS.` };
+  // dbPath reports where the index layer will really open the db (it walks up to an existing .chemx).
+  return { ...located, dbPath: path.join(findChemxDir(located.root), 'index.db'), version: LOADED_VERSION };
+};

package/cli/mcp/envelope.js

@@ -0,0 +1,62 @@
+// Turns handler results into MCP content: plain text, no ANSI, no JSON-in-text for wrapper output.
+import { stripAnsi } from '../terminal.js';
+import { STATUS } from '../result-status.js';
+import { LOADED_VERSION } from './server-info.js';
+
+const textItem = (text) => ({ type: 'text', text });
+
+const stripDeep = (value) => {
+  const isString = typeof value === 'string';
+  if (isString) return stripAnsi(value);
+  if (Array.isArray(value)) return value.map(stripDeep);
+  const isPlainObject = value !== null && typeof value === 'object';
+  if (!isPlainObject) return value;
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, stripDeep(v)]));
+};
+
+const isContentEnvelope = (output) => Boolean(output) && Array.isArray(output.content);
+const isWrapperResult = (output) => Boolean(output) && typeof output.output === 'string' && typeof output.code === 'number';
+
+const wrapperText = ({ output, code, error }) => {
+  const isFailure = code !== 0;
+  const body = stripAnsi(output || '');
+  if (!isFailure) return body || '(no output)';
+  const reason = stripAnsi(error || '').trim();
+  return [body.trim(), reason, `exit ${code}`].filter(Boolean).join('\n');
+};
+
+const KNOWN_STATUSES = new Set(Object.values(STATUS));
+
+// The one failure test for single calls and batch items: a tri-state status decides when present,
+// otherwise a nonzero wrapper code, success:false, an error message or isError.
+export const isFailedResult = (output) => {
+  const hasKnownStatus = KNOWN_STATUSES.has(output?.status);
+  if (hasKnownStatus) return output.status === STATUS.FAIL;
+  const hasFailCode = isWrapperResult(output) && output.code !== 0;
+  const hasFalseSuccess = output?.success === false;
+  const hasErrorMessage = typeof output?.error === 'string' && output.error.length > 0;
+  return hasFailCode || hasFalseSuccess || hasErrorMessage || Boolean(output?.isError);
+};
+
+// One handler result to { content, isError }.
+export const toEnvelope = (output) => {
+  const isTextOutput = typeof output === 'string';
+  if (isTextOutput) return { content: [textItem(stripAnsi(output))], isError: false };
+  if (isContentEnvelope(output)) {
+    const content = output.content.map((c) => (c.type === 'text' ? textItem(stripAnsi(c.text)) : c));
+    return { content, isError: Boolean(output.isError) };
+  }
+  if (isWrapperResult(output)) return { content: [textItem(wrapperText(output))], isError: output.code !== 0 };
+  const serialized = JSON.stringify(stripDeep(output ?? null));
+  return { content: [textItem(serialized)], isError: isFailedResult(output) };
+};
+
+export const errorEnvelope = (message) => ({ content: [textItem(stripAnsi(message))], isError: true });
+
+export const scopeLine = (scope) => {
+  const isResolved = Boolean(scope?.root);
+  if (!isResolved) return textItem(`chemx root: unresolved v${LOADED_VERSION}`);
+  return textItem(`chemx root: ${scope.root} (${scope.rootSource}) v${scope.version}`);
+};
+
+export { textItem };

package/cli/mcp/fingerprint.js

@@ -0,0 +1,26 @@
+// Fingerprint of the cli/ sources on disk: size and mtime of every non-spec .js file, hashed.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+export const CLI_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const isSourceFile = (name) => name.endsWith('.js') && !name.endsWith('.spec.js');
+
+const collectSourceStats = (dir, out) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectSourceStats(abs, out);
+    else if (isSourceFile(entry.name)) {
+      const stat = fs.statSync(abs);
+      out.push(`${path.relative(CLI_DIR, abs)}:${stat.size}:${stat.mtimeMs}`);
+    }
+  }
+  return out;
+};
+
+export const fingerprintCliSources = (dir = CLI_DIR) => crypto
+  .createHash('sha1')
+  .update(collectSourceStats(dir, []).sort().join('\n'))
+  .digest('hex')
+  .slice(0, 12);

package/cli/mcp/fresh-entry.js

@@ -0,0 +1,34 @@
+// One-shot executor for a stale MCP server: runs one tool call with the code on disk.
+// stdin: { toolName, toolArgs, root } as JSON. stdout: one line, RESULT_MARK + JSON of
+// { output } | { error } | { loadFailure }. loadFailure means the code on disk did not load.
+import { RESULT_MARK, LOADED_MARK } from './fresh-protocol.js';
+
+const readStdin = async () => {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf-8');
+};
+
+const describe = (err) => (err instanceof Error ? err.message : String(err));
+const emit = (payload) => process.stdout.write(`\n${RESULT_MARK}${JSON.stringify(payload)}\n`);
+
+const run = async () => {
+  const request = JSON.parse(await readStdin());
+  let executeMcpTool = null;
+  try {
+    ({ executeMcpTool } = await import('./tools.js'));
+  } catch (err) {
+    emit({ loadFailure: describe(err) });
+    return;
+  }
+  process.stdout.write(`\n${LOADED_MARK}\n`);
+  try {
+    const output = await executeMcpTool(request.toolName, request.toolArgs, request.root);
+    emit({ output: output ?? null });
+  } catch (err) {
+    emit({ error: describe(err) });
+  }
+};
+
+await run();
+process.exit(0);

package/cli/mcp/fresh-protocol.js

@@ -0,0 +1,37 @@
+// Wire format between a stale MCP server and its one-shot fresh process.
+export const RESULT_MARK = '@@chemx-fresh-result@@';
+// Printed by the child as soon as the code on disk has imported, before any tool runs.
+export const LOADED_MARK = '@@chemx-fresh-loaded@@';
+
+// The last marked line of the child's stdout, parsed; null when there is none.
+export const parseFreshResult = (stdout) => {
+  const marked = String(stdout).split('\n').filter((line) => line.startsWith(RESULT_MARK));
+  const last = marked.at(-1);
+  if (!last) return null;
+  try {
+    return JSON.parse(last.slice(RESULT_MARK.length));
+  } catch {
+    return null;
+  }
+};
+
+const tail = (text) => String(text).trim().split('\n').slice(-3).join(' | ');
+
+// Child exit to { kind: 'ok', output } | { kind: 'error', error } | { kind: 'load', message } | { kind: 'crash', message }.
+// load: the child died before the code imported, so nothing ran. crash: it imported, then died without
+// a result, so the call may have partly run.
+export const classifyFreshExit = ({ stdout, stderr, code }) => {
+  const parsed = parseFreshResult(stdout);
+  const hasResult = parsed !== null;
+  const isLoadFailure = hasResult && Boolean(parsed.loadFailure);
+  const isToolError = hasResult && Boolean(parsed.error);
+  const hasLoaded = String(stdout).split('\n').includes(LOADED_MARK);
+  const detail = `fresh process exited ${code} without a result: ${tail(stderr) || 'no stderr'}`;
+  const isCrash = !hasResult && hasLoaded;
+  const isNoLoad = !hasResult && !hasLoaded;
+  if (isCrash) return { kind: 'crash', message: detail };
+  if (isNoLoad) return { kind: 'load', message: detail };
+  if (isLoadFailure) return { kind: 'load', message: parsed.loadFailure };
+  if (isToolError) return { kind: 'error', error: parsed.error };
+  return { kind: 'ok', output: parsed.output };
+};

package/cli/mcp/fresh-runner.js

@@ -0,0 +1,40 @@
+// Runs one MCP tool call in a one-shot child process that loads the code on disk.
+import { spawn as nodeSpawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { classifyFreshExit } from './fresh-protocol.js';
+
+const ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'fresh-entry.js');
+const DEFAULT_TIMEOUT_SECONDS = 600;
+const GRACE_MS = 5000;
+
+// The call's own timeout (seconds, as the verify/test/build actions take it) plus a grace period.
+export const timeoutMsFor = (toolArgs) => {
+  const asked = toolArgs?.params?.timeout ?? toolArgs?.timeout;
+  const isUsable = typeof asked === 'number' && asked > 0;
+  return (isUsable ? asked : DEFAULT_TIMEOUT_SECONDS) * 1000 + GRACE_MS;
+};
+
+// Resolves { kind: 'ok', output } | { kind: 'error', error } | { kind: 'load', message } | { kind: 'timeout' }.
+export const createFreshRunner = ({ spawn = nodeSpawn, entry = ENTRY } = {}) => ({ toolName, toolArgs, root, env }) => new Promise((resolve) => {
+  const child = spawn(process.execPath, [entry], { cwd: root, env, stdio: ['pipe', 'pipe', 'pipe'] });
+  let stdout = '';
+  let stderr = '';
+  let isDone = false;
+  const finish = (result) => {
+    if (isDone) return;
+    isDone = true;
+    clearTimeout(timer);
+    resolve(result);
+  };
+  const timer = setTimeout(() => {
+    child.kill('SIGKILL');
+    finish({ kind: 'timeout' });
+  }, timeoutMsFor(toolArgs));
+  child.stdout.on('data', (chunk) => { stdout += chunk; });
+  child.stderr.on('data', (chunk) => { stderr += chunk; });
+  child.on('error', (err) => finish({ kind: 'load', message: `cannot start the fresh process: ${err.message}` }));
+  child.on('close', (code) => finish(classifyFreshExit({ stdout, stderr, code })));
+  child.stdin.on('error', () => {});
+  child.stdin.end(JSON.stringify({ toolName, toolArgs, root }));
+});

package/cli/mcp/help.js

@@ -0,0 +1,53 @@
+// Compact per-action reference for the master `chemx` MCP tool (action: 'help') and server instructions.
+
+export const ACTION_HELP = {
+  help: '{ action? } this table, or one row',
+  read: '{ path, rev?, symbol?, outline?, logic?, template?, enrich?, startLine?, endLine? } (alias r); rev reads the file at a git revision',
+  show: '{ args: [rev, --patch?, --full?] } one commit: subject, author, date, body, stat; --patch is -U0 and collapses like d',
+  q: '{ query, literal?, lines?, blastRadius?, trace?, backtrace?, semantic?, hybrid?, tier?, limit?, reindex? } (alias search)',
+  patch: '{ path, target|search, replacement|replace, multiple?, dryRun? } writes; needs a declared root',
+  write: '{ path, content } writes; needs a declared root',
+  check: '{ path } single-file rule check',
+  audit: '{ path|dir?, full?, triage? } (triage writes team tasks)',
+  audit_feed: '{ view?: history|pillars|scopes, scope?, since?, fullOnly?, limit? } read-only rows from .chemx history and status, newest 100 (max 500), with total and cut; string form `audit --feed=<view>`',
+  verify: '{ dir?, includeBuild? }',
+  test: '{ dir?, testTarget?, filter?, command? } command runs only if it equals a package.json script or CHEMX_MCP_ALLOW_SHELL=1; testTarget is one path or glob, filter has no $ ` " \\',
+  typecheck: '{ dir?, command? } command rule as test',
+  build: '{ dir?, command? } command rule as test',
+  autofix: '{ path?, dryRun? } writes unless dryRun',
+  generate: '{ name, tier?, kind?, jig?, dryRun?, ... } writes',
+  patterns: '{ dir?, type?, compact? }',
+  trend: '{}',
+  d: '{ args?: string[] } git diff -U0 (alias diff); args ["--conflicts"] = combined diff of unmerged files; --output, --no-index, --ext-diff refused',
+  conflicts: '{} unmerged paths mid-merge/rebase, with ours/base/theirs lines of each conflict hunk',
+  log: '{ args?: string[] } git log --oneline (default 10); --output refused',
+  p: '{ query? } package.json: -s scripts, -d deps, or one key (alias pkg)',
+  f: '{ filter? } tracked files incl. submodules; filter is a glob (*, **, ?) or a substring (alias ls)',
+  j: '{ path } JSON: small files verbatim, larger ones as shape with scalar values (alias json)',
+  issue: '{ error, stack?, repo?, autoPost? } autoPost publishes to GitHub; needs a declared root',
+  project: '{ subAction, goal?|message? } writes (alias coordinator)',
+  tesseract: '{ args? } swarm matrix (aliases cube, matrix)',
+  team: '{ subAction? }',
+  team_status: '{}',
+  team_feed: '{ sinceId?, threadId?, taskId?, agentId?, limit? }',
+  team_post: '{ message, authorId?, recipientId?, taskId? } writes',
+  team_task: '{ subAction: list|add|claim|done|..., taskId?, title?, needs?: light|standard|deep } non-list sub-actions write',
+  team_lock: '{ action: acquire|release, filePath, agentId, purpose?, ttlMs? } writes',
+  team_inbox: '{ agentId|as, sinceId?, limit?, markRead? }',
+  team_dm: '{ to|recipientId, message, as? } writes'
+};
+
+export const renderActionHelp = (actionNames, only = null) => {
+  const names = only ? actionNames.filter((name) => name === only) : actionNames;
+  const isUnknown = Boolean(only) && names.length === 0;
+  if (isUnknown) return `Unknown action "${only}". Actions: ${actionNames.join(', ')}`;
+  const rows = names.map((name) => `${name}: ${ACTION_HELP[name] ?? 'see action name'}`);
+  const footer = 'Forms: { action, params } | { command: "read src/a.ts --outline" } | { commands: ["d", "p -s"] } | { batch: [{ action, params }] }. Every call accepts projectRoot.';
+  return [...rows, footer].join('\n');
+};
+
+export const SERVER_INSTRUCTIONS = [
+  'Chemical X: one master tool `chemx`. Call { action: "help" } for the per-action parameter table.',
+  'Pass projectRoot (absolute) on every call that targets a specific repo; writes are refused when the root was only guessed from the server start directory. Paths must sit inside the root; an absolute path never selects a root by itself.',
+  'Every result ends with a "chemx root:" line naming the root and how it was chosen. A "stale chemx MCP server" line means the code on disk changed after this server started: each call then runs in a fresh process with the code on disk (slower) under a notice on the first line, and mutating calls are refused if that code does not load. Reconnect via /mcp to restore speed.'
+].join(' ');

package/cli/mcp/index.js

@@ -10,18 +10,21 @@ import {
   installAllMcpConfigs
 } from './installer.js';
 import { syncAntigravityMcpSchemas } from './antigravity.js';
+import { describeServerOrigin } from './server-info.js';
 
 export const runMcpServer = async (rawArgs = []) => {
-  if (rawArgs.includes('--sync')) {
+  const hasSyncFlag = rawArgs.includes('--sync');
+  if (hasSyncFlag) {
     const targetDir = rawArgs.find((a) => !a.startsWith('-')) || null;
     return syncAntigravityMcpSchemas(targetDir);
   }
-  if (rawArgs.includes('--install')) {
+  const hasInstallFlag = rawArgs.includes('--install');
+  if (hasInstallFlag) {
     return runMcpInstaller(rawArgs);
   }
   // Stdio server must keep stdout strictly reserved for JSON-RPC messages.
   // Informative logs go to stderr.
-  process.stderr.write('⚡ Chemical X Protocol MCP Server active (stdio transport)\n');
+  process.stderr.write(`Chemical X MCP server active (stdio): ${describeServerOrigin()}\n`);
   startStdioServer(resolveServerOptions(rawArgs));
 };
 
@@ -31,8 +34,9 @@ export const resolveServerOptions = (rawArgs = []) => {
 };
 
 export const runMcpInstaller = async (rawArgs = []) => {
-  const targetDir = rawArgs[0] || process.cwd();
-  return installAllMcpConfigs(targetDir, { silent: false });
+  const targetDir = rawArgs.find((a) => !a.startsWith('-')) || process.cwd();
+  const includeHome = rawArgs.includes('--global') || rawArgs.includes('--antigravity');
+  return installAllMcpConfigs(targetDir, { silent: false, includeHome });
 };
 
 export {

package/cli/mcp/inflight.js

@@ -0,0 +1,47 @@
+// In-flight tools/call tracking: cancellation (notifications/cancelled) and progress heartbeats
+// (notifications/progress when the client sent params._meta.progressToken).
+import { runWithRequestContext } from '../request-context.js';
+
+const DEFAULT_PROGRESS_INTERVAL_MS = 5000;
+
+export const createInflight = ({ notify = null, progressIntervalMs = DEFAULT_PROGRESS_INTERVAL_MS } = {}) => {
+  const controllers = new Map();
+
+  const startHeartbeat = (progressToken, label) => {
+    const canReport = typeof notify === 'function' && progressToken !== undefined && progressToken !== null;
+    if (!canReport) return () => {};
+    const startedAt = Date.now();
+    let beats = 0;
+    const beat = () => {
+      beats += 1;
+      const seconds = Math.round((Date.now() - startedAt) / 1000);
+      notify('notifications/progress', { progressToken, progress: beats, message: `${label} running (${seconds}s)` });
+    };
+    beat();
+    const timer = setInterval(beat, progressIntervalMs);
+    return () => clearInterval(timer);
+  };
+
+  // Runs fn under a cancellable request context. Resolves to { cancelled, value }.
+  const run = async (id, params, fn) => {
+    const controller = new AbortController();
+    controllers.set(id, controller);
+    const label = params?.arguments?.action || params?.arguments?.command || params?.name || 'chemx';
+    const stopHeartbeat = startHeartbeat(params?._meta?.progressToken, label);
+    try {
+      const value = await runWithRequestContext({ signal: controller.signal }, fn);
+      return { cancelled: controller.signal.aborted, value };
+    } finally {
+      stopHeartbeat();
+      controllers.delete(id);
+    }
+  };
+
+  const cancel = (requestId) => {
+    const controller = controllers.get(requestId);
+    if (controller) controller.abort();
+    return Boolean(controller);
+  };
+
+  return { run, cancel, size: () => controllers.size };
+};

package/cli/mcp/installer-jsonc.js

@@ -0,0 +1,64 @@
+/**
+ * Minimal JSONC reader for MCP config files.
+ * Strips // and block comments and trailing commas outside strings, then JSON.parse.
+ * Reports whether comments were present so callers can refuse a lossy rewrite.
+ */
+
+const scanOutsideStrings = (text, onCode) => {
+  let out = '';
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      out += ch;
+      const isEscape = ch === '\\';
+      if (isEscape) { out += text[i + 1] ?? ''; i++; continue; }
+      const closesString = ch === '"';
+      if (closesString) inString = false;
+      continue;
+    }
+    const opensString = ch === '"';
+    if (opensString) { inString = true; out += ch; continue; }
+    const step = onCode(text, i);
+    out += step.emit;
+    i += step.skip;
+  }
+  return out;
+};
+
+const stripComments = (text) => {
+  let hasComments = false;
+  const code = scanOutsideStrings(text, (src, i) => {
+    const isLineComment = src.startsWith('//', i);
+    const isBlockComment = src.startsWith('/*', i);
+    if (isLineComment) {
+      hasComments = true;
+      const end = src.indexOf('\n', i);
+      return { emit: '', skip: (end === -1 ? src.length : end) - i - 1 };
+    }
+    if (isBlockComment) {
+      hasComments = true;
+      const end = src.indexOf('*/', i + 2);
+      return { emit: ' ', skip: (end === -1 ? src.length : end + 2) - i - 1 };
+    }
+    return { emit: src[i], skip: 0 };
+  });
+  return { code, hasComments };
+};
+
+const stripTrailingCommas = (code) => scanOutsideStrings(code, (src, i) => {
+  const isComma = src[i] === ',';
+  const nextCode = isComma ? src.slice(i + 1).trimStart()[0] : '';
+  const isTrailing = nextCode === '}' || nextCode === ']';
+  return { emit: isTrailing ? '' : src[i], skip: 0 };
+});
+
+/** Returns [value, error, { hasComments }]. Never throws. */
+export const parseJsonc = (text = '') => {
+  const { code, hasComments } = stripComments(String(text));
+  try {
+    return [JSON.parse(stripTrailingCommas(code)), null, { hasComments }];
+  } catch (err) {
+    return [null, err instanceof Error ? err : new Error(String(err)), { hasComments }];
+  }
+};

package/cli/mcp/installer-package.js

@@ -0,0 +1,54 @@
+/**
+ * Adds scripts to a consumer package.json without reformatting it or dropping content:
+ * - a one-line (minified) file stays one line; otherwise its own indent is kept;
+ * - a file with comments or that is not a JSON object is refused and left byte-identical;
+ * - only missing script names are added, existing ones are never changed.
+ */
+import fs from 'node:fs';
+import { parseJsonc } from './installer-jsonc.js';
+import { writeFileSafely } from './installer-write.js';
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const detectIndent = (text) => (text.match(/^[ \t]+(?=")/m) || ['  '])[0];
+
+/** Serializes value in the layout of the original text. */
+const serializeLike = (text, value) => {
+  const isSingleLine = !text.trim().includes('\n');
+  const body = isSingleLine ? JSON.stringify(value) : JSON.stringify(value, null, detectIndent(text));
+  const hasTrailingNewline = text.endsWith('\n');
+  return hasTrailingNewline ? `${body}\n` : body;
+};
+
+const refusal = (file, reason) => ({ status: 'refused', file, reason, added: [] });
+
+/** Reasons a package.json must not be rewritten, or null when it is safe to edit. */
+const findRefusalReason = (pkg, parseError, meta) => {
+  const isObject = !parseError && isPlainObject(pkg);
+  if (!isObject) return 'package.json is not a JSON object; left untouched';
+  if (meta.hasComments) return 'package.json has comments that a rewrite would drop; left untouched';
+  const hasInvalidScripts = pkg.scripts !== undefined && !isPlainObject(pkg.scripts);
+  if (hasInvalidScripts) return '"scripts" is not an object; left untouched';
+  return null;
+};
+
+/**
+ * Adds the scripts that pickWanted(existingScripts) names and package.json lacks.
+ * Returns { status: 'absent' | 'refused' | 'unchanged' | 'written', file, reason?, added }.
+ */
+export const addPackageScripts = (pkgPath, pickWanted) => {
+  const hasPackage = fs.existsSync(pkgPath);
+  if (!hasPackage) return { status: 'absent', file: pkgPath, added: [] };
+  const text = fs.readFileSync(pkgPath, 'utf-8');
+  const [pkg, parseError, meta] = parseJsonc(text);
+  const reason = findRefusalReason(pkg, parseError, meta);
+  const isRefused = reason !== null;
+  if (isRefused) return refusal(pkgPath, reason);
+  const scripts = pkg.scripts || {};
+  const missing = Object.entries(pickWanted(scripts)).filter(([name]) => !scripts[name]);
+  const hasNothingToAdd = missing.length === 0;
+  if (hasNothingToAdd) return { status: 'unchanged', file: pkgPath, added: [] };
+  const next = { ...pkg, scripts: { ...scripts, ...Object.fromEntries(missing) } };
+  const { status } = writeFileSafely(pkgPath, serializeLike(text, next), { backup: false });
+  return { status, file: pkgPath, added: missing.map(([name]) => name) };
+};

package/cli/mcp/installer-report.js

@@ -0,0 +1,47 @@
+/** Status predicates and console reporting for the MCP config installer. */
+import path from 'node:path';
+
+export const isRefusedEntry = (result) => result.status === 'refused';
+export const isSkippedEntry = (result) => result.status === 'skipped';
+export const isWrittenEntry = (result) => result.status === 'written';
+export const isAppliedEntry = (result) => Boolean(result) && !isRefusedEntry(result) && !isSkippedEntry(result);
+
+const displayPath = (file) => path.basename(path.dirname(file)) + '/' + path.basename(file);
+
+export const reportEntry = (result, label, isSilent) => {
+  if (isSilent) return;
+  const rel = displayPath(result.file);
+  const isNotApplied = isRefusedEntry(result) || isSkippedEntry(result);
+  if (isNotApplied) { process.stderr.write(`  \x1b[33m⚠\x1b[0m Skipped ${label} (${rel}): ${result.reason}\n`); return; }
+  const verb = result.status === 'unchanged' ? 'Already configured' : 'Configured';
+  process.stdout.write(`  \x1b[32m✔\x1b[0m ${verb} ${label} MCP server in: ${rel}\n`);
+};
+
+export const reportPackageScripts = (result, isSilent) => {
+  const isWritten = isWrittenEntry(result);
+  const shouldAnnounce = isWritten && !isSilent;
+  if (shouldAnnounce) process.stdout.write('  \x1b[32m✔\x1b[0m Added chemx verification & MCP scripts to package.json\n');
+  const shouldWarn = isRefusedEntry(result) && !isSilent;
+  if (shouldWarn) process.stderr.write(`  \x1b[33m⚠\x1b[0m Skipped package.json scripts: ${result.reason}\n`);
+};
+
+/** Path relative to the project, or absolute for files outside it (the home directory). */
+const projectPath = (base, file) => {
+  const rel = path.relative(base, file);
+  const isOutsideProject = rel.startsWith('..') || path.isAbsolute(rel);
+  return isOutsideProject ? file : rel;
+};
+
+export const summarizeInstall = (base, { refused, skipped, written }) => {
+  const hasRefusals = refused.length > 0;
+  const hasPartialApply = hasRefusals && written.length > 0;
+  if (hasPartialApply) {
+    const wrote = written.map((file) => projectPath(base, file)).join(', ');
+    const left = refused.map((r) => projectPath(base, r.file)).join(', ');
+    return `\x1b[33m⚠ Partial apply: wrote ${wrote}; refused ${left} (see above).\x1b[0m`;
+  }
+  if (hasRefusals) return '\x1b[33m⚠ Chemical X MCP server not configured in refused files (see above).\x1b[0m';
+  const hasSkips = skipped.length > 0;
+  if (hasSkips) return '\x1b[33m⚠ Chemical X MCP server configured, but some requested targets were skipped (see above).\x1b[0m';
+  return '\x1b[1m\x1b[32m✔ Chemical X MCP server configured.\x1b[0m';
+};