@ecc-hgy/ae 0.5.0 → 0.6.0

package/src/skeleton.js

@@ -1,129 +1,164 @@
-import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-
-const DEFAULT_DRY_RUN = false;
-
-const SKELETON_DIRS = [
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const DEFAULT_DRY_RUN = false;
+
+const CORE_DIRS = [
   'spec',
   path.join('spec', 'needs'),
   path.join('spec', 'ADR'),
-  'reference',
+  'docs',
   'data',
-  'scripts',
 ];
 
-const GITKEEP_DIRS = [
+const CORE_GITKEEP_DIRS = [
   path.join('spec', 'needs'),
   path.join('spec', 'ADR'),
-  'reference',
+  'docs',
   'data',
-  'scripts',
-];
-
-const ENTRY_FILES = [
-  'README.md',
-  'AGENTS.md',
-  'CLAUDE.md',
-  'handoff.md',
-  path.join('spec', 'README.md'),
-  path.join('spec', 'INDEX.md'),
-  path.join('spec', 'AGENTS.md'),
-  path.join('spec', 'CLAUDE.md'),
-  path.join('spec', 'ADR', 'AGENTS.md'),
-  path.join('spec', 'ADR', 'CLAUDE.md'),
 ];
 
+const ALTERNATE_SOURCE_ROOTS = ['app', 'apps', 'lib', 'packages'];
+const ALTERNATE_TEST_ROOTS = ['test', '__tests__'];
+
+const ENTRY_FILES = [
+  'README.md',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'handoff.md',
+  path.join('spec', 'README.md'),
+  path.join('spec', 'INDEX.md'),
+  path.join('spec', 'AGENTS.md'),
+  path.join('spec', 'CLAUDE.md'),
+  path.join('spec', 'ADR', 'AGENTS.md'),
+  path.join('spec', 'ADR', 'CLAUDE.md'),
+];
+
 export async function createDirectories(target, options = {}) {
   const dryRun = Boolean(options.dryRun ?? DEFAULT_DRY_RUN);
   const created = [];
   const skipped = [];
   const updated = [];
+  const skeletonDirs = [...CORE_DIRS];
+  const gitkeepDirs = [...CORE_GITKEEP_DIRS];
 
-  for (const dir of SKELETON_DIRS) {
-    const absolute = path.join(target, dir);
-    const display = `${normalizeRelative(dir)}/`;
-
-    if (await exists(absolute)) {
-      const current = await stat(absolute);
-      if (!current.isDirectory()) {
-        throw new Error(`expected directory but found file: ${absolute}`);
-      }
-      skipped.push(display);
-    } else {
-      created.push(display);
-      if (!dryRun) {
-        await mkdir(absolute, { recursive: true });
-      }
-    }
+  if (await shouldIncludeDefaultRoot(target, 'src', ALTERNATE_SOURCE_ROOTS)) {
+    skeletonDirs.push('src');
+    gitkeepDirs.push('src');
   }
 
-  for (const dir of GITKEEP_DIRS) {
-    const file = path.join(target, dir, '.gitkeep');
-    const display = normalizeRelative(path.join(dir, '.gitkeep'));
-
-    if (await exists(file)) {
-      skipped.push(display);
-    } else {
-      created.push(display);
-      if (!dryRun) {
-        await mkdir(path.dirname(file), { recursive: true });
-        await writeFile(file, '');
-      }
-    }
+  if (await shouldIncludeDefaultRoot(target, 'tests', ALTERNATE_TEST_ROOTS)) {
+    skeletonDirs.push('tests');
+    gitkeepDirs.push('tests');
   }
 
-  return { created, skipped, updated };
+  for (const dir of skeletonDirs) {
+    const absolute = path.join(target, dir);
+    const display = `${normalizeRelative(dir)}/`;
+
+    if (await exists(absolute)) {
+      const current = await stat(absolute);
+      if (!current.isDirectory()) {
+        throw new Error(`expected directory but found file: ${absolute}`);
+      }
+      skipped.push(display);
+    } else {
+      created.push(display);
+      if (!dryRun) {
+        await mkdir(absolute, { recursive: true });
+      }
+    }
+  }
+
+  for (const dir of gitkeepDirs) {
+    const file = path.join(target, dir, '.gitkeep');
+    const display = normalizeRelative(path.join(dir, '.gitkeep'));
+
+    if (await exists(file)) {
+      skipped.push(display);
+    } else {
+      created.push(display);
+      if (!dryRun) {
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, '');
+      }
+    }
+  }
+
+  return { created, skipped, updated };
+}
+
+export async function renderEntryFiles(target, templateRoot, options = {}) {
+  const dryRun = Boolean(options.dryRun ?? DEFAULT_DRY_RUN);
+  const projectName = options.projectName ?? path.basename(target);
+  const projectGoal = options.projectGoal ?? 'TODO: 用一句话说明这个项目要解决什么问题。';
+  const created = [];
+  const skipped = [];
+  const updated = [];
+
+  for (const file of ENTRY_FILES) {
+    const source = path.join(templateRoot, file);
+    const dest = path.join(target, file);
+    const display = normalizeRelative(file);
+
+    if (await exists(dest)) {
+      skipped.push(display);
+      continue;
+    }
+
+    const template = await readFile(source, 'utf8');
+    const rendered = renderTemplate(template, { projectName, projectGoal });
+    created.push(display);
+
+    if (!dryRun) {
+      await mkdir(path.dirname(dest), { recursive: true });
+      await writeFile(dest, rendered);
+    }
+  }
+
+  return { created, skipped, updated };
+}
+
+function renderTemplate(template, replacements) {
+  return template
+    .replaceAll('{{PROJECT_NAME}}', replacements.projectName)
+    .replaceAll('{{PROJECT_GOAL}}', replacements.projectGoal);
+}
+
+async function exists(value) {
+  try {
+    await stat(value);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
 }
 
-export async function renderEntryFiles(target, templateRoot, options = {}) {
-  const dryRun = Boolean(options.dryRun ?? DEFAULT_DRY_RUN);
-  const projectName = options.projectName ?? path.basename(target);
-  const projectGoal = options.projectGoal ?? 'TODO: 用一句话说明这个项目要解决什么问题。';
-  const created = [];
-  const skipped = [];
-  const updated = [];
-
-  for (const file of ENTRY_FILES) {
-    const source = path.join(templateRoot, file);
-    const dest = path.join(target, file);
-    const display = normalizeRelative(file);
-
-    if (await exists(dest)) {
-      skipped.push(display);
-      continue;
-    }
-
-    const template = await readFile(source, 'utf8');
-    const rendered = renderTemplate(template, { projectName, projectGoal });
-    created.push(display);
-
-    if (!dryRun) {
-      await mkdir(path.dirname(dest), { recursive: true });
-      await writeFile(dest, rendered);
+async function hasDirectory(target, candidates) {
+  for (const candidate of candidates) {
+    try {
+      if ((await stat(path.join(target, candidate))).isDirectory()) {
+        return true;
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') {
+        throw error;
+      }
     }
   }
-
-  return { created, skipped, updated };
-}
-
-function renderTemplate(template, replacements) {
-  return template
-    .replaceAll('{{PROJECT_NAME}}', replacements.projectName)
-    .replaceAll('{{PROJECT_GOAL}}', replacements.projectGoal);
+  return false;
 }
 
-async function exists(value) {
-  try {
-    await stat(value);
+async function shouldIncludeDefaultRoot(target, defaultRoot, alternatives) {
+  if (await exists(path.join(target, defaultRoot))) {
     return true;
-  } catch (error) {
-    if (error?.code === 'ENOENT') {
-      return false;
-    }
-    throw error;
   }
+  return !(await hasDirectory(target, alternatives));
 }
-
-function normalizeRelative(value) {
-  return value.split(path.sep).join('/');
-}
+
+function normalizeRelative(value) {
+  return value.split(path.sep).join('/');
+}

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`.