adspecs 0.1.12

package/src/lib/scaffolder.js

@@ -0,0 +1,518 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { copyDirFiltered, removeDir, countFiles } = require('./copier');
+const { generateReadme, generateWikiReadme, generateServiceReadme, DOCS_READMES } = require('./readme-gen');
+const { mergeJsonFile, mergeProjectJson } = require('./json-merge');
+const { generatePathsConfig } = require('./paths-defaults');
+
+/**
+ * 脚手架核心
+ *
+ * 接收 per-zone decisions 对象，按决策分支执行（create/recreate/update/skip）。
+ * 通过 logger 回调实时输出每阶段状态。
+ * 支持子目录决策、模式升级自动补充、skip 场景下 feature.json 属性补全。
+ */
+
+// ============================================================
+// 主入口
+// ============================================================
+
+/**
+ * 执行脚手架
+ *
+ * @param {object} opts
+ * @param {string} opts.targetDir - 目标项目根目录
+ * @param {string} opts.pluginDir - 插件根目录
+ * @param {string} opts.mode - 初始化模式
+ * @param {string} opts.frontDemo - 前端技术栈（vue/antd/skip）
+ * @param {string} opts.project_name
+ * @param {string} opts.project_short_name
+ * @param {string} opts.project_dir
+ * @param {string} opts.company_name
+ * @param {string} opts.confidentiality
+ * @param {string} opts.modules
+ * @param {object} opts.decisions - 每区域决策 { areaKey: 'create'|'recreate'|'update'|'skip' }
+ * @param {object} opts.subDecisions - 子目录决策 { conventions, templates }
+ * @param {object} opts.modeUpgrade - 模式升级检测 { detected, emptyDirs }
+ * @param {function} opts.logger - 实时状态回调 (msg: string) => void
+ * @returns {Promise<object>} 执行报告
+ */
+async function scaffold(opts) {
+  const {
+    targetDir,
+    pluginDir,
+    mode,
+    frontDemo,
+    project_name,
+    project_short_name,
+    project_dir,
+    company_name,
+    confidentiality,
+    modules,
+    decisions,
+    subDecisions = { conventions: 'skip', templates: 'skip' },
+    modeUpgrade = { detected: false, emptyDirs: [] },
+    logger = () => {},
+  } = opts;
+
+  const report = {
+    targetDir,
+    mode,
+    projectName: project_name,
+    projectShortName: project_short_name,
+    companyName: company_name,
+    confidentiality,
+    stages: [],
+    startedAt: new Date().toISOString(),
+  };
+
+  const FRONT_DEMO_SOURCE = frontDemo === 'antd' ? 'antd-front-demo' : 'front-demo';
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // === 阶段 1: docs/ ===
+  report.stages.push(
+    await scaffoldDocs(targetDir, pluginDir, mode, FRONT_DEMO_SOURCE, decisions.docs, subDecisions, modeUpgrade, logger)
+  );
+
+  // === 阶段 2: wiki/ ===
+  report.stages.push(scaffoldWiki(targetDir, decisions.wiki, logger));
+
+  // === 阶段 3: web-ui/ (full/demo) ===
+  if (mode === 'full' || mode === 'demo') {
+    report.stages.push(await scaffoldWebUi(targetDir, pluginDir, decisions.webUi, logger));
+  }
+
+  // === 阶段 4: service/ (full/demo) ===
+  if (mode === 'full' || mode === 'demo') {
+    report.stages.push(scaffoldService(targetDir, modules, decisions.service, logger));
+  }
+
+  // === 阶段 5: front-demo/ (classic/full/demo，且 frontDemo !== 'skip') ===
+  if (mode !== 'simple' && frontDemo !== 'skip') {
+    report.stages.push(await scaffoldFrontDemo(targetDir, pluginDir, FRONT_DEMO_SOURCE, decisions.frontDemo, logger));
+  } else if (mode !== 'simple' && frontDemo === 'skip') {
+    logger(`⏭ 阶段 5 跳过：用户选择不创建 front-demo/`);
+    report.stages.push({ name: 'front-demo/', status: 'skipped', reason: '用户选择跳过' });
+  }
+
+  // === 阶段 6: .adspecs/ ===
+  report.stages.push(
+    await scaffoldAdspecs(targetDir, pluginDir, decisions.adspecs, subDecisions, logger)
+  );
+
+  // === 阶段 6.5: project.json ===
+  const projectJsonResult = writeProjectJson(targetDir, pluginDir, {
+    project_name,
+    project_short_name,
+    project_dir,
+    company_name,
+    confidentiality,
+  });
+  logger(
+    projectJsonResult.created
+      ? `✅ 阶段 6.5 完成：项目元数据已生成 .adspecs/project.json`
+      : `🔄 阶段 6.5 完成：项目元数据已更新 .adspecs/project.json`
+  );
+  report.stages.push({
+    name: '.adspecs/project.json',
+    status: projectJsonResult.created ? 'created' : 'updated',
+    detail: projectJsonResult,
+  });
+
+  // === 阶段 7: paths.json ===
+  const pathsResult = writePathsJson(targetDir);
+  logger(
+    pathsResult.created
+      ? `✅ 阶段 7 完成：路径配置文件已生成 .adspecs/paths.json`
+      : `⏭ 阶段 7 跳过：.adspecs/paths.json 已存在`
+  );
+  report.stages.push({
+    name: '.adspecs/paths.json',
+    status: pathsResult.created ? 'created' : 'exists',
+  });
+
+  report.completedAt = new Date().toISOString();
+  return report;
+}
+
+// ============================================================
+// 各阶段实现
+// ============================================================
+
+/**
+ * 决策前处理：根据 decision 决定目录状态
+ *
+ * @returns {'created'|'recreated'|'skipped'|'updated'} action
+ */
+function prepareDirByDecision(dirPath, decision, logger, areaName) {
+  if (decision === 'skip') {
+    return 'skip';
+  }
+  if (decision === 'recreate') {
+    if (fs.existsSync(dirPath)) {
+      removeDir(dirPath);
+      logger(`🔄 删除旧 ${areaName}/ 并重建...`);
+    }
+    fs.mkdirSync(dirPath, { recursive: true });
+    return 'recreate';
+  }
+  if (decision === 'update') {
+    // update：保留目录，后续操作会覆盖文件
+    fs.mkdirSync(dirPath, { recursive: true });
+    return 'update';
+  }
+  // create：目录原本就不存在
+  fs.mkdirSync(dirPath, { recursive: true });
+  return 'create';
+}
+
+/**
+ * 阶段 1: docs/ 目录结构
+ */
+async function scaffoldDocs(targetDir, pluginDir, mode, frontDemoSource, decision, subDecisions, modeUpgrade, logger) {
+  const docsDir = path.join(targetDir, 'docs');
+  const stage = { name: 'docs/', dirs: [], files: 0 };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 1 跳过：docs/ 已存在，保留现有内容`);
+
+    // 子决策：conventions
+    if (subDecisions.conventions === 'update') {
+      const frontendStandard = resolveFrontendStandard(frontDemoSource);
+      copyDirFiltered(
+        path.join(pluginDir, 'references', frontendStandard),
+        path.join(docsDir, '40-project_conventions/frontend-standard')
+      );
+      logger(`🔄 阶段 1 补充更新：docs/40-project_conventions/frontend-standard/ 已按前端技术栈更新`);
+      stage.subDecisions = { conventions: 'update' };
+    }
+
+    // 模式升级自动补充
+    if (modeUpgrade.detected) {
+      const frontendStandard = resolveFrontendStandard(frontDemoSource);
+      fs.mkdirSync(path.join(docsDir, '40-project_conventions/frontend-standard'), { recursive: true });
+      copyDirFiltered(
+        path.join(pluginDir, 'references', frontendStandard),
+        path.join(docsDir, '40-project_conventions/frontend-standard')
+      );
+      logger(`📦 补充：检测到 40-project_conventions/ 为空目录（简易模式产物），已按前端技术栈补充 frontend-standard/`);
+      stage.modeUpgrade = modeUpgrade;
+    }
+
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(docsDir, decision, logger, 'docs');
+
+  // 11 个一级子目录
+  const subdirs = [
+    '00-planning',
+    '00-customer-requirements',
+    '10-architecture',
+    '20-prd',
+    '30-system-design',
+    '40-project_conventions',
+    '70-scripts/depoly',
+    '80-development/800-log',
+    '80-development/801-dev',
+    '80-development/802-test',
+    '100-help',
+    '300-specs',
+  ];
+  for (const sub of subdirs) {
+    fs.mkdirSync(path.join(docsDir, sub), { recursive: true });
+    stage.dirs.push(sub);
+  }
+
+  // 40-project_conventions 按模式处理
+  const convDir = path.join(docsDir, '40-project_conventions');
+  fs.mkdirSync(path.join(convDir, 'frontend-standard'), { recursive: true });
+  fs.mkdirSync(path.join(convDir, 'end-standard'), { recursive: true });
+
+  if (mode === 'demo') {
+    copyDirFiltered(
+      path.join(pluginDir, 'references/ant6-front-standard'),
+      path.join(convDir, 'frontend-standard')
+    );
+    copyDirFiltered(
+      path.join(pluginDir, 'references/python-end-standard'),
+      path.join(convDir, 'end-standard')
+    );
+  } else if (mode === 'classic' || mode === 'full') {
+    const frontendStandard = resolveFrontendStandard(frontDemoSource);
+    copyDirFiltered(
+      path.join(pluginDir, 'references', frontendStandard),
+      path.join(convDir, 'frontend-standard')
+    );
+  }
+
+  // 生成各子目录的 README.md（create/recreate/update 都重新生成）
+  if (decision !== 'skip') {
+    for (const [subdirKey, meta] of Object.entries(DOCS_READMES)) {
+      const readmePath = path.join(docsDir, subdirKey, 'README.md');
+      fs.writeFileSync(readmePath, generateReadme(meta), 'utf8');
+      stage.files++;
+    }
+  }
+
+  stage.fileCount = countFiles(docsDir);
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const verb = action === 'recreate' ? '重新创建' : '创建';
+  const convNote =
+    mode === 'demo'
+      ? '，40 按 Python+React 技术栈复制前后端规范'
+      : mode === 'simple'
+        ? '，40 仅创建空目录'
+        : '，其中 40 从 references 复制';
+  logger(`✅ 阶段 1 完成：docs/ 目录结构已${verb}（11 个一级子目录${convNote}）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 2: wiki/ 基线文件目录
+ */
+function scaffoldWiki(targetDir, decision, logger) {
+  const wikiDir = path.join(targetDir, 'wiki');
+  const stage = { name: 'wiki/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 2 跳过：wiki/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(wikiDir, decision, logger, 'wiki');
+  fs.writeFileSync(path.join(wikiDir, 'README.md'), generateWikiReadme(), 'utf8');
+
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+  stage.fileCount = 1;
+
+  const verb = action === 'recreate' ? '重新创建' : '创建';
+  logger(`✅ 阶段 2 完成：wiki/ 基线文件目录已${verb}`);
+
+  return stage;
+}
+
+/**
+ * 阶段 3: web-ui/ 前端项目（完整/轻量模式）
+ */
+async function scaffoldWebUi(targetDir, pluginDir, decision, logger) {
+  const webUiDir = path.join(targetDir, 'web-ui');
+  const stage = { name: 'web-ui/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 3 跳过：web-ui/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(webUiDir, decision, logger, 'web-ui');
+
+  // update / create / recreate 都从 references 复制
+  const result = copyDirFiltered(path.join(pluginDir, 'references/web-ui'), webUiDir);
+
+  stage.fileCount = result.fileCount;
+  stage.skippedDirs = result.skippedDirs;
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const verb = action === 'recreate' ? '重新复制' : '复制';
+  logger(`✅ 阶段 3 完成：web-ui/ 前端项目已${verb}（${result.fileCount} 个文件）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 4: service/ 后端服务目录（完整/轻量模式）
+ */
+function scaffoldService(targetDir, modules, decision, logger) {
+  const serviceDir = path.join(targetDir, 'service');
+  const stage = { name: 'service/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 4 跳过：service/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(serviceDir, decision, logger, 'service');
+  fs.writeFileSync(path.join(serviceDir, 'README.md'), generateServiceReadme(), 'utf8');
+
+  // 按模块列表创建子目录
+  if (modules) {
+    const moduleList = modules.split(',').map((s) => s.trim()).filter(Boolean);
+    for (const mod of moduleList) {
+      // 格式：{port}-crm-{name}:{package}
+      const match = mod.match(/^(\d+)-crm-([^:]+):(.+)$/);
+      if (match) {
+        const [, port, name] = match;
+        const modPath = path.join(serviceDir, `${port}-crm-${name}`, 'service');
+        fs.mkdirSync(modPath, { recursive: true });
+        fs.writeFileSync(path.join(modPath, 'README.md'), generateServiceReadme(), 'utf8');
+      }
+    }
+  }
+
+  stage.fileCount = countFiles(serviceDir);
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const verb = action === 'recreate' ? '重新创建' : '创建';
+  logger(`✅ 阶段 4 完成：service 目录已${verb}`);
+
+  return stage;
+}
+
+/**
+ * 阶段 5: front-demo/ 前端演示项目（经典/完整/轻量模式）
+ */
+async function scaffoldFrontDemo(targetDir, pluginDir, frontDemoSource, decision, logger) {
+  const frontDemoDir = path.join(targetDir, 'front-demo');
+  const stage = { name: 'front-demo/', frontDemoSource };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 5 跳过：front-demo/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(frontDemoDir, decision, logger, 'front-demo');
+
+  const result = copyDirFiltered(
+    path.join(pluginDir, 'references', frontDemoSource),
+    frontDemoDir
+  );
+
+  stage.fileCount = result.fileCount;
+  stage.skippedDirs = result.skippedDirs;
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const techName = frontDemoSource === 'antd-front-demo' ? 'Ant Design React' : 'Vue';
+  const verb = action === 'recreate' ? '重新复制' : '复制';
+  logger(`✅ 阶段 5 完成：front-demo/ 已${verb}（${techName}，${result.fileCount} 个文件）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 6: .adspecs/ 配置与脚本目录
+ */
+async function scaffoldAdspecs(targetDir, pluginDir, decision, subDecisions, logger) {
+  const adspecsDir = path.join(targetDir, '.adspecs');
+  const stage = { name: '.adspecs/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 6 跳过：.adspecs/ 已存在，保留现有内容`);
+
+    // 子决策：templates
+    if (subDecisions.templates === 'update') {
+      copyDirFiltered(
+        path.join(pluginDir, '.adspecs/templates'),
+        path.join(adspecsDir, 'templates')
+      );
+      logger(`🔄 阶段 6 补充更新：.adspecs/templates/ 已从插件根目录更新`);
+      stage.subDecisions = { templates: 'update' };
+    }
+
+    // 属性补全（无论是否更新 templates 都执行）
+    const featureResult = mergeJsonFile(
+      path.join(adspecsDir, 'feature.json'),
+      path.join(pluginDir, '.adspecs/feature.json')
+    );
+    if (featureResult.addedKeys.length > 0) {
+      logger(`🔧 阶段 6 属性补全：feature.json 已补充缺失属性 [${featureResult.addedKeys.join(', ')}]`);
+      stage.featureResult = featureResult;
+    } else {
+      logger(`✅ 阶段 6：feature.json 属性完整，无需补全`);
+    }
+
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  // recreate / update / create
+  let backupFeature = null;
+  let backupProject = null;
+
+  if (decision === 'recreate' && fs.existsSync(adspecsDir)) {
+    // 备份 feature.json / project.json
+    const featurePath = path.join(adspecsDir, 'feature.json');
+    const projectPath = path.join(adspecsDir, 'project.json');
+    if (fs.existsSync(featurePath)) backupFeature = fs.readFileSync(featurePath, 'utf8');
+    if (fs.existsSync(projectPath)) backupProject = fs.readFileSync(projectPath, 'utf8');
+    removeDir(adspecsDir);
+    logger(`🔄 删除旧 .adspecs/ 并重建...`);
+  } else if (decision === 'update') {
+    // update：保留目录，后续覆盖复制
+    fs.mkdirSync(adspecsDir, { recursive: true });
+  }
+
+  // 从插件根目录复制 .adspecs/
+  const result = copyDirFiltered(path.join(pluginDir, '.adspecs'), adspecsDir);
+  stage.fileCount = result.fileCount;
+
+  // recreate 场景：恢复备份并合并
+  if (decision === 'recreate' && (backupFeature || backupProject)) {
+    if (backupFeature) {
+      const featureResult = mergeJsonFile(
+        path.join(adspecsDir, 'feature.json'),
+        path.join(pluginDir, '.adspecs/feature.json')
+      );
+      stage.featureResult = featureResult;
+    }
+    stage.projectJsonBacked = !!backupProject;
+    logger(`🔧 feature.json/project.json 已恢复并补全属性`);
+  }
+
+  stage.status = decision === 'recreate' ? 'recreated' : 'created';
+  const verb = decision === 'recreate' ? '重新复制' : '复制';
+  logger(`✅ 阶段 6 完成：.adspecs/ 配置与脚本目录已${verb}（${result.fileCount} 个文件）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 6.5: 生成 .adspecs/project.json
+ */
+function writeProjectJson(targetDir, pluginDir, values) {
+  const targetPath = path.join(targetDir, '.adspecs/project.json');
+  const referencePath = path.join(pluginDir, '.adspecs/project.json');
+  const created = !fs.existsSync(targetPath);
+
+  const merged = mergeProjectJson(
+    targetPath,
+    { ...values, created_at: new Date().toISOString().slice(0, 10) },
+    referencePath
+  );
+
+  return { created, merged };
+}
+
+/**
+ * 阶段 7: 生成 .adspecs/paths.json
+ */
+function writePathsJson(targetDir) {
+  const targetPath = path.join(targetDir, '.adspecs/paths.json');
+  const created = !fs.existsSync(targetPath);
+
+  if (created) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    const config = generatePathsConfig();
+    fs.writeFileSync(targetPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  }
+
+  return { created };
+}
+
+/**
+ * 根据前端演示源解析前端规范目录名
+ */
+function resolveFrontendStandard(frontDemoSource) {
+  return frontDemoSource === 'antd-front-demo' ? 'ant6-front-standard' : 'ecp-front-standard';
+}
+
+module.exports = { scaffold };

package/src/lib/short-name.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * project_short_name 自动推导
+ *
+ * 规则（与 project-init SKILL.md 保持一致）：
+ * 1. 从 project_name 中提取所有英文字母和数字（去除中文、空格、连字符、下划线等）
+ * 2. 转为小写
+ * 3. 如果结果为空（项目名称全中文），则从 project_dir 推导（去除连字符和下划线）
+ * 4. 如果仍为空，使用 'project' 作为默认值
+ */
+
+/**
+ * 推导 project_short_name
+ * @param {string} projectName - 项目完整名称
+ * @param {string} projectDir - 项目目录名（可选）
+ * @returns {string} 仅包含英文字母和数字的小写短名称
+ */
+function deriveShortName(projectName, projectDir) {
+  // 1. 从 project_name 提取英文字母和数字
+  if (projectName) {
+    const fromName = projectName.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+    if (fromName) return fromName;
+  }
+
+  // 2. 从 project_dir 推导（去除连字符和下划线）
+  if (projectDir) {
+    const fromDir = projectDir.replace(/[-_\s]/g, '').toLowerCase();
+    if (fromDir) return fromDir;
+  }
+
+  // 3. 默认值
+  return 'project';
+}
+
+module.exports = { deriveShortName };

package/src/utils.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * adspecs CLI 通用工具
+ *
+ * 此模块作为 package.json 的 "main" 入口，
+ * 供其他 Node.js 脚本 require('adspecs') 时使用。
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * 获取插件根目录（即 adspecs/ 目录）
+ * @returns {string}
+ */
+function getPluginDir() {
+  return path.resolve(__dirname, '..');
+}
+
+/**
+ * 获取 package.json 内容
+ * @returns {object}
+ */
+function getPkg() {
+  const pkgPath = path.join(getPluginDir(), 'package.json');
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+}
+
+/**
+ * 获取版本号
+ * @returns {string}
+ */
+function getVersion() {
+  return getPkg().version;
+}
+
+/**
+ * 判断目标路径是否在 adspecs 插件目录内
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+function isInsidePlugin(targetPath) {
+  const pluginDir = getPluginDir();
+  const resolved = path.resolve(targetPath);
+  return resolved.startsWith(pluginDir);
+}
+
+/**
+ * 安全读取 JSON 文件
+ * @param {string} filePath
+ * @param {object} [fallback]
+ * @returns {object|null}
+ */
+function safeReadJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * 安全写入 JSON 文件（带 2 空格缩进 + 尾部换行）
+ * @param {string} filePath
+ * @param {object} data
+ */
+function safeWriteJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+module.exports = {
+  getPluginDir,
+  getPkg,
+  getVersion,
+  isInsidePlugin,
+  safeReadJson,
+  safeWriteJson,
+};