@shirayner/ace 0.1.1-snapshot.5 → 0.1.1-snapshot.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shirayner/ace",
-  "version": "0.1.1-snapshot.5",
+  "version": "0.1.1-snapshot.7",
   "description": "AI Coding Environment - One command to set up your Claude Code harness",
   "bin": {
     "ace": "./bin/ace.js"

package/src/commands/init.js

@@ -1,7 +1,10 @@
 import * as p from '@clack/prompts';
+import path from 'path';
+import fs from 'fs-extra';
 import { createRequire } from 'module';
-import { PRESETS, COMPONENTS } from '../core/constants.js';
+import { PRESETS, COMPONENTS, CLAUDE_DIR, TEMPLATES_DIR, isAceOwnedFile } from '../core/constants.js';
 import { Installer } from '../core/installer.js';
+import { mergeClaudeMd } from '../core/merger.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
@@ -19,10 +22,8 @@ export async function initCommand(options) {
   const version = pkg.version;
   const components = PRESETS['full'];
 
-  // ─── Intro ──────────────────────────────────────────────
   p.intro(`ace v${version}`);
 
-  // ─── Conflict detection ─────────────────────────────────
   const installer = new Installer({
     force: options.force,
     dryRun: options.dryRun,
@@ -33,89 +34,100 @@ export async function initCommand(options) {
 
   let resolutions = {};
 
+  // ─── Conflict detection with categorized preview ───
   if (!options.force) {
-    const conflicts = await installer.detectConflicts();
-    const conflictKeys = Object.keys(conflicts);
-
-    if (conflictKeys.length > 0) {
-      const totalFiles = conflictKeys.reduce((sum, k) => sum + conflicts[k].files.length, 0);
-      const mergeComponents = conflictKeys.filter(k => conflicts[k].hasMerge);
-
-      if (mergeComponents.length > 0) {
-        p.log.info('Safe merge: CLAUDE.md, settings.json (preserves your changes)');
-      }
-      if (totalFiles > 0) {
-        p.log.warn(`${totalFiles} existing file(s) found`);
+    const preview = await buildInstallPreview(installer, components);
+    const hasExisting = preview.merge.length > 0 || preview.skip.length > 0 || preview.conflict.length > 0;
+
+    if (hasExisting) {
+      // Show safe merge section
+      if (preview.merge.length > 0) {
+        const mergeLines = preview.merge.map(m => `  ${m.dest} — ${m.detail}`);
+        p.log.info(['Safe merge:', ...mergeLines].join('\n'));
       }
 
-      const action = await p.select({
-        message: 'How to handle existing files?',
-        options: [
-          { value: 'skip', label: 'Keep & merge', hint: 'recommended' },
-          { value: 'overwrite', label: 'Overwrite all', hint: 'replace with latest' },
-          { value: 'cancel', label: 'Cancel' },
-        ],
-        initialValue: 'skip',
-      });
-
-      if (p.isCancel(action) || action === 'cancel') {
-        p.cancel('Setup cancelled.');
-        process.exit(0);
+      // Show auto-skip section
+      if (preview.skip.length > 0) {
+        const skipLines = preview.skip.map(s => `  ${s} — preserves your data`);
+        p.log.message(['Auto-skip:', ...skipLines].join('\n'));
       }
 
-      for (const key of conflictKeys) {
-        resolutions[key] = action;
+      // Show conflict section + prompt
+      if (preview.conflict.length > 0) {
+        const conflictLines = preview.conflict.map(f => `  ${f}`);
+        p.log.warn([`${preview.conflict.length} existing file(s):`, ...conflictLines].join('\n'));
+
+        const action = await p.select({
+          message: `How to handle ${preview.conflict.length} existing files?`,
+          options: [
+            { value: 'skip', label: 'Keep existing', hint: 'recommended' },
+            { value: 'overwrite', label: 'Overwrite with latest' },
+            { value: 'cancel', label: 'Cancel' },
+          ],
+          initialValue: 'skip',
+        });
+
+        if (p.isCancel(action) || action === 'cancel') {
+          p.cancel('Setup cancelled.');
+          process.exit(0);
+        }
+
+        for (const componentName of components) {
+          resolutions[componentName] = action;
+        }
       }
     }
   }
 
   installer.resolutions = resolutions;
 
-  // ─── Dry-run notice ─────────────────────────────────────
   if (options.dryRun) {
     p.log.warn('dry-run — no changes will be made');
   }
 
-  // ─── Install ────────────────────────────────────────────
-  p.log.step('Installing to ~/.claude/');
+  // ─── Install with single spinner ───────────────────
+  const s = p.spinner();
+  const componentResults = [];
+
+  s.start('Installing...');
 
   for (const componentName of components) {
     const component = COMPONENTS[componentName];
     if (!component) continue;
 
     const label = componentLabels[componentName] || componentName;
+    s.message(`Installing ${label}...`);
+
     const beforeInstalled = installer.results.installed.length;
     const beforeMerged = installer.results.merged.length;
     const beforeSkipped = installer.results.skipped.length;
 
-    const s = p.spinner();
-    s.start(label);
-
     try {
       await installer.installComponent(componentName, component);
-      s.stop(label);
-
-      const newInstalled = installer.results.installed.length - beforeInstalled;
-      const newMerged = installer.results.merged.length - beforeMerged;
-      const newSkipped = installer.results.skipped.length - beforeSkipped;
-
-      if (newMerged > 0 && newInstalled === 0 && newSkipped === 0) {
-        p.log.info(`${label} — merged`);
-      } else if (newSkipped > 0 && newInstalled === 0 && newMerged === 0) {
-        p.log.message(`${label} — unchanged`);
-      } else {
-        const count = newInstalled + newMerged;
-        const detail = count > 0 ? `${count} file${count > 1 ? 's' : ''}` : '';
-        p.log.success(`${label} — ${detail}`);
-      }
+      componentResults.push({
+        label,
+        installed: installer.results.installed.length - beforeInstalled,
+        merged: installer.results.merged.length - beforeMerged,
+        skipped: installer.results.skipped.length - beforeSkipped,
+        error: null,
+      });
     } catch (err) {
-      s.stop(label);
-      p.log.error(`${label} — ${err.message}`);
+      componentResults.push({
+        label,
+        installed: installer.results.installed.length - beforeInstalled,
+        merged: installer.results.merged.length - beforeMerged,
+        skipped: installer.results.skipped.length - beforeSkipped,
+        error: err.message,
+      });
       installer.results.errors.push({ component: componentName, error: err.message });
     }
   }
 
-  // ─── Summary ────────────────────────────────────────────
+  s.stop('Installed to ~/.claude/');
+
+  // ─── Summary table ─────────────────────────────────
+  p.log.message(formatSummaryTable(componentResults));
+
   const { installed, merged, skipped, errors } = installer.results;
   const parts = [];
   if (installed.length > 0) parts.push(`${installed.length} installed`);
@@ -128,12 +140,12 @@ export async function initCommand(options) {
     p.log.warn(`${parts.join(', ')}, ${errors.length} failed`);
   }
 
-  // ─── Next Steps ─────────────────────────────────────────
+  // ─── Next Steps ────────────────────────────────────
   p.note(
     [
       'Get started',
       '  1. cd <your-project> && ace spec init',
-      '  2. Open Claude Code, type: /opsx:propose 创建需求提案',
+      '  2. Open Claude Code, type: /opsx:propose',
       '',
       'Customize',
       '  Change role      edit ~/.claude/memory/user_profile.md',
@@ -144,10 +156,98 @@ export async function initCommand(options) {
     'Next steps'
   );
 
-  // ─── Outro ──────────────────────────────────────────────
   if (errors.length === 0) {
     p.outro('Done. Go to your project and run ace spec init.');
   } else {
     p.outro('Done with errors. Run ace doctor to diagnose.');
   }
 }
+
+// ─── Helpers ───────────────────────────────────────────
+
+/**
+ * Scan target directory and categorize existing files by handling strategy.
+ */
+async function buildInstallPreview(installer, components) {
+  const preview = { merge: [], skip: [], conflict: [] };
+
+  for (const componentName of components) {
+    const component = COMPONENTS[componentName];
+    if (!component || component.isPlugin) continue;
+
+    if (component.files) {
+      for (const file of component.files) {
+        const destPath = path.join(installer.targetDir, file.dest);
+        if (await fs.pathExists(destPath)) {
+          if (file.merge === 'claude-md' || file.merge === 'settings-json') {
+            preview.merge.push({ src: file.src, dest: file.dest, strategy: file.merge });
+          } else if (file.merge === 'skip-existing') {
+            preview.skip.push(file.dest);
+          } else {
+            preview.conflict.push(file.dest);
+          }
+        }
+      }
+    }
+
+    if (component.rulesDir) {
+      const srcDir = path.join(installer.templatesDir, component.rulesDir);
+      const destDir = path.join(installer.targetDir, component.rulesDir);
+      if (await fs.pathExists(srcDir)) {
+        const files = (await fs.readdir(srcDir)).filter(f => f.endsWith('.md'));
+        for (const f of files) {
+          const relativePath = path.join(component.rulesDir, f).replace(/\\/g, '/');
+          // ACE-owned files are overwritten directly, not shown as conflicts
+          if (await fs.pathExists(path.join(destDir, f)) && !isAceOwnedFile(relativePath)) {
+            preview.conflict.push(relativePath);
+          }
+        }
+      }
+    }
+
+    if (component.conditional) {
+      for (const file of component.conditional) {
+        if (file.roles?.includes(installer.role)) {
+          const destPath = path.join(installer.targetDir, file.dest);
+          // ACE-owned files are overwritten directly, not shown as conflicts
+          if (await fs.pathExists(destPath) && !isAceOwnedFile(file.dest)) {
+            preview.conflict.push(file.dest);
+          }
+        }
+      }
+    }
+  }
+
+  // Enrich merge files with detail
+  for (const item of preview.merge) {
+    if (item.strategy === 'claude-md') {
+      try {
+        const existing = await fs.readFile(path.join(installer.targetDir, item.dest), 'utf-8');
+        const template = await fs.readFile(path.join(installer.templatesDir, item.src), 'utf-8');
+        const { added } = mergeClaudeMd(existing, template);
+        item.detail = added.length > 0 ? `adds ${added.length} new @references` : 'up to date';
+      } catch {
+        item.detail = 'will merge';
+      }
+    } else if (item.strategy === 'settings-json') {
+      item.detail = 'merges permissions & plugins';
+    }
+  }
+
+  return preview;
+}
+
+/**
+ * Format component results into an aligned summary table.
+ */
+function formatSummaryTable(results) {
+  const maxLen = Math.max(...results.map(r => r.label.length));
+  return results.map(r => {
+    const padded = r.label.padEnd(maxLen);
+    if (r.error) return `\u25A0 ${padded}  ${r.error}`;
+    if (r.merged > 0 && r.installed === 0 && r.skipped === 0) return `\u25C6 ${padded}  merged`;
+    if (r.skipped > 0 && r.installed === 0 && r.merged === 0) return `\u2502 ${padded}  unchanged`;
+    const count = r.installed + r.merged;
+    return `\u25C6 ${padded}  ${count} file${count > 1 ? 's' : ''}`;
+  }).join('\n');
+}

package/src/core/constants.js

@@ -67,6 +67,36 @@ export const SPEC_TEMPLATE_FILES = [
   'retrospective-template.md',
 ];
 
+/**
+ * Patterns for files owned by ACE - these are overwritten directly on init without prompting.
+ * Used to identify ACE-owned content in rules/, hooks/, and hookify/.
+ */
+export const ACE_OWNED_PATTERNS = [
+  /^rules\/ace\//,          // rules/ace/*.md
+  /^hooks\/ace\./,          // hooks/ace.*.sh
+  /^hookify\.ace\./,        // hookify.ace.*.local.md
+];
+
+/**
+ * Check if a file path (relative to ~/.claude/) is owned by ACE.
+ * @param {string} relativePath - Path like 'rules/ace/thinking.md' or 'hooks/ace.java-compile-check.sh'
+ * @returns {boolean}
+ */
+export function isAceOwnedFile(relativePath) {
+  return ACE_OWNED_PATTERNS.some(pattern => pattern.test(relativePath));
+}
+
+/**
+ * Check if an @reference path is owned by ACE.
+ * @param {string} refPath - Reference path like '~/.claude/rules/ace/thinking.md' or '~/.claude/hooks/ace.java-compile-check.sh'
+ * @returns {boolean}
+ */
+export function isAceOwnedRef(refPath) {
+  // Remove the ~/.claude/ prefix if present
+  const relativePath = refPath.replace(/^~\/\.claude\//, '');
+  return isAceOwnedFile(relativePath);
+}
+
 export const COMPONENTS = {
   core: {
     description: 'Core config (CLAUDE.md + settings.json)',
@@ -97,13 +127,13 @@ export const COMPONENTS = {
     description: 'Safety guard rules (block dangerous ops, protect secrets, safe git, code quality, require verification)',
     required: false,
     files: [
-      { src: 'hookify/ace.hookify.block-dangerous-ops.local.md', dest: 'hooks/ace.hookify.block-dangerous-ops.local.md' },
-      { src: 'hookify/ace.hookify.protect-secrets.local.md', dest: 'hooks/ace.hookify.protect-secrets.local.md' },
-      { src: 'hookify/ace.hookify.safe-git-commands.local.md', dest: 'hooks/ace.hookify.safe-git-commands.local.md' },
-      { src: 'hookify/ace.hookify.code-quality-gate.local.md', dest: 'hooks/ace.hookify.code-quality-gate.local.md' },
-      { src: 'hookify/ace.hookify.require-verification.local.md', dest: 'hooks/ace.hookify.require-verification.local.md' },
-      { src: 'hookify/hookify.dangerous-commands.local.md', dest: 'hooks/hookify.dangerous-commands.local.md' },
-      { src: 'hookify/hookify.sensitive-data.local.md', dest: 'hooks/hookify.sensitive-data.local.md' },
+      { src: 'hookify/hookify.ace.block-dangerous-ops.local.md', dest: 'hookify.ace.block-dangerous-ops.local.md' },
+      { src: 'hookify/hookify.ace.protect-secrets.local.md', dest: 'hookify.ace.protect-secrets.local.md' },
+      { src: 'hookify/hookify.ace.safe-git-commands.local.md', dest: 'hookify.ace.safe-git-commands.local.md' },
+      { src: 'hookify/hookify.ace.code-quality-gate.local.md', dest: 'hookify.ace.code-quality-gate.local.md' },
+      { src: 'hookify/hookify.ace.require-verification.local.md', dest: 'hookify.ace.require-verification.local.md' },
+      { src: 'hookify/hookify.ace.dangerous-commands.local.md', dest: 'hookify.ace.dangerous-commands.local.md' },
+      { src: 'hookify/hookify.ace.sensitive-data.local.md', dest: 'hookify.ace.sensitive-data.local.md' },
     ],
   },
   memory: {

package/src/core/installer.js

@@ -3,7 +3,7 @@ import path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
 import {
-  CLAUDE_DIR, TEMPLATES_DIR, COMPONENTS,
+  CLAUDE_DIR, TEMPLATES_DIR, COMPONENTS, isAceOwnedFile,
   PLUGIN_SRC_DIR, PLUGIN_CACHE_DIR, INSTALLED_PLUGINS_FILE,
   KNOWN_MARKETPLACES_FILE, MARKETPLACE_DIR, MARKETPLACE_NAME,
   PLUGIN_KEY, PLUGIN_NAME,
@@ -255,22 +255,25 @@ export class Installer {
     }
 
     if (exists && !this.force) {
-      if (fileSpec.merge === 'claude-md') {
+      // ACE-owned files are always overwritten (no user prompt needed)
+      if (isAceOwnedFile(fileSpec.dest)) {
+        // fall through to install (overwrite)
+      } else if (fileSpec.merge === 'claude-md') {
         await this.mergeClaudeMdFile(srcPath, destPath, fileSpec);
         return;
-      }
-      if (fileSpec.merge === 'settings-json') {
+      } else if (fileSpec.merge === 'settings-json') {
         await this.mergeSettingsJsonFile(srcPath, destPath, fileSpec);
         return;
-      }
-      // Check per-component resolution
-      const resolution = this.resolutions[componentName];
-      if (resolution === 'overwrite') {
-        // fall through to install
       } else {
-        // default: skip
-        this.results.skipped.push(fileSpec.dest);
-        return;
+        // Check per-component resolution
+        const resolution = this.resolutions[componentName];
+        if (resolution === 'overwrite') {
+          // fall through to install
+        } else {
+          // default: skip
+          this.results.skipped.push(fileSpec.dest);
+          return;
+        }
       }
     }
 

package/src/core/merger.js

@@ -1,19 +1,146 @@
 import fs from 'fs-extra';
 import path from 'path';
 import deepmerge from 'deepmerge';
+import { isAceOwnedRef } from './constants.js';
 
 /**
- * Merge CLAUDE.md: append missing @references from template into existing file.
- * Preserves all existing content, only adds new @references.
+ * Marker constants for ACE-managed sections in CLAUDE.md
+ */
+const ACE_MANAGED_START = '<!-- ace:managed:start -->';
+const ACE_MANAGED_END = '<!-- ace:managed:end -->';
+
+/**
+ * Merge CLAUDE.md using marker-based section replacement.
+ *
+ * Strategy:
+ * 1. If both existing and template have ace:managed markers, replace the section
+ *    between markers with template content, while preserving content outside markers.
+ * 2. Clean up any ACE-owned references outside the managed section (obsolete refs).
+ * 3. If markers are missing or incomplete, fall back to append-only strategy for
+ *    backward compatibility.
+ *
+ * @param {string} existingContent - Current CLAUDE.md content
+ * @param {string} templateContent - Template CLAUDE.md content
+ * @returns {{content: string, added: string[], removed: string[]}} Merged content and change list
  */
 export function mergeClaudeMd(existingContent, templateContent) {
+  // Check if both files have complete marker sections
+  const existingHasMarkers = hasCompleteMarkers(existingContent);
+  const templateHasMarkers = hasCompleteMarkers(templateContent);
+
+  if (existingHasMarkers && templateHasMarkers) {
+    return mergeWithMarkers(existingContent, templateContent);
+  }
+
+  // Fall back to legacy append strategy
+  return mergeWithAppend(existingContent, templateContent);
+}
+
+/**
+ * Check if content has both start and end markers.
+ */
+function hasCompleteMarkers(content) {
+  const hasStart = content.includes(ACE_MANAGED_START);
+  const hasEnd = content.includes(ACE_MANAGED_END);
+  return hasStart && hasEnd;
+}
+
+/**
+ * Merge using marker-based section replacement.
+ * Replaces content between ace:managed markers and cleans up obsolete ACE refs.
+ */
+function mergeWithMarkers(existingContent, templateContent) {
+  // Extract the managed section from template
+  const templateManaged = extractManagedSection(templateContent);
+
+  // Get all ACE-owned refs from template (these are the current/active ones)
+  const templateRefs = extractRefs(templateManaged);
+
+  // Replace the managed section in existing content
+  let result = replaceManagedSection(existingContent, templateManaged);
+
+  // Clean up any obsolete ACE refs outside the managed section
+  const removed = [];
+  const lines = result.split('\n');
+  const cleanedLines = lines.map(line => {
+    const refs = extractRefs(line);
+    const hasObsoleteAceRef = refs.some(ref => {
+      // Check if this is an ACE-owned ref that's NOT in the new template
+      if (isAceOwnedRef(ref)) {
+        const refWithAt = `@${ref}`;
+        if (!templateRefs.includes(refWithAt)) {
+          removed.push(ref);
+          return true; // This line has an obsolete ref
+        }
+      }
+      return false;
+    });
+
+    // Return null to mark for removal, otherwise keep line
+    return hasObsoleteAceRef ? null : line;
+  }).filter(line => line !== null);
+
+  result = cleanedLines.join('\n');
+
+  // Get the new refs that were added (in the managed section)
+  const existingRefs = extractRefs(existingContent);
+  const added = templateRefs
+    .map(ref => ref.replace(/^@/, ''))
+    .filter(ref => !existingRefs.includes(ref));
+
+  return { content: result, added, removed };
+}
+
+/**
+ * Extract content between ace:managed markers.
+ */
+function extractManagedSection(content) {
+  const startIdx = content.indexOf(ACE_MANAGED_START);
+  const endIdx = content.indexOf(ACE_MANAGED_END);
+
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return content;
+  }
+
+  return content.slice(startIdx, endIdx + ACE_MANAGED_END.length);
+}
+
+/**
+ * Replace the managed section in existing content with new managed content.
+ */
+function replaceManagedSection(existingContent, newManagedContent) {
+  const startIdx = existingContent.indexOf(ACE_MANAGED_START);
+  const endIdx = existingContent.indexOf(ACE_MANAGED_END);
+
+  if (startIdx === -1 || endIdx === -1) {
+    return existingContent;
+  }
+
+  const before = existingContent.slice(0, startIdx);
+  const after = existingContent.slice(endIdx + ACE_MANAGED_END.length);
+
+  // Normalize whitespace: ensure single newline separation
+  return before.trimEnd() + '\n' + newManagedContent + '\n' + after.trimStart();
+}
+
+/**
+ * Legacy merge strategy: append missing @references from template.
+ * Used for backward compatibility when markers are not present.
+ */
+function mergeWithAppend(existingContent, templateContent) {
   const existingRefs = extractRefs(existingContent);
   const templateRefs = extractRefs(templateContent);
 
-  const missingRefs = templateRefs.filter(ref => !existingRefs.includes(ref));
+  // Filter out ACE-owned refs from existing (we'll add current ones from template)
+  // This provides some cleanup even in legacy mode
+  const userRefs = existingRefs.filter(ref => !isAceOwnedRef(ref));
+  const templateRefsBare = templateRefs.map(ref => ref.replace(/^@/, ''));
+
+  // Find refs in template but not in user's refs
+  const missingRefs = templateRefsBare.filter(ref => !userRefs.includes(ref));
 
   if (missingRefs.length === 0) {
-    return { content: existingContent, added: [] };
+    return { content: existingContent, added: [], removed: [] };
   }
 
   // Append missing references at the end with a section marker
@@ -32,15 +159,22 @@ export function mergeClaudeMd(existingContent, templateContent) {
   return {
     content: existingContent.trimEnd() + '\n' + appendSection,
     added: missingRefs,
+    removed: [],
   };
 }
 
+/**
+ * Extract @reference paths from content.
+ */
 function extractRefs(content) {
   const refPattern = /@~?\/?\.?claude\/[^\s)]+/g;
   const matches = content.match(refPattern) || [];
-  return matches.map(ref => ref.replace(/^@/, ''));
+  return matches;
 }
 
+/**
+ * Find the full line containing a reference.
+ */
 function findRefLine(content, ref) {
   const lines = content.split('\n');
   return lines.find(line => line.includes(ref));

package/src/core/spec-installer.js

@@ -64,11 +64,6 @@ export class SpecInstaller {
   async runOpenspecInit() {
     if (this.skipOpenspec) return;
 
-    if (await fs.pathExists(this.openspecDir) && !this.force) {
-      this.results.skipped.push('openspec/ (already exists)');
-      return;
-    }
-
     if (this.dryRun) {
       this.results.installed.push('openspec/ (via openspec init)');
       return;

package/templates/CLAUDE.md

@@ -1,5 +1,6 @@
 # 全局配置索引
 
+<!-- ace:managed:start -->
 ## 核心原则
 - @~/.claude/rules/ace/thinking.md - 深度思考原则（序验深广辨简）
 
@@ -15,11 +16,6 @@
 ## 质量控制
 - @~/.claude/rules/ace/memory-policy.md - Memory 质量策略
 
-## Hookify 规则
-- @~/.claude/hooks/ace.hookify.block-dangerous-ops.local.md - 阻止危险操作
-- @~/.claude/hooks/ace.hookify.protect-secrets.local.md - 保护敏感信息
-- @~/.claude/hooks/ace.hookify.safe-git-commands.local.md - Git 安全命令
-- @~/.claude/hooks/ace.hookify.code-quality-gate.local.md - 代码质量门禁
-
 ## 交互规则
 - @~/.claude/rules/ace/interactive-clarify.md - 交互式澄清规则
+<!-- ace:managed:end -->