specline 1.4.0 → 2.0.0

package/cli.mjs

@@ -1,99 +1,27 @@
 #!/usr/bin/env node
 
 import { existsSync, mkdirSync, readdirSync, copyFileSync, writeFileSync, readFileSync } from 'fs';
-import { join, dirname, resolve, relative, basename } from 'path';
-import { fileURLToPath } from 'url';
-import { createHash } from 'crypto';
+import { join, dirname, resolve } from 'path';
 import { get } from 'https';
 import { execSync, spawnSync } from 'child_process';
 import { createInterface } from 'readline/promises';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const TEMPLATES_DIR = join(__dirname, 'templates');
+import { PACKAGE_ROOT, TEMPLATES_DIR } from './lib/paths.mjs';
+import { computeFileHash } from './lib/hash.mjs';
+import { readLockFile, writeLockFile } from './lib/lock.mjs';
+import { cliGate } from './lib/gate.mjs';
+import { cliHook } from './lib/hook.mjs';
+import { cliPlatforms } from './lib/platforms.mjs';
+import { runInit, resolvePlatforms, parsePlatformList } from './lib/init.mjs';
+import { runSync } from './lib/sync.mjs';
 
-// 从 package.json 读取版本号（由 npm version 命令自动维护）
-const PKG = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
+const PKG = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
 const VERSION = PKG.version;
 
 // ============================================================
-// 共享工具函数 — 锁文件读写、哈希计算
+// 共享工具函数
 // ============================================================
 
-/**
- * 计算内容的 SHA-256 哈希，返回 sha256:<hex> 格式字符串
- */
-function sha256(content) {
-  const hash = createHash('sha256').update(content).digest('hex');
-  return `sha256:${hash}`;
-}
-
-/**
- * 读取文件内容并计算 SHA-256 哈希
- */
-function computeFileHash(filePath) {
-  const content = readFileSync(filePath);
-  return sha256(content);
-}
-
-/**
- * 读取 specline/.specline-lock.yaml，手工行解析器
- * 返回 { version, synced_at, files: Map<string, string> } | null
- */
-function readLockFile(projectDir) {
-  const lockPath = join(projectDir, 'specline', '.specline-lock.yaml');
-  if (!existsSync(lockPath)) return null;
-
-  const lines = readFileSync(lockPath, 'utf-8').split('\n');
-  const result = { version: '', synced_at: '', files: new Map() };
-  let inFiles = false;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed === '' || trimmed.startsWith('#')) continue;
-
-    if (trimmed.startsWith('version:')) {
-      result.version = trimmed.slice('version:'.length).trim().replace(/^"(.*)"$/, '$1');
-    } else if (trimmed.startsWith('synced_at:')) {
-      result.synced_at = trimmed.slice('synced_at:'.length).trim().replace(/^"(.*)"$/, '$1');
-    } else if (trimmed === 'files:') {
-      inFiles = true;
-    } else if (inFiles && trimmed.includes(':')) {
-      const colonIdx = trimmed.indexOf(':');
-      const key = trimmed.slice(0, colonIdx).trim();
-      const value = trimmed.slice(colonIdx + 1).trim();
-      result.files.set(key, value);
-    }
-  }
-
-  return result;
-}
-
-/**
- * 将锁数据序列化为 YAML 格式写入 specline/.specline-lock.yaml
- */
-function writeLockFile(projectDir, lockData) {
-  const lockDir = join(projectDir, 'specline');
-  if (!existsSync(lockDir)) {
-    mkdirSync(lockDir, { recursive: true });
-  }
-  const lockPath = join(lockDir, '.specline-lock.yaml');
-  const lines = [
-    '# Specline Lock File — 自动生成，请勿手动编辑',
-    `version: "${lockData.version}"`,
-    `synced_at: "${lockData.synced_at}"`,
-    'files:',
-  ];
-  for (const [key, value] of lockData.files) {
-    lines.push(`  ${key}: ${value}`);
-  }
-  writeFileSync(lockPath, lines.join('\n') + '\n', 'utf-8');
-}
-
-/**
- * 遍历指定目录所有文件，构建锁数据结构
- * rootDir: 要遍历的根目录（必须是目标项目目录，这样 init 后锁哈希与实际文件一致）
- * 返回 { version, synced_at, files: Map<string, string> }
- */
 function buildLockData(projectDir, rootDir) {
   const files = new Map();
   const walkRoot = rootDir || TEMPLATES_DIR;
@@ -120,9 +48,6 @@ function buildLockData(projectDir, rootDir) {
   };
 }
 
-/**
- * 版本号语义比较：返回 -1 (a<b)、0 (a==b)、1 (a>b)
- */
 function compareVersions(a, b) {
   const aParts = a.split('.').map(Number);
   const bParts = b.split('.').map(Number);
@@ -135,32 +60,6 @@ function compareVersions(a, b) {
   return 0;
 }
 
-/**
- * 九态决策树：根据模板哈希、锁记录、项目文件状态，分类文件同步策略
- */
-function classifyFile(templatePath, templateHash, lockEntry, projectPath) {
-  const projectExists = existsSync(projectPath);
-  if (!projectExists) return { type: 'NEW', path: templatePath };
-
-  const projectHash = computeFileHash(projectPath);
-
-  if (lockEntry) {
-    if (projectHash === lockEntry) {
-      // PRISTINE
-      if (templateHash === lockEntry) return { type: 'UNCHANGED', path: templatePath };
-      return { type: 'WILL_UPDATE', path: templatePath };
-    } else {
-      // MODIFIED
-      if (templateHash === lockEntry) return { type: 'MODIFIED_ONLY', path: templatePath };
-      return { type: 'CONFLICT', path: templatePath };
-    }
-  } else {
-    // 旧版项目，无 lock 记录
-    if (projectHash === templateHash) return { type: 'UNCHANGED', path: templatePath };
-    return { type: 'NO_LOCK_CONFLICT', path: templatePath };
-  }
-}
-
 // ============================================================
 // 日志输出函数
 // ============================================================
@@ -197,150 +96,25 @@ function copyDirRecursive(src, dest) {
   }
 }
 
-// ============================================================
-// 智能合并函数 — hooks.json / config.yaml / CONFLICT 备份
-// ============================================================
-
-/**
- * hooks.json 语义合并：清理所有 specline-* 条目，注入模板最新官方 hook
- */
-function mergeHooksJson(existingContent, templateContent) {
-  let existingObj, templateObj;
-  try {
-    existingObj = JSON.parse(existingContent);
-  } catch {
-    warn('hooks.json 解析失败，将使用模板完整替换');
-    return templateContent;
-  }
+async function askConfirm(question) {
+  if (!process.stdin.isTTY) return true;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    templateObj = JSON.parse(templateContent);
+    const answer = await rl.question(question + ' ');
+    const trimmed = answer.trim().toLowerCase();
+    return trimmed === '' || trimmed === 'y' || trimmed === 'yes';
   } catch {
-    warn('模板 hooks.json 解析失败，保留现有文件');
-    return existingContent;
-  }
-
-  for (const eventName of Object.keys(templateObj.hooks || {})) {
-    if (!existingObj.hooks) {
-      existingObj.hooks = {};
-    }
-    if (!existingObj.hooks[eventName]) {
-      existingObj.hooks[eventName] = [];
-    }
-    existingObj.hooks[eventName] = existingObj.hooks[eventName].filter(
-      (entry) => !(entry.command || '').includes('specline-')
-    );
-    existingObj.hooks[eventName] = [
-      ...templateObj.hooks[eventName],
-      ...existingObj.hooks[eventName],
-    ];
-  }
-  return JSON.stringify(existingObj, null, 2) + '\n';
-}
-
-function countCustomHooks(hooksObj) {
-  let count = 0;
-  for (const eventName of Object.keys(hooksObj.hooks || {})) {
-    for (const entry of (hooksObj.hooks[eventName] || [])) {
-      if (!(entry.command || '').includes('specline-')) count++;
-    }
-  }
-  return count;
-}
-
-/**
- * YAML 段落结构
- */
-function parseYamlSections(content) {
-  const lines = content.split('\n');
-  const sections = [];
-  let currentComments = [];
-  let currentKey = null;
-  let currentBodyLines = [];
-  let inBody = false;
-
-  function flushSection() {
-    if (currentComments.length > 0 || currentBodyLines.length > 0 || currentKey) {
-      const bodyStr = currentBodyLines.join('\n');
-      // 判定 isEmpty：body 为空、纯注释、或仅声明 key 但无实际值
-      const bodyTrimmed = bodyStr.trim();
-      const onlyKeyDeclaration = currentKey !== null &&
-        currentBodyLines.length === 1 &&
-        bodyTrimmed.match(/^\w[\w_-]*\s*:\s*$/) !== null;
-      const isEmpty = bodyTrimmed === '' ||
-        bodyTrimmed.startsWith('#') ||
-        onlyKeyDeclaration;
-      sections.push({ key: currentKey, headerComments: [...currentComments], body: bodyStr, isEmpty });
-    }
-    currentComments = [];
-    currentKey = null;
-    currentBodyLines = [];
-    inBody = false;
-  }
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed === '') { if (inBody) currentBodyLines.push(line); continue; }
-    if (trimmed.startsWith('#')) { if (inBody) currentBodyLines.push(line); else currentComments.push(line); continue; }
-    const topKeyMatch = line.match(/^(\w[\w_-]*)\s*:(.*)/);
-    if (topKeyMatch && !line.startsWith(' ') && !line.startsWith('\t')) {
-      flushSection();
-      currentKey = topKeyMatch[1];
-      currentBodyLines = [line];
-      inBody = true;
-      continue;
-    }
-    if (inBody) currentBodyLines.push(line);
-  }
-  flushSection();
-  return sections;
-}
-
-function findSection(sections, key) {
-  return sections.find((s) => s.key === key) || null;
-}
-
-function mergeConfigYaml(existingContent, templateContent) {
-  const existingSections = parseYamlSections(existingContent);
-  const templateSections = parseYamlSections(templateContent);
-  const resultLines = [];
-
-  for (const tmplSec of templateSections) {
-    const existSec = findSection(existingSections, tmplSec.key);
-    if (existSec) {
-      if (!existSec.isEmpty && existSec.body.trim() !== tmplSec.body.trim()) {
-        resultLines.push(...tmplSec.headerComments);
-        resultLines.push(existSec.body);
-      } else {
-        resultLines.push(...tmplSec.headerComments);
-        resultLines.push(tmplSec.body);
-      }
-      resultLines.push('');
-    } else if (tmplSec.key !== null) {
-      resultLines.push('# 🆕 新增配置段 (specline sync)');
-      resultLines.push(...tmplSec.headerComments);
-      resultLines.push(tmplSec.body);
-      resultLines.push('');
-    }
-  }
-
-  for (const existSec of existingSections) {
-    if (existSec.key === null) continue;
-    if (!findSection(templateSections, existSec.key)) {
-      resultLines.push(...existSec.headerComments);
-      resultLines.push(existSec.body);
-      resultLines.push('');
-    }
+    return false;
+  } finally {
+    rl.close();
   }
-  return resultLines.join('\n');
 }
 
-function backupBeforeOverwrite(destPath) {
-  const backupPath = destPath + '.orig';
-  copyFileSync(destPath, backupPath);
-  return backupPath;
-}
+// ============================================================
+// 命令实现 — init / sync / update（保持原有逻辑，Task 16/18 再拆）
+// ============================================================
 
-function cmd_init(targetPath) {
+async function cmd_init(targetPath, rawArgs) {
   const cwd = process.cwd();
   const target = resolve(cwd, targetPath || '.');
 
@@ -350,79 +124,48 @@ function cmd_init(targetPath) {
   }
 
   const lockFile = join(target, 'specline', '.specline-lock.yaml');
-  const forceMode = process.argv.includes('--force') || process.argv.includes('-f');
-
-  if (existsSync(lockFile) && !forceMode) {
-    warn('Specline 已在此项目中初始化。使用 --force 强制覆盖。');
-    process.exit(0);
-  }
-
-  // 检测 hooks.json 冲突
-  const hooksJsonDest = join(target, '.cursor', 'hooks.json');
-  if (existsSync(hooksJsonDest)) {
-    const backupPath = hooksJsonDest + '.bak';
-    copyFileSync(hooksJsonDest, backupPath);
-    warn('已备份原有 hooks.json → .cursor/hooks.json.bak');
-  }
+  const forceMode = rawArgs.includes('--force') || rawArgs.includes('-f');
+  const withShellGuard = rawArgs.includes('--with-shell-guard');
 
-  // 创建目录结构
-  const dirs = [
-    '.cursor/agents',
-    '.cursor/skills',
-    '.cursor/hooks',
-    'specline/changes/archive',
-    'specline/specs',
-  ];
-
-  for (const dir of dirs) {
-    const fullDir = join(target, dir);
-    if (!existsSync(fullDir)) {
-      mkdirSync(fullDir, { recursive: true });
+  let platformArg;
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--platform' && rawArgs[i + 1]) {
+      platformArg = rawArgs[++i];
     }
   }
 
-  // 从 templates/ 复制文件
-  if (!existsSync(TEMPLATES_DIR)) {
-    error(`templates/ 目录不存在: ${TEMPLATES_DIR}`);
-    process.exit(1);
+  if (existsSync(lockFile) && !forceMode && !platformArg) {
+    warn('Specline 已在此项目中初始化。使用 --force 强制覆盖，或使用 --platform 追加平台。');
+    process.exit(0);
   }
 
-  copyDirRecursive(TEMPLATES_DIR, target);
+  const platforms = await resolvePlatforms(process.stdin.isTTY, platformArg);
 
-  // 统计各类文件数量
-  function countFiles(dir) {
-    let count = 0;
-    if (!existsSync(dir)) return 0;
-    try {
-      const entries = readdirSync(dir, { withFileTypes: true, recursive: true });
-      for (const entry of entries) {
-        if (entry.isFile()) count++;
-      }
-    } catch (_) {}
-    return count;
-  }
+  const result = runInit({
+    target,
+    platforms,
+    withShellGuard,
+    version: VERSION,
+    force: forceMode,
+  });
 
-  const agentsCount = countFiles(join(target, '.cursor', 'agents'));
-  const skillsCount = countFiles(join(target, '.cursor', 'skills'));
-  const hooksCount = countFiles(join(target, '.cursor', 'hooks'));
+  if (result.appended && result.appended.length > 0) {
+    success(`追加平台：${result.appended.join(', ')}。已有平台不受影响。`);
+  } else {
+    success('Specline 初始化完成');
+  }
+  log(`📁 文件: ${result.skills} skills, ${result.agents} agents, ${result.hooks} hooks`);
+  if (result.platforms.length > 0) {
+    log(`🌐 平台: ${result.platforms.join(', ')}`);
+  } else {
+    log('🌐 平台: 无（仅创建 specline/ 核心目录）');
+  }
 
-  success('Specline 初始化完成');
-  log(`📁 文件: ${skillsCount} skills, ${agentsCount} agents, ${hooksCount} hooks`);
   log('');
-  log('🚀 试试在 Cursor 中输入:');
+  log('🚀 试试输入:');
   log('   /specline-pipeline "你的第一个需求"');
   log('   /specline-explore');
 
-  // 生成锁文件
-  const lockPath = join(target, 'specline', '.specline-lock.yaml');
-  if (existsSync(lockPath) && !forceMode) {
-    warn('锁文件已存在，跳过');
-  } else {
-    const lockData = buildLockData(target, target);
-    writeLockFile(target, lockData);
-    success('已生成锁文件');
-  }
-
   process.exit(0);
 }
 
@@ -455,26 +198,7 @@ function fetchLatestVersion() {
   });
 }
 
-/**
- * 交互式确认提问：回车/Y/y/Yes/yes → true, N/n/No/no → false
- * 非 TTY 环境直接返回 true（无人值守模式）
- */
-async function askConfirm(question) {
-  if (!process.stdin.isTTY) return true;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = await rl.question(question + ' ');
-    const trimmed = answer.trim().toLowerCase();
-    return trimmed === '' || trimmed === 'y' || trimmed === 'yes';
-  } catch {
-    return false;
-  } finally {
-    rl.close();
-  }
-}
-
 async function cmd_update() {
-  // 1. 从 npm registry 获取最新版本
   let latest;
   try {
     latest = await fetchLatestVersion();
@@ -492,13 +216,11 @@ async function cmd_update() {
     process.exit(0);
   }
 
-  // 2. 版本比较
   if (compareVersions(VERSION, latest) >= 0) {
     success('已是最新版本 (v' + VERSION + ')');
     process.exit(0);
   }
 
-  // 3. 交互确认
   log('✨ 新版本可用: v' + latest + '（当前: v' + VERSION + '）');
 
   if (!process.stdin.isTTY) {
@@ -512,7 +234,6 @@ async function cmd_update() {
     process.exit(0);
   }
 
-  // 4. 执行 npm install -g specline@latest
   log('正在升级 specline...');
   try {
     execSync('npm install -g specline@latest', { stdio: 'inherit' });
@@ -530,7 +251,6 @@ async function cmd_update() {
 
   success('已升级至 v' + latest);
 
-  // 5. 检测是否为 specline 项目，询问是否同步模板
   const cwd = process.cwd();
   const lockFile = join(cwd, 'specline', '.specline-lock.yaml');
   if (existsSync(lockFile)) {
@@ -551,14 +271,12 @@ async function cmd_update() {
   process.exit(0);
 }
 
-function cmd_sync({ dryRun, targetPath }) {
+function cmd_sync({ dryRun, targetPath, platformArg }) {
   const cwd = process.cwd();
   const target = resolve(cwd, targetPath || '.');
 
-  // 1. 检查项目是否已初始化
   const lockFile = join(target, 'specline', '.specline-lock.yaml');
   if (!existsSync(lockFile)) {
-    // 向后兼容：检查旧版 .specline-config.yaml
     const oldMarker = join(target, '.specline-config.yaml');
     if (existsSync(oldMarker)) {
       warn('检测到旧版项目，正在自动迁移...');
@@ -571,259 +289,116 @@ function cmd_sync({ dryRun, targetPath }) {
     }
   }
 
-  // 2. 构建上游模板哈希映射
-  const upstreamData = buildLockData(target);
-  const upstreamFiles = upstreamData.files;
-
-  // 3. 读取锁文件
   const lockData = readLockFile(target);
-
-  // 4. 版本校验
   if (lockData && compareVersions(lockData.version, VERSION) > 0) {
-    warn('锁文件版本 (v' + lockData.version + ') 高于 CLI 版本 (v' + VERSION + ')，继续同步可能导致问题');
-    if (!process.stdin.isTTY) {
-      error('非交互式环境，已跳过同步');
-      process.exit(1);
-    }
-    error('锁文件版本高于 CLI，请先更新 CLI');
+    error('锁文件版本 (v' + lockData.version + ') 高于 CLI 版本 (v' + VERSION + ')，请先更新 CLI');
     process.exit(1);
   }
 
-  // 5. 收集所有需要分类的路径
-  const allPaths = new Set();
-  for (const p of upstreamFiles.keys()) allPaths.add(p);
-  if (lockData) {
-    for (const p of lockData.files.keys()) {
-      if (!upstreamFiles.has(p)) allPaths.add(p);
-    }
-  }
-
-  // 6. 分类
-  const results = [];
-  for (const path of allPaths) {
-    const templateHash = upstreamFiles.get(path) || null;
-    const lockEntry = lockData ? (lockData.files.get(path) || null) : null;
-    const projectPath = join(target, path);
-
-    if (templateHash === null) {
-      results.push({ type: 'UPSTREAM_REMOVED', path });
-    } else {
-      results.push(classifyFile(path, templateHash, lockEntry, projectPath));
-    }
-  }
-
-  // 7. 统计
-  const stats = { newCount: 0, updated: 0, conflicted: 0, skippedModified: 0, unchanged: 0, upstreamRemoved: 0 };
-  for (const r of results) {
-    if (r.type === 'NEW') stats.newCount++;
-    else if (r.type === 'WILL_UPDATE') stats.updated++;
-    else if (r.type === 'CONFLICT' || r.type === 'NO_LOCK_CONFLICT') stats.conflicted++;
-    else if (r.type === 'MODIFIED_ONLY') stats.skippedModified++;
-    else if (r.type === 'UPSTREAM_REMOVED') stats.upstreamRemoved++;
-    else stats.unchanged++;
-  }
+  const platforms = platformArg ? parsePlatformList(platformArg) : undefined;
 
-  // 8. dryRun 模式只预览
-  if (dryRun) {
-    const HOOKS_JSON = '.cursor/hooks.json';
-    const CONFIG_YAML = 'specline/config.yaml';
-    let hooksPlan = null;
-
-    for (const r of results) {
-      if (r.type === 'UNCHANGED' || r.type === 'MODIFIED_ONLY') {
-        if (r.path === HOOKS_JSON) {
-          const projPath = join(target, r.path);
-          if (existsSync(projPath)) {
-            try {
-              const existingObj = JSON.parse(readFileSync(projPath, 'utf-8'));
-              hooksPlan = { customCount: countCustomHooks(existingObj) };
-            } catch {}
-          }
-        }
-        if (r.path === CONFIG_YAML) {
-          log('💡 config.yaml: 用户已修改，保留现有配置不变');
-        }
-        continue;
-      }
-
-      if (r.path === HOOKS_JSON) {
-        hooksPlan = hooksPlan || { customCount: 0 };
-        // 读取用户现有 hooks.json，计算自定义 hook 数量
-        const projPath = join(target, r.path);
-        if (existsSync(projPath) && !hooksPlan.readFromUser) {
-          try {
-            const existingObj = JSON.parse(readFileSync(projPath, 'utf-8'));
-            hooksPlan = { customCount: countCustomHooks(existingObj), readFromUser: true };
-          } catch {}
-        }
-        let tplCount = 0;
-        try {
-          const tpl = JSON.parse(readFileSync(join(TEMPLATES_DIR, r.path), 'utf-8'));
-          for (const ev of Object.keys(tpl.hooks || {})) tplCount += (tpl.hooks[ev] || []).length;
-        } catch {}
-        log(`🔄 hooks.json 语义合并: 保留 ${hooksPlan.customCount >= 0 ? hooksPlan.customCount : '?'} 个自定义 hook, 更新 ${tplCount} 个官方 hook`);
-        continue;
+  try {
+    const result = runSync(target, { dryRun, platforms });
+
+    if (dryRun) {
+      for (const item of result.plan) {
+        if (item.type === 'UNCHANGED' || item.type === 'MODIFIED_ONLY') continue;
+        const labels = {
+          NEW: '➕ 新增',
+          WILL_UPDATE: '🔄 更新',
+          CONFLICT: '⚠️  冲突（将备份后覆盖）',
+          UPSTREAM_REMOVED: '🗑️  上游移除',
+        };
+        log((labels[item.type] || item.type) + '  ' + item.path);
       }
-
-      if (r.path === CONFIG_YAML) {
-        log('💡 config.yaml: 保留用户配置不变，更新文档注释');
-        continue;
+      const s = result.stats;
+      if (s.newCount === 0 && s.updated === 0 && s.conflicted === 0 && s.upstreamRemoved === 0) {
+        log('所有模板文件已是最新，无需同步');
+      } else {
+        log('\n以上为预览，未实际执行。去掉 --dry-run 以执行同步。');
       }
-
-      const labels = { NEW: '➕ 新增', WILL_UPDATE: '🔄 更新', CONFLICT: '⚠️  冲突（将备份后覆盖）', NO_LOCK_CONFLICT: '⚠️  无锁记录', UPSTREAM_REMOVED: '🗑️  上游移除' };
-      log(labels[r.type] + '  ' + r.path);
-    }
-    if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0
-        && stats.skippedModified === 0 && stats.upstreamRemoved === 0) {
-      log('所有模板文件已是最新，无需同步');
-    } else {
-      log('\n以上为预览，未实际执行。去掉 --dry-run 以执行同步。');
-    }
-    process.exit(0);
-  }
-
-  // 9. 执行写入
-  const newFiles = new Map();
-  const HOOKS_JSON = '.cursor/hooks.json';
-  const CONFIG_YAML = 'specline/config.yaml';
-  const mergeStats = { hooksMerged: false, configUpdated: false, backupsCreated: 0 };
-
-  for (const r of results) {
-    if (r.type === 'UNCHANGED' || r.type === 'MODIFIED_ONLY') {
-      const projectPath = join(target, r.path);
-      if (existsSync(projectPath)) {
-        newFiles.set(r.path, computeFileHash(projectPath));
+      if (result.migrated) {
+        log('📦 Lock file 将从 v1 迁移至 v2');
       }
-      continue;
-    }
-
-    if (r.type === 'UPSTREAM_REMOVED') {
-      warn('上游已移除：' + r.path);
-      continue;
+      process.exit(0);
     }
 
-    const srcPath = join(TEMPLATES_DIR, r.path);
-    const destPath = join(target, r.path);
-    const destDir = dirname(destPath);
-    if (!existsSync(destDir)) {
-      mkdirSync(destDir, { recursive: true });
+    const s = result.stats;
+    if (s.newCount === 0 && s.updated === 0 && s.conflicted === 0
+        && s.skippedModified === 0 && s.upstreamRemoved === 0) {
+      success('项目模板已是最新，无需同步 (v' + VERSION + ')');
+    } else {
+      log('📊 同步摘要：');
+      log('   ✅ 已新增: ' + s.newCount);
+      log('   🔄 已更新: ' + s.updated);
+      log('   ⚠️  已覆盖（冲突）: ' + s.conflicted);
+      log('   ⏭️  已跳过（本地修改）: ' + s.skippedModified);
+      log('   🗑️  上游已移除: ' + s.upstreamRemoved);
+      log('   ✨ 锁文件已更新至 v' + VERSION);
     }
-
-    try {
-      // 特殊文件：hooks.json 语义合并
-      if (r.path === HOOKS_JSON) {
-        const existingContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '{}';
-        const templateContent = readFileSync(srcPath, 'utf-8');
-        try {
-          const merged = mergeHooksJson(existingContent, templateContent);
-          writeFileSync(destPath, merged, 'utf-8');
-          newFiles.set(r.path, sha256(merged));
-          mergeStats.hooksMerged = true;
-        } catch {
-          warn('hooks.json 合并失败，将保留现有文件');
-          newFiles.set(r.path, computeFileHash(destPath));
-        }
-        continue;
-      }
-
-      // 特殊文件：config.yaml 注释合并
-      if (r.path === CONFIG_YAML) {
-        const existingContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
-        const templateContent = readFileSync(srcPath, 'utf-8');
-        try {
-          const merged = mergeConfigYaml(existingContent, templateContent);
-          writeFileSync(destPath, merged, 'utf-8');
-          newFiles.set(r.path, sha256(merged));
-          mergeStats.configUpdated = true;
-        } catch {
-          warn('config.yaml 合并失败，将保留现有文件');
-          newFiles.set(r.path, computeFileHash(destPath));
-        }
-        continue;
-      }
-
-      // CONFLICT：备份后覆盖
-      if (r.type === 'CONFLICT' || r.type === 'NO_LOCK_CONFLICT') {
-        if (existsSync(destPath)) {
-          const backupPath = backupBeforeOverwrite(destPath);
-          mergeStats.backupsCreated++;
-          warn('已覆盖（冲突，备份: ' + basename(backupPath) + '）: ' + r.path);
-        }
-        copyFileSync(srcPath, destPath);
-        newFiles.set(r.path, computeFileHash(destPath));
-      } else {
-        copyFileSync(srcPath, destPath);
-        newFiles.set(r.path, computeFileHash(destPath));
-      }
-    } catch (err) {
-      warn(r.path + ' 写入失败：' + err.message);
-      if (lockData && lockData.files.has(r.path)) {
-        newFiles.set(r.path, lockData.files.get(r.path));
-      }
+    if (result.migrated) {
+      success('Lock file 已从 v1 迁移至 v2 格式');
     }
-  }
-
-  // 10. 更新锁文件
-  writeLockFile(target, {
-    version: VERSION,
-    synced_at: new Date().toISOString(),
-    files: newFiles,
-  });
-
-  // 11. 输出摘要
-  if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0
-      && stats.skippedModified === 0 && stats.upstreamRemoved === 0
-      && !mergeStats.hooksMerged && !mergeStats.configUpdated) {
-    success('项目模板已是最新，无需同步 (v' + VERSION + ')');
-  } else {
-    log('📊 同步摘要：');
-    log('   总模板文件: ' + allPaths.size);
-    log('   ✅ 已新增: ' + stats.newCount);
-    log('   🔄 已更新: ' + stats.updated);
-    log('   ⚠️  已覆盖（冲突）: ' + stats.conflicted);
-    log('   ⏭️  已跳过（本地修改）: ' + stats.skippedModified);
-    log('   🗑️  上游已移除: ' + stats.upstreamRemoved);
-    if (mergeStats.hooksMerged) log('   🔧 hooks.json: 语义合并完成');
-    if (mergeStats.configUpdated) log('   📝 config.yaml: 注释已更新');
-    if (mergeStats.backupsCreated > 0) log('   💾 创建备份: ' + mergeStats.backupsCreated + ' 个 .orig 文件');
-    log('   ✨ 锁文件已更新至 v' + VERSION);
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
   }
 
   process.exit(0);
 }
 
+// ============================================================
+// 命令路由
+// ============================================================
+
 function cmd_version() {
   log(`specline v${VERSION}`);
   process.exit(0);
 }
 
-function cmd_help() {
-  log(`specline v${VERSION} — Spec-driven AI coding pipeline for Cursor IDE
+function cmd_help(exitCode = 0) {
+  log(`specline v${VERSION} — Spec-driven AI coding pipeline
 
 用法:
-  specline init [path]           在指定路径初始化流水线基础设施
-  specline init --force          强制覆盖已有配置
-  specline update                检查 CLI 自身更新（npm registry）
-  specline sync [--dry-run] [path]  同步项目模板文件到最新版本
-  specline --version, -v         显示版本号
-  specline --help, -h            显示此帮助信息
+  specline init [path]               在指定路径初始化流水线基础设施
+  specline init --platform <list>    指定平台 (cursor,claude,codex,opencode,all,none)
+  specline init --force              强制覆盖已有配置
+  specline init --with-shell-guard   启用 shell 命令安全防护 hook
+  specline sync [--dry-run] [path]   同步项目模板文件到最新版本
+  specline sync --platform <list>    只同步指定平台
+  specline update                    检查 CLI 自身更新（npm registry）
+  specline gate <sub> [--change <n>] 运行 Gate 检查（spec/build/lint/list …）
+  specline hook <sub> [--platform p] 运行 Hook 脚本（session-start …）
+  specline platforms                 显示已部署平台列表
+  specline --version, -v             显示版本号
+  specline --help, -h                显示此帮助信息
 
 示例:
-  specline init                  在当前目录初始化
-  specline init ./my-project     在指定目录初始化
-  specline sync --dry-run        预览模板文件更新
-  npx specline init              无需全局安装即可使用
+  specline init                      在当前目录初始化（TTY 下交互选择平台）
+  specline init --platform cursor    只部署 Cursor 平台
+  specline init --platform all       部署全部 4 个平台
+  specline init ./my-project         在指定目录初始化
+  specline sync --dry-run            预览模板文件更新
+  specline gate spec --change feat   运行 spec gate 检查
+  specline hook session-start        运行 session-start hook
+  specline platforms                 列出已部署平台
+  npx specline init                  无需全局安装即可使用
 `);
-  process.exit(0);
+  process.exit(exitCode);
 }
 
-// 入口
 const [,, command, ...args] = process.argv;
 
 switch (command) {
   case 'init': {
-    const pathArg = args.filter(a => a !== '--force' && a !== '-f')[0];
-    cmd_init(pathArg);
+    const initFlags = ['--force', '-f', '--with-shell-guard', '--platform'];
+    const pathArg = args.filter(a => {
+      if (initFlags.includes(a)) return false;
+      const prevIdx = args.indexOf(a) - 1;
+      if (prevIdx >= 0 && args[prevIdx] === '--platform') return false;
+      return true;
+    })[0];
+    await cmd_init(pathArg, args);
     break;
   }
   case 'update': {
@@ -832,8 +407,31 @@ switch (command) {
   }
   case 'sync': {
     const dryRun = args.includes('--dry-run');
-    const pathArg = args.filter(a => a !== '--dry-run')[0];
-    cmd_sync({ dryRun, targetPath: pathArg });
+    let syncPlatformArg;
+    const filteredArgs = [];
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--platform' && args[i + 1]) {
+        syncPlatformArg = args[++i];
+      } else if (args[i] !== '--dry-run') {
+        filteredArgs.push(args[i]);
+      }
+    }
+    cmd_sync({ dryRun, targetPath: filteredArgs[0], platformArg: syncPlatformArg });
+    break;
+  }
+  case 'gate': {
+    const exitCode = cliGate(args);
+    process.exit(exitCode);
+    break;
+  }
+  case 'hook': {
+    const exitCode = cliHook(args);
+    process.exit(exitCode);
+    break;
+  }
+  case 'platforms': {
+    const exitCode = cliPlatforms();
+    process.exit(exitCode);
     break;
   }
   case '--version':
@@ -842,7 +440,12 @@ switch (command) {
     break;
   case '--help':
   case '-h':
-  default:
     cmd_help();
     break;
+  default:
+    if (command) {
+      console.error(`\x1b[31m未知命令: ${command}\x1b[0m\n`);
+    }
+    cmd_help(command ? 1 : 0);
+    break;
 }