adspecs 0.1.12

package/src/lib/paths-defaults.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * .adspecs/paths.json 默认配置
+ *
+ * 各技能读取 paths.json 时，对缺失的 key 使用这些默认值。
+ * 与各技能 SKILL.md 中的硬编码默认值保持一致。
+ */
+
+const DEFAULT_PATHS = {
+  biz_analysis_dir: 'docs/00-customer-requirements',
+  architecture_dir: 'docs/10-architecture',
+  research_output_dir: 'docs/02-prd',
+  sow_dir: 'docs/05-sow',
+  prd_dir: 'docs/20-prd',
+  design_dir: 'docs/30-system-design',
+  test_report_dir: 'docs/80-development',
+  export_dir: 'docs/90-export',
+  wiki_dir: 'wiki',
+};
+
+/**
+ * 生成 paths.json 内容
+ * @returns {object} 完整的 paths.json 对象
+ */
+function generatePathsConfig() {
+  return {
+    $schema: 'adspecs plugin path configuration',
+    version: 1,
+    paths: { ...DEFAULT_PATHS },
+  };
+}
+
+module.exports = {
+  DEFAULT_PATHS,
+  generatePathsConfig,
+};

package/src/lib/prompts.js

@@ -0,0 +1,345 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { input, select, confirm } = require('@inquirer/prompts');
+const { hasAnyFile, isEmptyDirectoryTree } = require('./dir-utils');
+const { areaDisplayName } = require('./area-scanner');
+
+/**
+ * 交互式提示封装
+ *
+ * 处理三种模式：
+ * - 交互模式（默认）：通过 inquirer 提示用户输入
+ * - 非交互模式（--non-interactive）：所有未提供的参数使用默认值
+ * - 强制模式（--force）：所有已存在区域直接 recreate
+ */
+
+// ============================================================
+// 项目信息收集
+// ============================================================
+
+/**
+ * 收集项目信息（5 个字段）
+ *
+ * @param {object} options - CLI 传入的选项
+ * @returns {Promise<object>} 完整的项目信息对象
+ */
+async function collectProjectInfo(options) {
+  const nonInteractive = options.nonInteractive || false;
+
+  // === 第一次收集：核心信息 ===
+  const projectName =
+    options.projectName ||
+    (nonInteractive ? 'my-project' : await input({ message: '请输入项目名称：' }));
+
+  const projectDir =
+    options.projectDir ??
+    (nonInteractive
+      ? ''
+      : await input({ message: '请输入项目目录名（留空=当前目录）：', default: '' }));
+
+  // === 初始化模式 ===
+  const mode =
+    options.mode ||
+    (nonInteractive
+      ? 'simple'
+      : await select({
+          message: '请选择初始化模式：',
+          choices: [
+            { name: '简易模式 — 仅文档目录 (docs + wiki)', value: 'simple' },
+            { name: '经典模式 — 文档 + 前端演示 (+ front-demo)', value: 'classic' },
+            { name: '完整模式 — 所有目录 (+ web-ui + service)', value: 'full' },
+            { name: '轻量模式 — Python+React 全栈 demo', value: 'demo' },
+          ],
+        }));
+
+  // === 前端技术栈（仅 classic/full 模式需要选择） ===
+  let frontDemo = options.frontDemo || 'vue';
+  if ((mode === 'classic' || mode === 'full') && !options.frontDemo && !nonInteractive) {
+    frontDemo = await select({
+      message: '请选择前端演示技术栈：',
+      choices: [
+        { name: 'Vue（Vue 3 + Vite + TypeScript + Element Plus）', value: 'vue' },
+        { name: 'Ant Design React（React + Ant Design 6）', value: 'antd' },
+        { name: '跳过 — 不创建前端演示项目', value: 'skip' },
+      ],
+    });
+  }
+  if (mode === 'demo') {
+    frontDemo = 'antd'; // 轻量模式固定 Ant Design React
+  }
+
+  // === 第二次收集：补充信息 ===
+  const companyName =
+    options.company ||
+    (nonInteractive
+      ? 'XX有限公司'
+      : await input({
+          message: '请输入公司名称（不填默认"XX有限公司"）：',
+          default: 'XX有限公司',
+        }));
+
+  const confidentiality =
+    options.confidentiality && options.confidentiality !== '内部资料'
+      ? options.confidentiality
+      : nonInteractive
+        ? '内部资料'
+        : await select({
+            message: '请选择文件密级（不选默认"内部资料"）：',
+            choices: [
+              { name: '内部资料（默认） — 仅限公司内部使用', value: '内部资料' },
+              { name: '公开 — 可对外公开', value: '公开' },
+              { name: '机密 — 限授权人员访问', value: '机密' },
+              { name: '绝密 — 最高保密等级', value: '绝密' },
+            ],
+          });
+
+  return {
+    project_name: projectName,
+    project_dir: projectDir,
+    company_name: companyName,
+    confidentiality,
+    mode,
+    frontDemo,
+    modules: options.modules || '3100-crm-mdm:mdm,3103-crm-contract:contract',
+  };
+}
+
+// ============================================================
+// 冲突决策（每区域 3 选项）
+// ============================================================
+
+/**
+ * 收集每区域的冲突决策
+ *
+ * @param {object} areaStates - 区域状态映射（来自 scanAreaStates）
+ * @param {object} options - CLI 选项
+ * @returns {Promise<object>} 决策映射 { areaKey: 'create'|'recreate'|'update'|'skip' }
+ */
+async function collectDecisions(areaStates, options) {
+  const force = options.force || false;
+  const nonInteractive = options.nonInteractive || false;
+
+  // --force：所有已存在区域直接 recreate
+  if (force) {
+    const decisions = {};
+    for (const [key, state] of Object.entries(areaStates)) {
+      decisions[key] = state.exists ? 'recreate' : 'create';
+    }
+    return decisions;
+  }
+
+  // --non-interactive：所有已存在区域 skip（保留现有）
+  if (nonInteractive) {
+    const decisions = {};
+    for (const [key, state] of Object.entries(areaStates)) {
+      decisions[key] = state.exists ? 'skip' : 'create';
+    }
+    return decisions;
+  }
+
+  // 交互模式：对每个已存在区域调用 3 选项 prompt
+  const decisions = {};
+  const existingAreas = Object.entries(areaStates).filter(([, state]) => state.exists);
+
+  if (existingAreas.length === 0) {
+    // 所有区域都不存在 → 全部 create
+    for (const key of Object.keys(areaStates)) {
+      decisions[key] = 'create';
+    }
+    return decisions;
+  }
+
+  // 提示用户是否要逐个确认
+  if (existingAreas.length >= 2) {
+    const bulkChoice = await select({
+      message: `检测到 ${existingAreas.length} 个区域已存在，如何统一处理？`,
+      choices: [
+        { name: '逐个确认 — 对每个区域分别选择处理方式', value: 'ask-each' },
+        { name: '全部重新创建 — 删除并重建所有已存在区域', value: 'recreate-all' },
+        { name: '全部跳过 — 保留所有已存在区域', value: 'skip-all' },
+      ],
+    });
+
+    if (bulkChoice === 'recreate-all') {
+      for (const [key, state] of Object.entries(areaStates)) {
+        decisions[key] = state.exists ? 'recreate' : 'create';
+      }
+      return decisions;
+    }
+    if (bulkChoice === 'skip-all') {
+      for (const [key, state] of Object.entries(areaStates)) {
+        decisions[key] = state.exists ? 'skip' : 'create';
+      }
+      return decisions;
+    }
+    // ask-each: 继续逐个询问
+  }
+
+  // 逐个询问
+  for (const [key, state] of Object.entries(areaStates)) {
+    if (!state.exists) {
+      decisions[key] = 'create';
+    } else {
+      decisions[key] = await askAreaDecision(areaDisplayName(key));
+    }
+  }
+
+  return decisions;
+}
+
+/**
+ * 3 选项冲突决策
+ *
+ * @param {string} areaName - 区域显示名（如 'docs'）
+ * @returns {Promise<'recreate'|'update'|'skip'>}
+ */
+async function askAreaDecision(areaName) {
+  return await select({
+    message: `${areaName}/ 已存在，如何处理？`,
+    choices: [
+      { name: '重新创建 — 删除现有目录，使用最新模板重建', value: 'recreate' },
+      { name: '更新 — 保留现有目录，按新内容覆盖（保留本地修改之外的文件）', value: 'update' },
+      { name: '跳过 — 保留现有目录，不做任何修改', value: 'skip' },
+    ],
+  });
+}
+
+// ============================================================
+// 子目录决策
+// ============================================================
+
+/**
+ * 收集子目录决策（仅当父目录 skip 时）
+ *
+ * @param {object} decisions - 区域决策
+ * @param {string} targetDir - 目标目录
+ * @param {object} options - CLI 选项
+ * @returns {Promise<object>} 子决策 { conventions, templates }
+ */
+async function collectSubDecisions(decisions, targetDir, options) {
+  const sub = { conventions: 'skip', templates: 'skip' };
+  const nonInteractive = options.nonInteractive || false;
+  const force = options.force || false;
+
+  // --force 模式：全部 skip（因为 recreate 已经完整重建了）
+  if (force) return sub;
+
+  // --non-interactive 模式：全部 skip
+  if (nonInteractive) return sub;
+
+  // conventions_decision：docs/ skip 且 40-project_conventions/ 有文件
+  if (decisions.docs === 'skip') {
+    const convDir = path.join(targetDir, 'docs/40-project_conventions');
+    if (fs.existsSync(convDir) && hasAnyFile(convDir)) {
+      sub.conventions = await askSubDecision('docs/40-project_conventions');
+    }
+  }
+
+  // templates_decision：.adspecs/ skip 且 templates/ 有文件
+  if (decisions.adspecs === 'skip') {
+    const tmplDir = path.join(targetDir, '.adspecs/templates');
+    if (fs.existsSync(tmplDir) && hasAnyFile(tmplDir)) {
+      sub.templates = await askSubDecision('.adspecs/templates');
+    }
+  }
+
+  return sub;
+}
+
+/**
+ * 子目录更新决策（2 选项）
+ *
+ * @param {string} subDirName - 子目录显示名
+ * @returns {Promise<'update'|'skip'>}
+ */
+async function askSubDecision(subDirName) {
+  return await select({
+    message: `${subDirName}/ 目录已存在且包含文件，是否使用最新规范文件更新？`,
+    choices: [
+      { name: '更新 — 使用最新文件覆盖现有内容', value: 'update' },
+      { name: '跳过 — 保留现有内容，不做任何修改', value: 'skip' },
+    ],
+  });
+}
+
+// ============================================================
+// 模式升级检测
+// ============================================================
+
+/**
+ * 检测模式升级场景（simple → classic/full/demo）
+ *
+ * 当 docs/ 已存在且 skip，且当前模式为 classic/full/demo，
+ * 检查 40-project_conventions/frontend-standard/ 是否为空（简易模式产物特征）。
+ * 如果是，则需要自动补充 frontend-standard/ 文件。
+ *
+ * 简易模式会在 40-project_conventions/ 下生成 README.md 并创建空子目录
+ * frontend-standard/ 和 end-standard/，因此不能检查整个 40 目录，而要检查
+ * frontend-standard/ 子目录是否为空。
+ *
+ * @param {object} decisions - 区域决策
+ * @param {string} mode - 当前模式
+ * @param {string} targetDir - 目标目录
+ * @returns {object} { detected, emptyDirs }
+ */
+function detectModeUpgrade(decisions, mode, targetDir) {
+  // 仅 classic/full/demo 模式需要检测
+  if (mode === 'simple') {
+    return { detected: false, emptyDirs: [] };
+  }
+
+  // 仅当 docs/ 为 skip 时才有意义
+  if (decisions.docs !== 'skip') {
+    return { detected: false, emptyDirs: [] };
+  }
+
+  const frontendStdDir = path.join(targetDir, 'docs/40-project_conventions/frontend-standard');
+  if (!fs.existsSync(frontendStdDir)) {
+    return { detected: false, emptyDirs: [] };
+  }
+
+  // 检查 frontend-standard/ 是否为空（无任何文件）
+  // 注意：不使用 isEmptyDirectoryTree，因为我们要检查的是这个特定子目录
+  if (!hasAnyFile(frontendStdDir)) {
+    return {
+      detected: true,
+      emptyDirs: ['40-project_conventions/frontend-standard/'],
+    };
+  }
+
+  return { detected: false, emptyDirs: [] };
+}
+
+// ============================================================
+// 执行前确认
+// ============================================================
+
+/**
+ * 执行前确认
+ *
+ * @param {object} options - CLI 选项
+ * @returns {Promise<boolean>}
+ */
+async function confirmExecution(options) {
+  // --force / --non-interactive / --yes 自动确认
+  if (options.force || options.nonInteractive || options.yes) {
+    return true;
+  }
+
+  return await confirm({
+    message: '是否继续执行以上计划？',
+    default: true,
+  });
+}
+
+module.exports = {
+  collectProjectInfo,
+  collectDecisions,
+  collectSubDecisions,
+  detectModeUpgrade,
+  confirmExecution,
+  askAreaDecision,
+  askSubDecision,
+};

package/src/lib/readme-gen.js

@@ -0,0 +1,143 @@
+'use strict';
+
+/**
+ * README.md 模板生成
+ *
+ * 与 project-init SKILL.md 中定义的 README.md 模板格式保持一致。
+ */
+
+const TODAY = new Date().toISOString().slice(0, 10);
+
+/**
+ * 生成标准 README.md 内容
+ *
+ * @param {object} opts
+ * @param {string} opts.title - 目录名称（作为 H1）
+ * @param {string} opts.purpose - 用途说明
+ * @param {Array<{name: string, desc: string}>} [opts.subdirs] - 子目录说明列表
+ * @param {string} [opts.namingConvention] - 文件命名规范
+ * @param {string} [opts.date] - 修订日期（默认今天）
+ * @returns {string}
+ */
+function generateReadme({ title, purpose, subdirs = [], namingConvention = '', date = TODAY }) {
+  const lines = [`# ${title}`, '', purpose, ''];
+
+  if (subdirs.length > 0) {
+    lines.push('## 目录说明', '', '| 子目录 | 说明 |', '| --- | --- |');
+    for (const sub of subdirs) {
+      lines.push(`| ${sub.name} | ${sub.desc} |`);
+    }
+    lines.push('');
+  }
+
+  if (namingConvention) {
+    lines.push('## 文件命名规范', '', namingConvention, '');
+  }
+
+  lines.push(
+    '## 修订记录',
+    '',
+    '| 日期 | 版本 | 修改内容 | 修改人 |',
+    '| --- | --- | --- | --- |',
+    `| ${date} | 1.0 | 初始创建 | system |`,
+    ''
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * 各 docs 子目录的 README 元数据
+ */
+const DOCS_READMES = {
+  '00-planning': {
+    title: '00-planning',
+    purpose: '规划阶段文档，存放平台级规划产物（业务场景、子模块依赖关系、统一数据模型等）。',
+    namingConvention: '`{seq}-{name}.md`（如 `01-smom-wms_business_architecture.md`）',
+  },
+  '00-customer-requirements': {
+    title: '00-customer-requirements',
+    purpose: '客户需求文档，存放客户原始需求、会议纪要、需求沟通记录。',
+    subdirs: [{ name: 'crm/', desc: 'CRM 模块客户需求' }],
+  },
+  '10-architecture': {
+    title: '10-architecture',
+    purpose: '架构文档，系统架构设计、模块依赖关系、统一数据模型。',
+    namingConvention: '`{seq}-{name}.md`（如 `01-smom-wms_business_architecture.md`）',
+  },
+  '20-prd': {
+    title: '20-prd',
+    purpose: 'PRD 文档，产品需求说明书。',
+    subdirs: [{ name: 'crm/', desc: 'CRM 模块 PRD' }],
+    namingConvention: '`{module-code}-{module-name}/` 下存放',
+  },
+  '30-system-design': {
+    title: '30-system-design',
+    purpose: '系统设计，后端系统设计、SQL Schema、前端设计、TDD 任务清单。',
+    subdirs: [{ name: 'crm/', desc: 'CRM 模块系统设计' }],
+    namingConvention:
+      '`{module-code}-{module-name}_system-design.md`、`{module-code}-{module-name}_schema.sql`',
+  },
+  '40-project_conventions': {
+    title: '40-project_conventions',
+    purpose: '项目约定，前后端集成开发规范和接口约定。',
+    subdirs: [
+      { name: 'frontend-standard/', desc: '前端约定（按技术栈来源不同）' },
+      { name: 'end-standard/', desc: '后端约定（仅轻量模式复制 Python 后端规范）' },
+    ],
+  },
+  '70-scripts': {
+    title: '70-scripts',
+    purpose: '脚本，部署脚本和工具脚本。',
+    subdirs: [{ name: 'depoly/', desc: '部署相关脚本' }],
+  },
+  '80-development': {
+    title: '80-development',
+    purpose: '开发产物，开发工件和测试工件归档。',
+    subdirs: [
+      { name: '800-log/', desc: '开发日志，AI 会话记录和开发历史追踪' },
+      { name: '801-dev/', desc: '开发工件' },
+      { name: '802-test/', desc: '测试工件' },
+    ],
+    namingConvention: '`{YYYYMMDD}_{主题}.md` 或 `{YYYYMMDD_HHmmss}_{主题}.md`',
+  },
+  '100-help': {
+    title: '100-help',
+    purpose: '帮助文档，使用手册和参考指南。',
+  },
+  '300-specs': {
+    title: '300-specs',
+    purpose: '功能规格说明书。',
+    namingConvention: '`p{module}-{seq}_{name}_spec.md`，配套 `p{module}-{seq}_{name}_sim-data.md`',
+  },
+};
+
+/**
+ * 生成 wiki/README.md
+ */
+function generateWikiReadme(date = TODAY) {
+  return generateReadme({
+    title: 'wiki',
+    purpose:
+      '基线文件目录，用于存放项目级别的基线规格文件，包括功能规格、接口规格、数据规格等。',
+    subdirs: [{ name: '（按需创建）', desc: '按模块或主题组织基线文件' }],
+    namingConvention: '`{module}-{name}_spec.md`',
+    date,
+  });
+}
+
+/**
+ * 生成 service/README.md
+ */
+function generateServiceReadme() {
+  return (
+    '这是后端服务模块放置目录，在完成技术架构设计后，所有后端服务模块的源代码将放置在此目录下。\n'
+  );
+}
+
+module.exports = {
+  generateReadme,
+  generateWikiReadme,
+  generateServiceReadme,
+  DOCS_READMES,
+};