@tfdesign/b-end 1.0.4

package/scripts/postinstall-cursor-skill.mjs

@@ -0,0 +1,382 @@
+// 安装 @tfdesign/b-end 后自动执行三件事：
+//
+//  1. IDE Skill 自动写入（仅 opt-in 通道，不写 always-on）
+//     → .cursor/skills/tfds/    （Cursor      → /tfds 唤起）
+//     → .claude/skills/tfds/    （Claude Code → /tfds 唤起）
+//     → .codex/skills/tfds/     （Codex       → 项目内参考）
+//     → ~/.codex/skills/tfds/   （Codex       → 用户级 /tfds Skill，需新开/重启 Codex 会话）
+//     → .agents/skills/tfds/    （通用 agent 兜底，与 .codex 并存）
+//     ⚠️ 不再自动写 .trae/rules/tfds.md：Trae rules 是 always-on 全局规则，
+//        与 TFDS"显式调用才生效"原则冲突。Trae 用户请把 skills/tfds/ 手动加入项目知识库。
+//     跳过：SKIP_TFDS_CURSOR_SKILL=1；目标已存在且完整时不覆盖，旧版/缺文件时自动同步
+//
+//  2. 入口 CSS 自动补丁（最关键步骤，消除手动操作）
+//     在 @import "tailwindcss" 之后自动插入：
+//       @import "@tfdesign/b-end/theme.css";
+//       @source "./**/*.{js,jsx,ts,tsx}";
+//       @source "<relPath>/node_modules/@tfdesign/b-end/**/*.{js,jsx}";
+//     候选文件：src/index.css、src/main.css、src/styles.css、
+//              src/global.css、app/globals.css、styles/globals.css、index.css
+//     已有 theme.css import → 跳过；未找到 @import "tailwindcss" → 不改写，终端提示
+//     跳过：SKIP_TFDS_CSS_PATCH=1
+//
+//  3. 终端安装报告（已做了什么、还差什么、如何唤起规范）
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgRoot = path.resolve(__dirname, '..');
+
+const projectRoot = process.env.INIT_CWD || process.cwd();
+
+// ─────────────────────────────────────────────────────────────────
+// 前置检查：确认运行在正确的业务项目根（有自己的 package.json，且不是 tfds-b-end 自身）
+// ─────────────────────────────────────────────────────────────────
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const projectPkg = readJson(path.join(projectRoot, 'package.json'));
+const isSelfPkg = projectPkg?.name === '@tfdesign/b-end';
+const hasNoPkg = !projectPkg;
+
+if (hasNoPkg || isSelfPkg) {
+  console.log('\n╔══════════════════════════════════════════════════════╗');
+  console.log('║   @tfdesign/b-end  ⚠ 安装位置需要调整         ║');
+  console.log('╚══════════════════════════════════════════════════════╝\n');
+
+  if (hasNoPkg) {
+    console.log('  当前目录没有业务项目的 package.json。');
+  } else {
+    console.log('  当前目录是 tfds-b-end 包自身，不是业务项目根。');
+  }
+  console.log('  不需要手动新建项目或手动猜 file: 路径，请改用离线包根目录的一键安装脚本。\n');
+
+  console.log('  ── 推荐做法：把 tfds-npm-distribution/ 放进目标文件夹后执行 ──\n');
+  console.log('       node tfds-npm-distribution/setup.mjs\n');
+  console.log('  脚本会自动判断：');
+  console.log('    • 已有项目：复用现有 package.json / vite.config / 入口 CSS，缺什么补什么');
+  console.log('    • 全新空文件夹：自动创建最小 Vite + React 项目，然后继续安装 TFDS\n');
+  console.log('  如果安装包不在目标项目根，请显式指定目标：');
+  console.log('       node "/绝对路径/.../tfds-npm-distribution/setup.mjs" --target "/绝对路径/.../业务项目根"\n');
+  console.log('  仅旧包没有 setup.mjs 时，才在业务项目根手动执行：');
+  console.log(`       npm i "file:${pkgRoot}" --save\n`);
+  console.log('  详见：README.md → "全新项目？从这里开始"\n');
+  process.exit(0);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Step 1: Cursor / Agents Skill 复制
+// ─────────────────────────────────────────────────────────────────
+
+const skillSrcLower = path.join(pkgRoot, 'skills', 'tfds');
+const skillSrcLegacy = path.join(pkgRoot, 'skills', 'TFDS');
+const skillSrc = fs.existsSync(skillSrcLower)
+  ? skillSrcLower
+  : fs.existsSync(skillSrcLegacy)
+    ? skillSrcLegacy
+    : null;
+
+const REQUIRED_TFDS_SKILL_FILES = [
+  'SKILL.md',
+  'DESIGN_PRINCIPLES.md',
+  'PAGE_ARCHETYPES.md',
+  'components.summary.json',
+  'components.index.json',
+  'LAYOUT_RULES.md',
+  'GLOBAL_DESIGN_RULES.md',
+  'CHECKLIST.md',
+  'COMMON_FAILURES.md',
+];
+
+function readText(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function hasSourceSkillDiff(dest) {
+  return REQUIRED_TFDS_SKILL_FILES.some((file) => {
+    const sourceFile = path.join(skillSrc, file);
+    const destFile = path.join(dest, file);
+    return readText(sourceFile) !== readText(destFile);
+  });
+}
+
+function needsSkillRefresh(dest) {
+  const missingRequiredFile = REQUIRED_TFDS_SKILL_FILES.some((file) => !fs.existsSync(path.join(dest, file)));
+  if (missingRequiredFile) return true;
+
+  return hasSourceSkillDiff(dest);
+}
+
+function copySkillDir(dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  fs.cpSync(skillSrc, dest, { recursive: true, force: true });
+}
+
+/** @type {string[]} postinstall 步骤摘要，最后汇总打印 */
+const done = [];
+/** @type {string[]} 需用户手动处理的提示 */
+const todo = [];
+
+// ⚠️ SKILL_DIR_TARGETS 必须在 installSkillDir() 定义与调用之前声明，避免 const TDZ 错误
+const SKILL_DIR_TARGETS = {
+  cursor: { base: path.join(projectRoot, '.cursor', 'skills'), label: 'Cursor      Skill → .cursor/skills/tfds/  （唤起：/tfds）' },
+  claude: { base: path.join(projectRoot, '.claude', 'skills'), label: 'Claude Code Skill → .claude/skills/tfds/  （唤起：/tfds）' },
+  codex:  { base: path.join(projectRoot, '.codex',  'skills'), label: 'Codex       参考文件 → .codex/skills/tfds/   （若 /tfds 不出现，请用下方手动提示词）' },
+  agents: { base: path.join(projectRoot, '.agents', 'skills'), label: 'Agents      Skill → .agents/skills/tfds/  （通用 agent 兜底）' },
+};
+
+/**
+ * 复制整个 skill 目录到指定 IDE 的 skills 路径。
+ * @param {'cursor'|'claude'|'codex'|'agents'} which
+ */
+function installSkillDir(which) {
+  const target = SKILL_DIR_TARGETS[which];
+  const dest = path.join(target.base, 'tfds');
+
+  // 迁移旧版大写路径（仅 Cursor）
+  if (which === 'cursor') {
+    const legacy = path.join(projectRoot, '.cursor', 'skills', 'TFDS');
+    if (!fs.existsSync(dest) && fs.existsSync(legacy)) {
+      try {
+        fs.renameSync(legacy, dest);
+        done.push('Cursor Skill 大写路径已迁移 → .cursor/skills/tfds/  （/tfds）');
+      } catch (e) {
+        todo.push(`Skill 迁移失败（${e?.message}），请手动重命名 .cursor/skills/TFDS → tfds`);
+      }
+      return;
+    }
+  }
+
+  if (fs.existsSync(dest)) {
+    if (needsSkillRefresh(dest)) {
+      try {
+        copySkillDir(dest);
+        done.push(`Skill 已存在且已同步新版（${which}）：${path.relative(projectRoot, dest)}`);
+      } catch (e) {
+        todo.push(`Skill 同步失败（${which}）：${e?.message || e}。请删除 ${path.relative(projectRoot, dest)} 后重新执行 npm i。`);
+      }
+    } else {
+      done.push(`Skill 已存在且完整，跳过（${which}）：${path.relative(projectRoot, dest)}`);
+    }
+    return;
+  }
+
+  try {
+    copySkillDir(dest);
+    done.push(target.label);
+  } catch (e) {
+    todo.push(`Skill 复制失败（${which}）：${e?.message || e}`);
+  }
+}
+
+function resolveCodexHome() {
+  if (process.env.CODEX_HOME) return path.resolve(process.env.CODEX_HOME);
+  const home = os.homedir();
+  return home ? path.join(home, '.codex') : null;
+}
+
+function installCodexUserSkill() {
+  const codexHome = resolveCodexHome();
+  if (!codexHome) {
+    todo.push('Codex 用户级 Skill 未写入：无法解析 home 目录。');
+    return;
+  }
+
+  const dest = path.join(codexHome, 'skills', 'tfds');
+  if (fs.existsSync(dest)) {
+    if (needsSkillRefresh(dest)) {
+      try {
+        copySkillDir(dest);
+        done.push(`Codex 用户级 Skill 已存在且已同步新版：${dest}`);
+      } catch (e) {
+        todo.push(`Codex 用户级 Skill 同步失败：${e?.message || e}。请删除 ${dest} 后重新执行 npm i。`);
+      }
+    } else {
+      done.push(`Codex 用户级 Skill 已存在且完整，跳过：${dest}`);
+    }
+    return;
+  }
+
+  try {
+    copySkillDir(dest);
+    done.push(`Codex 用户级 Skill → ${dest}  （新开/重启 Codex 后 /tfds）`);
+  } catch (e) {
+    todo.push(`Codex 用户级 Skill 写入失败：${e?.message || e}。可手动复制 skills/tfds 到 ${dest}`);
+  }
+}
+
+if (process.env.SKIP_TFDS_CURSOR_SKILL === '1') {
+  done.push('Skill 复制已跳过（SKIP_TFDS_CURSOR_SKILL=1）');
+} else if (!skillSrc) {
+  todo.push('包内未找到 skills/tfds 目录，Skill 未复制（可能是 files 裁剪的极简包）');
+} else {
+  installSkillDir('cursor');   // Cursor      → .cursor/skills/tfds/
+  installSkillDir('claude');   // Claude Code → .claude/skills/tfds/
+  installSkillDir('codex');    // Codex       → .codex/skills/tfds/
+  installSkillDir('agents');   // 通用兜底     → .agents/skills/tfds/
+  if (process.env.SKIP_TFDS_CODEX_GLOBAL === '1') {
+    done.push('Codex 用户级 Skill 复制已跳过（SKIP_TFDS_CODEX_GLOBAL=1）');
+  } else {
+    installCodexUserSkill();
+  }
+  // Trae：故意不自动写 .trae/rules/（避免 always-on 污染所有对话）
+  todo.push(
+    'Trae 用户请手动操作：把 node_modules/@tfdesign/b-end/skills/tfds/ 加入 Trae 项目知识库（命名 tfds），之后 @tfds 引用。',
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Step 2: 入口 CSS 自动补丁
+// ─────────────────────────────────────────────────────────────────
+
+if (process.env.SKIP_TFDS_CSS_PATCH === '1') {
+  todo.push(
+    'CSS 补丁已跳过（SKIP_TFDS_CSS_PATCH=1），请手动在入口 CSS 添加 theme.css import 与 @source 扫描',
+  );
+} else {
+  patchEntryCss();
+}
+
+function candidateCssFiles() {
+  const rels = [
+    'src/index.css',
+    'src/main.css',
+    'src/styles.css',
+    'src/global.css',
+    'app/globals.css',
+    'styles/globals.css',
+    'index.css',
+  ];
+  return rels.map((r) => path.join(projectRoot, r)).filter((p) => fs.existsSync(p));
+}
+
+function patchEntryCss() {
+  const cssFiles = candidateCssFiles();
+
+  if (cssFiles.length === 0) {
+    todo.push(
+      '未在常见路径找到入口 CSS，请手动在入口 CSS 添加（src/index.css 为例）：\n' +
+        '      @import "tailwindcss";\n' +
+        '      @import "@tfdesign/b-end/theme.css";\n' +
+        '      @source "./**/*.{js,jsx,ts,tsx}";\n' +
+        '      @source "../node_modules/@tfdesign/b-end/**/*.{js,jsx}";',
+    );
+    return;
+  }
+
+  for (const cssPath of cssFiles) {
+    let content;
+    try {
+      content = fs.readFileSync(cssPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const rel = path.relative(projectRoot, cssPath);
+
+    // 已有 theme.css → 无需操作
+    if (/@tfdesign\/b-end\/theme\.css/.test(content)) {
+      done.push(`CSS 已配置，无需更改：${rel}`);
+      return;
+    }
+
+    // 没有 @import "tailwindcss" → 不改写，提示手动
+    if (!/@import\s+["']tailwindcss["']/.test(content)) {
+      continue; // 尝试下一个候选
+    }
+
+    // 计算 CSS 文件到 node_modules 的相对路径
+    const cssDir = path.dirname(cssPath);
+    const nmRel = path.relative(cssDir, path.join(projectRoot, 'node_modules')).replace(/\\/g, '/') || '.';
+
+    const hasSource = /@source[^;]*@tfdesign\/b-end/i.test(content);
+
+    // 在 @import "tailwindcss"; 行后插入
+    const insertion =
+      `\n@import "@tfdesign/b-end/theme.css";` +
+      (hasSource ? '' : `\n@source "./**/*.{js,jsx,ts,tsx}";\n@source "${nmRel}/@tfdesign/b-end/**/*.{js,jsx}";`);
+
+    const patched = content.replace(
+      /(@import\s+["']tailwindcss["'];[^\n]*)/,
+      `$1${insertion}`,
+    );
+
+    try {
+      fs.writeFileSync(cssPath, patched, 'utf8');
+      done.push(`CSS 已自动配置：${rel}`);
+      done.push(`  + @import "@tfdesign/b-end/theme.css"`);
+      if (!hasSource) {
+        done.push(`  + @source "./**/*.{js,jsx,ts,tsx}"`);
+        done.push(`  + @source "${nmRel}/@tfdesign/b-end/**/*.{js,jsx}"`);
+      }
+    } catch (e) {
+      todo.push(
+        `CSS 自动补丁写入失败（${rel}）：${e?.message}，请手动在 @import "tailwindcss" 后追加：\n` +
+          `      @import "@tfdesign/b-end/theme.css";\n` +
+          `      @source "${nmRel}/@tfdesign/b-end/**/*.{js,jsx}";`,
+      );
+    }
+    return; // 只补丁第一个匹配的 CSS 文件
+  }
+
+  // 所有候选 CSS 都没有 @import "tailwindcss"
+  const firstCss = path.relative(projectRoot, cssFiles[0]);
+  todo.push(
+    `在 ${firstCss} 中未找到 @import "tailwindcss"，CSS 未自动修改。\n` +
+      '      请在入口 CSS 的 @import "tailwindcss" 之后手动追加：\n' +
+      '      @import "@tfdesign/b-end/theme.css";\n' +
+      '      @source "../node_modules/@tfdesign/b-end/**/*.{js,jsx}";',
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Step 3: 终端安装报告
+// ─────────────────────────────────────────────────────────────────
+
+console.log('\n╔══════════════════════════════════════════════════════╗');
+console.log('║      @tfdesign/b-end  安装完成                ║');
+console.log('╚══════════════════════════════════════════════════════╝\n');
+
+if (done.length) {
+  console.log('✓ 已完成：');
+  done.forEach((l) => console.log(`  ${l}`));
+}
+
+if (todo.length) {
+  console.log('\n⚠ 还需手动处理：');
+  todo.forEach((l) => console.log(`  ! ${l}`));
+}
+
+console.log('\n──────────────────────────────────────────────────────');
+console.log('  规范仅在你主动调用时生效（opt-in，不影响其他对话）：');
+console.log('    Cursor      → 重新打开项目 / 新开 Agent 会话后输入  /tfds');
+console.log('    Claude Code → 重启当前 Claude Code 会话后输入  /tfds');
+console.log('    Codex       → 新开/重启 Codex 会话后输入  /tfds（当前会话通常不会热加载）');
+console.log('    Trae        → 不会自动出现 /tfds；把 skills/tfds/ 手动加入项目知识库 → @tfds');
+console.log('');
+console.log('  ⚠ 勿把 TFDS 规范写入 AGENTS.md / .trae/rules/（全局通道会污染所有对话）');
+console.log('  ⚠ 输入 / 后没看到 tfds？这通常是 IDE 尚未重新扫描 Skill 目录；请重启 IDE / 重新打开项目 / 新开会话。');
+console.log('──────────────────────────────────────────────────────');
+console.log(
+  '  自检（只读）：node node_modules/@tfdesign/b-end/scripts/check-tfds-integration.mjs',
+);
+console.log(
+  '  跳过 CSS 补丁：SKIP_TFDS_CSS_PATCH=1 npm i   |   跳过 Skill：SKIP_TFDS_CURSOR_SKILL=1 npm i   |   跳过 Codex 全局 Skill：SKIP_TFDS_CODEX_GLOBAL=1 npm i',
+);
+console.log('');
+
+process.exit(0);