aether-colony 5.0.0 → 5.2.1

package/bin/lib/update-transaction.js

@@ -172,10 +172,35 @@ class UpdateTransaction {
 
     // Directories to exclude from sync (user data, local state, and separately-synced dirs)
     // v4.0: archive and chambers added — these are private and must not sync to target repos
-    this.EXCLUDE_DIRS = ['data', 'dreams', 'checkpoints', 'locks', 'temp', 'agents', 'commands', 'rules', 'archive', 'chambers'];
+    // v6.0: oracle, midden, exchange added for complete user data protection
+    this.EXCLUDE_DIRS = ['data', 'dreams', 'oracle', 'midden', 'checkpoints', 'locks', 'temp', 'agents', 'commands', 'rules', 'archive', 'chambers', 'exchange'];
+
+    // Files to exclude from sync (user wisdom, protected files)
+    this.EXCLUDE_FILES = ['QUEEN.md'];
 
     // Target directories for git safety checks
     this.targetDirs = ['.aether', '.claude/commands/ant', '.claude/agents/ant', '.claude/rules', '.opencode/commands/ant', '.opencode/agents'];
+
+    // Managed paths for update safety checks (must align with files update can actually modify)
+    this.protectedAetherDirs = new Set([
+      'data',
+      'dreams',
+      'oracle',
+      'midden',
+      'checkpoints',
+      'locks',
+      'temp',
+      'archive',
+      'chambers',
+      'exchange',
+    ]);
+    this.managedPrefixes = [
+      '.claude/commands/ant',
+      '.claude/agents/ant',
+      '.claude/rules',
+      '.opencode/commands/ant',
+      '.opencode/agents',
+    ];
   }
 
   /**
@@ -210,7 +235,22 @@ class UpdateTransaction {
    */
   writeJsonSync(filePath, data) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+    const content = JSON.stringify(data, null, 2) + '\n';
+    const tmpPath = filePath + '.tmp';
+    try {
+      fs.writeFileSync(tmpPath, content);
+      fs.renameSync(tmpPath, filePath);
+    } catch (err) {
+      // Clean up temp file on failure
+      try {
+        if (fs.existsSync(tmpPath)) {
+          fs.unlinkSync(tmpPath);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+      throw err;
+    }
   }
 
   /**
@@ -228,6 +268,40 @@ class UpdateTransaction {
     }
   }
 
+  /**
+   * Copy file atomically using temp file + rename pattern
+   * Prevents partial file corruption on process interruption
+   * @param {string} srcPath - Source file path
+   * @param {string} destPath - Destination file path
+   * @private
+   */
+  copyFileAtomic(srcPath, destPath) {
+    const tempPath = `${destPath}.tmp.${process.pid}.${Date.now()}`;
+
+    try {
+      // Copy to temp file first
+      fs.copyFileSync(srcPath, tempPath);
+
+      // Atomic rename (POSIX guarantees atomicity)
+      fs.renameSync(tempPath, destPath);
+
+      // Set executable permission for shell scripts
+      if (destPath.endsWith('.sh')) {
+        fs.chmodSync(destPath, 0o755);
+      }
+    } catch (err) {
+      // Clean up temp file on failure
+      try {
+        if (fs.existsSync(tempPath)) {
+          fs.unlinkSync(tempPath);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+      throw err;
+    }
+  }
+
   /**
    * Check if path is a git repository
    * @returns {boolean} True if git repo
@@ -242,6 +316,54 @@ class UpdateTransaction {
     }
   }
 
+  /**
+   * Normalize git porcelain path output.
+   * Handles rename syntax and quoted/escaped paths.
+   * @param {string} filePath - Raw path fragment from git porcelain
+   * @returns {string} Normalized path
+   * @private
+   */
+  normalizePorcelainPath(filePath) {
+    let normalized = filePath;
+
+    if (normalized.includes(' -> ')) {
+      normalized = normalized.split(' -> ').pop();
+    }
+
+    if (normalized.startsWith('"') && normalized.endsWith('"')) {
+      normalized = normalized
+        .slice(1, -1)
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\');
+    }
+
+    return normalized;
+  }
+
+  /**
+   * True when a path is managed by update and may be overwritten by sync.
+   * Paths under .aether/data and other protected runtime dirs are intentionally excluded.
+   * @param {string} filePath - Normalized or raw path
+   * @returns {boolean} Whether update should treat this path as managed
+   * @private
+   */
+  isManagedUpdatePath(filePath) {
+    const p = this.normalizePorcelainPath(filePath);
+
+    if (p === '.aether' || p.startsWith('.aether/')) {
+      const rel = p === '.aether' ? '' : p.slice('.aether/'.length);
+      if (!rel) return true;
+
+      const first = rel.split('/')[0];
+      if (!first || first.startsWith('.')) return false;
+      if (this.protectedAetherDirs.has(first)) return false;
+      if (rel === 'QUEEN.md') return false;
+      return true;
+    }
+
+    return this.managedPrefixes.some(prefix => p === prefix || p.startsWith(`${prefix}/`));
+  }
+
   /**
    * Detect dirty repository state with detailed categorization
    * @returns {object} Dirty state info: { isDirty, tracked, untracked, staged }
@@ -257,14 +379,25 @@ class UpdateTransaction {
         encoding: 'utf8',
       });
 
-      const lines = result.trim().split('\n').filter(Boolean);
+      // Preserve the two-column porcelain status prefix on each line.
+      // Using `trim()` on the whole output would strip leading spaces from
+      // the first line and can misclassify unstaged vs staged changes.
+      const lines = result.split('\n').filter(line => line.trim().length > 0);
       const tracked = [];
       const untracked = [];
       const staged = [];
+      let managedCount = 0;
 
       for (const line of lines) {
         const status = line.slice(0, 2);
-        const filePath = line.slice(3);
+        const rawPath = line.slice(3);
+        const filePath = this.normalizePorcelainPath(rawPath);
+
+        if (!this.isManagedUpdatePath(filePath)) {
+          continue;
+        }
+
+        managedCount++;
 
         // Staged changes (in index)
         if (status[0] !== ' ' && status[0] !== '?') {
@@ -281,7 +414,7 @@ class UpdateTransaction {
       }
 
       return {
-        isDirty: lines.length > 0,
+        isDirty: managedCount > 0,
         tracked,
         untracked,
         staged,
@@ -580,10 +713,7 @@ class UpdateTransaction {
           }
 
           if (shouldCopy) {
-            fs.copyFileSync(srcPath, destPath);
-            if (relPath.endsWith('.sh')) {
-              fs.chmodSync(destPath, 0o755);
-            }
+            this.copyFileAtomic(srcPath, destPath);
             copied++;
           }
         } catch (err) {
@@ -653,7 +783,52 @@ class UpdateTransaction {
    */
   shouldExclude(relPath) {
     const parts = relPath.split(path.sep);
-    return parts.some(part => this.EXCLUDE_DIRS.includes(part));
+    // Check for excluded directories
+    if (parts.some(part => this.EXCLUDE_DIRS.includes(part))) {
+      return true;
+    }
+    // Check for excluded files (QUEEN.md protection)
+    const basename = path.basename(relPath);
+    if (this.EXCLUDE_FILES.includes(basename)) {
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get files that the update would actually overwrite (hub version differs from repo version).
+   * Used by the dirty-file check to only warn about files that matter.
+   * @returns {string[]} Repo-relative paths of files that would be overwritten
+   */
+  getConflictingFiles() {
+    const conflicts = [];
+
+    // Helper: check a hub->repo dir pair for differing files
+    const checkDir = (hubDir, repoDir, prefix) => {
+      if (!fs.existsSync(hubDir)) return;
+      const srcFiles = this.listFilesRecursive(hubDir);
+      for (const relPath of srcFiles) {
+        if (this.shouldExclude(relPath)) continue;
+        const destPath = path.join(repoDir, relPath);
+        if (fs.existsSync(destPath)) {
+          const srcHash = this.hashFileSync(path.join(hubDir, relPath));
+          const destHash = this.hashFileSync(destPath);
+          if (srcHash !== destHash) {
+            conflicts.push(`${prefix}${relPath}`);
+          }
+        }
+      }
+    };
+
+    const repoAether = path.join(this.repoPath, '.aether');
+    checkDir(this.HUB_SYSTEM_DIR, repoAether, '.aether/');
+    checkDir(this.HUB_COMMANDS_CLAUDE, path.join(this.repoPath, '.claude', 'commands', 'ant'), '.claude/commands/ant/');
+    checkDir(this.HUB_COMMANDS_OPENCODE, path.join(this.repoPath, '.opencode', 'commands', 'ant'), '.opencode/commands/ant/');
+    checkDir(this.HUB_AGENTS, path.join(this.repoPath, '.opencode', 'agents'), '.opencode/agents/');
+    checkDir(this.HUB_AGENTS_CLAUDE, path.join(this.repoPath, '.claude', 'agents', 'ant'), '.claude/agents/ant/');
+    checkDir(this.HUB_RULES, path.join(this.repoPath, '.claude', 'rules'), '.claude/rules/');
+
+    return conflicts;
   }
 
   /**
@@ -699,28 +874,30 @@ class UpdateTransaction {
       const srcPath = path.join(srcDir, relPath);
       const destPath = path.join(destDir, relPath);
 
+      // Hash comparison: determine if copy is needed (runs for both dry-run and actual)
+      let shouldCopy = true;
+      if (fs.existsSync(destPath)) {
+        const srcHash = this.hashFileSync(srcPath);
+        const destHash = this.hashFileSync(destPath);
+        if (srcHash === destHash) {
+          shouldCopy = false;
+          skipped++;
+        }
+      }
+
       if (!dryRun) {
         fs.mkdirSync(path.dirname(destPath), { recursive: true });
 
-        // Hash comparison
-        let shouldCopy = true;
-        if (fs.existsSync(destPath)) {
-          const srcHash = this.hashFileSync(srcPath);
-          const destHash = this.hashFileSync(destPath);
-          if (srcHash === destHash) {
-            shouldCopy = false;
-            skipped++;
-          }
+        if (shouldCopy) {
+          this.copyFileAtomic(srcPath, destPath);
+          copied++;  // FIX: Only increment when actually copied
         }
-
+      } else {
+        // dry-run: count files that WOULD be copied
         if (shouldCopy) {
-          fs.copyFileSync(srcPath, destPath);
-          if (relPath.endsWith('.sh')) {
-            fs.chmodSync(destPath, 0o755);
-          }
+          copied++;  // Count only files that would actually be copied
         }
       }
-      copied++;
     }
 
     // Cleanup: remove files in dest that aren't in source
@@ -766,18 +943,75 @@ class UpdateTransaction {
     return { copied, removed, skipped };
   }
 
+  /**
+   * Move a file or directory to trash instead of deleting
+   * @param {string} itemPath - Path to file or directory
+   * @param {string} repoPath - Repository root for trash location
+   * @returns {boolean} True if moved to trash successfully
+   * @private
+   */
+  moveToTrash(itemPath, repoPath) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const trashDir = path.join(repoPath, '.aether', '.trash', timestamp);
+    const basename = path.basename(itemPath);
+    const trashPath = path.join(trashDir, basename);
+
+    try {
+      fs.mkdirSync(trashDir, { recursive: true });
+      fs.renameSync(itemPath, trashPath);
+      return true;
+    } catch (err) {
+      // If rename fails (cross-device), fall back to copy + delete
+      try {
+        fs.mkdirSync(trashDir, { recursive: true });
+        if (fs.statSync(itemPath).isDirectory()) {
+          fs.cpSync(itemPath, path.join(trashDir, basename), { recursive: true });
+          fs.rmSync(itemPath, { recursive: true, force: true });
+        } else {
+          fs.copyFileSync(itemPath, path.join(trashDir, basename));
+          fs.unlinkSync(itemPath);
+        }
+        return true;
+      } catch (fallbackErr) {
+        return false;
+      }
+    }
+  }
+
   /**
    * Remove known stale directories and files left behind by pre-3.0.0 versions.
-   * These paths were incorrectly distributed in earlier releases and must be
-   * explicitly removed — EXCLUDE_DIRS prevents NEW pollution but does not clean
-   * items that already exist on disk.
+   *
+   * IMPORTANT: Removed items are moved to .aether/.trash/ NOT deleted.
+   * Users can inspect and manually clean trash when ready.
+   * Trash folders are timestamped for easy identification.
+   *
+   * Protected paths (never cleaned):
+   * - .aether/data/ - Colony state
+   * - .aether/dreams/ - Session notes
+   * - .aether/oracle/ - Research progress
+   * - .aether/midden/ - Failure tracking
+   * - .aether/QUEEN.md - User's wisdom file
    *
    * Idempotent: safe to call when items do not exist.
    *
    * @param {string} repoPath - Absolute path to the target repository root
-   * @returns {{ cleaned: string[], failed: Array<{label: string, error: string}> }}
+   * @returns {{ cleaned: string[], failed: Array<{label: string, error: string}>, trashDir: string }}
    */
   cleanupStaleAetherDirs(repoPath) {
+    // Safety check: never clean protected directories
+    const protectedDirs = ['data', 'dreams', 'oracle', 'midden'];
+    const protectedFiles = ['QUEEN.md'];
+
+    // Verify none of our stale items are in protected paths
+    const aetherDir = path.join(repoPath, '.aether');
+    for (const dir of protectedDirs) {
+      const protectedPath = path.join(aetherDir, dir);
+      if (fs.existsSync(protectedPath)) {
+        // Log that protected dir exists and will be preserved
+        this.log?.(`  Preserving protected directory: .aether/${dir}/`);
+      }
+    }
+
     const staleItems = [
       {
         path: path.join(repoPath, '.aether', 'agents'),
@@ -806,18 +1040,17 @@ class UpdateTransaction {
       }
 
       try {
-        if (item.type === 'dir') {
-          fs.rmSync(item.path, { recursive: true, force: true });
+        if (this.moveToTrash(item.path, repoPath)) {
+          cleaned.push(item.label);
         } else {
-          fs.unlinkSync(item.path);
+          failed.push({ label: item.label, error: 'Failed to move to trash' });
         }
-        cleaned.push(item.label);
       } catch (err) {
         failed.push({ label: item.label, error: err.message });
       }
     }
 
-    return { cleaned, failed };
+    return { cleaned, failed, trashDir: path.join(repoPath, '.aether', '.trash') };
   }
 
   /**
@@ -1250,6 +1483,23 @@ class UpdateTransaction {
         return false;
       }
 
+      // Restore backed-up managed files before stash pop
+      // Stash only contains the user's local modifications; managed files
+      // overwritten by syncFiles must be restored from the checkpoint backup.
+      if (this.checkpoint.backedUpFiles && this.checkpoint.backedUpFiles.length > 0) {
+        for (const entry of this.checkpoint.backedUpFiles) {
+          try {
+            if (fs.existsSync(entry.backupPath)) {
+              fs.mkdirSync(path.dirname(path.join(this.repoPath, entry.relPath)), { recursive: true });
+              fs.copyFileSync(entry.backupPath, path.join(this.repoPath, entry.relPath));
+              this.log(`  Restored managed file: ${entry.relPath}`);
+            }
+          } catch (err) {
+            this.log(`  Warning: could not restore ${entry.relPath}: ${err.message}`);
+          }
+        }
+      }
+
       // Restore from stash if available
       if (this.checkpoint.stashRef) {
         try {
@@ -1451,4 +1701,4 @@ module.exports = {
   UpdateError,
   UpdateErrorCodes,
   TransactionStates,
-};
+};

package/bin/npx-install.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+/**
+ * npx-install.js — Professional installer for Aether Colony
+ *
+ * Usage: npx aether-colony install
+ *
+ * Creates the global hub at ~/.aether/ with all system files,
+ * slash commands, and agent definitions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const BANNER = `
+      █████╗ ███████╗████████╗██╗  ██╗███████╗██████╗
+     ██╔══██╗██╔════╝╚══██╔══╝██║  ██║██╔════╝██╔══██╗
+     ███████║█████╗     ██║   ███████║█████╗  ██████╔╝
+     ██╔══██║██╔══╝     ██║   ██╔══██║██╔══╝  ██╔══██╗
+     ██║  ██║███████╗   ██║   ██║  ██║███████╗██║  ██║
+     ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
+`;
+
+const AETHER_VERSION = require('../package.json').version;
+const HOME_DIR = os.homedir();
+const HUB_DIR = path.join(HOME_DIR, '.aether');
+const CLAUDE_COMMANDS_DIR = path.join(HOME_DIR, '.claude', 'commands', 'ant');
+const CLAUDE_AGENTS_DIR = path.join(HOME_DIR, '.claude', 'agents', 'ant');
+
+// Get the package root (where this script is located)
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const AETHER_SRC = path.join(PACKAGE_ROOT, '.aether');
+const CLAUDE_COMMANDS_SRC = path.join(PACKAGE_ROOT, '.claude', 'commands', 'ant');
+const OPENCODE_AGENTS_SRC = path.join(PACKAGE_ROOT, '.opencode', 'agents');
+const OPENCODE_COMMANDS_SRC = path.join(PACKAGE_ROOT, '.opencode', 'commands', 'ant');
+
+function log(message, type = 'info') {
+  const icons = {
+    info: 'ℹ',
+    success: '✓',
+    warning: '⚠',
+    error: '✗',
+    ant: '🐜'
+  };
+  console.log(`${icons[type] || '•'} ${message}`);
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
+  }
+  return false;
+}
+
+function copyDir(src, dest, options = {}) {
+  const { exclude = [] } = options;
+  ensureDir(dest);
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  let copied = 0;
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    // Skip excluded directories
+    if (exclude.includes(entry.name)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      copied += copyDir(srcPath, destPath, options);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      copied++;
+    }
+  }
+
+  return copied;
+}
+
+function copyFile(src, dest) {
+  const destDir = path.dirname(dest);
+  ensureDir(destDir);
+  fs.copyFileSync(src, dest);
+}
+
+function install() {
+  console.log(BANNER);
+  console.log('\n');
+
+  let filesCopied = 0;
+
+  // Step 1: Create hub directory structure
+  log('Creating hub directory structure...', 'ant');
+  const hubDirs = [
+    path.join(HUB_DIR, 'system'),
+    path.join(HUB_DIR, 'system', 'docs'),
+    path.join(HUB_DIR, 'system', 'utils'),
+    path.join(HUB_DIR, 'system', 'templates'),
+    path.join(HUB_DIR, 'system', 'schemas'),
+    path.join(HUB_DIR, 'system', 'exchange'),
+    path.join(HUB_DIR, 'system', 'rules'),
+    path.join(HUB_DIR, 'data'),
+    path.join(HUB_DIR, 'chambers')
+  ];
+
+  for (const dir of hubDirs) {
+    if (ensureDir(dir)) {
+      log(`  Created ${path.relative(HOME_DIR, dir)}`, 'info');
+    }
+  }
+
+  // Step 2: Copy system files from .aether/
+  log('Copying system files to hub...', 'ant');
+  if (fs.existsSync(AETHER_SRC)) {
+    // Private directories to exclude
+    const excludeDirs = ['data', 'dreams', 'oracle', 'checkpoints', 'locks', 'temp', 'archive', 'chambers'];
+    filesCopied += copyDir(AETHER_SRC, path.join(HUB_DIR, 'system'), { exclude: excludeDirs });
+    log(`  Copied ${filesCopied} files from .aether/`, 'success');
+  } else {
+    log('  Warning: .aether/ source not found', 'warning');
+  }
+
+  // Step 3: Copy Claude Code commands
+  log('Installing Claude Code commands...', 'ant');
+  if (fs.existsSync(CLAUDE_COMMANDS_SRC)) {
+    const cmdCount = copyDir(CLAUDE_COMMANDS_SRC, CLAUDE_COMMANDS_DIR);
+    log(`  Installed ${cmdCount} slash commands to ~/.claude/commands/ant/`, 'success');
+    filesCopied += cmdCount;
+  }
+
+  // Step 4: Copy Claude Code agents (from OpenCode agents)
+  log('Installing Claude Code agents...', 'ant');
+  if (fs.existsSync(OPENCODE_AGENTS_SRC)) {
+    const agentCount = copyDir(OPENCODE_AGENTS_SRC, CLAUDE_AGENTS_DIR);
+    log(`  Installed ${agentCount} agents to ~/.claude/agents/ant/`, 'success');
+    filesCopied += agentCount;
+  }
+
+  // Step 5: Write version file
+  const versionData = {
+    version: AETHER_VERSION,
+    installed_at: new Date().toISOString(),
+    package_root: PACKAGE_ROOT
+  };
+  fs.writeFileSync(
+    path.join(HUB_DIR, 'version.json'),
+    JSON.stringify(versionData, null, 2)
+  );
+  log('  Version info written', 'success');
+
+  // Step 6: Create global QUEEN.md if missing
+  const globalQueen = path.join(HUB_DIR, 'QUEEN.md');
+  if (!fs.existsSync(globalQueen)) {
+    const queenTemplate = path.join(HUB_DIR, 'system', 'templates', 'QUEEN.md.template');
+    if (fs.existsSync(queenTemplate)) {
+      let content = fs.readFileSync(queenTemplate, 'utf8');
+      content = content.replace(/{TIMESTAMP}/g, new Date().toISOString());
+      fs.writeFileSync(globalQueen, content);
+      log('  Created global QUEEN.md', 'success');
+    }
+  }
+
+  // Summary
+  console.log('\n  ─────────────────────────────────────────────\n');
+  log(`Installation complete! ${filesCopied} files installed.`, 'success');
+  console.log('\n  Next steps:\n');
+  console.log('    1. Run /ant:init "your goal" in any project');
+  console.log('    2. Use /ant:build to execute phases');
+  console.log('    3. Run /ant:help for command reference\n');
+  console.log('  ─────────────────────────────────────────────\n');
+}
+
+// Run installer
+install();