@aiti-ai/aiti-cmd 0.0.0-stage → 0.1.9

package/AGENTS.md

@@ -0,0 +1,28 @@
+# aiti-cmd 扩展（部署目录直改指南）
+
+## 结构
+- 运行时文件平铺在本目录根（index.ts / core.cjs …，宿主 loader 按相对路径加载——**禁手改运行时平铺文件**，改 src/ 再 build）
+- `src/` 源码（client/src + 服务端 ts/cjs）· `dist/` 构建产物（禁手改）· `tools/` 构建/部署脚本
+- npm 包形态的扩展：本目录 package.json 含 version 与 aitiConfigs 声明
+
+## 小改现场流程（改文案/样式/小逻辑）
+1. 改 `src/` 下对应源码
+2. `node tools/build.mjs`（client 有构建产物的扩展；纯服务端改动跳过）
+3. `curl -X POST http://127.0.0.1:3001/api/extensions/reload`（dev；prod 3002；外部经 nginx 带 basePath：/dev、/mac、/mdev、/win、/wdev → `/xxx/api/extensions/reload`）
+4. 浏览器刷新页面验证
+
+## 大改回源码仓
+- 源码仓：`extensions/aiti-cmd/`（git 管理，deploy 同步回本目录）
+- 改完在源码仓跑 `node tools/deploy.mjs`（或仓库根 `node scripts/deploy-all.mjs --only aiti-cmd`）
+
+## 数据目录（数据分层：config / cache）
+- `ctx.configDir` 根级 = 配置与关键小状态（aiti-configs 备份范围；小、珍贵、人可读）
+- `ctx.cacheDir`（= `<configDir>/cache/`）= 可删缓存：db/venv/日志/大文件；rm -rf 后扩展下次访问自动重建
+- `ctx.dataDir` 已移除（访问即抛）——新代码禁用
+- 本扩展白名单（永不为 cache 的配置文件）见 package.json `aitiConfigs.configFiles`
+
+## 红线
+- 禁轮询（setInterval 拉取）；需要等待用事件/回调/SSE（桥的 SSE、aiti-event-bus topics）
+- 禁重启生产服务（pi-web 3002 等 restart 须用户明确同意）
+- 禁手改 dist/ 与运行时平铺文件；跨扩展通信走 ctx.services（禁 globalThis.__ext 直穿）
+- 服务端：SQLite 一律 WAL + 分批小事务（批间 setImmediate 让步）；禁 execFileSync 调 >1s 外部程序；>8MB 文件禁同步读

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiti-ai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/audit.ts

@@ -0,0 +1,255 @@
+/**
+ * aiti-cmd · 执行审计 —— 仿 pi 的 JSONL 全量留存（安全审计）
+ *
+ * 所有执行逐条 append-only 落盘到 <ctx.cacheDir>/logs/<YYYY-MM-DD>.jsonl（= ~/.pi/web/data/aiti-cmd/cache/logs/），
+ * 按天分片、追加写、历史不可改（权限 600）。输出另存 sidecar 纯文本文件
+ * （去 ANSI；>1MB 截断 + outputTruncated 标记 + 保留尾部）。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+
+/** 日志保留天数（按天分片文件超期清理） */
+const RETENTION_DAYS = parseInt(process.env.AITI_CMD_RETENTION_DAYS || "90", 10) || 90;
+
+export interface AuditRecord {
+  ts: number;
+  id: string;
+  kind: "exec";
+  /** 触发来源——开放语义（aiti-cmd-exec-integration-plan.md §3.1）：新入口可传新值，未知值在
+   *  POST /run 收口为 "unknown"。基线枚举（只作参照不封闭）：
+   *  manual | message | shell | favorite | asr-selfheal | schedule | suggest | ai-helper | codebuddy | service | unknown */
+  source: string;
+  /** true = POST /run 未带 source 被兜底（不再静默吞成 manual，防新入口漏传，§3.1） */
+  sourceDefaulted?: boolean;
+  /** 触发来源：pi 会话 id（消息识别执行时关联） */
+  piSessionId?: string;
+  cwd?: string;
+  /** 完整命令（参数已填充） */
+  cmd: string;
+  /** 参数（运行前填写的占位符值） */
+  params?: Record<string, string>;
+  /** 环境变量名（值不落盘——脱敏） */
+  envNames?: string[];
+  /** 命中危险模式 */
+  danger?: string[];
+  confirm?: boolean;
+  /** 沙箱模式 */
+  sandbox?: string;
+  pid?: number;
+  exit?: number | null;
+  signal?: string | null;
+  durationMs?: number;
+  outBytes?: number;
+  outputTruncated?: boolean;
+  outputFile?: string;
+  /** 哈希链（防篡改）：sha256(prevHash + 本记录无 hash 字段的规范序列化) */
+  hash?: string;
+}
+
+export interface AuditQuery {
+  from?: number;
+  to?: number;
+  source?: string;
+  exit?: string;
+  cmd?: string;
+  limit?: number;
+}
+
+export function createAudit(cacheDir: string) {
+  const logsDir = path.join(cacheDir, "logs");
+  fs.mkdirSync(logsDir, { recursive: true, mode: 0o700 });
+
+  const todayFile = () => path.join(logsDir, new Date().toISOString().slice(0, 10) + ".jsonl");
+
+  // ---- 哈希链（防篡改）：lastHash 在进程内随 append 推进；启动时从现有文件尾部重建 ----
+  let lastHash = "";
+  function rebuildChain() {
+    lastHash = "";
+    for (const f of listFiles()) {
+      try {
+        const lines = fs.readFileSync(path.join(logsDir, f), "utf8").split("\n");
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const rec = JSON.parse(line) as AuditRecord;
+            if (rec.hash) lastHash = rec.hash;
+          } catch { /* skip bad line */ }
+        }
+      } catch { /* skip file */ }
+    }
+  }
+  function chainHash(prev: string, rec: AuditRecord): string {
+    const { hash: _h, ...canon } = rec; // 规范序列化（去掉 hash 自身，防止自引用）
+    return createHash("sha256").update(prev + JSON.stringify(canon)).digest("hex");
+  }
+  rebuildChain();
+
+  function append(rec: AuditRecord) {
+    try {
+      rec.hash = chainHash(lastHash, rec);
+      lastHash = rec.hash;
+      fs.appendFileSync(todayFile(), JSON.stringify(rec) + "\n", { mode: 0o600 });
+    } catch (e) {
+      console.error("[aiti-cmd] audit append failed:", e);
+    }
+  }
+
+  /** 校验哈希链：从第一条带 hash 的记录向后重放；篡改/缺失 → 返回损坏点 */
+  function verify(): { ok: boolean; count: number; legacy: number; brokenAt?: string; checkedHashes: number } {
+    let prev = "";
+    let count = 0, legacy = 0, checked = 0;
+    let brokenAt: string | undefined;
+    for (const f of listFiles()) {
+      try {
+        const lines = fs.readFileSync(path.join(logsDir, f), "utf8").split("\n");
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const rec = JSON.parse(line) as AuditRecord;
+            count++;
+            if (!rec.hash) { legacy++; continue; } // 升级前 legacy 记录不参与校验
+            const expected = chainHash(prev, rec);
+            if (expected !== rec.hash) { brokenAt = rec.id; break; }
+            prev = rec.hash;
+            checked++;
+          } catch { /* skip bad line */ }
+        }
+        if (brokenAt) break;
+      } catch { /* skip file */ }
+    }
+    return { ok: !brokenAt, count, legacy, brokenAt, checkedHashes: checked };
+  }
+
+  /** 保留策略：删除超过保留天数的日志文件（.jsonl + .out.txt），返回删除数 */
+  function cleanupRetention(): number {
+    let removed = 0;
+    const cutoff = Date.now() - RETENTION_DAYS * 24 * 3600 * 1000;
+    try {
+      const files = fs.readdirSync(logsDir);
+      for (const f of files) {
+        // 文件日期：jsonl 取文件名前缀（YYYY-MM-DD）；out.txt 取对应 id 记录的日期（简化：按 mtime）
+        let dateStr: string | null = null;
+        const m = f.match(/^(\d{4}-\d{2}-\d{2})\.jsonl$/);
+        if (m) dateStr = m[1];
+        else {
+          try { dateStr = new Date(fs.statSync(path.join(logsDir, f)).mtime).toISOString().slice(0, 10); } catch { continue; }
+        }
+        const fileTs = Date.parse(dateStr);
+        if (!isNaN(fileTs) && fileTs < cutoff) {
+          try { fs.unlinkSync(path.join(logsDir, f)); removed++; } catch {}
+        }
+      }
+    } catch {}
+    return removed;
+  }
+
+
+  /** 执行输出落盘：去 ANSI 纯文本，>1MB 截断保留尾部（>=MAX 字节则输出尾部 MAX*0.4） */
+  function writeOutput(id: string, raw: string): { outBytes: number; outputTruncated: boolean; outputFile: string } {
+    const clean = stripAnsi(raw);
+    const bytes = Buffer.byteLength(clean, "utf8");
+    const MAX = 1024 * 1024;
+    const outputTruncated = bytes > MAX;
+    const final = outputTruncated ? clean.slice(-Math.floor(MAX * 0.6)) : clean;
+    const outputFile = path.join(logsDir, `${id}.out.txt`);
+    try {
+      fs.writeFileSync(outputFile, final, { mode: 0o600 });
+    } catch (e) {
+      console.error("[aiti-cmd] audit output write failed:", e);
+    }
+    return { outBytes: bytes, outputTruncated, outputFile };
+  }
+
+  function readOutput(id: string): string | null {
+    try {
+      const p = path.join(logsDir, `${id}.out.txt`);
+      if (!fs.existsSync(p)) return null;
+      return fs.readFileSync(p, "utf8");
+    } catch {
+      return null;
+    }
+  }
+
+  function listFiles(): string[] {
+    try {
+      return fs.readdirSync(logsDir).filter((f) => f.endsWith(".jsonl")).sort();
+    } catch {
+      return [];
+    }
+  }
+
+  function query(q: AuditQuery = {}): AuditRecord[] {
+    const out: AuditRecord[] = [];
+    const files = listFiles();
+    for (const f of files) {
+      try {
+        const lines = fs.readFileSync(path.join(logsDir, f), "utf8").split("\n");
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const rec = JSON.parse(line) as AuditRecord;
+            if (q.from && rec.ts < q.from) continue;
+            if (q.to && rec.ts > q.to) continue;
+            if (q.source && rec.source !== q.source) continue;
+            if (q.exit !== undefined && rec.exit !== Number(q.exit)) continue;
+            if (q.cmd && !rec.cmd.includes(q.cmd)) continue;
+            out.push(rec);
+          } catch { /* skip bad line */ }
+        }
+      } catch { /* skip file */ }
+    }
+    out.sort((a, b) => b.ts - a.ts);
+    const limit = Math.min(Math.max(parseInt(String(q.limit || 100), 10) || 100, 1), 1000);
+    return out.slice(0, limit);
+  }
+
+  /** 按 source 汇总（§3.1 /history?groupBy=source 数据源）：全量扫描聚合数量/最近时间/失败率 */
+  function summarizeBySource(): { source: string; count: number; lastTs: number; failCount: number; failRate: number }[] {
+    const acc = new Map<string, { count: number; lastTs: number; failCount: number }>();
+    for (const f of listFiles()) {
+      try {
+        const lines = fs.readFileSync(path.join(logsDir, f), "utf8").split("\n");
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const rec = JSON.parse(line) as AuditRecord;
+            const src = rec.source || "unknown";
+            let a = acc.get(src);
+            if (!a) { a = { count: 0, lastTs: 0, failCount: 0 }; acc.set(src, a); }
+            a.count++;
+            if (rec.ts > a.lastTs) a.lastTs = rec.ts;
+            // 失败语义与查询一致：exit 非 0（含信号杀 128+n）计失败；exit null（排队取消/在途）不计
+            if (typeof rec.exit === "number" && rec.exit !== 0) a.failCount++;
+          } catch { /* skip bad line */ }
+        }
+      } catch { /* skip file */ }
+    }
+    return [...acc.entries()]
+      .map(([source, a]) => ({ source, count: a.count, lastTs: a.lastTs, failCount: a.failCount, failRate: a.count ? a.failCount / a.count : 0 }))
+      .sort((x, y) => y.count - x.count || y.lastTs - x.lastTs);
+  }
+
+  function getById(id: string): AuditRecord | null {    for (const f of listFiles()) {
+      try {
+        const lines = fs.readFileSync(path.join(logsDir, f), "utf8").split("\n");
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const rec = JSON.parse(line) as AuditRecord;
+            if (rec.id === id) return rec;
+          } catch { /* skip */ }
+        }
+      } catch { /* skip */ }
+    }
+    return null;
+  }
+
+  return { append, writeOutput, readOutput, query, summarizeBySource, getById, verify, cleanupRetention, logsDir, retentionDays: RETENTION_DAYS };
+}
+
+// ---- ANSI 剥离（轻量，覆盖 SGR/光标/清屏等常见序列） ----
+const ANSI_RE = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\))/g;
+function stripAnsi(text: string): string {
+  return String(text).replace(ANSI_RE, "");
+}

package/check-client.mjs

@@ -0,0 +1,273 @@
+/**
+ * check-client —— 扩展 client .mjs/.js 的 TS 残留 tripwire（零依赖，纯 node）。
+ *
+ * 背景：aiti-plan-review 事故（docs/aiti-ext-client-hardening-plan.md §1）——
+ * `useState<any>(null)` 解析为合法 JS 比较表达式 `useState < any > (null)`，
+ * node --check / TS 解析器 / babel 全不报错，只有运行时才炸。纯语法检查
+ * 原理性无效，只能启发式规则 + 渲染期错误边界兜底。
+ *
+ * 用法：
+ *   CLI    node check-client.mjs <file|dir>...        FAIL → exit 1
+ *   自测   node check-client.mjs --selftest           fixtures 全过 → exit 0
+ *   API    lintClientSource(src) → violations[]       { line, level, rule, text }
+ *          lintPath(path)        → { files, violations }（文件或目录，递归）
+ *          checkClientDir(dir,{log})                 FAIL → throw（deploy 脚本用）
+ *
+ * 词法：规则匹配前先剥离注释/字符串/模板字面量（${} 插值内代码保留检查）——
+ * aiti-editor 的 Monaco TS stub 模板串、JSDoc @return 都是合法内容，不剥全误报。
+ * 已知极限：regex 字面量含引号等 lexer 歧义允许漏报（tripwire 定位非编译器）。
+ *
+ * 豁免：目标行或其上一行含 `check-client:allow` 即跳过该行。
+ * 权威源：本文件；aiti-extman 部署副本由其 tools/deploy.mjs 拷贝（改动两处同步）。
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ── 规则（分级）──────────────────────────────────────────────────────────────
+
+const RULES = [
+  // FAIL：合法 JS 但运行时必炸 / 纯 TS 语法
+  { level: "FAIL", re: /\b(useState|useRef|useMemo|useCallback|useReducer|useImperativeHandle)\s*</, why: "React hook 泛型（运行时必炸）" },
+  // 注：含「any/unknown/string」字样的规则用字符串构 RegExp——本文件自身也
+  // 会被扫，正则字面量里的 (?:any 会被自己命中（词法器不处理 regex 字面量），
+  // 字符串字面量则会被词法遮蔽。
+  { level: "FAIL", re: new RegExp("\\bas\\s+(?:" + "any|unknown|const)\\b"), why: "as 断言" },
+  { level: "FAIL", re: new RegExp(":\\s*(?:" + "any|unknown)\\b"), why: ": any/: unknown 注解" },
+  { level: "FAIL", re: /\b(?:import|export)\s+type\s/, why: "import/export type" },
+  { level: "FAIL", re: /\b(?:interface|enum)\s+[A-Za-z_$]/, why: "interface/enum 声明" },
+  // warn：疑似残留，人工确认，不阻断
+  { level: "warn", re: new RegExp(":\\s*(?:" + "string|number|boolean|void)\\b(?!\\s*[._\\w])"), why: "疑似类型注解" },
+  { level: "warn", re: /\bsatisfies\s/, why: "satisfies" },
+  { level: "warn", re: /\b(?:Record|Partial|Readonly|Omit|Pick)\s*</, why: "TS 工具类型" },
+];
+
+// ── 词法剥离：注释/字符串/模板字面量 → 空格（保留换行，行号不漂移）─────────
+export function stripLiterals(src) {
+  const out = src.split("");
+  const n = src.length;
+  const mask = (from, to) => {
+    for (let k = from; k < to && k < n; k++) if (out[k] !== "\n") out[k] = " ";
+  };
+  let mode = "code";
+  let depth = 0;
+  const stack = []; // 模板 ${ 插值进入时的 brace 深度（支持嵌套模板）
+  let i = 0;
+  while (i < n) {
+    const c = src[i];
+    const d = i + 1 < n ? src[i + 1] : "";
+    if (mode === "code") {
+      if (c === "/" && d === "/") {
+        const j = src.indexOf("\n", i);
+        const end = j === -1 ? n : j;
+        mask(i, end);
+        i = end;
+      } else if (c === "/" && d === "*") {
+        const j = src.indexOf("*/", i + 2);
+        const end = j === -1 ? n : j + 2;
+        mask(i, end);
+        i = end;
+      } else if (c === "'" || c === '"') {
+        let j = i + 1;
+        while (j < n && src[j] !== c && src[j] !== "\n") j += src[j] === "\\" ? 2 : 1;
+        if (j < n && src[j] === c) {
+          mask(i, j + 1);
+          i = j + 1;
+        } else {
+          // 未闭合到行尾 → 可能是 regex 字面量歧义，只遮开引号，按代码继续
+          out[i] = " ";
+          i++;
+        }
+      } else if (c === "`") {
+        mode = "tpl";
+        out[i] = " ";
+        i++;
+      } else if (c === "{") {
+        depth++;
+        i++;
+      } else if (c === "}") {
+        if (stack.length && depth === stack[stack.length - 1]) {
+          stack.pop();
+          mode = "tpl"; // 插值结束回模板
+          out[i] = " ";
+        } else {
+          depth = Math.max(0, depth - 1);
+        }
+        i++;
+      } else i++;
+    } else if (mode === "tpl") {
+      if (c === "\\") {
+        mask(i, Math.min(i + 2, n));
+        i += 2;
+      } else if (c === "`") {
+        mode = "code";
+        out[i] = " ";
+        i++;
+      } else if (c === "$" && d === "{") {
+        stack.push(depth);
+        mode = "code";
+        mask(i, i + 2);
+        i += 2;
+      } else {
+        if (c !== "\n") out[i] = " ";
+        i++;
+      }
+    } else {
+      // 不可达：line/block/字符串均在 code 分支内联处理
+      i++;
+    }
+  }
+  return out.join("");
+}
+
+// ── 单源检查 ────────────────────────────────────────────────────────────────
+export function lintClientSource(src) {
+  const masked = stripLiterals(src);
+  const origLines = src.split("\n");
+  const maskedLines = masked.split("\n");
+  const violations = [];
+  for (let i = 0; i < maskedLines.length; i++) {
+    const prev = i > 0 ? origLines[i - 1] : "";
+    if (origLines[i].includes("check-client:allow") || prev.includes("check-client:allow")) continue;
+    for (const { level, re, why } of RULES) {
+      if (re.test(maskedLines[i])) {
+        violations.push({ line: i + 1, level, rule: why, text: origLines[i].trim().slice(0, 90) });
+      }
+    }
+  }
+  return violations;
+}
+
+// ── 文件/目录检查 ───────────────────────────────────────────────────────────
+const SKIP_DIR = new Set(["node_modules", ".git"]);
+/** 超过此体积视为 vendored bundle（如 Monaco ts.worker，合法含 interface 字样），不查。 */
+const MAX_BYTES = 512 * 1024;
+const isClientFile = (name) => /\.(mjs|js|cjs)$/.test(name) && !/\.min\./.test(name) && !/\.test\./.test(name);
+
+export function lintPath(p, out = { files: 0, violations: [] }) {
+  const st = statSync(p);
+  if (st.isDirectory()) {
+    for (const name of readdirSync(p)) {
+      if (SKIP_DIR.has(name)) continue;
+      lintPath(join(p, name), out);
+    }
+    return out;
+  }
+  const base = p.split("/").pop();
+  if (!isClientFile(base)) return out;
+  if (st.size > MAX_BYTES) return out; // vendored bundle 豁免
+  out.files++;
+  for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  return out;
+}
+
+export function formatViolations(violations) {
+  return violations
+    .map((v) => `  ${v.level} ${v.file}:${v.line} [${v.rule}] ${v.text}`)
+    .join("\n");
+}
+
+/** deploy 脚本用：检查目录，FAIL 抛错（消息含违规清单），warn 只打日志不阻断。 */
+export function checkClientDir(dir, { log = console.log } = {}) {
+  const { files, violations } = lintPath(resolve(dir));
+  const fails = violations.filter((v) => v.level === "FAIL");
+  const warns = violations.filter((v) => v.level === "warn");
+  if (warns.length) log(`[check-client] ${warns.length} 处疑似 TS 残留（不阻断，建议人工确认）：\n${formatViolations(warns)}`);
+  if (fails.length) {
+    throw new Error(
+      `client 检查未通过：${files} 个文件中 ${fails.length} 处 TS 残留（.mjs 里是合法 JS，语法检查不报，运行时必炸）。\n` +
+        formatViolations(fails) +
+        `\n修复或在该行加注释 // check-client:allow 豁免。详见 docs/aiti-ext-client-hardening-plan.md`,
+    );
+  }
+  if (files) log(`[check-client] ${files} 个 client 文件检查通过`);
+  return { files, fails: fails.length, warns: warns.length };
+}
+
+/**
+ * extman 安装用：扫整个扩展目录（含第三方，不遵循 client/ 约定）。
+ * 在 SKIP_DIR 之上额外跳过构建产物/vendored 目录（Monaco ts.worker、语言包等
+ * 合法包含 TS 字样，词法器对 minified 代码不提供保证）；体积上限同上。
+ */
+export function lintExtensionDir(dir) {
+  const out = { files: 0, violations: [] };
+  const walk = (p) => {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p)) {
+        if (SKIP_DIR.has(name) || VENDORED_DIRS.has(name)) continue;
+        walk(join(p, name));
+      }
+      return;
+    }
+    const base = p.split("/").pop();
+    if (!isClientFile(base) || st.size > MAX_BYTES) return;
+    out.files++;
+    for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  };
+  walk(resolve(dir));
+  return out;
+}
+const VENDORED_DIRS = new Set(["vendor", "monaco", "dist", "build", "assets", "static", "bundles", "chunks"]);
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+function selftest() {
+  const MUST_FAIL = [
+    "const [st, setSt] = useState<any>(null);",
+    "const r = useRef<number>(null);",
+    "const x = v as any;",
+    "function f(a: unknown) {}",
+    'import type { Foo } from "./x";',
+    "interface Foo { a: string }",
+    "enum Color { Red }",
+    "const y = v as const;",
+  ];
+  const MUST_WARN = [
+    "const opts = { mode: string };",
+    "x satisfies Y;",
+    "const m: Record<string, any> = {};",
+  ];
+  const MUST_PASS = [
+    'const REACT_TYPE_STUB = `\ndeclare module "react" {\n  export function useState<T>(init: T): [T];\n  export const Fragment: any;\n}\n`;',
+    "/** @return {{chars1: string, chars2: string}} */",
+    "const [s] = useState(null);",
+    "useState<any>(null); // check-client:allow",
+    "// check-client:allow\nuseState<never>(0);",
+    "const cmp = a < b && c > (d);",
+    "if (a // 注释里 as any 不算\n  ) run();",
+  ];
+  let bad = 0;
+  const check = (src, expect, desc) => {
+    const v = lintClientSource(src);
+    const fails = v.filter((x) => x.level === "FAIL");
+    const ok = expect === "FAIL" ? fails.length > 0 : expect === "PASS" ? v.length === 0 : v.length > 0 && fails.length === 0;
+    if (!ok) {
+      bad++;
+      console.log(`SELFTEST FAIL [${desc}] 期望 ${expect}，实际 ${JSON.stringify(v)}`);
+    }
+  };
+  MUST_FAIL.forEach((s) => check(s, "FAIL", s.slice(0, 40)));
+  MUST_WARN.forEach((s) => check(s, "WARN", s.slice(0, 40)));
+  MUST_PASS.forEach((s) => check(s, "PASS", s.replace(/\n/g, "⏎").slice(0, 40)));
+  if (bad) {
+    console.log(`selftest: ${bad} 处未过`);
+    process.exit(1);
+  }
+  console.log("selftest: 全部通过（8 FAIL / 3 WARN / 7 PASS）");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.filename)) {
+  if (process.argv.includes("--selftest")) {
+    selftest();
+  } else if (process.argv.length > 2) {
+    const all = { files: 0, violations: [] };
+    for (const p of process.argv.slice(2)) lintPath(resolve(p), all);
+    const fails = all.violations.filter((v) => v.level === "FAIL");
+    const warns = all.violations.filter((v) => v.level === "warn");
+    if (all.violations.length) console.log(formatViolations(all.violations));
+    console.log(`\n${all.files} 个文件：FAIL=${fails.length} warn=${warns.length}`);
+    process.exit(fails.length ? 1 : 0);
+  } else {
+    console.log("用法：node check-client.mjs <file|dir>... ｜ --selftest");
+    process.exit(2);
+  }
+}