antigravity-ai-kit 3.2.0 → 3.4.0

package/README.md

@@ -1,6 +1,6 @@
 # 🚀 Antigravity AI Kit
 
-![version](https://img.shields.io/badge/version-3.2.0-blue)
+![version](https://img.shields.io/badge/version-3.3.1-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 ![AI Agents](https://img.shields.io/badge/AI%20Agents-19-purple)
 ![Skills](https://img.shields.io/badge/Skills-32-orange)
@@ -100,22 +100,14 @@ Creates a new project with `.agent/` pre-configured. Templates: `minimal`, `node
 npx antigravity-ai-kit init
 ```
 
-This automatically copies the `.agent/` folder to your project.
-
-### Option 3: Manual Installation
+### 🔄 Updating
 
 ```bash
-# 1. Clone the repository
-git clone https://github.com/besync-labs/antigravity-ai-kit.git
-
-# 2. Copy .agent/ to your project
-cp -r antigravity-ai-kit/.agent/ your-project/.agent/
-
-# 3. Start your session
-/status
+ag-kit update             # Non-destructive — preserves your customizations
+ag-kit update --dry-run   # Preview changes without applying
 ```
 
-That's it! The kit is now active and ready to accelerate your development.
+> **Prefer `ag-kit update` over `ag-kit init --force`**. The update command preserves your session data, ADRs, learning contexts, and customizations. Use `init --force` only for clean reinstalls.
 
 ### ✅ Verify Installation
 
@@ -124,6 +116,31 @@ ag-kit verify     # Manifest integrity check
 ag-kit scan       # Security scan
 ```
 
+### 🛡️ Safety Guarantees
+
+Antigravity AI Kit is designed to **never touch your project files**. All operations are scoped to the `.agent/` directory.
+
+| Your Project Files | Safe? | Details |
+|:---|:---|:---|
+| Source code (`src/`, `lib/`, `app/`) | ✅ Never touched | Init/update only operates on `.agent/` |
+| Config files (`.env`, `package.json`) | ✅ Never touched | No project config is read or written |
+| Documentation (`docs/`, `README.md`) | ✅ Never touched | Only `.agent/` docs are managed |
+| Tests (`tests/`, `__tests__/`) | ✅ Never touched | Kit tests are internal to the package |
+| Platform files (`android/`, `ios/`) | ✅ Never touched | No platform-specific operations |
+
+**`init --force` safety features (v3.3.1+):**
+- 🔒 **Auto-backup**: Creates timestamped backup of existing `.agent/` before overwriting
+- ⚛️ **Atomic copy**: Uses temp directory + rename to prevent corruption on failure
+- 🔗 **Symlink guard**: Skips symbolic links to prevent path traversal attacks
+- ⚠️ **Session warning**: Alerts if active work-in-progress would be destroyed
+- 🔍 **Dry-run preview**: `--dry-run --force` shows exactly which user files would be overwritten
+
+**`update` preserved files:**
+- `session-context.md` — Your active session notes
+- `session-state.json` — Your session metadata
+- `decisions/` — Your Architecture Decision Records
+- `contexts/` — Your learning data and plan quality logs
+
 ---
 
 ## 🏗️ Architecture Overview

package/bin/ag-kit.js

@@ -16,6 +16,7 @@ const path = require('path');
 
 const VERSION = require('../package.json').version;
 const AGENT_FOLDER = '.agent';
+const { safeCopyDirSync, readJsonSafe } = require('../lib/io');
 
 // ANSI colors
 const colors = {
@@ -49,7 +50,7 @@ ${colors.reset}
 ${colors.green}🚀 Antigravity AI Kit v${VERSION}${colors.reset}
 ${colors.yellow}   Transform Your IDE into an Autonomous Engineering Team${colors.reset}
 
-   • 19 AI Agents    • 31 Skills
+   • 19 AI Agents    • 32 Skills
    • 31 Commands     • 14 Workflows
    • Runtime Engine  • Error Budget
 `);
@@ -95,23 +96,28 @@ ${colors.bright}IDE Reference:${colors.reset}
 `);
 }
 
-function copyFolderSync(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true });
-  }
-  
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    
-    if (entry.isDirectory()) {
-      copyFolderSync(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
+/**
+ * Creates a timestamped backup of a directory.
+ * @param {string} dirPath - Directory to back up
+ * @returns {string} Path to the backup directory
+ */
+function backupDirectory(dirPath) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${dirPath}.backup-${timestamp}`;
+  safeCopyDirSync(dirPath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Checks if there is an active session with in-progress work.
+ * @param {string} agentPath - Path to existing .agent directory
+ * @returns {boolean} True if session-state indicates active work
+ */
+function hasActiveSession(agentPath) {
+  const statePath = path.join(agentPath, 'session-state.json');
+  const state = readJsonSafe(statePath, null);
+  if (!state) return false;
+  return state.currentTask || state.inProgress || state.activeWorkflow;
 }
 
 function countItems(dir, type = 'dir') {
@@ -146,24 +152,76 @@ function initCommand(options) {
   // Check if already exists
   if (fs.existsSync(agentPath) && !options.force) {
     log(`\n⚠️  ${AGENT_FOLDER} folder already exists!`, 'yellow');
-    log('   Use --force to overwrite\n', 'yellow');
+    log('   Use --force to overwrite', 'yellow');
+    log('   Use ag-kit update for non-destructive updates\n', 'yellow');
     process.exit(1);
   }
   
+  // M-3: Active session warning for --force
+  if (options.force && fs.existsSync(agentPath) && hasActiveSession(agentPath)) {
+    log('\n⚠️  Active session detected! Force-overwrite will destroy in-progress work.', 'yellow');
+    log('   Consider using ag-kit update instead.\n', 'yellow');
+  }
+
   if (options.dryRun) {
     log('\n🔍 Dry run mode - no changes will be made\n', 'cyan');
     log(`   Would copy: ${sourcePath}`, 'cyan');
     log(`   To: ${agentPath}\n`, 'cyan');
+    // M-2: Show force damage preview
+    if (options.force && fs.existsSync(agentPath)) {
+      log('   ⚠️  --force would overwrite these user files:', 'yellow');
+      const userFiles = ['session-context.md', 'session-state.json'];
+      const userDirs = ['decisions', 'contexts'];
+      for (const f of userFiles) {
+        if (fs.existsSync(path.join(agentPath, f))) {
+          log(`      • ${f}`, 'yellow');
+        }
+      }
+      for (const d of userDirs) {
+        if (fs.existsSync(path.join(agentPath, d))) {
+          log(`      • ${d}/ (directory)`, 'yellow');
+        }
+      }
+      log('', 'reset');
+    }
     return;
   }
   
-  // Copy .agent folder
-  logStep('1/3', 'Copying .agent folder...');
+  // C-2: Auto-backup before force-overwrite
+  if (options.force && fs.existsSync(agentPath)) {
+    logStep('1/4', 'Backing up existing .agent folder...');
+    try {
+      const backupPath = backupDirectory(agentPath);
+      log(`   ✓ Backup created: ${path.basename(backupPath)}`, 'green');
+    } catch (err) {
+      log(`   ⚠️  Backup failed: ${err.message}`, 'yellow');
+      log('   Proceeding without backup...', 'yellow');
+    }
+  }
+
+  // C-3: Atomic copy via temp directory
+  const stepPrefix = options.force && fs.existsSync(agentPath) ? '2/4' : '1/3';
+  logStep(stepPrefix, 'Copying .agent folder...');
   
+  const tempPath = `${agentPath}.tmp-${Date.now()}`;
   try {
-    copyFolderSync(sourcePath, agentPath);
+    safeCopyDirSync(sourcePath, tempPath);
+    // Remove old directory if force-overwriting
+    if (fs.existsSync(agentPath)) {
+      fs.rmSync(agentPath, { recursive: true, force: true });
+    }
+    // Atomic rename: move temp to final
+    fs.renameSync(tempPath, agentPath);
     log('   ✓ Copied successfully', 'green');
   } catch (err) {
+    // Cleanup temp directory on failure
+    try {
+      if (fs.existsSync(tempPath)) {
+        fs.rmSync(tempPath, { recursive: true, force: true });
+      }
+    } catch {
+      // Cleanup failure is non-critical
+    }
     log(`   ✗ Failed to copy: ${err.message}`, 'red');
     process.exit(1);
   }
@@ -366,6 +424,13 @@ function updateCommand(updateOptions) {
     const updater = require('../lib/updater');
     const isDryRun = updateOptions.dryRun;
 
+    // M-1: Show version transition
+    const currentManifest = readJsonSafe(path.join(agentPath, 'manifest.json'), {});
+    const currentVersion = currentManifest.kitVersion || 'unknown';
+    if (currentVersion !== VERSION) {
+      log(`\n   📦 Upgrading from v${currentVersion} → v${VERSION}`, 'cyan');
+    }
+
     if (isDryRun) {
       log('\n🔍 Dry run mode — no changes will be made\n', 'cyan');
     }

package/lib/io.js

@@ -68,7 +68,44 @@ function readJsonSafe(filePath, defaultValue = null) {
   }
 }
 
+/**
+ * Recursively copies a directory, skipping symbolic links for security.
+ *
+ * Symlinks are skipped because they could point outside the intended
+ * scope (e.g., outside .agent/), enabling path traversal attacks.
+ *
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @returns {void}
+ */
+function safeCopyDirSync(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    // Security: skip symlinks to prevent path traversal
+    const stat = fs.lstatSync(srcPath);
+    if (stat.isSymbolicLink()) {
+      log.debug('Skipping symlink for security', { path: srcPath });
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      safeCopyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
 module.exports = {
   writeJsonAtomic,
   readJsonSafe,
+  safeCopyDirSync,
 };

package/lib/plugin-system.js

@@ -16,7 +16,7 @@ const fs = require('fs');
 const path = require('path');
 
 const { AGENT_DIR, ENGINE_DIR, PLUGINS_DIR, HOOKS_DIR } = require('./constants');
-const { writeJsonAtomic } = require('./io');
+const { writeJsonAtomic, safeCopyDirSync } = require('./io');
 const { createLogger } = require('./logger');
 const log = createLogger('plugin-system');
 const PLUGINS_REGISTRY = 'plugins-registry.json';
@@ -289,7 +289,7 @@ function installPlugin(pluginPath, projectRoot) {
   for (const skillDir of (manifest.skills || [])) {
     const src = path.join(pluginPath, 'skills', skillDir);
     const dest = path.join(projectRoot, AGENT_DIR, 'skills', skillDir);
-    copyDirSync(src, dest);
+    safeCopyDirSync(src, dest);
     installed.skills++;
   }
 
@@ -593,31 +593,7 @@ function copyFileSync(src, dest) {
   fs.copyFileSync(src, dest);
 }
 
-/**
- * Recursively copies a directory.
- *
- * @param {string} src - Source directory
- * @param {string} dest - Destination directory
- * @returns {void}
- */
-function copyDirSync(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true });
-  }
-
-  const entries = fs.readdirSync(src, { withFileTypes: true });
 
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
-}
 
 module.exports = {
   validatePlugin,

package/lib/security-scanner.js

@@ -262,6 +262,12 @@ function collectAllFiles(dirPath) {
   for (const entry of entries) {
     const fullPath = path.join(dirPath, entry.name);
 
+    // Security: skip symlinks to prevent path traversal
+    const stat = fs.lstatSync(fullPath);
+    if (stat.isSymbolicLink()) {
+      continue;
+    }
+
     if (entry.isDirectory() && entry.name !== 'node_modules' && entry.name !== '.git') {
       files.push(...collectAllFiles(fullPath));
     } else if (entry.isFile()) {

package/lib/updater.js

@@ -27,6 +27,7 @@ const PRESERVED_FILES = new Set([
 /** Directories whose contents should never be overwritten */
 const PRESERVED_DIRS = new Set([
   'decisions',
+  'contexts',
 ]);
 
 /**

package/lib/verify.js

@@ -189,6 +189,32 @@ function runAllChecks(projectRoot) {
     results.push(checkJsonFile(path.join(agentDir, ENGINE_DIR, engineFile), `engine:${engineFile}`));
   }
 
+  // --- Check 10a: Rule files exist ---
+  const manifestRules = manifest.capabilities?.rules?.items || [];
+  for (const rule of manifestRules) {
+    const rulePath = path.join(agentDir, rule.file);
+    const exists = fs.existsSync(rulePath);
+    results.push({
+      name: `rule-file:${rule.name}`,
+      status: exists ? 'pass' : 'fail',
+      message: exists ? `Rule exists: ${rule.name}` : `Missing rule file: ${rule.file}`,
+    });
+  }
+
+  // --- Check 10b: Rule count matches ---
+  const ruleCountManifest = manifest.capabilities?.rules?.count || 0;
+  const ruleCountFS = fs.existsSync(path.join(agentDir, 'rules'))
+    ? fs.readdirSync(path.join(agentDir, 'rules')).filter((f) => f.endsWith('.md') && f !== 'README.md').length
+    : 0;
+  results.push({
+    name: 'rule-count',
+    status: ruleCountManifest === ruleCountFS ? 'pass' : 'fail',
+    message:
+      ruleCountManifest === ruleCountFS
+        ? `Rule count matches: ${ruleCountFS}`
+        : `Rule count mismatch: manifest=${ruleCountManifest}, filesystem=${ruleCountFS}`,
+  });
+
   // --- Check 11: Hooks file valid ---
   results.push(checkJsonFile(path.join(agentDir, HOOKS_DIR, 'hooks.json'), 'hooks-json'));
 
@@ -212,6 +238,19 @@ function runAllChecks(projectRoot) {
           });
         }
       }
+      // --- Check 13: Cross-reference — alwaysLoadRules files exist ---
+      const mandatoryRules = loadingRules.planningMandates?.alwaysLoadRules || [];
+      for (const ruleName of mandatoryRules) {
+        const rulePath = path.join(agentDir, 'rules', `${ruleName}.md`);
+        const ruleExists = fs.existsSync(rulePath);
+        results.push({
+          name: `xref:mandatory-rule:${ruleName}`,
+          status: ruleExists ? 'pass' : 'fail',
+          message: ruleExists
+            ? `Mandatory rule "${ruleName}" exists`
+            : `Mandatory rule "${ruleName}" referenced in alwaysLoadRules but file missing: rules/${ruleName}.md`,
+        });
+      }
     } catch {
       results.push({ name: 'xref:loading-rules', status: 'warn', message: 'Could not parse loading-rules.json for cross-reference check' });
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "antigravity-ai-kit",
-  "version": "3.2.0",
-  "description": "🚀 Trust-Grade AI development framework with a 29-module runtime engine — 19 Agents, 32 Skills, 31 Commands, 14 Workflows, 327 Tests. Workflow enforcement, task governance, agent reputation, self-healing, and skill marketplace.",
+  "version": "3.4.0",
+  "description": "🚀 Trust-Grade AI development framework with a 29-module runtime engine — 19 Agents, 32 Skills, 31 Commands, 14 Workflows, 8 Rules, 330 Tests. Workflow enforcement, task governance, agent reputation, self-healing, and skill marketplace.",
   "main": "bin/ag-kit.js",
   "bin": {
     "ag-kit": "./bin/ag-kit.js"