cc-env-checker 0.1.0

package/README.md

@@ -0,0 +1,413 @@
+# cc-env-checker
+
+[中文](#中文) | [English](#english)
+
+`cc-env-checker` is a CLI for checking Claude Code environment risk and health. It is intended as a reference analysis tool, not a 100% authoritative detector.
+
+`cc-env-checker` 是一个用于检查 Claude Code 环境风险与健康状态的 CLI。它的定位是参考分析工具，不应被当成百分百准确的判定器。
+
+## 中文
+
+### 这是什么
+
+`cc-env-checker` 用于帮助你快速判断当前机器上的 Claude Code 运行环境是否存在明显风险或异常，例如：
+
+- Node.js / npm 运行环境是否满足要求
+- `claude` 命令是否可用
+- Claude 本地配置和数据目录是否存在
+- 网络连通性、DNS、代理配置是否异常
+- 是否存在可观察到的本地痕迹、指纹信号和静态安装特征
+
+它不会替你修复问题，但会把风险按 `low`、`medium`、`high`、`unknown` 分级，并输出推荐动作。
+
+### 功能概览
+
+- 环境健康检查：Node.js、npm、PATH、代理、DNS、外网探测
+- 安装状态检查：`claude --version`、`claude --help`
+- 配置检查：`~/.claude.json`、`~/.claude`、`NO_PROXY`
+- 本地痕迹检查：telemetry、projects、credentials 文件存在性
+- 指纹信号检查：CI、SSH、tmux、screen、TTY、IDE、git remote 类型、运行时清单
+- 静态安装分析：从本地 Claude 安装文本中提取 endpoint / header / event 分组信号
+- 聚合报告：整体风险、重点发现、建议动作、`evidenceSummary`、`coverageMatrix`
+
+### 环境要求
+
+- Node.js `>=20`
+- npm
+
+说明：
+
+- 这个工具本身通过 Node.js 运行，见 [package.json](./package.json) 中的 `engines.node`
+- 不要求你必须已经安装 Claude Code，但如果没有安装，相关检查会返回 `fail`、`warn` 或 `skip`
+
+### 安装
+
+全局安装：
+
+```bash
+npm install -g cc-env-checker
+```
+
+在仓库内本地运行：
+
+```bash
+npm install
+node ./src/cli.js doctor
+```
+
+### 卸载
+
+当前没有单独的 CLI 卸载命令，使用 npm 的标准卸载方式：
+
+```bash
+npm uninstall -g cc-env-checker
+```
+
+### 命令
+
+当前实际暴露的命令如下：
+
+```bash
+cc-env-checker doctor
+cc-env-checker network
+cc-env-checker runtime
+cc-env-checker install
+cc-env-checker config
+cc-env-checker report
+```
+
+说明：
+
+- `doctor` 会运行全部检查模块
+- `report` 会输出完整 JSON 报告
+- `artifacts`、`fingerprint`、`static-install` 当前会包含在 `doctor` / `report` 的聚合结果里，但不是独立子命令
+
+### 常用示例
+
+```bash
+cc-env-checker doctor
+cc-env-checker doctor --lang zh-CN
+cc-env-checker doctor --lang en --verbose
+cc-env-checker network --json
+cc-env-checker report
+```
+
+### 输出语言如何实现
+
+CLI 输出已经内建双语能力，目前支持：
+
+- `zh-CN`
+- `en`
+
+实现方式：
+
+- 默认根据系统语言解析输出语言
+- 可以通过 `--lang zh-CN` 或 `--lang en` 强制指定
+- 所有文案由 `src/i18n.js` 中的字典统一管理
+
+例如：
+
+```bash
+cc-env-checker doctor --lang zh-CN
+cc-env-checker doctor --lang en
+```
+
+### 检测内容
+
+`doctor` / `report` 会聚合以下模块：
+
+- `network`
+  - 外网连通性
+  - 出口 IP 概况
+  - 外部 IP 风险信号
+  - `api.anthropic.com` / `console.anthropic.com` DNS 解析
+  - 代理环境变量一致性
+- `runtime`
+  - Node.js 版本
+  - npm 可用性
+  - PATH 重复项
+- `install`
+  - `claude --version`
+  - `claude --help`
+- `config`
+  - `~/.claude.json`
+  - `~/.claude`
+  - `NO_PROXY`
+- `artifacts`
+  - 身份配置摘要
+  - telemetry 缓存目录
+  - projects 历史目录
+  - credentials 文件存在性
+- `fingerprint`
+  - CI / SSH / tmux / screen / TTY / IDE 信号
+  - 运行时清单：`bun`、`deno`、`npm`、`pnpm`、`yarn`
+  - git remote 的粗粒度类型
+- `static-install`
+  - 本地安装文本中的 endpoint 分组
+  - header 分组
+  - event 名称分组
+
+### 输出格式
+
+输出默认包含：
+
+- 整体风险
+- 生成时间
+- 模块统计
+- 重点发现
+- 覆盖矩阵
+- 依据摘要
+- 每个模块下的检查结果
+- 建议动作
+
+JSON 输出可通过以下方式获得：
+
+```bash
+cc-env-checker doctor --json
+cc-env-checker network --json
+cc-env-checker report
+```
+
+其中 `doctor --json` 和 `report` 会包含：
+
+- `articleModel`
+- `evidenceSummary`
+- `coverageMatrix`
+
+### 参数
+
+```bash
+--lang        指定输出语言，例如 zh-CN 或 en
+--verbose     显示详细依据和观测值
+--json        输出机器可读 JSON
+--no-remote   关闭真实联网探测
+--timeout     设置联网探测超时时间（毫秒）
+```
+
+### 风险等级
+
+- `low`：未发现明显问题，或仅有轻微关注项
+- `medium`：已确认存在可能影响稳定性或一致性的问题
+- `high`：已确认存在关键路径问题，建议优先处理
+- `unknown`：当前证据不足，无法判断
+
+整体风险使用“最高风险项优先”的聚合规则。
+
+### 隐私说明
+
+默认情况下，部分网络检查会访问第三方服务，用于获取公网 IP、网络元数据和外部 IP 风险信号。
+
+- 如不希望执行真实联网探测，请使用 `--no-remote`
+- 敏感本地细节默认不会在普通输出中展开，通常需要 `--verbose` 才会显示更多观测信息
+- 本工具会尽量对身份、邮箱、路径等敏感值做掩码或摘要化处理，但输出结果仍应按诊断信息谨慎对待
+
+### 发布前检查
+
+```bash
+npm test
+npm run pack:check
+```
+
+---
+
+## English
+
+### What It Does
+
+`cc-env-checker` helps you quickly assess whether a machine is ready to run Claude Code safely and predictably. It looks for obvious risks and missing prerequisites such as:
+
+- incompatible Node.js or missing npm
+- missing or broken `claude` command
+- missing Claude config or data directories
+- network, DNS, and proxy issues
+- observable local artifacts, fingerprint signals, and static install indicators
+
+It does not fix issues automatically. It classifies findings as `low`, `medium`, `high`, or `unknown` and returns recommended actions.
+
+### Feature Summary
+
+- Environment health checks: Node.js, npm, PATH, proxy, DNS, remote probes
+- Install checks: `claude --version`, `claude --help`
+- Config checks: `~/.claude.json`, `~/.claude`, `NO_PROXY`
+- Local artifact checks: telemetry, projects, credentials-file presence
+- Fingerprint checks: CI, SSH, tmux, screen, TTY, IDE, git remote type, runtime inventory
+- Static install analysis: endpoint / header / event groups extracted from the local Claude install text
+- Aggregated reporting: overall risk, top findings, recommended actions, `evidenceSummary`, and `coverageMatrix`
+
+### Requirements
+
+- Node.js `>=20`
+- npm
+
+Notes:
+
+- The CLI itself runs on Node.js. See `engines.node` in [package.json](./package.json)
+- Claude Code is not a hard prerequisite for running this tool, but Claude-related checks will return `fail`, `warn`, or `skip` if Claude is not installed
+
+### Install
+
+Install globally:
+
+```bash
+npm install -g cc-env-checker
+```
+
+Run locally inside the repo:
+
+```bash
+npm install
+node ./src/cli.js doctor
+```
+
+### Uninstall
+
+There is no dedicated uninstall subcommand. Use standard npm uninstall:
+
+```bash
+npm uninstall -g cc-env-checker
+```
+
+### Commands
+
+These are the currently exposed CLI commands:
+
+```bash
+cc-env-checker doctor
+cc-env-checker network
+cc-env-checker runtime
+cc-env-checker install
+cc-env-checker config
+cc-env-checker report
+```
+
+Notes:
+
+- `doctor` runs all check modules
+- `report` prints the full JSON report
+- `artifacts`, `fingerprint`, and `static-install` are currently included in aggregated `doctor` / `report` output, but are not registered as standalone subcommands
+
+### Examples
+
+```bash
+cc-env-checker doctor
+cc-env-checker doctor --lang zh-CN
+cc-env-checker doctor --lang en --verbose
+cc-env-checker network --json
+cc-env-checker report
+```
+
+### How Multilingual Output Works
+
+The CLI already supports two output locales:
+
+- `zh-CN`
+- `en`
+
+Implementation details:
+
+- output language defaults to system locale detection
+- you can override it with `--lang zh-CN` or `--lang en`
+- all user-facing strings are managed in `src/i18n.js`
+
+Examples:
+
+```bash
+cc-env-checker doctor --lang zh-CN
+cc-env-checker doctor --lang en
+```
+
+### What It Checks
+
+`doctor` / `report` aggregate the following modules:
+
+- `network`
+  - internet connectivity
+  - egress IP profile
+  - external IP risk signal
+  - DNS resolution for `api.anthropic.com` / `console.anthropic.com`
+  - proxy environment consistency
+- `runtime`
+  - Node.js version
+  - npm availability
+  - duplicate PATH entries
+- `install`
+  - `claude --version`
+  - `claude --help`
+- `config`
+  - `~/.claude.json`
+  - `~/.claude`
+  - `NO_PROXY`
+- `artifacts`
+  - identity config summary
+  - telemetry cache directory
+  - projects history directory
+  - credentials-file presence
+- `fingerprint`
+  - CI / SSH / tmux / screen / TTY / IDE signals
+  - runtime inventory: `bun`, `deno`, `npm`, `pnpm`, `yarn`
+  - coarse git remote transport type
+- `static-install`
+  - endpoint groups in local install text
+  - header groups
+  - event-name groups
+
+### Output
+
+output includes:
+
+- overall risk
+- generated time
+- module statistics
+- top findings
+- coverage matrix
+- evidence summary
+- per-module check results
+- recommended actions
+
+You can get JSON output with:
+
+```bash
+cc-env-checker doctor --json
+cc-env-checker network --json
+cc-env-checker report
+```
+
+`doctor --json` and `report` include:
+
+- `articleModel`
+- `evidenceSummary`
+- `coverageMatrix`
+
+### Options
+
+```bash
+--lang        override output language, e.g. zh-CN or en
+--verbose     show detailed evidence and observations
+--json        print machine-readable JSON
+--no-remote   disable live remote probes
+--timeout     set remote probe timeout in milliseconds
+```
+
+### Risk Levels
+
+- `low`: no obvious issue, or only minor concerns
+- `medium`: a confirmed issue that may affect stability or consistency
+- `high`: a confirmed issue on a critical path that should be addressed first
+- `unknown`: not enough evidence to decide
+
+Overall risk follows a highest-finding-wins rule.
+
+### Privacy Notes
+
+By default, some network checks contact third-party services to inspect public IP metadata and external IP risk hints.
+
+- use `--no-remote` to disable live remote probes
+- sensitive local details are generally hidden from normal output and are more likely to appear only with `--verbose`
+- the tool tries to mask or summarize sensitive values such as identity fields, email, and paths, but diagnostic output should still be handled carefully
+
+### Release Checks
+
+```bash
+npm test
+npm run pack:check
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cc-env-checker",
+  "version": "0.1.0",
+  "description": "Claude Code environment risk checker CLI",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "cli",
+    "diagnostics",
+    "environment",
+    "network",
+    "npm-package"
+  ],
+  "type": "module",
+  "bin": {
+    "cc-env-checker": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node ./src/cli.js",
+    "doctor": "node ./src/cli.js doctor",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "cac": "^6.7.14"
+  }
+}