@shirayner/ace 0.1.0-snapshot.1

package/bin/ace.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'module';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from '../src/commands/init.js';
+import { doctorCommand } from '../src/commands/doctor.js';
+import { listCommand } from '../src/commands/list.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('ace')
+  .description('AI Coding Environment - One command to set up your Claude Code harness')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Initialize AI coding environment')
+  .option('-p, --preset <name>', 'Installation preset: full, minimal, safe', 'full')
+  .option('-f, --force', 'Overwrite existing files', false)
+  .option('--dry-run', 'Show what would be done without making changes', false)
+  .option('--no-interaction', 'Skip interactive prompts, use defaults', false)
+  .action(initCommand);
+
+program
+  .command('doctor')
+  .description('Verify installation integrity')
+  .action(doctorCommand);
+
+program
+  .command('list')
+  .description('List installed components and their status')
+  .action(listCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@shirayner/ace",
+  "version": "0.1.0-snapshot.1",
+  "description": "AI Coding Environment - One command to set up your Claude Code harness",
+  "bin": {
+    "ace": "./bin/ace.js"
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --test tests/",
+    "lint": "eslint src/"
+  },
+  "keywords": [
+    "claude-code",
+    "ai",
+    "coding",
+    "environment",
+    "harness",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "inquirer": "^9.2.0",
+    "fs-extra": "^11.2.0",
+    "deepmerge": "^4.3.1",
+    "ora": "^8.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/commands/doctor.js

@@ -0,0 +1,86 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import { CLAUDE_DIR, COMPONENTS } from '../core/constants.js';
+
+export async function doctorCommand() {
+  console.log(chalk.bold('\n  ace doctor — verifying installation\n'));
+
+  const checks = [];
+
+  // 1. Check ~/.claude/ exists
+  checks.push(await check('~/.claude/ directory', fs.pathExists(CLAUDE_DIR)));
+
+  // 2. Check core files
+  checks.push(await check('CLAUDE.md', fs.pathExists(path.join(CLAUDE_DIR, 'CLAUDE.md'))));
+  checks.push(await check('settings.json', fs.pathExists(path.join(CLAUDE_DIR, 'settings.json'))));
+
+  // 3. Check rules
+  const ruleFiles = COMPONENTS.rules.files;
+  for (const file of ruleFiles) {
+    checks.push(await check(`rules/${path.basename(file.dest)}`, fs.pathExists(path.join(CLAUDE_DIR, file.dest))));
+  }
+
+  // 4. Check skills
+  const skillDirs = COMPONENTS.skills.directories;
+  for (const dir of skillDirs) {
+    const skillMd = path.join(CLAUDE_DIR, dir, 'SKILL.md');
+    checks.push(await check(dir, fs.pathExists(skillMd)));
+  }
+
+  // 5. Check memory
+  checks.push(await check('memory/MEMORY.md', fs.pathExists(path.join(CLAUDE_DIR, 'memory', 'MEMORY.md'))));
+
+  // 6. Validate settings.json structure
+  try {
+    const settings = await fs.readJson(path.join(CLAUDE_DIR, 'settings.json'));
+    checks.push({ name: 'settings.json valid JSON', ok: true });
+
+    const hasHooks = settings?.permissions?.hooks;
+    checks.push({ name: 'settings.json has hooks config', ok: !!hasHooks });
+
+    const hasMemoryDir = settings?.autoMemoryDirectory;
+    checks.push({ name: 'settings.json has autoMemoryDirectory', ok: !!hasMemoryDir });
+  } catch {
+    checks.push({ name: 'settings.json parseable', ok: false });
+  }
+
+  // 7. Validate CLAUDE.md @references
+  try {
+    const claudeMd = await fs.readFile(path.join(CLAUDE_DIR, 'CLAUDE.md'), 'utf-8');
+    const refs = claudeMd.match(/@~?\/?\.?claude\/[^\s)]+/g) || [];
+    for (const ref of refs) {
+      const refPath = ref.replace(/^@/, '').replace(/^~/, process.env.HOME || process.env.USERPROFILE);
+      checks.push(await check(`@ref: ${path.basename(refPath)}`, fs.pathExists(refPath)));
+    }
+  } catch {
+    checks.push({ name: 'CLAUDE.md readable', ok: false });
+  }
+
+  // Summary
+  const passed = checks.filter(c => c.ok).length;
+  const failed = checks.filter(c => !c.ok).length;
+
+  console.log();
+  checks.forEach(c => {
+    const icon = c.ok ? chalk.green('  pass') : chalk.red('  FAIL');
+    console.log(`  ${icon}  ${c.name}`);
+  });
+
+  console.log(chalk.bold(`\n  ${passed} passed, ${failed} failed\n`));
+
+  if (failed > 0) {
+    console.log(chalk.yellow('  Run `ace init` to fix missing components.\n'));
+  } else {
+    console.log(chalk.green('  All checks passed. Environment is healthy.\n'));
+  }
+}
+
+async function check(name, promise) {
+  try {
+    const ok = await promise;
+    return { name, ok: !!ok };
+  } catch {
+    return { name, ok: false };
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,98 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { PRESETS, ROLES } from '../core/constants.js';
+import { Installer } from '../core/installer.js';
+
+export async function initCommand(options) {
+  console.log(chalk.bold('\n  ace - AI Coding Environment\n'));
+
+  let role = 'fullstack';
+  let preset = options.preset;
+
+  // Interactive mode
+  if (options.interaction !== false) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'role',
+        message: 'What is your primary role?',
+        choices: Object.entries(ROLES).map(([key, val]) => ({
+          name: `${val.label} — ${val.description}`,
+          value: key,
+        })),
+        default: 'fullstack',
+      },
+      {
+        type: 'list',
+        name: 'preset',
+        message: 'Installation scope?',
+        choices: [
+          { name: 'Full — All components (rules, skills, hooks, safety guards, memory)', value: 'full' },
+          { name: 'Safe — Core + rules + skills + safety guards + memory', value: 'safe' },
+          { name: 'Minimal — Core + rules + skills only', value: 'minimal' },
+        ],
+        default: 'full',
+      },
+    ]);
+    role = answers.role;
+    preset = answers.preset;
+  }
+
+  const components = PRESETS[preset];
+  if (!components) {
+    console.error(chalk.red(`Unknown preset: ${preset}. Available: ${Object.keys(PRESETS).join(', ')}`));
+    process.exit(1);
+  }
+
+  console.log(chalk.dim(`\n  Role: ${ROLES[role].label}`));
+  console.log(chalk.dim(`  Preset: ${preset}`));
+  console.log(chalk.dim(`  Components: ${components.join(', ')}`));
+  if (options.force) console.log(chalk.yellow('  Force mode: existing files will be overwritten'));
+  if (options.dryRun) console.log(chalk.cyan('  Dry-run mode: no changes will be made'));
+  console.log();
+
+  const installer = new Installer({
+    force: options.force,
+    dryRun: options.dryRun,
+    role,
+    components,
+  });
+
+  const results = installer.run();
+
+  // Wait for async
+  const { installed, skipped, merged, errors } = await results;
+
+  // Summary
+  console.log(chalk.bold('\n  Installation Summary\n'));
+
+  if (installed.length > 0) {
+    console.log(chalk.green(`  Installed (${installed.length}):`));
+    installed.forEach(f => console.log(chalk.green(`    + ${f}`)));
+  }
+
+  if (merged.length > 0) {
+    console.log(chalk.blue(`  Merged (${merged.length}):`));
+    merged.forEach(m => {
+      const detail = m.added ? ` (added ${m.added.length} refs)` : '';
+      console.log(chalk.blue(`    ~ ${m.file}${detail}`));
+    });
+  }
+
+  if (skipped.length > 0) {
+    console.log(chalk.yellow(`  Skipped (${skipped.length}) — already exist:`));
+    skipped.forEach(f => console.log(chalk.yellow(`    - ${f}`)));
+  }
+
+  if (errors.length > 0) {
+    console.log(chalk.red(`  Errors (${errors.length}):`));
+    errors.forEach(e => console.log(chalk.red(`    ! ${e.file || e.component}: ${e.error}`)));
+  }
+
+  if (errors.length === 0) {
+    console.log(chalk.green.bold('\n  Done! Your AI coding environment is ready.\n'));
+    console.log(chalk.dim('  Run `ace doctor` to verify the installation.'));
+  } else {
+    console.log(chalk.yellow('\n  Completed with errors. Run `ace doctor` to diagnose.\n'));
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,67 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import { CLAUDE_DIR, COMPONENTS } from '../core/constants.js';
+
+export async function listCommand() {
+  console.log(chalk.bold('\n  ace list — installed components\n'));
+
+  for (const [name, component] of Object.entries(COMPONENTS)) {
+    const status = await getComponentStatus(component);
+    const icon = status === 'installed' ? chalk.green('installed')
+      : status === 'partial' ? chalk.yellow(' partial')
+      : chalk.dim(' missing');
+
+    console.log(`  ${icon}  ${name} — ${component.description}`);
+
+    // Show details for partial status
+    if (status === 'partial') {
+      const details = await getComponentDetails(component);
+      details.missing.forEach(f => console.log(chalk.red(`           missing: ${f}`)));
+    }
+  }
+
+  console.log();
+}
+
+async function getComponentStatus(component) {
+  const allPaths = [];
+
+  if (component.files) {
+    allPaths.push(...component.files.map(f => path.join(CLAUDE_DIR, f.dest)));
+  }
+  if (component.directories) {
+    allPaths.push(...component.directories.map(d => path.join(CLAUDE_DIR, d)));
+  }
+  if (component.conditional) {
+    allPaths.push(...component.conditional.map(f => path.join(CLAUDE_DIR, f.dest)));
+  }
+
+  if (allPaths.length === 0) return 'installed';
+
+  const checks = await Promise.all(allPaths.map(p => fs.pathExists(p)));
+  const existCount = checks.filter(Boolean).length;
+
+  if (existCount === allPaths.length) return 'installed';
+  if (existCount > 0) return 'partial';
+  return 'missing';
+}
+
+async function getComponentDetails(component) {
+  const missing = [];
+  const installed = [];
+
+  const allFiles = [
+    ...(component.files || []).map(f => f.dest),
+    ...(component.directories || []),
+    ...(component.conditional || []).map(f => f.dest),
+  ];
+
+  for (const file of allFiles) {
+    const exists = await fs.pathExists(path.join(CLAUDE_DIR, file));
+    if (exists) installed.push(file);
+    else missing.push(file);
+  }
+
+  return { missing, installed };
+}

package/src/core/constants.js

@@ -0,0 +1,106 @@
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+export const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
+
+export const PRESETS = {
+  full: ['core', 'rules', 'skills', 'hooks', 'hookify', 'memory', 'commands'],
+  minimal: ['core', 'rules', 'skills'],
+  safe: ['core', 'rules', 'skills', 'hookify', 'memory'],
+};
+
+export const ROLES = {
+  backend: {
+    label: 'Backend Developer',
+    description: 'Java/Go/Python backend, microservices, APIs',
+    primaryLang: 'Java',
+    hooks: ['java-compile-check.sh'],
+  },
+  frontend: {
+    label: 'Frontend Developer',
+    description: 'React/Vue/TypeScript, Web UI, SPA/SSR',
+    primaryLang: 'TypeScript',
+    hooks: [],
+  },
+  client: {
+    label: 'Client Developer',
+    description: 'iOS/Android/Flutter, mobile apps',
+    primaryLang: 'Kotlin/Swift',
+    hooks: [],
+  },
+  fullstack: {
+    label: 'Fullstack Developer',
+    description: 'Full-stack development, frontend + backend',
+    primaryLang: 'TypeScript + Java',
+    hooks: ['java-compile-check.sh'],
+  },
+};
+
+export const COMPONENTS = {
+  core: {
+    description: 'Core config (CLAUDE.md + settings.json)',
+    required: true,
+    files: [
+      { src: 'CLAUDE.md', dest: 'CLAUDE.md', merge: 'claude-md' },
+      { src: 'settings.json', dest: 'settings.json', merge: 'settings-json' },
+    ],
+  },
+  rules: {
+    description: 'Cognitive & code quality rules',
+    required: true,
+    files: [
+      { src: 'rules/thinking.md', dest: 'rules/thinking.md' },
+      { src: 'rules/clean-code.md', dest: 'rules/clean-code.md' },
+      { src: 'rules/code-quality.md', dest: 'rules/code-quality.md' },
+      { src: 'rules/reporting.md', dest: 'rules/reporting.md' },
+      { src: 'rules/task-recovery.md', dest: 'rules/task-recovery.md' },
+      { src: 'rules/context-hygiene.md', dest: 'rules/context-hygiene.md' },
+      { src: 'rules/memory-policy.md', dest: 'rules/memory-policy.md' },
+    ],
+  },
+  skills: {
+    description: 'AI skills (auto-goal, coding, skill-creator, skill-optimize)',
+    required: true,
+    directories: [
+      'skills/auto-goal',
+      'skills/coding',
+      'skills/skill-creator',
+      'skills/skill-optimize',
+    ],
+  },
+  hooks: {
+    description: 'Hook scripts (optional, role-dependent)',
+    required: false,
+    conditional: [
+      { src: 'hooks/java-compile-check.sh', dest: 'hooks/java-compile-check.sh', roles: ['backend', 'fullstack'] },
+    ],
+  },
+  hookify: {
+    description: 'Safety guard rules (block dangerous ops, protect secrets, require verification)',
+    required: false,
+    files: [
+      { src: 'hookify/hookify.block-dangerous-ops.local.md', dest: 'hookify.block-dangerous-ops.local.md' },
+      { src: 'hookify/hookify.protect-secrets.local.md', dest: 'hookify.protect-secrets.local.md' },
+      { src: 'hookify/hookify.require-verification.local.md', dest: 'hookify.require-verification.local.md' },
+    ],
+  },
+  memory: {
+    description: 'Global memory templates',
+    required: false,
+    files: [
+      { src: 'memory/MEMORY.md', dest: 'memory/MEMORY.md', merge: 'skip-existing' },
+    ],
+    roleTemplates: true,
+  },
+  commands: {
+    description: 'Custom commands (report)',
+    required: false,
+    files: [
+      { src: 'commands/report.md', dest: 'commands/report.md' },
+    ],
+  },
+};

package/src/core/installer.js

@@ -0,0 +1,206 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { CLAUDE_DIR, TEMPLATES_DIR, COMPONENTS } from './constants.js';
+import { mergeClaudeMd, mergeSettingsJson, conflictCheck, backupFile } from './merger.js';
+
+export class Installer {
+  constructor(options = {}) {
+    this.targetDir = CLAUDE_DIR;
+    this.templatesDir = TEMPLATES_DIR;
+    this.force = options.force || false;
+    this.dryRun = options.dryRun || false;
+    this.role = options.role || 'fullstack';
+    this.components = options.components || [];
+    this.results = { installed: [], skipped: [], merged: [], errors: [] };
+  }
+
+  async run() {
+    if (!this.dryRun) {
+      await fs.ensureDir(this.targetDir);
+    }
+
+    for (const componentName of this.components) {
+      const component = COMPONENTS[componentName];
+      if (!component) continue;
+
+      const spinner = ora(`Installing ${componentName}...`).start();
+
+      try {
+        await this.installComponent(componentName, component);
+        spinner.succeed(`${componentName} installed`);
+      } catch (err) {
+        spinner.fail(`${componentName} failed: ${err.message}`);
+        this.results.errors.push({ component: componentName, error: err.message });
+      }
+    }
+
+    return this.results;
+  }
+
+  async installComponent(name, component) {
+    // Install regular files
+    if (component.files) {
+      for (const file of component.files) {
+        await this.installFile(file);
+      }
+    }
+
+    // Install conditional files (role-dependent)
+    if (component.conditional) {
+      for (const file of component.conditional) {
+        if (file.roles && file.roles.includes(this.role)) {
+          await this.installFile(file);
+        }
+      }
+    }
+
+    // Install directories (e.g., skills)
+    if (component.directories) {
+      for (const dir of component.directories) {
+        await this.installDirectory(dir);
+      }
+    }
+
+    // Install role-specific templates (e.g., memory/user_profile.md)
+    if (component.roleTemplates) {
+      await this.installRoleTemplate();
+    }
+  }
+
+  async installFile(fileSpec) {
+    const srcPath = path.join(this.templatesDir, fileSpec.src);
+    const destPath = path.join(this.targetDir, fileSpec.dest);
+
+    if (!await fs.pathExists(srcPath)) {
+      this.results.errors.push({ file: fileSpec.src, error: 'Template file not found' });
+      return;
+    }
+
+    const exists = await conflictCheck(destPath);
+
+    if (exists && fileSpec.merge === 'skip-existing') {
+      this.results.skipped.push(fileSpec.dest);
+      return;
+    }
+
+    if (exists && !this.force) {
+      if (fileSpec.merge === 'claude-md') {
+        await this.mergeClaudeMdFile(srcPath, destPath, fileSpec);
+        return;
+      }
+      if (fileSpec.merge === 'settings-json') {
+        await this.mergeSettingsJsonFile(srcPath, destPath, fileSpec);
+        return;
+      }
+      // No merge strategy — skip existing
+      this.results.skipped.push(fileSpec.dest);
+      return;
+    }
+
+    if (this.dryRun) {
+      console.log(chalk.cyan(`  [dry-run] Would install: ${fileSpec.dest}`));
+      this.results.installed.push(fileSpec.dest);
+      return;
+    }
+
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.copy(srcPath, destPath);
+    this.results.installed.push(fileSpec.dest);
+  }
+
+  async installDirectory(dir) {
+    const srcPath = path.join(this.templatesDir, dir);
+    const destPath = path.join(this.targetDir, dir);
+
+    if (!await fs.pathExists(srcPath)) {
+      this.results.errors.push({ file: dir, error: 'Template directory not found' });
+      return;
+    }
+
+    const exists = await conflictCheck(destPath);
+
+    if (exists && !this.force) {
+      this.results.skipped.push(dir);
+      return;
+    }
+
+    if (this.dryRun) {
+      console.log(chalk.cyan(`  [dry-run] Would install directory: ${dir}`));
+      this.results.installed.push(dir);
+      return;
+    }
+
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.copy(srcPath, destPath, { overwrite: this.force });
+    this.results.installed.push(dir);
+  }
+
+  async mergeClaudeMdFile(srcPath, destPath, fileSpec) {
+    const existing = await fs.readFile(destPath, 'utf-8');
+    const template = await fs.readFile(srcPath, 'utf-8');
+    const { content, added } = mergeClaudeMd(existing, template);
+
+    if (added.length === 0) {
+      this.results.skipped.push(fileSpec.dest);
+      return;
+    }
+
+    if (this.dryRun) {
+      console.log(chalk.cyan(`  [dry-run] Would merge CLAUDE.md, adding ${added.length} references`));
+      this.results.merged.push({ file: fileSpec.dest, added });
+      return;
+    }
+
+    await backupFile(destPath);
+    await fs.writeFile(destPath, content, 'utf-8');
+    this.results.merged.push({ file: fileSpec.dest, added });
+  }
+
+  async mergeSettingsJsonFile(srcPath, destPath, fileSpec) {
+    const existing = await fs.readJson(destPath);
+    const template = await fs.readJson(srcPath);
+    const merged = mergeSettingsJson(existing, template);
+
+    if (JSON.stringify(existing) === JSON.stringify(merged)) {
+      this.results.skipped.push(fileSpec.dest);
+      return;
+    }
+
+    if (this.dryRun) {
+      console.log(chalk.cyan(`  [dry-run] Would merge settings.json`));
+      this.results.merged.push({ file: fileSpec.dest });
+      return;
+    }
+
+    await backupFile(destPath);
+    await fs.writeJson(destPath, merged, { spaces: 2 });
+    this.results.merged.push({ file: fileSpec.dest });
+  }
+
+  async installRoleTemplate() {
+    const templatePath = path.join(this.templatesDir, 'memory', 'roles', `${this.role}.md`);
+    const destPath = path.join(this.targetDir, 'memory', 'user_profile.md');
+
+    if (await conflictCheck(destPath)) {
+      this.results.skipped.push('memory/user_profile.md');
+      return;
+    }
+
+    if (!await fs.pathExists(templatePath)) {
+      this.results.errors.push({ file: `memory/roles/${this.role}.md`, error: 'Role template not found' });
+      return;
+    }
+
+    if (this.dryRun) {
+      console.log(chalk.cyan(`  [dry-run] Would install user profile template for role: ${this.role}`));
+      this.results.installed.push('memory/user_profile.md');
+      return;
+    }
+
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.copy(templatePath, destPath);
+    this.results.installed.push('memory/user_profile.md');
+  }
+}