@flowrail/init 0.0.9 → 0.0.11

package/dist/doctor-script.js

@@ -10,15 +10,19 @@ const path_1 = __importDefault(require("path"));
 exports.DOCTOR_SCRIPT_FILENAME = 'scripts/check-flowrail.mjs';
 /**
  * The content of the doctor script dropped into the target repo.
- * It is a self-contained ES module — no deps outside node:fs.
+ * It is a self-contained ES module — no deps outside node: builtins.
  */
-const DOCTOR_SCRIPT_CONTENT = `#!/usr/bin/env node
+const DOCTOR_SCRIPT_CONTENT = String.raw `#!/usr/bin/env node
 /**
- * FlowRail doctor script — checks that .mcp.json is present and wired.
+ * FlowRail doctor script — checks that .mcp.json is present and wired,
+ * and that runtime source imports are declared in package.json.
  * Generated by @flowrail/init. Safe to commit to the repo.
  * Re-run the installer if this script fails: npx @flowrail/init@latest
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import path from 'node:path';
 
 const mcpPath = '.mcp.json';
 let ok = true;
@@ -26,7 +30,7 @@ let ok = true;
 if (!existsSync(mcpPath)) {
   console.error(
     'FlowRail: .mcp.json is missing — Claude Code MCP tools ' +
-      '(mcp__flowrail__*) will not be available.\\n' +
+      '(mcp__flowrail__*) will not be available.\n' +
       'Fix: npx @flowrail/init@latest',
   );
   ok = false;
@@ -36,20 +40,1301 @@ if (!existsSync(mcpPath)) {
     if (!cfg?.mcpServers?.flowrail) {
       console.error(
         'FlowRail: .mcp.json has no mcpServers.flowrail entry — ' +
-          'Claude Code MCP tools (mcp__flowrail__*) will not be available.\\n' +
+          'Claude Code MCP tools (mcp__flowrail__*) will not be available.\n' +
           'Fix: npx @flowrail/init@latest',
       );
       ok = false;
     }
   } catch {
     console.error(
-      'FlowRail: .mcp.json is malformed JSON.\\n' +
+      'FlowRail: .mcp.json is malformed JSON.\n' +
         'Fix: delete it and re-run: npx @flowrail/init@latest',
     );
     ok = false;
   }
 }
 
+const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.mts', '.cts']);
+const DECLARATION_EXTENSIONS = ['.d.ts', '.d.mts', '.d.cts'];
+const DEPENDENCY_SECTIONS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+];
+const EXCLUDED_SEGMENTS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.git',
+  'coverage',
+]);
+const TSCONFIG_EXTENDS_DEPTH_LIMIT = 10;
+const BUILTIN_MODULES = new Set(
+  builtinModules.map((moduleName) => moduleName.replace(/^node:/, '')),
+);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stripJsonComments(text) {
+  let output = '';
+  let index = 0;
+  let inString = false;
+  let quote = '';
+
+  while (index < text.length) {
+    const char = text[index];
+    const next = text[index + 1];
+
+    if (inString) {
+      output += char;
+      if (char === '\\' && index + 1 < text.length) {
+        output += text[index + 1];
+        index += 2;
+        continue;
+      }
+      if (char === quote) {
+        inString = false;
+        quote = '';
+      }
+      index += 1;
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      output += char;
+      index += 1;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      index += 2;
+      while (index < text.length && text[index] !== '\n' && text[index] !== '\r') {
+        index += 1;
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      index += 2;
+      while (index + 1 < text.length && !(text[index] === '*' && text[index + 1] === '/')) {
+        index += 1;
+      }
+      index += index + 1 < text.length ? 2 : 0;
+      continue;
+    }
+
+    output += char;
+    index += 1;
+  }
+
+  return output;
+}
+
+function stripJsonTrailingCommas(text) {
+  let output = '';
+  let index = 0;
+  let inString = false;
+  let quote = '';
+
+  while (index < text.length) {
+    const char = text[index];
+
+    if (inString) {
+      output += char;
+      if (char === '\\' && index + 1 < text.length) {
+        output += text[index + 1];
+        index += 2;
+        continue;
+      }
+      if (char === quote) {
+        inString = false;
+        quote = '';
+      }
+      index += 1;
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      output += char;
+      index += 1;
+      continue;
+    }
+
+    if (char === ',') {
+      let lookahead = index + 1;
+      while (lookahead < text.length && /\s/.test(text[lookahead])) lookahead += 1;
+      if (text[lookahead] === '}' || text[lookahead] === ']') {
+        index += 1;
+        continue;
+      }
+    }
+
+    output += char;
+    index += 1;
+  }
+
+  return output;
+}
+
+function parseJsoncFile(filePath) {
+  try {
+    return JSON.parse(stripJsonTrailingCommas(stripJsonComments(readFileSync(filePath, 'utf8'))));
+  } catch {
+    return null;
+  }
+}
+
+function isFile(filePath) {
+  try {
+    return statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function tsconfigKeyToRegExp(key) {
+  // A tsconfig "paths" key may carry a single '*' wildcard ANYWHERE (not only
+  // a trailing '/*'): '@env/*/config' is legal and matches '@env/prod/config'.
+  // Escape EVERY regex metacharacter (incl. '?', which appears in real keys
+  // like '@assets/*.svg?react'), then turn each '*' into '.*' (TS '*' matches
+  // any substring, slashes included). Anchored full-match. Returns null if the
+  // key still cannot compile to a RegExp — the caller skips it rather than
+  // letting the doctor crash the build on its own limitation (class-3 spirit).
+  const escaped = key.replace(/[$.+?^(){}|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  try {
+    return new RegExp('^' + escaped + '$');
+  } catch {
+    return null;
+  }
+}
+
+function addTsconfigPathAlias(aliases, key) {
+  if (key.includes('*')) {
+    const pattern = tsconfigKeyToRegExp(key);
+    if (pattern !== null) aliases.patterns.push(pattern);
+  } else {
+    aliases.exact.add(key);
+  }
+}
+
+function collectTsconfigFiles(dir, files = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (EXCLUDED_SEGMENTS.has(entry.name)) continue;
+
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectTsconfigFiles(fullPath, files);
+    } else if (
+      entry.isFile() &&
+      entry.name.startsWith('tsconfig') &&
+      entry.name.endsWith('.json')
+    ) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function isInsideDirectory(rootDir, candidatePath) {
+  const relative = path.relative(rootDir, candidatePath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function resolveTsconfigExtendsCandidate(basePath, mustBeInsideRoot) {
+  const rootDir = path.resolve(process.cwd());
+  const candidates = [basePath];
+  if (!basePath.endsWith('.json')) candidates.push(basePath + '.json');
+  candidates.push(path.join(basePath, 'tsconfig.json'));
+
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (mustBeInsideRoot && !isInsideDirectory(rootDir, resolved)) continue;
+    if (isFile(resolved)) return resolved;
+  }
+  return null;
+}
+
+function resolveRelativeTsconfigExtendsEntry(configPath, extendsValue) {
+  const rootDir = path.resolve(process.cwd());
+  const basePath = path.resolve(path.dirname(configPath), extendsValue);
+  return resolveTsconfigExtendsCandidate(basePath, isInsideDirectory(rootDir, path.resolve(configPath)));
+}
+
+function parsePackageTsconfigExtendsSpecifier(extendsValue) {
+  if (
+    extendsValue.startsWith('.') ||
+    extendsValue.startsWith('/') ||
+    path.isAbsolute(extendsValue)
+  ) {
+    return null;
+  }
+
+  const parts = extendsValue.split('/');
+  let packageName;
+  let subpathParts;
+
+  if (extendsValue.startsWith('@')) {
+    if (parts.length < 2 || parts[0] === '' || parts[1] === '') return null;
+    packageName = parts[0] + '/' + parts[1];
+    subpathParts = parts.slice(2);
+  } else {
+    if (parts[0] === '') return null;
+    packageName = parts[0];
+    subpathParts = parts.slice(1);
+  }
+
+  if (subpathParts.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    return null;
+  }
+
+  return {
+    packageName,
+    subpath: subpathParts.length > 0 ? subpathParts.join('/') : 'tsconfig.json',
+  };
+}
+
+function resolvePackageTsconfigExtendsEntry(configPath, extendsValue) {
+  const parsed = parsePackageTsconfigExtendsSpecifier(extendsValue);
+  if (parsed === null) return null;
+
+  let currentDir = path.resolve(path.dirname(configPath));
+  while (true) {
+    const basePath = path.join(
+      currentDir,
+      'node_modules',
+      parsed.packageName,
+      parsed.subpath,
+    );
+    const resolved = resolveTsconfigExtendsCandidate(basePath, false);
+    if (resolved !== null) return resolved;
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return null;
+    currentDir = parentDir;
+  }
+}
+
+function resolveTsconfigExtendsEntry(configPath, extendsValue) {
+  if (typeof extendsValue !== 'string') return null;
+
+  const trimmed = extendsValue.trim();
+  if (trimmed === '') return null;
+  if (trimmed.startsWith('.')) return resolveRelativeTsconfigExtendsEntry(configPath, trimmed);
+  return resolvePackageTsconfigExtendsEntry(configPath, trimmed);
+}
+
+function resolveTsconfigExtends(configPath, extendsValue) {
+  const values = Array.isArray(extendsValue) ? extendsValue : [extendsValue];
+  const resolvedPaths = [];
+
+  for (const value of values) {
+    const resolvedPath = resolveTsconfigExtendsEntry(configPath, value);
+    if (resolvedPath !== null) resolvedPaths.push(resolvedPath);
+  }
+  return resolvedPaths;
+}
+
+function addTsconfigPathAliasesFromFile(configPath, aliases, visited, depth) {
+  const resolvedPath = path.resolve(configPath);
+  if (depth >= TSCONFIG_EXTENDS_DEPTH_LIMIT || visited.has(resolvedPath)) return;
+  visited.add(resolvedPath);
+
+  const cfg = parseJsoncFile(resolvedPath);
+  if (!isPlainObject(cfg)) return;
+
+  for (const extendedPath of resolveTsconfigExtends(resolvedPath, cfg.extends)) {
+    addTsconfigPathAliasesFromFile(extendedPath, aliases, visited, depth + 1);
+  }
+
+  const paths = cfg?.compilerOptions?.paths;
+  if (!isPlainObject(paths)) return;
+
+  for (const key of Object.keys(paths)) {
+    addTsconfigPathAlias(aliases, key);
+  }
+}
+
+function readTsconfigPathAliases() {
+  const aliases = { exact: new Set(), patterns: [] };
+
+  for (const configPath of collectTsconfigFiles(process.cwd())) {
+    addTsconfigPathAliasesFromFile(configPath, aliases, new Set(), 0);
+  }
+
+  return aliases;
+}
+
+const TSCONFIG_PATH_ALIASES = readTsconfigPathAliases();
+
+function isTsconfigPathAlias(specifier) {
+  if (TSCONFIG_PATH_ALIASES.exact.has(specifier)) return true;
+  return TSCONFIG_PATH_ALIASES.patterns.some((pattern) => pattern.test(specifier));
+}
+
+function addDeclaredModulesFromPackageJson(packageJsonPath, declared) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  } catch {
+    return false;
+  }
+
+  for (const section of DEPENDENCY_SECTIONS) {
+    const deps = pkg?.[section];
+    if (!isPlainObject(deps)) continue;
+    for (const name of Object.keys(deps)) declared.add(name);
+  }
+  return true;
+}
+
+function collectPackageJsonFiles(dir, files = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (EXCLUDED_SEGMENTS.has(entry.name)) continue;
+
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectPackageJsonFiles(fullPath, files);
+    } else if (entry.isFile() && entry.name === 'package.json') {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function readDeclaredModules() {
+  if (!existsSync('package.json')) return null;
+
+  const declared = new Set();
+  const rootPackageJsonPath = path.resolve('package.json');
+  if (!addDeclaredModulesFromPackageJson(rootPackageJsonPath, declared)) return null;
+
+  for (const packageJsonPath of collectPackageJsonFiles(process.cwd())) {
+    if (path.resolve(packageJsonPath) === rootPackageJsonPath) continue;
+    addDeclaredModulesFromPackageJson(packageJsonPath, declared);
+  }
+  return declared;
+}
+
+function isDeclarationFileName(fileName) {
+  const lower = fileName.toLowerCase();
+  return DECLARATION_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+
+function collectSourceFiles(dir, files = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (EXCLUDED_SEGMENTS.has(entry.name)) continue;
+
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectSourceFiles(fullPath, files);
+    } else if (
+      entry.isFile() &&
+      !isDeclarationFileName(entry.name) &&
+      SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())
+    ) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function packageNameForSpecifier(specifier) {
+  const clean = specifier.trim();
+  if (
+    clean === '' ||
+    clean.startsWith('.') ||
+    clean.startsWith('/') ||
+    clean.includes('://') ||
+    /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(clean) ||
+    clean.startsWith('@/') ||
+    clean.startsWith('#') ||
+    clean.startsWith('~/') ||
+    clean === '~' ||
+    isTsconfigPathAlias(clean)
+  ) {
+    return null;
+  }
+
+  const bare = clean.startsWith('node:') ? clean.slice('node:'.length) : clean;
+  const builtinRoot = bare.split('/')[0];
+  if (BUILTIN_MODULES.has(bare) || BUILTIN_MODULES.has(builtinRoot)) {
+    return null;
+  }
+
+  if (bare.startsWith('@')) {
+    const parts = bare.split('/');
+    if (parts.length >= 2 && parts[0] && parts[1]) {
+      return parts[0] + '/' + parts[1];
+    }
+    return bare;
+  }
+  return bare.split('/')[0];
+}
+
+const STATIC_SENTINEL = String.fromCharCode(0);
+const DYNAMIC_SENTINEL = String.fromCharCode(1);
+const BACKTICK_CODE = 96;
+const DOLLAR_CODE = 36;
+
+function staticSentinel(index) {
+  return STATIC_SENTINEL + String(index) + STATIC_SENTINEL;
+}
+
+function dynamicSentinel(index) {
+  return DYNAMIC_SENTINEL + String(index) + DYNAMIC_SENTINEL;
+}
+
+function readQuotedString(text, start, quote) {
+  let value = '';
+  let index = start + 1;
+
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '\\') {
+      if (index + 1 < text.length) {
+        if (text[index + 1] === '\r' && text[index + 2] === '\n') {
+          index += 3;
+          continue;
+        }
+        if (text[index + 1] === '\n' || text[index + 1] === '\r') {
+          index += 2;
+          continue;
+        }
+        value += text[index + 1];
+        index += 2;
+      } else {
+        index += 1;
+      }
+      continue;
+    }
+    if (char === '\n' || char === '\r') {
+      return { end: index, value };
+    }
+    if (char === quote) {
+      return { end: index + 1, value };
+    }
+    value += char;
+    index += 1;
+  }
+
+  return { end: text.length, value };
+}
+
+function skipLineComment(text, start) {
+  let index = start + 2;
+  while (index < text.length && text[index] !== '\n' && text[index] !== '\r') {
+    index += 1;
+  }
+  return index;
+}
+
+function skipBlockComment(text, start) {
+  let index = start + 2;
+  while (index + 1 < text.length) {
+    if (text[index] === '*' && text[index + 1] === '/') {
+      return index + 2;
+    }
+    index += 1;
+  }
+  return text.length;
+}
+
+function commentWhitespace(text, start, end) {
+  let value = ' ';
+  for (let index = start; index < end; index += 1) {
+    const char = text[index];
+    if (char === '\n' || char === '\r') value += char;
+  }
+  return value;
+}
+
+const REGEX_PREFIX_PUNCTUATORS = new Set([
+  '(',
+  ',',
+  '[',
+  '{',
+  ';',
+  ':',
+  '=',
+  '!',
+  '&',
+  '|',
+  '?',
+  '+',
+  '-',
+  '*',
+  '/',
+  '%',
+  '^',
+  '~',
+  '<',
+  '>',
+]);
+const REGEX_PREFIX_KEYWORDS = new Set([
+  'return',
+  'throw',
+  'typeof',
+  'instanceof',
+  'in',
+  'of',
+  'do',
+  'else',
+  'yield',
+  'await',
+  'case',
+  'void',
+  'delete',
+  'new',
+]);
+
+function isIdentifierStart(char) {
+  return /[A-Za-z_$]/.test(char);
+}
+
+function isIdentifierPart(char) {
+  return /[A-Za-z0-9_$]/.test(char);
+}
+
+function readIdentifier(text, start) {
+  let index = start + 1;
+  while (index < text.length && isIdentifierPart(text[index])) index += 1;
+  return index;
+}
+
+function tokenAllowsRegex(previousToken) {
+  if (previousToken === null) return true;
+  if (previousToken.type === 'keyword') return REGEX_PREFIX_KEYWORDS.has(previousToken.value);
+  if (previousToken.type === 'punctuator') {
+    return REGEX_PREFIX_PUNCTUATORS.has(previousToken.value);
+  }
+  return false;
+}
+
+function tokenForPunctuator(char) {
+  if (char === ')' || char === ']' || char === '}') return { type: 'expression', value: char };
+  return { type: 'punctuator', value: char };
+}
+
+function readRegexLiteral(text, start) {
+  let inClass = false;
+  let index = start + 1;
+
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '\n' || char === '\r') return index;
+    if (char === '\\') {
+      if (index + 1 < text.length && (text[index + 1] === '\n' || text[index + 1] === '\r')) {
+        return index + 1;
+      }
+      index += index + 1 < text.length ? 2 : 1;
+      continue;
+    }
+    if (char === '[') {
+      inClass = true;
+      index += 1;
+      continue;
+    }
+    if (char === ']' && inClass) {
+      inClass = false;
+      index += 1;
+      continue;
+    }
+    if (char === '/' && !inClass) {
+      index += 1;
+      while (index < text.length && isIdentifierPart(text[index])) index += 1;
+      return index;
+    }
+    index += 1;
+  }
+
+  return index;
+}
+
+function skipTemplateExpression(text, start) {
+  let depth = 1;
+  let index = start;
+  let previousToken = null;
+
+  while (index < text.length) {
+    const char = text[index];
+    const next = text[index + 1];
+    const code = text.charCodeAt(index);
+
+    if (/\s/.test(char)) {
+      index += 1;
+      continue;
+    }
+    if (isIdentifierStart(char)) {
+      const end = readIdentifier(text, index);
+      const value = text.slice(index, end);
+      previousToken = {
+        type:
+          REGEX_PREFIX_KEYWORDS.has(value) && previousToken?.value !== '.'
+            ? 'keyword'
+            : 'identifier',
+        value,
+      };
+      index = end;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      index = readQuotedString(text, index, char).end;
+      previousToken = { type: 'expression', value: char };
+      continue;
+    }
+    if (code === BACKTICK_CODE) {
+      index = readTemplateLiteral(text, index).end;
+      previousToken = { type: 'expression', value: 'template' };
+      continue;
+    }
+    if (char === '/' && next === '/') {
+      index = skipLineComment(text, index);
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      index = skipBlockComment(text, index);
+      continue;
+    }
+    if (char === '/' && tokenAllowsRegex(previousToken)) {
+      index = readRegexLiteral(text, index);
+      previousToken = { type: 'expression', value: 'regex' };
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+      previousToken = { type: 'punctuator', value: char };
+      index += 1;
+      continue;
+    }
+    if (char === '}') {
+      depth -= 1;
+      index += 1;
+      if (depth === 0) return index;
+      previousToken = { type: 'expression', value: char };
+      continue;
+    }
+    previousToken = tokenForPunctuator(char);
+    index += 1;
+  }
+
+  return index;
+}
+
+function readTemplateLiteral(text, start) {
+  let value = '';
+  let dynamic = false;
+  const expressions = [];
+  let index = start + 1;
+
+  while (index < text.length) {
+    const char = text[index];
+    const code = text.charCodeAt(index);
+
+    if (char === '\\') {
+      if (!dynamic && index + 1 < text.length) value += text[index + 1];
+      index += index + 1 < text.length ? 2 : 1;
+      continue;
+    }
+    if (code === BACKTICK_CODE) {
+      return {
+        dynamic,
+        end: index + 1,
+        expressions,
+        source: text.slice(start, index + 1),
+        value,
+      };
+    }
+    if (code === DOLLAR_CODE && text[index + 1] === '{') {
+      dynamic = true;
+      const expressionStart = index + 2;
+      const expressionEnd = skipTemplateExpression(text, expressionStart);
+      const expressionClose =
+        expressionEnd > expressionStart && text[expressionEnd - 1] === '}'
+          ? expressionEnd - 1
+          : expressionEnd;
+      expressions.push(text.slice(expressionStart, expressionClose));
+      index = expressionEnd;
+      continue;
+    }
+    if (!dynamic) value += char;
+    index += 1;
+  }
+
+  return { dynamic, end: text.length, expressions, source: text.slice(start), value };
+}
+
+function maskStringsAndComments(text, state) {
+  const strings = state?.strings ?? [];
+  const dynamicStrings = state?.dynamicStrings ?? [];
+  const templateExpressions = [];
+  let masked = '';
+  let index = 0;
+  let previousToken = null;
+
+  while (index < text.length) {
+    const char = text[index];
+    const next = text[index + 1];
+    const code = text.charCodeAt(index);
+
+    if (/\s/.test(char)) {
+      masked += char;
+      index += 1;
+      continue;
+    }
+    if (isIdentifierStart(char)) {
+      const end = readIdentifier(text, index);
+      const value = text.slice(index, end);
+      masked += value;
+      previousToken = {
+        type:
+          REGEX_PREFIX_KEYWORDS.has(value) && previousToken?.value !== '.'
+            ? 'keyword'
+            : 'identifier',
+        value,
+      };
+      index = end;
+      continue;
+    }
+    if (char === '/' && next === '/') {
+      const end = skipLineComment(text, index);
+      masked += commentWhitespace(text, index, end);
+      index = end;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      const end = skipBlockComment(text, index);
+      masked += commentWhitespace(text, index, end);
+      index = end;
+      continue;
+    }
+    if (char === '/' && tokenAllowsRegex(previousToken)) {
+      const end = readRegexLiteral(text, index);
+      masked += commentWhitespace(text, index, end);
+      previousToken = { type: 'expression', value: 'regex' };
+      index = end;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      const literal = readQuotedString(text, index, char);
+      const literalIndex = strings.push(literal.value) - 1;
+      masked += staticSentinel(literalIndex);
+      previousToken = { type: 'expression', value: char };
+      index = literal.end;
+      continue;
+    }
+    if (code === BACKTICK_CODE) {
+      const literal = readTemplateLiteral(text, index);
+      if (literal.dynamic) {
+        const literalIndex = dynamicStrings.push(literal.source) - 1;
+        masked += dynamicSentinel(literalIndex);
+        for (const expression of literal.expressions) {
+          const expressionScan = maskStringsAndComments(expression, {
+            dynamicStrings,
+            strings,
+          });
+          if (expressionScan.masked.trim()) templateExpressions.push(expressionScan.masked);
+        }
+      } else {
+        const literalIndex = strings.push(literal.value) - 1;
+        masked += staticSentinel(literalIndex);
+      }
+      previousToken = { type: 'expression', value: 'template' };
+      index = literal.end;
+      continue;
+    }
+
+    masked += char;
+    previousToken = tokenForPunctuator(char);
+    index += 1;
+  }
+
+  if (templateExpressions.length > 0) {
+    masked += '\n' + templateExpressions.join('\n');
+  }
+  return { dynamicStrings, masked, strings };
+}
+
+function staticSpecifierFromMatch(strings, indexText) {
+  const index = Number(indexText);
+  return Number.isInteger(index) ? strings[index] : undefined;
+}
+
+function isAllTypeOnlyNamedClause(clause) {
+  const trimmed = clause.trim();
+  const open = trimmed.indexOf('{');
+  const close = trimmed.lastIndexOf('}');
+  if (open === -1 || close === -1 || close < open) return false;
+  if (trimmed.slice(0, open).trim() !== '') return false;
+  if (trimmed.slice(close + 1).trim() !== '') return false;
+
+  const bindings = trimmed
+    .slice(open + 1, close)
+    .split(',')
+    .map((binding) => binding.trim())
+    .filter(Boolean);
+  return bindings.length > 0 && bindings.every((binding) => /^type\s+(?!as\b)/.test(binding));
+}
+
+function addSpecifier(specifiers, strings, indexText) {
+  const specifier = staticSpecifierFromMatch(strings, indexText);
+  if (specifier !== undefined) specifiers.add(specifier);
+}
+
+function expressionStartsWithStaticSentinelArgument(expression) {
+  const source = STATIC_SENTINEL + '(\\d+)' + STATIC_SENTINEL;
+  return new RegExp('^' + source + '\\s*(?:$|,)').test(expression.trim());
+}
+
+function expressionForWarning(expression, strings, dynamicStrings) {
+  const staticSource = STATIC_SENTINEL + '(\\d+)' + STATIC_SENTINEL;
+  const dynamicSource = DYNAMIC_SENTINEL + '(\\d+)' + DYNAMIC_SENTINEL;
+  return expression.trim().replace(new RegExp(staticSource, 'g'), (_match, indexText) => {
+    const value = strings[Number(indexText)];
+    return value === undefined ? '<static string>' : value;
+  }).replace(new RegExp(dynamicSource, 'g'), (_match, indexText) => {
+    const value = dynamicStrings[Number(indexText)];
+    return value === undefined ? '<dynamic template>' : value;
+  });
+}
+
+function skipWsBackward(text, index) {
+  while (index > 0 && /\s/.test(text[index - 1])) index -= 1;
+  return index;
+}
+
+function matchKeywordBackward(text, end, keyword) {
+  // If a whole-word 'keyword' ends exactly at 'end' (left boundary is not an
+  // identifier char), return its start index; else -1. Shared by the backward
+  // type-erasure scans below. (Note: does NOT treat a leading '.' as a
+  // boundary stop — isPrecededByTypeofKeyword needs that extra rule and keeps
+  // its own check.)
+  const start = end - keyword.length;
+  if (start < 0 || text.slice(start, end) !== keyword) return -1;
+  if (start > 0 && isIdentifierPart(text[start - 1])) return -1;
+  return start;
+}
+
+function isPrecededByTypeofKeyword(text, index) {
+  const wordEnd = skipWsBackward(text, index);
+  const wordStart = wordEnd - 'typeof'.length;
+  if (wordStart < 0 || text.slice(wordStart, wordEnd) !== 'typeof') return false;
+  if (wordStart > 0 && (isIdentifierPart(text[wordStart - 1]) || text[wordStart - 1] === '.')) {
+    return false;
+  }
+  return true;
+}
+
+function isTypeOnlyImportAssignmentRequire(text, requireStart) {
+  let index = skipWsBackward(text, requireStart);
+  if (index === 0 || text[index - 1] !== '=') return false;
+
+  index = skipWsBackward(text, index - 1);
+
+  const identifierEnd = index;
+  while (index > 0 && isIdentifierPart(text[index - 1])) index -= 1;
+  if (index === identifierEnd) return false;
+
+  const typeStart = matchKeywordBackward(text, skipWsBackward(text, index), 'type');
+  if (typeStart === -1) return false;
+
+  const importStart = matchKeywordBackward(text, skipWsBackward(text, typeStart), 'import');
+  return importStart !== -1;
+}
+
+function findCallCloseParen(text, callStart) {
+  const open = text.indexOf('(', callStart);
+  if (open === -1) return -1;
+  let depth = 0;
+  for (let index = open; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '(') {
+      depth += 1;
+      continue;
+    }
+    if (char === ')') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+function skipBackwardOverGenericParams(text, end) {
+  // text[end-1] is '>': return the index of the matching '<' (the position just
+  // before it), or -1 if unbalanced. Used to step over a type name's generic
+  // parameter list ('type Foo<T> = ...') when scanning backwards.
+  if (text[end - 1] !== '>') return end;
+  let depth = 0;
+  for (let index = end - 1; index >= 0; index -= 1) {
+    const char = text[index];
+    if (char === '>') depth += 1;
+    else if (char === '<') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+function isTypeAliasImportCall(text, importStart) {
+  // "type X = import('pkg')" / "type X<T> = import('pkg')" — a TS type alias
+  // whose whole RHS is a module-type query (no ".Member" / "typeof", so the
+  // existing isTypeQueryImportCall misses it). Erased at runtime, not a dep.
+  // Scan backward: ws, '=', ws, [generic '<...>'], type-name ident, ws, 'type'.
+  // Only ever skips (false negative); a runtime "const X = import()" lacks the
+  // leading "type" keyword and is still flagged.
+  let index = skipWsBackward(text, importStart);
+  if (index === 0 || text[index - 1] !== '=') return false;
+  index = skipWsBackward(text, index - 1);
+
+  if (text[index - 1] === '>') {
+    const open = skipBackwardOverGenericParams(text, index);
+    if (open < 0) return false;
+    index = skipWsBackward(text, open);
+  }
+
+  const identifierEnd = index;
+  while (index > 0 && isIdentifierPart(text[index - 1])) index -= 1;
+  if (index === identifierEnd) return false;
+
+  return matchKeywordBackward(text, skipWsBackward(text, index), 'type') !== -1;
+}
+
+function isTypeQueryImportCall(text, importStart) {
+  if (isPrecededByTypeofKeyword(text, importStart)) return true;
+
+  const close = findCallCloseParen(text, importStart);
+  if (close === -1) return false;
+
+  let index = close + 1;
+  while (index < text.length && /\s/.test(text[index])) index += 1;
+  if (text[index] !== '.') return false;
+
+  index += 1;
+  while (index < text.length && /\s/.test(text[index])) index += 1;
+  if (index >= text.length || !isIdentifierStart(text[index])) return false;
+
+  const memberEnd = readIdentifier(text, index);
+  const member = text.slice(index, memberEnd);
+  return member !== 'then' && member !== 'catch' && member !== 'finally';
+}
+
+function computePrefixBracketDepth(masked) {
+  // prefix[i] = net ()/{}/[] nesting depth of masked[0..i). Strings, comments,
+  // regex and template literals are already sentinel-masked, so brackets inside
+  // them don't count. A real ESM statement-form import/export is only valid at
+  // module top level (depth 0); an import-like literal nested in JSX text or any
+  // expression sits at depth > 0. Gating on depth 0 can only ADD a false
+  // negative (never a false positive that breaks a build) — the load-bearing
+  // ADR-018 invariant.
+  const prefix = new Int32Array(masked.length + 1);
+  let depth = 0;
+  for (let index = 0; index < masked.length; index += 1) {
+    const char = masked[index];
+    if (char === '(' || char === '{' || char === '[') depth += 1;
+    else if (char === ')' || char === '}' || char === ']') depth -= 1;
+    prefix[index + 1] = depth;
+  }
+  return prefix;
+}
+
+function extractModuleSpecifiers(text, filePath) {
+  const scan = maskStringsAndComments(text);
+  const prefixDepth = computePrefixBracketDepth(scan.masked);
+  const isStatementTopLevel = (matchIndex) => prefixDepth[matchIndex] === 0;
+  const specifiers = new Set();
+  const sentinelSource = STATIC_SENTINEL + '(\\d+)' + STATIC_SENTINEL;
+  const statementStartSource = '(?:^|[\\r\\n])[ \\t]*';
+  const importFromPattern = new RegExp(
+    statementStartSource + '\\bimport(?!\\s+type\\b)\\s+([^;]*?)\\bfrom\\s*' + sentinelSource,
+    'g',
+  );
+  const sideEffectImportPattern = new RegExp(
+    statementStartSource + '\\bimport\\s+' + sentinelSource,
+    'g',
+  );
+  const exportFromPattern = new RegExp(
+    statementStartSource +
+      '\\bexport(?!\\s+type\\b)\\s+((?:\\*\\s+as\\s+[A-Za-z_$][A-Za-z0-9_$]*|\\*|\\{[^}]*\\})\\s*)\\bfrom\\s*' +
+      sentinelSource,
+    'g',
+  );
+  const requirePattern = new RegExp(
+    '\\brequire\\s*\\(\\s*' + sentinelSource + '\\s*(?:,|\\))',
+    'g',
+  );
+  const importCallPattern = new RegExp(
+    '\\bimport\\s*\\(\\s*' + sentinelSource + '\\s*(?:,|\\))',
+    'g',
+  );
+
+  let match;
+  while ((match = importFromPattern.exec(scan.masked)) !== null) {
+    if (!isStatementTopLevel(match.index)) continue;
+    if (!isAllTypeOnlyNamedClause(match[1])) addSpecifier(specifiers, scan.strings, match[2]);
+  }
+  while ((match = sideEffectImportPattern.exec(scan.masked)) !== null) {
+    if (!isStatementTopLevel(match.index)) continue;
+    addSpecifier(specifiers, scan.strings, match[1]);
+  }
+  while ((match = exportFromPattern.exec(scan.masked)) !== null) {
+    if (!isStatementTopLevel(match.index)) continue;
+    if (!isAllTypeOnlyNamedClause(match[1])) addSpecifier(specifiers, scan.strings, match[2]);
+  }
+  while ((match = requirePattern.exec(scan.masked)) !== null) {
+    if (isTypeOnlyImportAssignmentRequire(scan.masked, match.index)) continue;
+    addSpecifier(specifiers, scan.strings, match[1]);
+  }
+  while ((match = importCallPattern.exec(scan.masked)) !== null) {
+    if (isTypeQueryImportCall(scan.masked, match.index)) continue;
+    if (isTypeAliasImportCall(scan.masked, match.index)) continue;
+    addSpecifier(specifiers, scan.strings, match[1]);
+  }
+
+  const dynamicPattern = /\b(?:require|import)\s*\(\s*([^)]*?)\)/g;
+  let dynamicMatch;
+  while ((dynamicMatch = dynamicPattern.exec(scan.masked)) !== null) {
+    const expression = dynamicMatch[1].trim();
+    if (!expression || expressionStartsWithStaticSentinelArgument(expression)) continue;
+    const relativePath = path.relative(process.cwd(), filePath) || filePath;
+    console.warn(
+      'FlowRail: skipped dynamic module specifier in ' +
+        relativePath +
+        ': ' +
+        expressionForWarning(expression, scan.strings, scan.dynamicStrings),
+    );
+  }
+
+  return specifiers;
+}
+
+function checkUndeclaredRuntimeImports() {
+  const declared = readDeclaredModules();
+  if (declared === null) return true;
+
+  const undeclared = new Set();
+  for (const filePath of collectSourceFiles(process.cwd())) {
+    let text;
+    try {
+      text = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    for (const specifier of extractModuleSpecifiers(text, filePath)) {
+      const packageName = packageNameForSpecifier(specifier);
+      if (packageName !== null && !declared.has(packageName)) {
+        undeclared.add(packageName);
+      }
+    }
+  }
+
+  if (undeclared.size === 0) return true;
+
+  const names = Array.from(undeclared).sort();
+  console.error(
+    'FlowRail: source imports runtime modules missing from package.json ' +
+      'dependencies/devDependencies/optionalDependencies/peerDependencies:\n' +
+      names.map((name) => '  - ' + name).join('\n') +
+      '\nFix: add the missing module(s) to package.json and re-run install.',
+  );
+  return false;
+}
+
+if (!checkUndeclaredRuntimeImports()) ok = false;
+
+// ---------------------------------------------------------------------------
+// ADR-019 Decision 6 — version-skew checks.
+//
+// Both checks DEGRADE GRACEFULLY: an inability to PROBE (offline npx,
+// unreachable server, missing API key) warns and skips — the doctor must
+// never convert its own probe failure into a hard build failure. Only a
+// SUCCESSFUL probe that reveals real skew fails the doctor.
+// ---------------------------------------------------------------------------
+
+function readClaudeSettings() {
+  try {
+    return JSON.parse(readFileSync(path.join('.claude', 'settings.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function flowrailHookCommands(settings) {
+  const commands = [];
+  const hooks = settings && typeof settings === 'object' ? settings.hooks : null;
+  if (!hooks || typeof hooks !== 'object') return commands;
+  for (const groups of Object.values(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      const entries = group && Array.isArray(group.hooks) ? group.hooks : [];
+      for (const hook of entries) {
+        if (hook && typeof hook.command === 'string' && hook.command.includes('flowrail-hook')) {
+          commands.push(hook.command);
+        }
+      }
+    }
+  }
+  return commands;
+}
+
+function referencedHookSubcommands(commands) {
+  const subcommands = new Set();
+  for (const command of commands) {
+    const match = command.match(/flowrail-hook\s+([a-z][a-z-]*)/);
+    if (match) subcommands.add(match[1]);
+  }
+  return subcommands;
+}
+
+/**
+ * (a) Every settings-referenced flowrail-hook subcommand must exist in the
+ * RESOLVED hook version. A stale npx cache running an old hook against newer
+ * wiring mis-fires silently at runtime (the hook's own unknown-subcommand
+ * handling fails open outside PreToolUse) — the doctor is where that skew
+ * surfaces loudly. Probes the hook's "capabilities" subcommand.
+ */
+function checkHookSubcommandCapabilities(settings) {
+  const referenced = referencedHookSubcommands(flowrailHookCommands(settings));
+  if (referenced.size === 0) return true;
+  let parsed;
+  try {
+    const out = execFileSync(
+      'npx',
+      ['--yes', '-p', '@flowrail/hook', 'flowrail-hook', 'capabilities'],
+      { encoding: 'utf8', timeout: 20000, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    parsed = JSON.parse(out);
+  } catch {
+    console.warn(
+      'FlowRail: could not probe flowrail-hook capabilities (offline, npx ' +
+        'unavailable, or a pre-capabilities hook version); skipping the ' +
+        'subcommand version-skew check.',
+    );
+    return true;
+  }
+  const advertised = new Set(
+    parsed && Array.isArray(parsed.subcommands) ? parsed.subcommands : [],
+  );
+  const missing = Array.from(referenced).filter((sub) => !advertised.has(sub));
+  if (missing.length === 0) return true;
+  console.error(
+    'FlowRail: .claude/settings.json references flowrail-hook subcommand(s) ' +
+      'missing from the resolved @flowrail/hook version: ' +
+      missing.join(', ') +
+      '\nA stale hook cannot serve these hooks. Fix: refresh the hook — ' +
+      'npx --yes @flowrail/init@latest',
+  );
+  return false;
+}
+
+function settingsHasFlowrailStopWiring(settings) {
+  const hooks = settings && typeof settings === 'object' ? settings.hooks : null;
+  const groups = hooks && Array.isArray(hooks.Stop) ? hooks.Stop : [];
+  for (const group of groups) {
+    const entries = group && Array.isArray(group.hooks) ? group.hooks : [];
+    for (const hook of entries) {
+      if (hook && typeof hook.command === 'string' && hook.command.includes('flowrail-hook')) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * (b) When the server advertises flowrail_review_app (tools/list) but
+ * .claude/settings.json has no FlowRail Stop wiring, whole-app reviews
+ * never trigger — settings written by a pre-ADR-019 init against a newer
+ * server. Needs the base URL (from the hook command's FLOWRAIL_MCP_URL
+ * prefix) and FLOWRAIL_API_KEY; missing either skips silently.
+ */
+async function checkStopWiringAgainstServer(settings) {
+  let baseUrl = null;
+  for (const command of flowrailHookCommands(settings)) {
+    const match = command.match(/FLOWRAIL_MCP_URL=(\S+)/);
+    if (match) {
+      baseUrl = match[1];
+      break;
+    }
+  }
+  const apiKey = process.env.FLOWRAIL_API_KEY;
+  if (!baseUrl || !apiKey) return true;
+
+  let tools;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    const response = await fetch(baseUrl.replace(/\/+$/, '') + '/mcp', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: 'Bearer ' + apiKey,
+      },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    const body = await response.json();
+    tools = body && body.result && Array.isArray(body.result.tools)
+      ? body.result.tools
+      : null;
+  } catch {
+    console.warn(
+      'FlowRail: could not reach the server for tools/list; skipping the ' +
+        'Stop-wiring check.',
+    );
+    return true;
+  }
+  if (!tools) return true;
+  const advertisesReviewApp = tools.some(
+    (tool) => tool && tool.name === 'flowrail_review_app',
+  );
+  if (!advertisesReviewApp) return true;
+  if (settingsHasFlowrailStopWiring(settings)) return true;
+  console.error(
+    'FlowRail: the server advertises flowrail_review_app but ' +
+      '.claude/settings.json has no FlowRail Stop hook wiring — whole-app ' +
+      'composition reviews will never trigger.\n' +
+      'Fix: re-run the installer — npx @flowrail/init@latest',
+  );
+  return false;
+}
+
+const claudeSettings = readClaudeSettings();
+if (claudeSettings !== null) {
+  if (!checkHookSubcommandCapabilities(claudeSettings)) ok = false;
+  if (!(await checkStopWiringAgainstServer(claudeSettings))) ok = false;
+}
+
 if (!ok) process.exit(1);
 `;
 /**