cc-env-checker 0.1.0

package/src/checks/static-install.js

@@ -0,0 +1,307 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  createCheckResult,
+  extractMatches,
+  resolveExecutable,
+} from './helpers.js';
+
+const ENDPOINT_GROUPS = [
+  {
+    id: 'anthropic-api',
+    patterns: [/https:\/\/api\.anthropic\.com\/[^\s"'`]+/g],
+  },
+  {
+    id: 'anthropic-mcp-proxy',
+    patterns: [/https:\/\/mcp-proxy\.anthropic\.com[^\s"'`]*/g],
+  },
+  {
+    id: 'datadog-logs',
+    patterns: [/https:\/\/http-intake\.logs\.[^\s"'`]+/g],
+  },
+];
+
+const HEADER_GROUPS = [
+  {
+    id: 'anthropic',
+    patterns: [/\bx-anthropic-[a-z0-9-]+\b/gi],
+  },
+  {
+    id: 'claude-code',
+    patterns: [/\bx-claude-code-[a-z0-9-]+\b/gi],
+  },
+  {
+    id: 'generic',
+    patterns: [/\bx-client-request-id\b/gi, /\buser-agent\b/gi],
+  },
+];
+
+const EVENT_GROUPS = [
+  {
+    id: 'tengu',
+    patterns: [/\btengu_[a-z0-9_]+\b/g],
+  },
+];
+
+const DEFAULT_INSTALL_MAX_FILE_BYTES = 128 * 1024;
+const DEFAULT_INSTALL_MAX_FILES = 24;
+const READABLE_INSTALL_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.json']);
+
+function summarizeGroupMatches(text, groups) {
+  return groups
+    .map((group) => ({
+      id: group.id,
+      count: extractMatches(text, group.patterns).length,
+    }))
+    .filter((group) => group.count > 0);
+}
+
+function formatCategoryDetails(groups, prefix) {
+  if (!groups.length) {
+    return [`${prefix}=none-observed`];
+  }
+
+  return groups.map((group) => `${group.id}=${group.count}`);
+}
+
+function sanitizeErrorLabel(error) {
+  if (error?.code) {
+    return `unreadable:${error.code}`;
+  }
+
+  return 'unreadable:unknown';
+}
+
+function createSummaryCheck({
+  id,
+  titleKey,
+  details,
+  summaryKey,
+  suggestionKey,
+  evidenceType = 'observed',
+  status = 'pass',
+}) {
+  return createCheckResult({
+    id,
+    titleKey,
+    status,
+    riskLevel: 'low',
+    evidenceType,
+    source: 'static-install',
+    summaryKey,
+    details,
+    suggestionKey,
+  });
+}
+
+function resolvePackageRoot(executablePath) {
+  return path.resolve(
+    path.dirname(executablePath),
+    '..',
+    'lib',
+    'node_modules',
+    'claude-code',
+  );
+}
+
+async function resolvePackageRoots(executablePath) {
+  const roots = [];
+  const pushUnique = (candidate) => {
+    if (candidate && !roots.includes(candidate)) {
+      roots.push(candidate);
+    }
+  };
+
+  pushUnique(resolvePackageRoot(executablePath));
+
+  try {
+    const realExecutablePath = await fs.realpath(executablePath);
+    const scopedPackageRoot = path.dirname(realExecutablePath);
+    pushUnique(scopedPackageRoot);
+
+    if (path.basename(scopedPackageRoot) === 'bin') {
+      pushUnique(path.resolve(scopedPackageRoot, '..'));
+    }
+  } catch {
+    // Fall back to the legacy derived package root when realpath is unavailable.
+  }
+
+  return roots;
+}
+
+async function collectInstallTextFiles(rootPath, { maxFiles = DEFAULT_INSTALL_MAX_FILES } = {}) {
+  const selected = [];
+  const queue = [rootPath];
+
+  while (queue.length > 0 && selected.length < maxFiles) {
+    const currentPath = queue.shift();
+    const entries = await fs.readdir(currentPath, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of entries) {
+      const entryPath = path.join(currentPath, entry.name);
+
+      if (entry.isDirectory()) {
+        queue.push(entryPath);
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      if (!READABLE_INSTALL_EXTENSIONS.has(path.extname(entry.name))) {
+        continue;
+      }
+
+      const stat = await fs.stat(entryPath);
+      if (stat.size > DEFAULT_INSTALL_MAX_FILE_BYTES) {
+        continue;
+      }
+
+      selected.push(entryPath);
+      if (selected.length >= maxFiles) {
+        break;
+      }
+    }
+  }
+
+  return selected;
+}
+
+export async function defaultReadInstallText(executablePath) {
+  const packageRoots = await resolvePackageRoots(executablePath);
+  let lastError = null;
+
+  for (const packageRoot of packageRoots) {
+    try {
+      const selectedFiles = await collectInstallTextFiles(packageRoot);
+      const chunks = await Promise.all(
+        selectedFiles.map((filePath) => fs.readFile(filePath, 'utf8')),
+      );
+
+      return {
+        ok: true,
+        text: chunks.join('\n'),
+      };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  return {
+    ok: false,
+    code: lastError?.code,
+    message: lastError?.message,
+  };
+}
+
+function createFailureChecks({ status, evidenceType, summaryKey, suggestionKey, details }) {
+  return [
+    createSummaryCheck({
+      id: 'static-install.endpoint-summary',
+      titleKey: 'check.staticInstall.endpoint.title',
+      status,
+      evidenceType,
+      summaryKey,
+      suggestionKey,
+      details,
+    }),
+    createSummaryCheck({
+      id: 'static-install.header-summary',
+      titleKey: 'check.staticInstall.header.title',
+      status,
+      evidenceType,
+      summaryKey,
+      suggestionKey,
+      details,
+    }),
+    createSummaryCheck({
+      id: 'static-install.event-summary',
+      titleKey: 'check.staticInstall.event.title',
+      status,
+      evidenceType,
+      summaryKey,
+      suggestionKey,
+      details,
+    }),
+  ];
+}
+
+export function createStaticInstallModule({
+  resolveExecutable: resolve = resolveExecutable,
+  readInstallText = defaultReadInstallText,
+} = {}) {
+  return {
+    id: 'static-install',
+    titleKey: 'module.staticInstall',
+    async run() {
+      const executable = await resolve('claude');
+
+      if (!executable.ok) {
+        return createFailureChecks({
+          status: 'skip',
+          evidenceType: 'unverifiable',
+          summaryKey: 'check.staticInstall.summary.skip',
+          suggestionKey: 'check.staticInstall.suggestion.skip',
+          details: ['install-text=unavailable'],
+        });
+      }
+
+      const textResult = await readInstallText(executable.path);
+
+      if (!textResult.ok) {
+        return createFailureChecks({
+          status: 'warn',
+          evidenceType: 'partial',
+          summaryKey: 'check.staticInstall.summary.warn',
+          suggestionKey: 'check.staticInstall.suggestion.warn',
+          details: [`install-text=${sanitizeErrorLabel(textResult)}`],
+        });
+      }
+
+      const endpointGroups = summarizeGroupMatches(textResult.text, ENDPOINT_GROUPS);
+      const headerGroups = summarizeGroupMatches(textResult.text, HEADER_GROUPS);
+      const eventGroups = summarizeGroupMatches(textResult.text, EVENT_GROUPS);
+
+      return [
+        createSummaryCheck({
+          id: 'static-install.endpoint-summary',
+          titleKey: 'check.staticInstall.endpoint.title',
+          status: endpointGroups.length ? 'pass' : 'warn',
+          evidenceType: endpointGroups.length ? 'observed' : 'partial',
+          summaryKey: endpointGroups.length
+            ? 'check.staticInstall.endpoint.summary.pass'
+            : 'check.staticInstall.endpoint.summary.warn',
+          details: formatCategoryDetails(endpointGroups, 'endpoint'),
+          suggestionKey: 'check.staticInstall.endpoint.suggestion.review',
+        }),
+        createSummaryCheck({
+          id: 'static-install.header-summary',
+          titleKey: 'check.staticInstall.header.title',
+          status: headerGroups.length ? 'pass' : 'warn',
+          evidenceType: headerGroups.length ? 'observed' : 'partial',
+          summaryKey: headerGroups.length
+            ? 'check.staticInstall.header.summary.pass'
+            : 'check.staticInstall.header.summary.warn',
+          details: formatCategoryDetails(headerGroups, 'header'),
+          suggestionKey: 'check.staticInstall.header.suggestion.review',
+        }),
+        createSummaryCheck({
+          id: 'static-install.event-summary',
+          titleKey: 'check.staticInstall.event.title',
+          status: eventGroups.length ? 'pass' : 'warn',
+          evidenceType: eventGroups.length ? 'observed' : 'partial',
+          summaryKey: eventGroups.length
+            ? 'check.staticInstall.event.summary.pass'
+            : 'check.staticInstall.event.summary.warn',
+          details: formatCategoryDetails(eventGroups, 'event'),
+          suggestionKey: 'check.staticInstall.event.suggestion.review',
+        }),
+      ];
+    },
+  };
+}
+
+export const staticInstallModule = createStaticInstallModule();

package/src/cli-app.js

@@ -0,0 +1,108 @@
+import { createDoctorReport } from './doctor.js';
+import { createTranslator, resolveLocale } from './i18n.js';
+import { defaultModules, selectModules } from './modules.js';
+import { renderHumanReport, renderJsonReport } from './render.js';
+
+function toModuleTitleKey(moduleId) {
+  const normalized = String(moduleId).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+  return `module.${normalized}`;
+}
+
+function normalizeArgs(argv) {
+  const flags = {
+    verbose: false,
+    json: false,
+    remote: true,
+    timeoutMs: 4000,
+    lang: undefined,
+  };
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--verbose') {
+      flags.verbose = true;
+      continue;
+    }
+    if (arg === '--json') {
+      flags.json = true;
+      continue;
+    }
+    if (arg === '--no-remote') {
+      flags.remote = false;
+      continue;
+    }
+    if (arg === '--timeout') {
+      const next = argv[index + 1];
+      if (next) {
+        flags.timeoutMs = Number(next);
+        index += 1;
+      }
+      continue;
+    }
+    if (arg === '--lang') {
+      const next = argv[index + 1];
+      if (next) {
+        flags.lang = next;
+        index += 1;
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+
+  const command = positionals[0] ?? 'doctor';
+
+  return { command, flags };
+}
+
+export function buildCli({
+  modules = defaultModules,
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  return {
+    async run(argv = []) {
+      const { command, flags } = normalizeArgs(argv);
+      const translator = createTranslator(resolveLocale(flags.lang));
+      flags.lang = translator.locale;
+      const selectedModules = selectModules(
+        modules,
+        command === 'report' ? undefined : command,
+      );
+
+      if (!selectedModules.length) {
+        stderr.write(`Unknown command: ${command}\n`);
+        return 1;
+      }
+
+      const report = await createDoctorReport({
+        modules: selectedModules,
+        context: flags,
+        onProgress(event) {
+          if (flags.json) {
+            return;
+          }
+
+          if (event.type === 'module:start') {
+            const moduleLabel = event.titleKey
+              ? translator.t(event.titleKey)
+              : translator.t(toModuleTitleKey(event.moduleId));
+            stdout.write(`${translator.t('ui.progress.runningChecks', { moduleId: moduleLabel })}\n`);
+          }
+        },
+      });
+
+      const payload = flags.json || command === 'report'
+        ? renderJsonReport(report, { ...flags, t: translator.t })
+        : renderHumanReport(report, { ...flags, t: translator.t });
+
+      stdout.write(payload);
+      if (!payload.endsWith('\n')) {
+        stdout.write('\n');
+      }
+
+      return report.overallRiskLevel === 'high' ? 2 : 0;
+    },
+  };
+}

package/src/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import { cac } from 'cac';
+
+import { buildCli } from './cli-app.js';
+import { createTranslator, resolveLocale } from './i18n.js';
+
+function parseRequestedLang(argv) {
+  const index = argv.indexOf('--lang');
+  if (index >= 0 && argv[index + 1]) {
+    return argv[index + 1];
+  }
+  return undefined;
+}
+
+const translator = createTranslator(resolveLocale(parseRequestedLang(process.argv.slice(2))));
+const cli = cac('cc-env-checker');
+const app = buildCli();
+
+function registerCommand(name) {
+  cli
+    .command(name, translator.t(`cli.description.${name}`))
+    .option('--verbose', translator.t('cli.option.verbose'))
+    .option('--json', translator.t('cli.option.json'))
+    .option('--lang <locale>', translator.t('cli.option.lang'))
+    .option('--no-remote', translator.t('cli.option.noRemote'))
+    .option('--timeout <ms>', translator.t('cli.option.timeout'), {
+      default: 4000,
+    })
+    .action(async (options) => {
+      const args = [name];
+      if (options.verbose) args.push('--verbose');
+      if (options.json) args.push('--json');
+      if (options.lang) args.push('--lang', String(options.lang));
+      if (options.remote === false) args.push('--no-remote');
+      if (options.timeout) args.push('--timeout', String(options.timeout));
+      const exitCode = await app.run(args);
+      process.exitCode = exitCode;
+    });
+}
+
+registerCommand('doctor');
+registerCommand('network');
+registerCommand('runtime');
+registerCommand('install');
+registerCommand('config');
+registerCommand('report');
+
+cli.help();
+cli.parse();

package/src/doctor.js

@@ -0,0 +1,67 @@
+import {
+  aggregateOverallRiskLevel,
+  buildCoverageMatrix,
+  buildRecommendedActions,
+  rankFindings,
+  summarizeEvidence,
+  summarizeModule,
+} from './report.js';
+
+export async function createDoctorReport({ modules, context, onProgress }) {
+  const moduleReports = [];
+  const allChecks = [];
+
+  for (const module of modules) {
+    onProgress?.({
+      type: 'module:start',
+      moduleId: module.id,
+      title: module.title,
+      ...(module.titleKey ? { titleKey: module.titleKey } : {}),
+    });
+    const checks = await module.run(context);
+    const moduleSummary = summarizeModule(module.id, checks);
+    moduleReports.push({
+      id: module.id,
+      title: module.title,
+      titleKey: module.titleKey,
+      ...moduleSummary,
+    });
+    allChecks.push(...checks);
+    onProgress?.({
+      type: 'module:finish',
+      moduleId: module.id,
+      title: module.title,
+      ...(module.titleKey ? { titleKey: module.titleKey } : {}),
+      riskLevel: moduleSummary.riskLevel,
+      status: moduleSummary.status,
+    });
+  }
+
+  const topFindings = rankFindings(allChecks).slice(0, 5);
+  const highRiskCount = allChecks.filter((check) => check.riskLevel === 'high').length;
+  const mediumRiskCount = allChecks.filter((check) => check.riskLevel === 'medium').length;
+  const actionableCount = allChecks.filter((check) => check.status === 'warn' || check.status === 'fail').length;
+
+  return {
+    generatedAt: new Date().toISOString(),
+    overallRiskLevel: aggregateOverallRiskLevel(allChecks),
+    summary: {
+      moduleCount: moduleReports.length,
+      checkCount: allChecks.length,
+      highRiskCount,
+      mediumRiskCount,
+      actionableCount,
+    },
+    modules: moduleReports,
+    topFindings,
+    recommendedActions: buildRecommendedActions(topFindings),
+    articleModel: 'claude-code-client-risk-v1',
+    evidenceSummary: summarizeEvidence(allChecks),
+    coverageMatrix: buildCoverageMatrix(allChecks),
+    context: {
+      remote: context.remote,
+      timeoutMs: context.timeoutMs,
+      verbose: context.verbose,
+    },
+  };
+}