@ecc-hgy/ae 0.4.0 → 0.6.0

package/src/utils/copy.js

@@ -1,100 +1,100 @@
-import { copyFile, chmod, mkdir, readdir, stat, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-
-export async function copyTreeIdempotent(srcDir, destDir, options = {}) {
-  const dryRun = Boolean(options.dryRun);
-  const created = [];
-  const skipped = [];
-
-  const source = await stat(srcDir);
-  if (!source.isDirectory()) {
-    throw new Error(`source is not a directory: ${srcDir}`);
-  }
-
-  await walk(srcDir, '');
-
-  return { created, skipped };
-
-  async function walk(currentSourceDir, relativeDir) {
-    const entries = await readdir(currentSourceDir, { withFileTypes: true });
-    const currentDestDir = path.join(destDir, relativeDir);
-
-    if (!dryRun) {
-      await mkdir(currentDestDir, { recursive: true });
-    }
-
-    if (entries.length === 0) {
-      const marker = normalizeRelative(path.join(relativeDir, '.gitkeep'));
-      const markerDest = path.join(currentDestDir, '.gitkeep');
-      if (await exists(markerDest)) {
-        skipped.push(marker);
-      } else {
-        created.push(marker);
-        if (!dryRun) {
-          await writeFile(markerDest, '');
-        }
-      }
-      return;
-    }
-
-    for (const entry of entries) {
-      const relativePath = path.join(relativeDir, entry.name);
-      const sourcePath = path.join(currentSourceDir, entry.name);
-      const destPath = path.join(destDir, relativePath);
-
-      if (entry.isDirectory()) {
-        await walk(sourcePath, relativePath);
-      } else if (entry.isFile()) {
-        const normalized = normalizeRelative(relativePath);
-        if (await exists(destPath)) {
-          skipped.push(normalized);
-        } else {
-          created.push(normalized);
-          if (!dryRun) {
-            await mkdir(path.dirname(destPath), { recursive: true });
-            await copyFile(sourcePath, destPath);
-            const mode = (await stat(sourcePath)).mode & 0o777;
-            await chmod(destPath, mode);
-          }
-        }
-      }
-    }
-  }
-}
-
-export async function copyFileIdempotent(srcFile, destFile, options = {}) {
-  const dryRun = Boolean(options.dryRun);
-  const source = await stat(srcFile);
-  if (!source.isFile()) {
-    throw new Error(`source is not a file: ${srcFile}`);
-  }
-
-  const relative = path.basename(destFile);
-  if (await exists(destFile)) {
-    return { created: [], skipped: [relative] };
-  }
-
-  if (!dryRun) {
-    await mkdir(path.dirname(destFile), { recursive: true });
-    await copyFile(srcFile, destFile);
-    await chmod(destFile, source.mode & 0o777);
-  }
-
-  return { created: [relative], skipped: [] };
-}
-
-async function exists(value) {
-  try {
-    await stat(value);
-    return true;
-  } catch (error) {
-    if (error?.code === 'ENOENT') {
-      return false;
-    }
-    throw error;
-  }
-}
-
-function normalizeRelative(value) {
-  return value.split(path.sep).join('/');
-}
+import { copyFile, chmod, mkdir, readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export async function copyTreeIdempotent(srcDir, destDir, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const created = [];
+  const skipped = [];
+
+  const source = await stat(srcDir);
+  if (!source.isDirectory()) {
+    throw new Error(`source is not a directory: ${srcDir}`);
+  }
+
+  await walk(srcDir, '');
+
+  return { created, skipped };
+
+  async function walk(currentSourceDir, relativeDir) {
+    const entries = await readdir(currentSourceDir, { withFileTypes: true });
+    const currentDestDir = path.join(destDir, relativeDir);
+
+    if (!dryRun) {
+      await mkdir(currentDestDir, { recursive: true });
+    }
+
+    if (entries.length === 0) {
+      const marker = normalizeRelative(path.join(relativeDir, '.gitkeep'));
+      const markerDest = path.join(currentDestDir, '.gitkeep');
+      if (await exists(markerDest)) {
+        skipped.push(marker);
+      } else {
+        created.push(marker);
+        if (!dryRun) {
+          await writeFile(markerDest, '');
+        }
+      }
+      return;
+    }
+
+    for (const entry of entries) {
+      const relativePath = path.join(relativeDir, entry.name);
+      const sourcePath = path.join(currentSourceDir, entry.name);
+      const destPath = path.join(destDir, relativePath);
+
+      if (entry.isDirectory()) {
+        await walk(sourcePath, relativePath);
+      } else if (entry.isFile()) {
+        const normalized = normalizeRelative(relativePath);
+        if (await exists(destPath)) {
+          skipped.push(normalized);
+        } else {
+          created.push(normalized);
+          if (!dryRun) {
+            await mkdir(path.dirname(destPath), { recursive: true });
+            await copyFile(sourcePath, destPath);
+            const mode = (await stat(sourcePath)).mode & 0o777;
+            await chmod(destPath, mode);
+          }
+        }
+      }
+    }
+  }
+}
+
+export async function copyFileIdempotent(srcFile, destFile, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const source = await stat(srcFile);
+  if (!source.isFile()) {
+    throw new Error(`source is not a file: ${srcFile}`);
+  }
+
+  const relative = path.basename(destFile);
+  if (await exists(destFile)) {
+    return { created: [], skipped: [relative] };
+  }
+
+  if (!dryRun) {
+    await mkdir(path.dirname(destFile), { recursive: true });
+    await copyFile(srcFile, destFile);
+    await chmod(destFile, source.mode & 0o777);
+  }
+
+  return { created: [relative], skipped: [] };
+}
+
+async function exists(value) {
+  try {
+    await stat(value);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function normalizeRelative(value) {
+  return value.split(path.sep).join('/');
+}

package/src/utils/paths.js

@@ -1,60 +1,60 @@
-import { existsSync } from 'node:fs';
-import { access } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-let cachedPackageRoot;
-
-export async function packageRootAsync() {
-  if (cachedPackageRoot) {
-    return cachedPackageRoot;
-  }
-
-  let current = path.dirname(fileURLToPath(import.meta.url));
-  while (true) {
-    const candidate = path.join(current, 'package.json');
-    try {
-      await access(candidate);
-      cachedPackageRoot = current;
-      return cachedPackageRoot;
-    } catch {
-      const parent = path.dirname(current);
-      if (parent === current) {
-        throw new Error('Could not find package.json from current module path.');
-      }
-      current = parent;
-    }
-  }
-}
-
-export function packageRoot() {
-  if (cachedPackageRoot) {
-    return cachedPackageRoot;
-  }
-
-  let current = path.dirname(fileURLToPath(import.meta.url));
-  while (true) {
-    if (existsSync(path.join(current, 'package.json'))) {
-      cachedPackageRoot = current;
-      return cachedPackageRoot;
-    }
-
-    const parent = path.dirname(current);
-    if (parent === current) {
-      throw new Error('Could not find package.json from current module path.');
-    }
-    current = parent;
-  }
-}
-
-export function assetPath(name) {
-  return path.join(packageRoot(), name);
-}
-
-export function skillsPath() {
-  return path.join(packageRoot(), 'skills');
-}
-
-export function templatesPath(subdir = '') {
-  return path.join(packageRoot(), 'templates', subdir);
-}
+import { existsSync } from 'node:fs';
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let cachedPackageRoot;
+
+export async function packageRootAsync() {
+  if (cachedPackageRoot) {
+    return cachedPackageRoot;
+  }
+
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = path.join(current, 'package.json');
+    try {
+      await access(candidate);
+      cachedPackageRoot = current;
+      return cachedPackageRoot;
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) {
+        throw new Error('Could not find package.json from current module path.');
+      }
+      current = parent;
+    }
+  }
+}
+
+export function packageRoot() {
+  if (cachedPackageRoot) {
+    return cachedPackageRoot;
+  }
+
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    if (existsSync(path.join(current, 'package.json'))) {
+      cachedPackageRoot = current;
+      return cachedPackageRoot;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error('Could not find package.json from current module path.');
+    }
+    current = parent;
+  }
+}
+
+export function assetPath(name) {
+  return path.join(packageRoot(), name);
+}
+
+export function skillsPath() {
+  return path.join(packageRoot(), 'skills');
+}
+
+export function templatesPath(subdir = '') {
+  return path.join(packageRoot(), 'templates', subdir);
+}

package/src/utils/report.js

@@ -1,30 +1,30 @@
-export function formatSetupReport({ created, skipped, target, dryRun }) {
-  const installedLabel = dryRun ? 'Would install' : 'Installed';
-  return [
-    dryRun ? 'AE setup dry run complete' : 'AE setup complete',
-    `- ${installedLabel}: ${created.length} (${summarize(created)})`,
-    `- Skipped: ${skipped.length} (${summarize(skipped)})`,
-    `- Target: ${target}`,
-    `- Next: run \`ae init "<goal>"\`.`,
-  ].join('\n');
-}
-
-export function formatInitReport({ created, skipped, target, dryRun }) {
-  const createdLabel = dryRun ? 'Would create' : 'Created';
-  return [
-    dryRun ? 'AE init dry run complete' : 'AE init complete',
-    `- ${createdLabel}: ${created.length} (${summarize(created)})`,
-    `- Skipped: ${skipped.length} (${summarize(skipped)})`,
-    `- Target: ${target}`,
-  ].join('\n');
-}
-
-function summarize(paths) {
-  if (paths.length === 0) {
-    return 'none';
-  }
-  if (paths.length <= 8) {
-    return paths.join(', ');
-  }
-  return `${paths.slice(0, 8).join(', ')}, ...`;
-}
+export function formatSetupReport({ created, skipped, target, dryRun }) {
+  const installedLabel = dryRun ? 'Would install' : 'Installed';
+  return [
+    dryRun ? 'AE setup dry run complete' : 'AE setup complete',
+    `- ${installedLabel}: ${created.length} (${summarize(created)})`,
+    `- Skipped: ${skipped.length} (${summarize(skipped)})`,
+    `- Target: ${target}`,
+    `- Next: run \`ae init "<goal>"\`.`,
+  ].join('\n');
+}
+
+export function formatInitReport({ created, skipped, target, dryRun }) {
+  const createdLabel = dryRun ? 'Would create' : 'Created';
+  return [
+    dryRun ? 'AE init dry run complete' : 'AE init complete',
+    `- ${createdLabel}: ${created.length} (${summarize(created)})`,
+    `- Skipped: ${skipped.length} (${summarize(skipped)})`,
+    `- Target: ${target}`,
+  ].join('\n');
+}
+
+function summarize(paths) {
+  if (paths.length === 0) {
+    return 'none';
+  }
+  if (paths.length <= 8) {
+    return paths.join(', ');
+  }
+  return `${paths.slice(0, 8).join(', ')}, ...`;
+}

package/templates/entries/AGENTS.md

@@ -1,3 +1,5 @@
 # {{PROJECT_NAME}}
 
 > {{PROJECT_GOAL}}
+
+- **目录按职责聚合、信息渐进披露**:除已有明确规范、框架约定或工具生成的目录外,手工维护的文件按职责或主题组织,避免无关文件长期平铺;入口保留概要与导航,细节随复杂度按需下沉,不为分层而分层;新增或修改时检查涉及范围的归属与边界,调整结构同步相关引用与说明。

package/templates/entries/CLAUDE.md

@@ -1,5 +1,5 @@
-# {{PROJECT_NAME}}
-
-**Always read [AGENTS.md](./AGENTS.md) at the start of every session before doing any work.**
-
-This project's instructions, rules, structure, and operating guidelines are all defined in `AGENTS.md`.
+# {{PROJECT_NAME}}
+
+**Always read [AGENTS.md](./AGENTS.md) at the start of every session before doing any work.**
+
+This project's instructions, rules, structure, and operating guidelines are all defined in `AGENTS.md`.

package/templates/entries/README.md

@@ -1,32 +1,34 @@
-# {{PROJECT_NAME}}
-
-> {{PROJECT_GOAL}}
-
-<!--
-根 README 的核心:让别人 30 秒搞清「为什么有用、能做什么、怎么用」。
-下面是建议骨架,按需增删、不必都填,也不必拘泥小节名:
-- 它是什么 + 一句话价值 → 上面的标题 + 一行(已占位)
-- 为什么 / 给谁 → 解决什么问题、面向谁
-- Quick Start → 最快见效的一段命令 / 步骤(装好 + 第一个能见效的操作)
-- 使用示例 → 典型场景(必要时再贴一段真实用法)
-- 目录地图 / 文档入口 → 关键目录 + 深入文档的链接
--->
-
-## 这是什么
-
-TODO: 一段话说清它解决什么问题、给谁用、用它能做什么。
-
-## Quick Start
-
-TODO: 最快跑起来的命令或步骤。
-
-<!-- ## 使用示例 —— 有典型场景时再加,贴一段真实用法 -->
-
-## 目录地图
-
+# {{PROJECT_NAME}}
+
+> {{PROJECT_GOAL}}
+
+<!--
+根 README 的核心:让别人 30 秒搞清「为什么有用、能做什么、怎么用」。
+下面是建议骨架,按需增删、不必都填,也不必拘泥小节名:
+- 它是什么 + 一句话价值 → 上面的标题 + 一行(已占位)
+- 为什么 / 给谁 → 解决什么问题、面向谁
+- Quick Start → 最快见效的一段命令 / 步骤(装好 + 第一个能见效的操作)
+- 使用示例 → 典型场景(必要时再贴一段真实用法)
+- 目录地图 / 文档入口 → 关键目录 + 深入文档的链接
+-->
+
+## 这是什么
+
+TODO: 一段话说清它解决什么问题、给谁用、用它能做什么。
+
+## Quick Start
+
+TODO: 最快跑起来的命令或步骤。
+
+<!-- ## 使用示例 —— 有典型场景时再加,贴一段真实用法 -->
+
+## 目录地图
+
 - `spec/`:SDD/TDD 规格产物——需求索引看 `spec/INDEX.md`,项目地图看 `spec/README.md`。
-- `reference/`:原始素材,只读心态。
-- `data/`:运行产物、导出、缓存。
-- `scripts/`:辅助脚本。
-
-<!-- 文档入口:AGENTS.md(项目指令)· handoff.md(当前态快照)· spec/INDEX.md(需求索引) -->
+- `src/`:业务代码、程序入口与脚本;按职责组织,不要求与 `spec/needs/` 一一对应。
+- `tests/`:测试代码与测试样例。
+- `docs/`:原始文档资料、说明与长期维护的知识。
+- `data/`:各类数据与运行结果,内部按项目需要渐进组织。
+- `dist/`:构建产物;有构建时由工具生成。
+
+<!-- 文档入口:AGENTS.md(项目指令)· handoff.md(当前态快照)· spec/INDEX.md(需求索引) -->

package/templates/entries/handoff.md

@@ -1 +1 @@
-<!-- 跨会话/跨项目进展交接，由 handoff skill 在会话结束时人工触发更新。 -->
+<!-- 跨会话/跨项目进展交接，由 handoff skill 在会话结束时人工触发更新。 -->

package/templates/entries/spec/ADR/AGENTS.md

@@ -1,30 +1,30 @@
-# spec/ADR/ 规则
-
-> 架构决策记录(ADR)规则。在 `spec/ADR/` 下创建或修改 ADR 时遵守本文件。
-
-## 命名
-
-`NNNN-<标题>.md`,**4 位序号**,kebab-case 标题。例:`0001-postgres-as-primary-store.md`。
-
-## frontmatter
-
-```yaml
----
-status: accepted          # proposed | accepted | superseded
-date: 2026-06-14
-supersedes: 0000-xxx.md   # 仅当取代旧 ADR 时填
----
-```
-
-正文按具体决策自然组织(背景 / 决策 / 理由 / 影响),不强加重模板。
-
-## 状态机
-
-```text
-proposed ─(评审接受)─► accepted ─(新 ADR 取代)─► superseded
-```
-
-- `proposed`:新提案,未拍板(由 writing-plans / review / improve-codebase-architecture 创建时默认)。
-- `accepted`:已评审接受;视为**约束**,其他需求不得违背。
-- `superseded`:被新 ADR 取代;新 ADR 的 `supersedes` 指回旧编号,**不删旧文件**。
-
+# spec/ADR/ 规则
+
+> 架构决策记录(ADR)规则。在 `spec/ADR/` 下创建或修改 ADR 时遵守本文件。
+
+## 命名
+
+`NNNN-<标题>.md`,**4 位序号**,kebab-case 标题。例:`0001-postgres-as-primary-store.md`。
+
+## frontmatter
+
+```yaml
+---
+status: accepted          # proposed | accepted | superseded
+date: 2026-06-14
+supersedes: 0000-xxx.md   # 仅当取代旧 ADR 时填
+---
+```
+
+正文按具体决策自然组织(背景 / 决策 / 理由 / 影响),不强加重模板。
+
+## 状态机
+
+```text
+proposed ─(评审接受)─► accepted ─(新 ADR 取代)─► superseded
+```
+
+- `proposed`:新提案,未拍板(由 writing-plans / review / improve-codebase-architecture 创建时默认)。
+- `accepted`:已评审接受;视为**约束**,其他需求不得违背。
+- `superseded`:被新 ADR 取代;新 ADR 的 `supersedes` 指回旧编号,**不删旧文件**。
+

package/templates/entries/spec/ADR/CLAUDE.md

@@ -1,5 +1,5 @@
-# spec/ADR/
-
-**Always read [AGENTS.md](./AGENTS.md) in this directory before creating or editing an ADR.**
-
-`spec/ADR/AGENTS.md` defines ADR naming, frontmatter, and the proposed/accepted/superseded state machine.
+# spec/ADR/
+
+**Always read [AGENTS.md](./AGENTS.md) in this directory before creating or editing an ADR.**
+
+`spec/ADR/AGENTS.md` defines ADR naming, frontmatter, and the proposed/accepted/superseded state machine.

package/templates/entries/spec/AGENTS.md

@@ -1,35 +1,35 @@
-# spec/ 规则
-
-> 本目录(`spec/`)的工作规则。在 `spec/` 下读写文件时遵守本文件。
-
-## 总领
-
-S1 节点 → 产物 → skill 的路由总览,见随包的 `using-agentic-engineering` skill——它判定"进不进 AE 流程"并分发到各节点。
-
-两道硬门禁:**A1 未对齐不写 prd**;**B2 期望态未对齐不修复**。
-
-
-## R1:落盘后同步 INDEX
-落盘 `spec/needs/<需求名>/` 下任何文件后,**必须同步更新 `spec/INDEX.md`** 对应行。若不确定如何更新,按上面「INDEX 推导规则」手动重算(未来可用 `ae index-rebuild` 幂等重扫)。
-
-### INDEX 推导规则
-
-`spec/INDEX.md` 给模型看:一次扫描看到所有需求 + 状态 + 进度。`当前节点` 列**不存储**在任何 frontmatter,由该需求下文件状态**实时推导**:
-
-| 条件 | 当前节点 |
-|------|---------|
-| prd 不存在 或 status=draft | A1 / A2 |
-| prd active + design 不存在/draft | A3 设计 |
-| prd+design active + todo 不存在 | A4 拆解 |
-| prd+design active + todo 有未完成项 | A5 执行 |
-| todo 全勾 + 未端到端验证 | A6 verify |
-| 所有 issues 已验收 + 已交付 | 已完成 |
-| 存在 active 的 issues | 进 B 子路径,按 issues 状态推 B2…B7 |
-| prd / design 任一 archived | 已归档 |
-
-- INDEX 是**推导态**:文件状态变就重新推导,**不要手编 `当前节点` 列**。
-
-
-## 何时升 ADR
-
+# spec/ 规则
+
+> 本目录(`spec/`)的工作规则。在 `spec/` 下读写文件时遵守本文件。
+
+## 总领
+
+S1 节点 → 产物 → skill 的路由总览,见随包的 `using-agentic-engineering` skill——它判定"进不进 AE 流程"并分发到各节点。
+
+两道硬门禁:**A1 未对齐不写 prd**;**B2 期望态未对齐不修复**。
+
+
+## R1:落盘后同步 INDEX
+落盘 `spec/needs/<需求名>/` 下任何文件后,**必须同步更新 `spec/INDEX.md`** 对应行。若不确定如何更新,按上面「INDEX 推导规则」手动重算(未来可用 `ae index-rebuild` 幂等重扫)。
+
+### INDEX 推导规则
+
+`spec/INDEX.md` 给模型看:一次扫描看到所有需求 + 状态 + 进度。`当前节点` 列**不存储**在任何 frontmatter,由该需求下文件状态**实时推导**:
+
+| 条件 | 当前节点 |
+|------|---------|
+| prd 不存在 或 status=draft | A1 / A2 |
+| prd active + design 不存在/draft | A3 设计 |
+| prd+design active + todo 不存在 | A4 拆解 |
+| prd+design active + todo 有未完成项 | A5 执行 |
+| todo 全勾 + 未端到端验证 | A6 verify |
+| 所有 issues 已验收 + 已交付 | 已完成 |
+| 存在 active 的 issues | 进 B 子路径,按 issues 状态推 B2…B7 |
+| prd / design 任一 archived | 已归档 |
+
+- INDEX 是**推导态**:文件状态变就重新推导,**不要手编 `当前节点` 列**。
+
+
+## 何时升 ADR
+
 决策影响**多个需求**或属项目级不变量时,从 `design.md` 升到`spec/ADR`(判断:推翻它会改动 >1 个需求)。单需求的技术决策留在该需求的 `design.md`。

package/templates/entries/spec/CLAUDE.md

@@ -1,5 +1,5 @@
-# spec/
-
-**Always read [AGENTS.md](./AGENTS.md) in this directory before working under `spec/`.**
-
-`spec/AGENTS.md` defines the S1 node map, the INDEX derivation table, and the post-write INDEX sync rule (R1).
+# spec/
+
+**Always read [AGENTS.md](./AGENTS.md) in this directory before working under `spec/`.**
+
+`spec/AGENTS.md` defines the S1 node map, the INDEX derivation table, and the post-write INDEX sync rule (R1).