cc-env-checker 0.1.0

package/src/checks/artifacts.js

@@ -0,0 +1,318 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createCheckResult, maskValue, safeReadJson, summarizeDirectory } from './helpers.js';
+
+async function defaultStatMtime(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return {
+      ok: true,
+      mtime: stat.mtime.toISOString(),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      code: error.code,
+      message: error.message,
+    };
+  }
+}
+
+function buildMtimeDetail(statResult) {
+  if (!statResult.ok) {
+    return null;
+  }
+
+  return `mtime=${statResult.mtime}`;
+}
+
+function summarizeHomeArtifactPath(segment) {
+  return `path=${path.posix.join('~', String(segment))}`;
+}
+
+function summarizeClaudeArtifactPath(...segments) {
+  return `path=${path.posix.join('~', '.claude', ...segments.map((segment) => String(segment)))}`;
+}
+
+function isMissingError(result) {
+  return Boolean(result && !result.ok && result.code === 'ENOENT');
+}
+
+function buildIdentityDetails({
+  configResult,
+  mtimeResult,
+}) {
+  if (!configResult.ok) {
+    return [
+      summarizeHomeArtifactPath('.claude.json'),
+      `error=${configResult.code ?? 'unavailable'}`,
+    ];
+  }
+
+  const details = [
+    summarizeHomeArtifactPath('.claude.json'),
+    `keys=${Object.keys(configResult.data ?? {}).length}`,
+    `userID=${configResult.data?.userID ? 'present' : 'absent'}`,
+    `accountUuid=${configResult.data?.accountUuid ? maskValue(configResult.data.accountUuid) : 'absent'}`,
+    `email=${configResult.data?.email ? maskValue(configResult.data.email, { start: 2, end: 10 }) : 'absent'}`,
+  ];
+
+  const mtimeDetail = buildMtimeDetail(mtimeResult);
+  if (mtimeDetail) {
+    details.push(mtimeDetail);
+  }
+
+  return details;
+}
+
+function buildDirectoryDetails({
+  dirLabel,
+  summaryResult,
+  mtimeResult,
+}) {
+  if (!summaryResult.ok) {
+    return [
+      summarizeClaudeArtifactPath(dirLabel),
+      `error=${summaryResult.code ?? 'unavailable'}`,
+    ];
+  }
+
+  const details = [
+    summarizeClaudeArtifactPath(dirLabel),
+    `entries=${summaryResult.entryCount}`,
+  ];
+
+  if ((summaryResult.sample ?? []).length > 0) {
+    details.push(`sampleCount=${summaryResult.sample.length}`);
+  }
+
+  const mtimeDetail = buildMtimeDetail(mtimeResult);
+  if (mtimeDetail) {
+    details.push(mtimeDetail);
+  }
+
+  return details;
+}
+
+function hasNonMissingProbeFailure(result) {
+  return Boolean(result && !result.ok && result.code && result.code !== 'ENOENT');
+}
+
+function hasMissingProbe(result) {
+  return isMissingError(result);
+}
+
+function buildCredentialsDetails({
+  credentialsPath,
+  present,
+  readResult,
+  mtimeResult,
+}) {
+  if (!present) {
+    const errorDetails = [];
+    if (hasNonMissingProbeFailure(readResult)) {
+      errorDetails.push(`readError=${readResult.code}`);
+    }
+    if (hasNonMissingProbeFailure(mtimeResult)) {
+      errorDetails.push(`statError=${mtimeResult.code}`);
+    }
+    if (errorDetails.length) {
+      return [credentialsPath, ...errorDetails];
+    }
+
+    return [credentialsPath, 'credentials-file=absent'];
+  }
+
+  const details = [credentialsPath, 'credentials-file=present'];
+  const mtimeDetail = buildMtimeDetail(mtimeResult);
+  if (mtimeDetail) {
+    details.push(mtimeDetail);
+  }
+
+  return details;
+}
+
+function resolveDirectoryState(summaryResult) {
+  if (summaryResult.ok) {
+    return {
+      status: 'pass',
+      riskLevel: summaryResult.entryCount > 0 ? 'low' : 'low',
+      evidenceType: 'observed',
+      summaryKey: 'check.artifacts.projects.summary.pass',
+      suggestionKey: 'check.artifacts.projects.suggestion.review',
+    };
+  }
+
+  if (hasNonMissingProbeFailure(summaryResult)) {
+    return {
+      status: 'warn',
+      riskLevel: 'high',
+      evidenceType: 'partial',
+      summaryKey: 'check.artifacts.projects.summary.warn',
+      suggestionKey: 'check.artifacts.projects.suggestion.review',
+    };
+  }
+
+  return {
+    status: 'skip',
+    riskLevel: 'unknown',
+    evidenceType: 'unverifiable',
+    summaryKey: 'check.artifacts.projects.summary.skip',
+    suggestionKey: 'check.artifacts.projects.suggestion.review',
+  };
+}
+
+function resolveCredentialsState({
+  readResult,
+  mtimeResult,
+}) {
+  if (readResult.ok || mtimeResult.ok) {
+    return {
+      status: 'warn',
+      riskLevel: 'high',
+      evidenceType: 'observed',
+      summaryKey: 'check.artifacts.credentials.summary.warn',
+      suggestionKey: 'check.artifacts.credentials.suggestion.warn',
+      present: true,
+    };
+  }
+
+  if (hasNonMissingProbeFailure(readResult) || hasNonMissingProbeFailure(mtimeResult)) {
+    return {
+      status: 'warn',
+      riskLevel: 'high',
+      evidenceType: 'partial',
+      summaryKey: 'check.artifacts.credentials.summary.warn',
+      suggestionKey: 'check.artifacts.credentials.suggestion.warn',
+      present: false,
+    };
+  }
+
+  if (hasMissingProbe(readResult) && hasMissingProbe(mtimeResult)) {
+    return {
+      status: 'pass',
+      riskLevel: 'low',
+      evidenceType: 'partial',
+      summaryKey: 'check.artifacts.credentials.summary.pass',
+      suggestionKey: 'check.common.noAction',
+      present: false,
+    };
+  }
+
+  return {
+    status: 'warn',
+    riskLevel: 'high',
+    evidenceType: 'partial',
+    summaryKey: 'check.artifacts.credentials.summary.warn',
+    suggestionKey: 'check.artifacts.credentials.suggestion.warn',
+    present: false,
+  };
+}
+
+export function createArtifactsModule({
+  homeDir = os.homedir(),
+  safeReadJson: readJson = safeReadJson,
+  summarizeDirectory: summarizeDir = summarizeDirectory,
+  statMtime = defaultStatMtime,
+} = {}) {
+  const claudeJsonPath = path.join(homeDir, '.claude.json');
+  const claudeDir = path.join(homeDir, '.claude');
+  const telemetryDir = path.join(claudeDir, 'telemetry');
+  const projectsDir = path.join(claudeDir, 'projects');
+  const credentialsPath = path.join(claudeDir, '.credentials.json');
+
+  return {
+    id: 'artifacts',
+    titleKey: 'module.artifacts',
+    async run() {
+      const configResult = await readJson(claudeJsonPath);
+      const telemetryResult = await summarizeDir(telemetryDir);
+      const projectsResult = await summarizeDir(projectsDir);
+      const credentialsResult = await readJson(credentialsPath);
+
+      const [configMtime, telemetryMtime, projectsMtime, credentialsMtime] = await Promise.all([
+        statMtime(claudeJsonPath),
+        statMtime(telemetryDir),
+        statMtime(projectsDir),
+        statMtime(credentialsPath),
+      ]);
+      const credentialsState = resolveCredentialsState({
+        readResult: credentialsResult,
+        mtimeResult: credentialsMtime,
+      });
+
+      return [
+        createCheckResult({
+          id: 'artifacts.identity-summary',
+          titleKey: 'check.artifacts.identity.title',
+          status: configResult.ok ? 'pass' : 'warn',
+          riskLevel: configResult.ok ? 'low' : 'medium',
+          evidenceType: configResult.ok ? 'observed' : 'partial',
+          source: 'local-file',
+          summaryKey: configResult.ok
+            ? 'check.artifacts.identity.summary.pass'
+            : 'check.artifacts.identity.summary.warn',
+          details: buildIdentityDetails({
+            configResult,
+            mtimeResult: configMtime,
+          }),
+          suggestionKey: configResult.ok
+            ? 'check.common.noAction'
+            : 'check.artifacts.identity.suggestion.warn',
+        }),
+        createCheckResult({
+          id: 'artifacts.telemetry-cache',
+          titleKey: 'check.artifacts.telemetry.title',
+          status: telemetryResult.ok ? 'pass' : 'warn',
+          riskLevel: telemetryResult.ok && telemetryResult.entryCount > 0 ? 'medium' : 'low',
+          evidenceType: telemetryResult.ok ? 'observed' : 'partial',
+          source: 'local-file',
+          summaryKey: telemetryResult.ok
+            ? 'check.artifacts.telemetry.summary.pass'
+            : 'check.artifacts.telemetry.summary.warn',
+          details: buildDirectoryDetails({
+            dirLabel: 'telemetry',
+            summaryResult: telemetryResult,
+            mtimeResult: telemetryMtime,
+          }),
+          suggestionKey: 'check.artifacts.telemetry.suggestion.review',
+        }),
+        createCheckResult({
+          id: 'artifacts.projects-history',
+          titleKey: 'check.artifacts.projects.title',
+          status: resolveDirectoryState(projectsResult).status,
+          riskLevel: resolveDirectoryState(projectsResult).riskLevel,
+          evidenceType: resolveDirectoryState(projectsResult).evidenceType,
+          source: 'local-file',
+          summaryKey: resolveDirectoryState(projectsResult).summaryKey,
+          details: buildDirectoryDetails({
+            dirLabel: 'projects',
+            summaryResult: projectsResult,
+            mtimeResult: projectsMtime,
+          }),
+          suggestionKey: resolveDirectoryState(projectsResult).suggestionKey,
+        }),
+        createCheckResult({
+          id: 'artifacts.credentials-file',
+          titleKey: 'check.artifacts.credentials.title',
+          status: credentialsState.status,
+          riskLevel: credentialsState.riskLevel,
+          evidenceType: credentialsState.evidenceType,
+          source: 'local-file',
+          summaryKey: credentialsState.summaryKey,
+          details: buildCredentialsDetails({
+            credentialsPath: summarizeClaudeArtifactPath('.credentials.json'),
+            present: credentialsState.present,
+            readResult: credentialsResult,
+            mtimeResult: credentialsMtime,
+          }),
+          suggestionKey: credentialsState.suggestionKey,
+        }),
+      ];
+    },
+  };
+}
+
+export const artifactsModule = createArtifactsModule();

package/src/checks/config.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createCheckResult } from './helpers.js';
+
+const CLAUDE_CONFIG_PATH = path.join(os.homedir(), '.claude.json');
+const CLAUDE_DIR_PATH = path.join(os.homedir(), '.claude');
+
+async function checkClaudeConfigPresence() {
+  try {
+    const content = await fs.readFile(CLAUDE_CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(content);
+
+    const details = [
+      `path=${CLAUDE_CONFIG_PATH}`,
+      `keys=${Object.keys(parsed).length}`,
+    ];
+
+    return createCheckResult({
+      id: 'config.claude-json',
+      titleKey: 'check.config.json.title',
+      status: 'pass',
+      riskLevel: 'low',
+      evidenceType: 'observed',
+      source: 'local',
+      summaryKey: 'check.config.json.summary.pass',
+      details,
+      suggestionKey: 'check.common.noAction',
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return createCheckResult({
+        id: 'config.claude-json',
+        titleKey: 'check.config.json.title',
+        status: 'warn',
+        riskLevel: 'medium',
+        evidenceType: 'observed',
+        source: 'local',
+        summaryKey: 'check.config.json.summary.missing',
+        details: [`path=${CLAUDE_CONFIG_PATH}`],
+        suggestionKey: 'check.config.json.suggestion.missing',
+      });
+    }
+
+    return createCheckResult({
+      id: 'config.claude-json',
+      titleKey: 'check.config.json.title',
+      status: 'fail',
+      riskLevel: 'high',
+      evidenceType: 'observed',
+      source: 'local',
+      summaryKey: 'check.config.json.summary.fail',
+      details: [error.message],
+      suggestionKey: 'check.config.json.suggestion.fail',
+    });
+  }
+}
+
+async function checkClaudeDirectory() {
+  try {
+    const stat = await fs.stat(CLAUDE_DIR_PATH);
+    if (!stat.isDirectory()) {
+      return createCheckResult({
+        id: 'config.claude-dir',
+        titleKey: 'check.config.dir.title',
+        status: 'fail',
+        riskLevel: 'high',
+        evidenceType: 'observed',
+        source: 'local',
+        summaryKey: 'check.config.dir.summary.invalid',
+        details: [`path=${CLAUDE_DIR_PATH}`],
+        suggestionKey: 'check.config.dir.suggestion.invalid',
+      });
+    }
+
+    const entries = await fs.readdir(CLAUDE_DIR_PATH);
+    return createCheckResult({
+      id: 'config.claude-dir',
+      titleKey: 'check.config.dir.title',
+      status: 'pass',
+      riskLevel: 'low',
+      evidenceType: 'observed',
+      source: 'local',
+      summaryKey: 'check.config.dir.summary.pass',
+      details: [`path=${CLAUDE_DIR_PATH}`, `entries=${entries.length}`],
+      suggestionKey: 'check.common.noAction',
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return createCheckResult({
+        id: 'config.claude-dir',
+        titleKey: 'check.config.dir.title',
+        status: 'warn',
+        riskLevel: 'medium',
+        evidenceType: 'observed',
+        source: 'local',
+        summaryKey: 'check.config.dir.summary.missing',
+        details: [`path=${CLAUDE_DIR_PATH}`],
+        suggestionKey: 'check.config.dir.suggestion.missing',
+      });
+    }
+
+    return createCheckResult({
+      id: 'config.claude-dir',
+      titleKey: 'check.config.dir.title',
+      status: 'fail',
+      riskLevel: 'high',
+      evidenceType: 'observed',
+      source: 'local',
+      summaryKey: 'check.config.dir.summary.fail',
+      details: [error.message],
+      suggestionKey: 'check.config.dir.suggestion.fail',
+    });
+  }
+}
+
+function checkProxyNoProxyRelationship() {
+  const noProxy = process.env.NO_PROXY;
+
+  if (!noProxy) {
+    return createCheckResult({
+      id: 'config.no-proxy',
+      titleKey: 'check.config.noProxy.title',
+      status: 'pass',
+      riskLevel: 'low',
+      evidenceType: 'observed',
+      source: 'local',
+      summaryKey: 'check.config.noProxy.summary.unset',
+      details: ['NO_PROXY=unset'],
+      suggestionKey: 'check.config.noProxy.suggestion.unset',
+    });
+  }
+
+  const entries = noProxy.split(',').map((entry) => entry.trim()).filter(Boolean);
+
+  if (!entries.length) {
+    return createCheckResult({
+      id: 'config.no-proxy',
+      titleKey: 'check.config.noProxy.title',
+      status: 'warn',
+      riskLevel: 'medium',
+      evidenceType: 'observed',
+      source: 'local',
+      summaryKey: 'check.config.noProxy.summary.empty',
+      details: [`NO_PROXY=${noProxy}`],
+      suggestionKey: 'check.config.noProxy.suggestion.empty',
+    });
+  }
+
+  return createCheckResult({
+    id: 'config.no-proxy',
+    titleKey: 'check.config.noProxy.title',
+    status: 'pass',
+    riskLevel: 'low',
+    evidenceType: 'observed',
+    source: 'local',
+    summaryKey: 'check.config.noProxy.summary.pass',
+    details: entries.slice(0, 5).map((entry) => `entry=${entry}`),
+    suggestionKey: 'check.config.noProxy.suggestion.pass',
+  });
+}
+
+export const configModule = {
+  id: 'config',
+  titleKey: 'module.config',
+  async run() {
+    return [
+      await checkClaudeConfigPresence(),
+      await checkClaudeDirectory(),
+      checkProxyNoProxyRelationship(),
+    ];
+  },
+};

package/src/checks/fingerprint.js

@@ -0,0 +1,192 @@
+import process from 'node:process';
+
+import { createCheckResult, runtimeSnapshot, tryExec } from './helpers.js';
+
+const INVENTORY_COMMANDS = ['bun', 'deno', 'npm', 'pnpm', 'yarn'];
+const FALSEY_ENV_VALUES = new Set(['false', '0', 'no', 'off']);
+
+function isTruthyEnvFlag(value) {
+  if (value === undefined || value === null) {
+    return false;
+  }
+
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+
+  return !FALSEY_ENV_VALUES.has(normalized);
+}
+
+function detectIde(env) {
+  if (isTruthyEnvFlag(env.CURSOR_TRACE_ID)) {
+    return 'cursor';
+  }
+
+  if (isTruthyEnvFlag(env.VSCODE_GIT_IPC_HANDLE) || isTruthyEnvFlag(env.VSCODE_IPC_HOOK_CLI) || String(env.TERM_PROGRAM ?? '').toLowerCase() === 'vscode') {
+    return 'vscode';
+  }
+
+  if (isTruthyEnvFlag(env.JETBRAINS_IDE) || isTruthyEnvFlag(env.IDEA_INITIAL_DIRECTORY) || isTruthyEnvFlag(env.PYCHARM_HOSTED)) {
+    return 'jetbrains';
+  }
+
+  return 'unknown';
+}
+
+function summarizeGitRemote(result) {
+  if (!result.ok || !result.stdout) {
+    return 'unavailable';
+  }
+
+  const remote = String(result.stdout).trim().toLowerCase();
+  if (remote.startsWith('git@') || remote.startsWith('ssh://')) {
+    return 'present:ssh';
+  }
+
+  if (remote.startsWith('https://') || remote.startsWith('http://')) {
+    return 'present:https';
+  }
+
+  if (remote.startsWith('file://')) {
+    return 'present:file';
+  }
+
+  return 'present:other';
+}
+
+function formatBooleanDetail(key, value) {
+  return `${key}=${Boolean(value)}`;
+}
+
+function summarizeRuntimeSnapshot() {
+  return runtimeSnapshot().filter((entry) => !entry.startsWith('hostname='));
+}
+
+async function probeRuntimeVersion(command, exec) {
+  const result = await exec(command, ['--version']);
+  if (!result.ok || !result.stdout) {
+    return `${command}=absent`;
+  }
+
+  const firstLine = String(result.stdout).split(/\r?\n/, 1)[0].trim();
+  const versionToken = firstLine.match(/v?\d+(?:\.\d+){0,3}(?:[-+][0-9A-Za-z.-]+)?/);
+
+  if (versionToken) {
+    return `${command}=present:${versionToken[0]}`;
+  }
+
+  return `${command}=present`;
+}
+
+async function buildRuntimeInventory(exec) {
+  const details = [`node=${process.version}`];
+  const probes = await Promise.all(INVENTORY_COMMANDS.map((command) => probeRuntimeVersion(command, exec)));
+  details.push(...probes);
+  return details;
+}
+
+async function buildGitRemoteSummary(exec) {
+  const result = await exec('git', ['remote', 'get-url', 'origin']);
+  return summarizeGitRemote(result);
+}
+
+function buildEnvironmentDetails({
+  env,
+  isTTY,
+  gitRemoteSummary,
+}) {
+  return [
+    ...summarizeRuntimeSnapshot(),
+    formatBooleanDetail('ci', isTruthyEnvFlag(env.CI)),
+    formatBooleanDetail('ssh', isTruthyEnvFlag(env.SSH_CONNECTION) || isTruthyEnvFlag(env.SSH_CLIENT) || isTruthyEnvFlag(env.SSH_TTY)),
+    formatBooleanDetail('tmux', isTruthyEnvFlag(env.TMUX)),
+    formatBooleanDetail('screen', isTruthyEnvFlag(env.STY)),
+    formatBooleanDetail('tty', isTTY),
+    `ide=${detectIde(env)}`,
+    `gitRemote=${gitRemoteSummary}`,
+  ];
+}
+
+function hasAutomationSignals(env) {
+  return isTruthyEnvFlag(env.CI)
+    || isTruthyEnvFlag(env.SSH_CONNECTION)
+    || isTruthyEnvFlag(env.SSH_CLIENT)
+    || isTruthyEnvFlag(env.SSH_TTY)
+    || isTruthyEnvFlag(env.TMUX)
+    || isTruthyEnvFlag(env.STY);
+}
+
+function resolveEnvironmentRisk(env) {
+  if (isTruthyEnvFlag(env.SSH_CONNECTION) || isTruthyEnvFlag(env.SSH_CLIENT) || isTruthyEnvFlag(env.SSH_TTY)) {
+    return {
+      status: 'warn',
+      riskLevel: 'high',
+    };
+  }
+
+  if (isTruthyEnvFlag(env.CI) || isTruthyEnvFlag(env.TMUX) || isTruthyEnvFlag(env.STY)) {
+    return {
+      status: 'warn',
+      riskLevel: 'medium',
+    };
+  }
+
+  return {
+    status: 'pass',
+    riskLevel: 'low',
+  };
+}
+
+export function createFingerprintModule({
+  env = process.env,
+  isTTY = Boolean(process.stdout.isTTY),
+  tryExec: exec = tryExec,
+} = {}) {
+  return {
+    id: 'fingerprint',
+    titleKey: 'module.fingerprint',
+    async run() {
+      const [runtimeDetails, gitRemoteHash] = await Promise.all([
+        buildRuntimeInventory(exec),
+        buildGitRemoteSummary(exec),
+      ]);
+      const environmentDetails = buildEnvironmentDetails({
+        env,
+        isTTY,
+        gitRemoteSummary: gitRemoteHash,
+      });
+      const environmentRisk = resolveEnvironmentRisk(env);
+      const environmentSummaryKey = environmentRisk.status === 'warn'
+        ? 'check.fingerprint.environment.summary.warn'
+        : 'check.fingerprint.environment.summary.pass';
+
+      return [
+        createCheckResult({
+          id: 'fingerprint.environment-signals',
+          titleKey: 'check.fingerprint.environment.title',
+          status: environmentRisk.status,
+          riskLevel: environmentRisk.riskLevel,
+          evidenceType: 'observed',
+          source: 'runtime-env',
+          summaryKey: environmentSummaryKey,
+          details: environmentDetails,
+          suggestionKey: 'check.fingerprint.environment.suggestion.review',
+        }),
+        createCheckResult({
+          id: 'fingerprint.runtime-inventory',
+          titleKey: 'check.fingerprint.runtime.title',
+          status: 'pass',
+          riskLevel: 'low',
+          evidenceType: 'observed',
+          source: 'runtime-env',
+          summaryKey: 'check.fingerprint.runtime.summary.pass',
+          details: runtimeDetails,
+          suggestionKey: hasAutomationSignals(env) ? 'check.fingerprint.runtime.suggestion.review' : 'check.common.noAction',
+        }),
+      ];
+    },
+  };
+}
+
+export const fingerprintModule = createFingerprintModule();