aether-colony 3.1.4 → 3.1.15

package/bin/cli.js

@@ -70,11 +70,9 @@ const COMMANDS_DEST = path.join(HOME, '.claude', 'commands', 'ant');
 
 // Hub paths
 const HUB_DIR = path.join(HOME, '.aether');
-const HUB_SYSTEM = path.join(HUB_DIR, 'system');
 const HUB_COMMANDS_CLAUDE = path.join(HUB_DIR, 'commands', 'claude');
 const HUB_COMMANDS_OPENCODE = path.join(HUB_DIR, 'commands', 'opencode');
 const HUB_AGENTS = path.join(HUB_DIR, 'agents');
-const HUB_VISUALIZATIONS = path.join(HUB_DIR, 'visualizations');
 const HUB_REGISTRY = path.join(HUB_DIR, 'registry.json');
 const HUB_VERSION = path.join(HUB_DIR, 'version.json');
 
@@ -836,6 +834,122 @@ function gitStashFiles(repoPath, files) {
   }
 }
 
+// Directories to exclude from hub sync (user data, local state)
+const HUB_EXCLUDE_DIRS = ['data', 'dreams', 'checkpoints', 'locks', 'temp'];
+
+/**
+ * Check if a path should be excluded from hub sync
+ * @param {string} relPath - Relative path from .aether/
+ * @returns {boolean} True if should be excluded
+ */
+function shouldExcludeFromHub(relPath) {
+  const parts = relPath.split(path.sep);
+  // Exclude if any part of the path is in the exclude list
+  return parts.some(part => HUB_EXCLUDE_DIRS.includes(part));
+}
+
+/**
+ * Sync .aether/ directory to hub, excluding user data directories
+ * @param {string} srcDir - Source .aether/ directory
+ * @param {string} destDir - Destination hub directory
+ * @returns {object} Sync result with copied, removed, skipped counts
+ */
+function syncAetherToHub(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) {
+    return { copied: 0, removed: 0, skipped: 0 };
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  // Get all files in source, filtering out excluded directories
+  const srcFiles = [];
+  function collectFiles(dir, base) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.relative(base, fullPath);
+
+      if (shouldExcludeFromHub(relPath)) continue;
+
+      if (entry.isDirectory()) {
+        collectFiles(fullPath, base);
+      } else {
+        srcFiles.push(relPath);
+      }
+    }
+  }
+  collectFiles(srcDir, srcDir);
+
+  // Copy files with hash comparison
+  let copied = 0;
+  let skipped = 0;
+  for (const relPath of srcFiles) {
+    const srcPath = path.join(srcDir, relPath);
+    const destPath = path.join(destDir, relPath);
+
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+    // Hash comparison
+    let shouldCopy = true;
+    if (fs.existsSync(destPath)) {
+      const srcHash = hashFileSync(srcPath);
+      const destHash = hashFileSync(destPath);
+      if (srcHash === destHash) {
+        shouldCopy = false;
+        skipped++;
+      }
+    }
+
+    if (shouldCopy) {
+      fs.copyFileSync(srcPath, destPath);
+      if (relPath.endsWith('.sh')) {
+        fs.chmodSync(destPath, 0o755);
+      }
+      copied++;
+    }
+  }
+
+  // Cleanup: remove files in dest that aren't in source (and aren't excluded)
+  const destFiles = [];
+  function collectDestFiles(dir, base) {
+    if (!fs.existsSync(dir)) return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'registry.json' || entry.name === 'version.json' || entry.name === 'manifest.json') continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.relative(base, fullPath);
+
+      if (shouldExcludeFromHub(relPath)) continue;
+
+      if (entry.isDirectory()) {
+        collectDestFiles(fullPath, base);
+      } else {
+        destFiles.push(relPath);
+      }
+    }
+  }
+  collectDestFiles(destDir, destDir);
+
+  const srcSet = new Set(srcFiles);
+  const removed = [];
+  for (const relPath of destFiles) {
+    if (!srcSet.has(relPath)) {
+      removed.push(relPath);
+      try {
+        fs.unlinkSync(path.join(destDir, relPath));
+      } catch (err) {
+        // Ignore cleanup errors
+      }
+    }
+  }
+
+  // Clean up empty directories
+  cleanEmptyDirs(destDir);
+
+  return { copied, removed, skipped };
+}
+
 function setupHub() {
   // Create ~/.aether/ directory structure and populate from package
   try {
@@ -848,17 +962,35 @@ function setupHub() {
       log(`  Warning: previous manifest is invalid, regenerating`);
     }
 
-    // Sync runtime/ -> ~/.aether/system/
+    // Sync runtime/ -> ~/.aether/ (clean production files)
+    // runtime/ is the staging area - explicit allowlist via sync-to-runtime.sh
     const runtimeSrc = path.join(PACKAGE_DIR, 'runtime');
     if (fs.existsSync(runtimeSrc)) {
-      const result = syncDirWithCleanup(runtimeSrc, HUB_SYSTEM);
-      log(`  Hub system: ${result.copied} files -> ${HUB_SYSTEM}`);
+      const result = syncAetherToHub(runtimeSrc, HUB_DIR);
+      log(`  Hub system: ${result.copied} files, ${result.skipped} unchanged -> ${HUB_DIR}`);
       if (result.removed.length > 0) {
         log(`  Hub system: removed ${result.removed.length} stale files`);
         for (const f of result.removed) log(`    - ${f}`);
       }
     }
 
+    // Clean up legacy directories from old hub structure
+    const legacyDirs = [
+      path.join(HUB_DIR, 'system'),
+      path.join(HUB_DIR, '.aether'),
+      path.join(HUB_DIR, 'visualizations'),
+    ];
+    for (const legacyDir of legacyDirs) {
+      if (fs.existsSync(legacyDir)) {
+        try {
+          removeDirSync(legacyDir);
+          log(`  Cleaned up legacy: ${path.basename(legacyDir)}/`);
+        } catch (err) {
+          // Ignore cleanup errors
+        }
+      }
+    }
+
     // Sync .claude/commands/ant/ -> ~/.aether/commands/claude/
     const claudeCmdSrc = fs.existsSync(COMMANDS_SRC)
       ? COMMANDS_SRC
@@ -894,17 +1026,6 @@ function setupHub() {
       }
     }
 
-    // Sync .aether/visualizations/ -> ~/.aether/visualizations/
-    const visualizationsSrc = path.join(PACKAGE_DIR, '.aether', 'visualizations');
-    if (fs.existsSync(visualizationsSrc)) {
-      const result = syncDirWithCleanup(visualizationsSrc, HUB_VISUALIZATIONS);
-      log(`  Hub visualizations: ${result.copied} files -> ${HUB_VISUALIZATIONS}`);
-      if (result.removed.length > 0) {
-        log(`  Hub visualizations: removed ${result.removed.length} stale files`);
-        for (const f of result.removed) log(`    - ${f}`);
-      }
-    }
-
     // Create/preserve registry.json
     if (!fs.existsSync(HUB_REGISTRY)) {
       writeJsonSync(HUB_REGISTRY, { schema_version: 1, repos: [] });
@@ -971,7 +1092,7 @@ async function updateRepo(repoPath, sourceVersion, opts) {
   }
 
   // Use UpdateTransaction for two-phase commit with automatic rollback
-  const transaction = new UpdateTransaction(repoPath, { sourceVersion, quiet });
+  const transaction = new UpdateTransaction(repoPath, { sourceVersion, quiet, force });
 
   try {
     const result = await transaction.execute(sourceVersion, { dryRun });
@@ -980,18 +1101,15 @@ async function updateRepo(repoPath, sourceVersion, opts) {
     const systemCopied = result.sync_result?.system?.copied || 0;
     const commandsCopied = (result.sync_result?.commands?.copied || 0);
     const agentsCopied = result.sync_result?.agents?.copied || 0;
-    const visualizationsCopied = result.sync_result?.visualizations?.copied || 0;
 
     const systemRemoved = result.sync_result?.system?.removed?.length || 0;
     const commandsRemoved = result.sync_result?.commands?.removed?.length || 0;
     const agentsRemoved = result.sync_result?.agents?.removed?.length || 0;
-    const visualizationsRemoved = result.sync_result?.visualizations?.removed?.length || 0;
 
     const allRemovedFiles = [
       ...(result.sync_result?.system?.removed || []),
       ...(result.sync_result?.commands?.removed || []).map(f => `.claude/commands/ant/${f}`),
       ...(result.sync_result?.agents?.removed || []).map(f => `.opencode/agents/${f}`),
-      ...(result.sync_result?.visualizations?.removed || []).map(f => `.aether/visualizations/${f}`),
     ];
 
     return {
@@ -1001,8 +1119,7 @@ async function updateRepo(repoPath, sourceVersion, opts) {
       system: systemCopied,
       commands: commandsCopied,
       agents: agentsCopied,
-      visualizations: visualizationsCopied,
-      removed: systemRemoved + commandsRemoved + agentsRemoved + visualizationsRemoved,
+      removed: systemRemoved + commandsRemoved + agentsRemoved,
       removedFiles: allRemovedFiles,
       stashCreated: !!transaction.checkpoint?.stashRef,
       checkpoint_id: result.checkpoint_id,
@@ -1171,14 +1288,14 @@ program
             console.error(`  Skipping. Use --force to stash and update.`);
             dirty++;
           } else if (result.status === 'dry-run') {
-            log(`  Would update: ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents, ${result.visualizations} visualizations]`);
+            log(`  Would update: ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents]`);
             if (result.removed > 0) {
               log(`  Would remove ${result.removed} stale files:`);
               for (const f of result.removedFiles) log(`    - ${f}`);
             }
             updated++;
           } else if (result.status === 'updated') {
-            log(`  ${c.success('Updated:')} ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents, ${result.visualizations} visualizations]`);
+            log(`  ${c.success('Updated:')} ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents]`);
             if (result.removed > 0) {
               log(`  Removed ${result.removed} stale files:`);
               for (const f of result.removedFiles) log(`    - ${f}`);
@@ -1254,7 +1371,7 @@ program
 
         if (result.status === 'dry-run') {
           console.log(`Would update: ${result.from} -> ${result.to}`);
-          console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files, ${result.visualizations} visualization files`);
+          console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files`);
           if (result.removed > 0) {
             console.log(`  Would remove ${result.removed} stale files:`);
             for (const f of result.removedFiles) console.log(`    - ${f}`);

package/bin/generate-commands.sh

@@ -39,6 +39,28 @@ log_error() {
     echo -e "${RED}[ERROR]${NC} $1"
 }
 
+# Compute SHA hash with error handling
+# Returns 0 on success, 1 on failure
+# Echoes hash on success, error message on failure
+compute_hash() {
+    local file="$1"
+
+    if [[ ! -r "$file" ]]; then
+        echo "NOT_READABLE"
+        return 1
+    fi
+
+    local hash
+    hash=$(shasum "$file" 2>/dev/null | cut -d' ' -f1)
+    if [[ -z "$hash" ]]; then
+        echo "HASH_FAILED"
+        return 1
+    fi
+
+    echo "$hash"
+    return 0
+}
+
 # Count commands in each directory
 count_commands() {
     local dir="$1"
@@ -49,10 +71,17 @@ count_commands() {
     fi
 }
 
-# List command files
+# List command files (PLAN-006 fix #13 - warn about non-.md files)
 list_commands() {
     local dir="$1"
     if [[ -d "$dir" ]]; then
+        # Check for non-.md files and warn
+        local non_md_count
+        non_md_count=$(find "$dir" -type f ! -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+        if [[ "$non_md_count" -gt 0 ]]; then
+            log_warn "$non_md_count non-.md file(s) found in $dir (ignored)"
+        fi
+
         find "$dir" -name "*.md" -exec basename {} \; | sort
     fi
 }
@@ -67,6 +96,19 @@ check_sync() {
     echo "Claude Code commands: $claude_count"
     echo "OpenCode commands:    $opencode_count"
 
+    # PLAN-006 fix #10 - warn about empty directories
+    if [[ "$claude_count" -eq 0 ]] && [[ "$opencode_count" -eq 0 ]]; then
+        log_warn "Both command directories are empty"
+        echo "This may indicate a misconfiguration"
+    fi
+
+    # PLAN-006 fix #11 - warn about large command counts
+    local max_commands=500
+    if [[ "$claude_count" -gt "$max_commands" ]] || [[ "$opencode_count" -gt "$max_commands" ]]; then
+        log_warn "Large number of commands ($claude_count/$opencode_count)"
+        echo "This may cause performance issues during sync checks"
+    fi
+
     if [[ "$claude_count" != "$opencode_count" ]]; then
         log_error "Command counts don't match!"
         return 1
@@ -96,12 +138,16 @@ check_sync() {
 check_content() {
     log_info "Checking content-level sync (checksums)..."
 
-    local claude_files=$(list_commands "$CLAUDE_DIR")
     local drift_count=0
+    local error_count=0
+    local match_count=0
     local drift_files=""
+    local error_files=""
 
-    for file in $claude_files; do
-        local claude_file="$CLAUDE_DIR/$file"
+    # Use null delimiter for safe iteration (handles filenames with spaces)
+    while IFS= read -r -d '' claude_file; do
+        local file
+        file=$(basename "$claude_file")
         local opencode_file="$OPENCODE_DIR/$file"
 
         # Skip if OpenCode file doesn't exist (already caught by Pass 1)
@@ -109,10 +155,23 @@ check_content() {
             continue
         fi
 
-        # Compare SHA-1 checksums (portable across macOS and Linux)
+        # Compute hashes with error handling
         local claude_hash opencode_hash
-        claude_hash=$(shasum "$claude_file" | cut -d' ' -f1)
-        opencode_hash=$(shasum "$opencode_file" | cut -d' ' -f1)
+        claude_hash=$(compute_hash "$claude_file")
+        if [[ $? -ne 0 ]]; then
+            log_error "Cannot hash $claude_file ($claude_hash)"
+            error_files="${error_files}  ${file} (${claude_hash})\n"
+            error_count=$((error_count + 1))
+            continue
+        fi
+
+        opencode_hash=$(compute_hash "$opencode_file")
+        if [[ $? -ne 0 ]]; then
+            log_error "Cannot hash $opencode_file ($opencode_hash)"
+            error_files="${error_files}  ${file} (${opencode_hash})\n"
+            error_count=$((error_count + 1))
+            continue
+        fi
 
         if [[ "$claude_hash" != "$opencode_hash" ]]; then
             drift_count=$((drift_count + 1))
@@ -122,13 +181,34 @@ check_content() {
             echo "  Claude:  $claude_hash"
             echo "  OpenCode: $opencode_hash"
 
-            # Show first 10 lines of diff for context (|| true to handle set -e)
+            # PLAN-006 fix #12 - improved diff error handling
             echo "  ---"
-            diff -u "$claude_file" "$opencode_file" | head -20 || true
+            local diff_output
+            if diff_output=$(diff -u "$claude_file" "$opencode_file" 2>&1); then
+                # Files are same (shouldn't happen if hashes differ, but handle it)
+                echo "$diff_output" | head -20
+            else
+                local diff_exit=$?
+                if [[ "$diff_output" == *"diff:"* && "$diff_output" == *"No such file"* ]]; then
+                    log_error "diff failed: $diff_output"
+                else
+                    # Normal diff output (exit 1 means files differ)
+                    echo "$diff_output" | head -20
+                fi
+            fi
             echo "  ---"
             echo ""
+        else
+            match_count=$((match_count + 1))
         fi
-    done
+    done < <(find "$CLAUDE_DIR" -name "*.md" -type f -print0 2>/dev/null | sort -z)
+
+    # Report results
+    if [[ "$error_count" -gt 0 ]]; then
+        echo ""
+        log_error "Hash errors in $error_count file(s):"
+        echo -e "$error_files"
+    fi
 
     if [[ "$drift_count" -gt 0 ]]; then
         echo ""
@@ -137,7 +217,11 @@ check_content() {
         return 1
     fi
 
-    log_info "All file contents match (checksums verified)"
+    if [[ "$error_count" -gt 0 ]]; then
+        return 1
+    fi
+
+    log_info "All file contents match (checksums verified: $match_count files)"
     return 0
 }
 
@@ -145,10 +229,10 @@ check_content() {
 show_diff() {
     log_info "Comparing command sets..."
 
-    local claude_files=$(list_commands "$CLAUDE_DIR")
-
-    for file in $claude_files; do
-        local claude_file="$CLAUDE_DIR/$file"
+    # Use null delimiter for safe iteration (handles filenames with spaces)
+    while IFS= read -r -d '' claude_file; do
+        local file
+        file=$(basename "$claude_file")
         local opencode_file="$OPENCODE_DIR/$file"
 
         if [[ ! -f "$opencode_file" ]]; then
@@ -163,7 +247,7 @@ show_diff() {
         if [[ "$claude_size" != "$opencode_size" ]]; then
             echo "$file: $claude_size lines (Claude) vs $opencode_size lines (OpenCode)"
         fi
-    done
+    done < <(find "$CLAUDE_DIR" -name "*.md" -type f -print0 2>/dev/null | sort -z)
 }
 
 # Display help

package/bin/lib/caste-colors.js

@@ -17,11 +17,11 @@ const pc = require('picocolors');
 
 // Caste definitions with colors and emojis (per CONTEXT.md decisions)
 const CASTE_STYLES = {
-  builder:  { color: 'blue',   emoji: '🔨', ansi: '\033[34m', pc: pc.blue },
-  watcher:  { color: 'green',  emoji: '👁️',  ansi: '\033[32m', pc: pc.green },
-  scout:    { color: 'yellow', emoji: '🔍', ansi: '\033[33m', pc: pc.yellow },
-  chaos:    { color: 'red',    emoji: '🎲', ansi: '\033[31m', pc: pc.red },
-  prime:    { color: 'magenta',emoji: '👑', ansi: '\033[35m', pc: pc.magenta }
+  builder:  { color: 'blue',   emoji: '🔨🐜', ansi: '\033[34m', pc: pc.blue },
+  watcher:  { color: 'green',  emoji: '👁️🐜',  ansi: '\033[32m', pc: pc.green },
+  scout:    { color: 'yellow', emoji: '🔍🐜', ansi: '\033[33m', pc: pc.yellow },
+  chaos:    { color: 'red',    emoji: '🎲🐜', ansi: '\033[31m', pc: pc.red },
+  prime:    { color: 'magenta',emoji: '👑🐜', ansi: '\033[35m', pc: pc.magenta }
 };
 
 // Get style for a caste (case-insensitive)

package/bin/lib/errors.js

@@ -179,6 +179,21 @@ class ConfigurationError extends AetherError {
   }
 }
 
+/**
+ * StateSchemaError - State file schema validation errors (PLAN-007 Fix 3)
+ */
+class StateSchemaError extends AetherError {
+  constructor(message, details = {}) {
+    super(
+      ErrorCodes.E_INVALID_STATE,
+      message,
+      details,
+      'Check state file structure and fix schema errors, or restore from backup'
+    );
+    this.name = 'StateSchemaError';
+  }
+}
+
 /**
  * Map error codes to sysexits.h exit codes
  * @param {string} code - Error code
@@ -233,6 +248,7 @@ module.exports = {
   ValidationError,
   FileSystemError,
   ConfigurationError,
+  StateSchemaError,
   ErrorCodes,
   getExitCode,
   wrapError,