@ecc-hgy/ae 0.2.0

package/src/cli.js

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { packageRoot } from './utils/paths.js';
+
+const HELP = `Usage: ae <command> [options]
+
+Commands:
+  setup                Install skills to .claude/.codex and drop a config/ae-rules.md template.
+  init [goal]          Create spec/ skeleton, render entry files, sync AE:RULES block from
+                       config/ae-rules.md. Requires \`ae setup\` to have run.
+
+Options:
+  -h, --help     Show help
+  -v, --version  Show version
+
+Typical workflow:
+  ae setup
+  [optional] edit config/ae-rules.md
+  ae init "<one-line project goal>"`;
+
+export async function run(argv = []) {
+  try {
+    const [command, ...rest] = argv;
+
+    if (!command || command === '--help' || command === '-h') {
+      console.log(HELP);
+      return 0;
+    }
+
+    if (command === '--version' || command === '-v') {
+      console.log(await readVersion());
+      return 0;
+    }
+
+    if (command === 'setup') {
+      const mod = await import('./commands/setup.js');
+      return await mod.run(rest);
+    }
+
+    if (command === 'init') {
+      const mod = await import('./commands/init.js');
+      return await mod.run(rest);
+    }
+
+    console.error(`Unknown command: ${command}`);
+    console.error('');
+    console.error(HELP);
+    process.exitCode = 1;
+    return 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+    return 1;
+  }
+}
+
+async function readVersion() {
+  const packageJson = JSON.parse(
+    await readFile(path.join(packageRoot(), 'package.json'), 'utf8'),
+  );
+  return packageJson.version;
+}

package/src/commands/init.js

@@ -0,0 +1,190 @@
+import { mkdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createDirectories, renderEntryFiles, syncRulesBlock, RulesMarkerError } from '../skeleton.js';
+import { templatesPath } from '../utils/paths.js';
+import { formatInitReport } from '../utils/report.js';
+
+const DEFAULT_GOAL = 'TODO: 用一句话说明这个项目要解决什么问题。';
+
+const HELP = `Usage: ae init [goal] [options]
+
+Options:
+  --target <path>  Initialize this project directory. Defaults to cwd.
+  --rules <path>   Read AE:RULES content from this markdown file.
+                   Defaults to <target>/config/ae-rules.md when present.
+  --dry-run        Show what would be created or synced without writing files.
+  -h, --help       Show help`;
+
+export async function run(argv = []) {
+  const options = parseArgs(argv);
+
+  if (options.help) {
+    console.log(HELP);
+    return 0;
+  }
+
+  const target = path.resolve(options.target ?? process.cwd());
+
+  try {
+    await ensureTargetDirectory(target, options.dryRun);
+    if (!(await hasInstalledAssets(target))) {
+      console.error(`Error: AE assets not found in ${target}.`);
+      console.error('Run `ae setup` first.');
+      process.exitCode = 1;
+      return 1;
+    }
+
+    const projectName = path.basename(target);
+    const projectGoal = options.goal ?? DEFAULT_GOAL;
+    const created = [];
+    const skipped = [];
+
+    const dirs = await createDirectories(target, { dryRun: options.dryRun });
+    created.push(...dirs.created);
+    skipped.push(...dirs.skipped);
+
+    const entries = await renderEntryFiles(target, templatesPath('entries'), {
+      projectName,
+      projectGoal,
+      dryRun: options.dryRun,
+    });
+    created.push(...entries.created);
+    skipped.push(...entries.skipped);
+
+    const rules = await syncRules(target, options);
+
+    console.log(formatInitReport({ created, skipped, target, rules, dryRun: options.dryRun }));
+    return 0;
+  } catch (error) {
+    if (error instanceof RulesMarkerError) {
+      console.error(`AE init failed: ${error.message}`);
+    } else {
+      console.error(`AE init failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exitCode = 1;
+    return 1;
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    target: undefined,
+    rules: undefined,
+    goalParts: [],
+    dryRun: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--target') {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error('--target requires a path');
+      }
+      options.target = value;
+      index += 1;
+    } else if (arg === '--rules') {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error('--rules requires a path');
+      }
+      options.rules = value;
+      index += 1;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option for init: ${arg}`);
+    } else {
+      options.goalParts.push(arg);
+    }
+  }
+
+  return {
+    target: options.target,
+    rules: options.rules,
+    dryRun: options.dryRun,
+    help: options.help,
+    goal: options.goalParts.length > 0 ? options.goalParts.join(' ') : undefined,
+  };
+}
+
+async function ensureTargetDirectory(target, dryRun) {
+  try {
+    const current = await stat(target);
+    if (!current.isDirectory()) {
+      throw new Error(`target exists but is not a directory: ${target}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+    if (!dryRun) {
+      await mkdir(target, { recursive: true });
+    }
+  }
+}
+
+async function hasInstalledAssets(target) {
+  return (
+    (await isDirectory(path.join(target, '.claude', 'skills'))) ||
+    (await isDirectory(path.join(target, '.codex', 'skills')))
+  );
+}
+
+async function syncRules(target, options) {
+  const rulesPath = options.rules
+    ? path.resolve(process.cwd(), options.rules)
+    : path.join(target, 'config', 'ae-rules.md');
+
+  const rulesInfo = await statMaybe(rulesPath);
+  if (!rulesInfo) {
+    if (options.rules) {
+      throw new Error(`rules file does not exist: ${rulesPath}`);
+    }
+    return 'skipped (no rules file)';
+  }
+
+  if (rulesInfo.isDirectory()) {
+    throw new Error(`expected a file, got directory: ${rulesPath}`);
+  }
+  if (!rulesInfo.isFile()) {
+    throw new Error(`expected a file: ${rulesPath}`);
+  }
+
+  const rulesContent = await readFile(rulesPath, 'utf8');
+  const agents = path.join(target, 'AGENTS.md');
+  const claude = path.join(target, 'CLAUDE.md');
+  const agentsExists = await exists(agents);
+  const claudeExists = await exists(claude);
+
+  if (options.dryRun && (!agentsExists || !claudeExists)) {
+    return 'would sync';
+  }
+
+  await syncRulesBlock(agents, rulesContent, { dryRun: options.dryRun });
+  await syncRulesBlock(claude, rulesContent, { dryRun: options.dryRun });
+  return options.dryRun ? 'would sync' : 'synced';
+}
+
+async function statMaybe(value) {
+  try {
+    return await stat(value);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+async function exists(value) {
+  return Boolean(await statMaybe(value));
+}
+
+async function isDirectory(value) {
+  const current = await statMaybe(value);
+  return Boolean(current?.isDirectory());
+}

package/src/commands/setup.js

@@ -0,0 +1,111 @@
+import { mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { copyFileIdempotent, copyTreeIdempotent } from '../utils/copy.js';
+import { skillsPath, templatesPath } from '../utils/paths.js';
+import { formatSetupReport } from '../utils/report.js';
+
+const HELP = `Usage: ae setup [options]
+
+Options:
+  --target <path>  Install AE assets into this project directory. Defaults to cwd.
+  --dry-run        Show what would be installed without writing files.
+  -h, --help       Show help`;
+
+export async function run(argv = []) {
+  const options = parseArgs(argv);
+
+  if (options.help) {
+    console.log(HELP);
+    return 0;
+  }
+
+  const target = path.resolve(options.target ?? process.cwd());
+
+  try {
+    await ensureTargetDirectory(target, options.dryRun);
+
+    const created = [];
+    const skipped = [];
+    const skillGroups = [
+      {
+        dest: path.join(target, '.claude', 'skills'),
+        prefix: path.join('.claude', 'skills'),
+      },
+      {
+        dest: path.join(target, '.codex', 'skills'),
+        prefix: path.join('.codex', 'skills'),
+      },
+    ];
+
+    for (const group of skillGroups) {
+      const result = await copyTreeIdempotent(skillsPath(), group.dest, {
+        dryRun: options.dryRun,
+      });
+      created.push(...result.created.map((item) => toDisplayPath(path.join(group.prefix, item))));
+      skipped.push(...result.skipped.map((item) => toDisplayPath(path.join(group.prefix, item))));
+    }
+
+    const rulesResult = await copyFileIdempotent(
+      templatesPath('ae-rules.md'),
+      path.join(target, 'config', 'ae-rules.md'),
+      { dryRun: options.dryRun },
+    );
+    created.push(...rulesResult.created.map((item) => toDisplayPath(path.join('config', item))));
+    skipped.push(...rulesResult.skipped.map((item) => toDisplayPath(path.join('config', item))));
+
+    console.log(formatSetupReport({ created, skipped, target, dryRun: options.dryRun }));
+    return 0;
+  } catch (error) {
+    console.error(`AE setup failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+    return 1;
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    target: undefined,
+    dryRun: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--target') {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error('--target requires a path');
+      }
+      options.target = value;
+      index += 1;
+    } else {
+      throw new Error(`Unknown option for setup: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+async function ensureTargetDirectory(target, dryRun) {
+  try {
+    const current = await stat(target);
+    if (!current.isDirectory()) {
+      throw new Error(`target exists but is not a directory: ${target}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+    if (!dryRun) {
+      await mkdir(target, { recursive: true });
+    }
+  }
+}
+
+function toDisplayPath(value) {
+  return value.split(path.sep).join('/');
+}

package/src/skeleton.js

@@ -0,0 +1,209 @@
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const RULES_BEGIN = '<!-- AE:RULES:BEGIN -->';
+export const RULES_END = '<!-- AE:RULES:END -->';
+const RULES_COMMENT = '<!-- 由 ae init 从 config/ae-rules.md 或 --rules 指定文件同步,勿手改 -->';
+const DEFAULT_DRY_RUN = false;
+
+const SKELETON_DIRS = [
+  'spec',
+  path.join('spec', 'needs'),
+  path.join('spec', 'ADR'),
+  'reference',
+  'data',
+  'scripts',
+];
+
+const GITKEEP_DIRS = [
+  path.join('spec', 'needs'),
+  path.join('spec', 'ADR'),
+  'reference',
+  'data',
+  'scripts',
+];
+
+const ENTRY_FILES = [
+  'README.md',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'handoff.md',
+  path.join('spec', 'README.md'),
+  path.join('spec', 'INDEX.md'),
+];
+
+export class RulesMarkerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RulesMarkerError';
+  }
+}
+
+export async function createDirectories(target, options = {}) {
+  const dryRun = Boolean(options.dryRun ?? DEFAULT_DRY_RUN);
+  const created = [];
+  const skipped = [];
+  const updated = [];
+
+  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 });
+      }
+    }
+  }
+
+  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, '');
+      }
+    }
+  }
+
+  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 };
+}
+
+export async function syncRulesBlock(targetFile, rulesContent, options = {}) {
+  const dryRun = Boolean(options.dryRun ?? DEFAULT_DRY_RUN);
+  const content = await readFile(targetFile, 'utf8');
+  const ranges = findRulesRanges(content, targetFile);
+  const block = buildRulesBlock(rulesContent);
+  const created = [];
+  const skipped = [];
+  const updated = [];
+  const display = path.basename(targetFile);
+
+  if (ranges.length === 0) {
+    const next = content.endsWith('\n') ? `${content}\n${block}` : `${content}\n\n${block}`;
+    if (next === content) {
+      skipped.push(display);
+      return { created, skipped, updated };
+    }
+    created.push(`${display}#AE:RULES`);
+    if (!dryRun) {
+      await writeFile(targetFile, next);
+    }
+    return { created, skipped, updated };
+  }
+
+  const [{ start, end }] = ranges;
+  const next = `${content.slice(0, start)}${block}${content.slice(end)}`;
+
+  if (next === content) {
+    skipped.push(`${display}#AE:RULES`);
+    return { created, skipped, updated };
+  }
+
+  updated.push(`${display}#AE:RULES`);
+  if (!dryRun) {
+    await writeFile(targetFile, next);
+  }
+
+  return { created, skipped, updated };
+}
+
+export function buildRulesBlock(rulesContent) {
+  const normalized = rulesContent.endsWith('\n') ? rulesContent : `${rulesContent}\n`;
+  return `${RULES_BEGIN}\n${RULES_COMMENT}\n${normalized}${RULES_END}\n`;
+}
+
+function renderTemplate(template, replacements) {
+  return template
+    .replaceAll('{{PROJECT_NAME}}', replacements.projectName)
+    .replaceAll('{{PROJECT_GOAL}}', replacements.projectGoal);
+}
+
+function findRulesRanges(content, targetFile) {
+  const beginMatches = [...content.matchAll(new RegExp(escapeRegExp(RULES_BEGIN), 'g'))];
+  const endMatches = [...content.matchAll(new RegExp(escapeRegExp(RULES_END), 'g'))];
+
+  if (beginMatches.length !== endMatches.length || beginMatches.length > 1) {
+    throw new RulesMarkerError(`malformed AE:RULES markers in ${targetFile}`);
+  }
+
+  if (beginMatches.length === 0) {
+    return [];
+  }
+
+  const start = beginMatches[0].index;
+  const end = endMatches[0].index + RULES_END.length;
+  if (start > endMatches[0].index) {
+    throw new RulesMarkerError(`malformed AE:RULES markers in ${targetFile}`);
+  }
+
+  let rangeEnd = end;
+  if (content.slice(rangeEnd, rangeEnd + 1) === '\n') {
+    rangeEnd += 1;
+  }
+
+  return [{ start, end: rangeEnd }];
+}
+
+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('/');
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/utils/copy.js

@@ -0,0 +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('/');
+}