@shirayner/ace 0.1.1-snapshot.6 → 0.1.2

package/README.en-US.md

@@ -16,15 +16,20 @@
 
 ```
 $ ace init
-? Your role: Fullstack Developer
-? Preset: full
-✔ core installed
-✔ rules installed
-✔ plugin installed (ace:auto-goal, ace:coding, ...)
-✔ hookify installed
-✔ hooks installed
-✔ memory installed
-Done! Your AI coding environment is ready.
+◇  ace v0.1.2
+│
+◇  Installed to ~/.claude/
+│
+│  ◆ Core Config     2 files
+│  ◆ Rules           8 files
+│  ◆ Plugin          installed
+│  ◆ Hooks           1 file
+│  ◆ Safety Guards   7 files
+│  ◆ Memory          2 files
+│
+◆  20 installed
+│
+└  Done. Go to your project and run ace spec init.
 ```
 
 ### Spec 驱动开发

package/README.md

@@ -45,15 +45,31 @@ ace init
 
 ```bash
 $ ace init
-? 选择你的角色: Fullstack Developer
-? 选择安装预设: full (完整功能)
-✓ Core 核心配置已安装
-✓ 8 条认知规则已部署
-✓ 4 个 AI Skills 已激活 (ace:auto-goal, ace:coding, ...)
-✓ Hookify 安全守卫已启用
-✓ 角色钩子脚本已配置
-✓ 记忆系统已初始化
-Done! 你的 AI 开发环境已就绪。
+◇  ace v0.1.2
+│
+◇  Installed to ~/.claude/
+│
+│  ◆ Core Config     2 files
+│  ◆ Rules           8 files
+│  ◆ Plugin          installed
+│  ◆ Hooks           1 file
+│  ◆ Safety Guards   7 files
+│  ◆ Memory          2 files
+│
+◆  20 installed
+│
+┌  Next steps
+│  Get started
+│    1. cd <your-project> && ace spec init
+│    2. Open Claude Code, type: /opsx:propose
+│
+│  Customize
+│    Change role      edit ~/.claude/memory/user_profile.md
+│    Adjust rules     edit ~/.claude/rules/ace/
+│    Safety guards    edit ~/.claude/hookify.ace.*.local.md
+│    Verify setup     ace doctor
+└
+└  Done. Go to your project and run ace spec init.
 ```
 
 ### Spec Coding 完整流程
@@ -146,30 +162,6 @@ All systems operational.
 
 ---
 
-## 📦 安装预设
-
-| 组件                                       | `full` | `safe` | `minimal` |
-| ------------------------------------------ | :------: | :------: | :---------: |
-| **Core** (CLAUDE.md + settings.json) |    ✅    |    ✅    |     ✅     |
-| **Rules** (8 条认知与代码质量规则)   |    ✅    |    ✅    |     ✅     |
-| **Plugin** (4 个 Skills)             |    ✅    |    ✅    |     ✅     |
-| **Hooks** (角色相关脚本)             |    ✅    |    ❌    |     ❌     |
-| **Hookify** (3 个安全守卫)           |    ✅    |    ✅    |     ❌     |
-| **Memory** (模板 + 开发者画像)       |    ✅    |    ✅    |     ❌     |
-
-```bash
-# 完整功能（推荐）
-ace init --preset full
-
-# 安全优先（适合团队协作）
-ace init --preset safe
-
-# 最小安装（仅核心功能）
-ace init --preset minimal
-```
-
----
-
 ## 🎓 核心设计理念
 
 ACE 的设计融合了多学科的深层洞察：
@@ -283,7 +275,8 @@ claude
 
 ACE 遵循**零侵入**原则：
 
-- **智能合并** — 与现有配置共存，从不覆盖
+- **智能合并** — CLAUDE.md 使用标记区块替换，settings.json 深度合并，用户配置始终保留
+- **ACE 文件自动覆盖** — rules/ace/*、hooks/* 等 ACE 自有文件升级时自动更新，无需用户决策
 - **自动备份** — 首次安装前创建完整快照
 - **干净卸载** — `ace uninstall` 一键恢复原始状态
 - **命名空间隔离** — 所有文件使用 `ace/` 前缀，避免冲突

package/package.json

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

package/src/commands/init.js

@@ -2,7 +2,7 @@ import * as p from '@clack/prompts';
 import path from 'path';
 import fs from 'fs-extra';
 import { createRequire } from 'module';
-import { PRESETS, COMPONENTS, CLAUDE_DIR, TEMPLATES_DIR } 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';
 
@@ -196,8 +196,10 @@ async function buildInstallPreview(installer, components) {
       if (await fs.pathExists(srcDir)) {
         const files = (await fs.readdir(srcDir)).filter(f => f.endsWith('.md'));
         for (const f of files) {
-          if (await fs.pathExists(path.join(destDir, f))) {
-            preview.conflict.push(path.join(component.rulesDir, f).replace(/\\/g, '/'));
+          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);
           }
         }
       }
@@ -207,7 +209,8 @@ async function buildInstallPreview(installer, components) {
       for (const file of component.conditional) {
         if (file.roles?.includes(installer.role)) {
           const destPath = path.join(installer.targetDir, file.dest);
-          if (await fs.pathExists(destPath)) {
+          // ACE-owned files are overwritten directly, not shown as conflicts
+          if (await fs.pathExists(destPath) && !isAceOwnedFile(file.dest)) {
             preview.conflict.push(file.dest);
           }
         }

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