ai-agent-config 2.4.9 → 2.5.2

package/README.md

@@ -1,196 +1,77 @@
 # ai-agent-config
 
-> Universal Global Skills & Workflows for AI Coding Assistants - User-configurable skill sources
+> Universal skill & workflow manager for AI coding assistants with bi-directional GitHub sync
 
 [![npm version](https://badge.fury.io/js/ai-agent-config.svg)](https://www.npmjs.com/package/ai-agent-config)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**One command to manage AI coding skills across Claude Code, Antigravity, Cursor, Windsurf, and more.**
-
-## 🚀 What's New in v2.2
-
-- ✅ **Minimal core** - Only 2 essential skills bundled (config-manager, skill-updater)
-- ✅ **User-configurable sources** - Add any skill repositories from GitHub
-- ✅ **Source management** - Enable, disable, add, remove sources via CLI
-- ✅ **Config management** - Export/import configs for team sharing
-- ✅ **Zero defaults** - No external sources by default, full user control
-
-## 📦 Quick Start
+## Install
 
 ```bash
-# Install globally
 npm install -g ai-agent-config
-
-# Initialize (optional)
-ai-agent init --repo https://github.com/youruser/my-ai-skills.git
-
-# Pull and auto-install
-ai-agent pull
-```
-
-## 🎯 Bundled Skills (2)
-
-The package includes 2 core skills for managing the system:
-
-1.  **config-manager** - Manage configuration and custom sources
-2.  **skill-updater** - Update skills from GitHub repositories
-
-## 📚 Add More Skills
-
-To get more skills, add custom sources from GitHub:
-
-```bash
-# Add Vercel Labs skills
-ai-agent source add https://github.com/vercel-labs/agent-skills.git \
-  --name vercel-labs \
-  --path skills
-
-# Add Everything Claude Code
-ai-agent source add https://github.com/affaan-m/everything-claude-code.git \
-  --name everything-claude-code \
-  --path skills
-
-# Update and install
-ai-agent update
-ai-agent install
-```
-
-## 🛠️ CLI Commands
-
-### Source Management
-```bash
-ai-agent source add <repo-url> [options]    # Add custom source
-ai-agent source remove <name>               # Remove source
-ai-agent source list                        # List all sources
-ai-agent source enable <name>               # Enable source
-ai-agent source disable <name>              # Disable source
-ai-agent source info <name>                 # View source details
-```
-
-### Config Management
-```bash
-ai-agent config get <key>                   # Get config value
-ai-agent config set <key> <value>           # Set config value
-ai-agent config edit                        # Edit in $EDITOR
-ai-agent config validate                    # Validate config
-ai-agent config export [file]               # Export config
-ai-agent config import <file> [--merge]     # Import config
-ai-agent config reset --yes                 # Reset to defaults
 ```
 
-### Installation & Updates
-```bash
-ai-agent init                               # Initialize/migrate config
-ai-agent pull                               # Pull + auto-install from GitHub
-ai-agent list                               # List installed skills
-ai-agent platforms                          # Show detected platforms
-ai-agent uninstall                          # Remove skills
-```
+## Quick Start
 
-## 🎨 Use Cases
-
-### For Companies
 ```bash
-# Add your company's private skills repo
-ai-agent source add https://github.com/acme-corp/coding-standards \
-  --name acme-standards
-
-# Share config file with team
-ai-agent config export acme-config.json
+# Initialize with your GitHub repo
+ai-agent init --repo https://github.com/youruser/my-ai-skills.git
 
-# Team members import
-ai-agent config import acme-config.json --merge
-```
+# Pull skills and auto-install to platforms
+ai-agent pull
 
-### For Individual Developers
-```bash
-# Add skills from multiple sources
-ai-agent source add https://github.com/vercel-labs/agent-skills.git --name vercel
-ai-agent source add https://github.com/yourname/my-skills --name personal
+# Add external skill sources
+ai-agent source add https://github.com/vercel-labs/agent-skills.git \
+  --name vercel-labs --path skills
 
-# Update and install
+# Sync external skills (pull -> sync -> push)
 ai-agent update
-ai-agent install
-```
-
-## 📍 File Locations
-
-```
-~/.ai-agent/
-├── config.json                    # User configuration
-└── .ai-agent-external-cache/      # Downloaded skill repositories
-
-AI Platform Skills:
-~/.claude/skills/                  # Claude Code
-~/.gemini/antigravity/skills/      # Antigravity IDE
-~/.cursor/skills/                  # Cursor
-~/.windsurf/skills/                # Windsurf
 ```
 
-## 🔧 Configuration File
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init --repo <url>` | Initialize config and clone repo |
+| `push` / `pull` | Git push/pull with your skills repo |
+| `update` | Pull -> sync external skills -> push |
+| `install` | Copy skills to platform directories |
+| `list` | List installed skills |
+| `platforms` | Show detected platforms |
+| `source add/remove/list` | Manage skill sources |
+| `config get/set/edit` | Manage configuration |
+| `uninstall` | Remove installed skills |
+
+## Supported Platforms
+
+| Platform | Skills Path |
+|----------|-------------|
+| Claude Code | `~/.claude/skills/` |
+| Antigravity IDE | `~/.gemini/antigravity/skills/` |
+| Cursor | `~/.cursor/skills/` |
+| Windsurf | `~/.windsurf/skills/` |
+| Codex CLI | `~/.codex/skills/` |
+| GitHub Copilot | `~/.github/copilot-instructions.md` |
+
+## Configuration
 
 User config at `~/.ai-agent/config.json`:
 
 ```json
 {
-  "version": "2.0",
+  "version": "2.3",
+  "repository": {
+    "url": "https://github.com/youruser/my-ai-skills.git",
+    "branch": "main",
+    "local": "~/.ai-agent/sync-repo"
+  },
   "sources": {
     "official": [],
-    "custom": [
-      {
-        "name": "my-skills",
-        "repo": "https://github.com/me/my-skills.git",
-        "branch": "main",
-        "path": "skills",
-        "enabled": true
-      }
-    ]
-  },
-  "preferences": {
-    "autoUpdate": true,
-    "updateInterval": "weekly"
+    "custom": []
   }
 }
 ```
 
-## 🤝 Contributing
-
-We welcome contributions! Here's how:
-
-1. **Share your skills**: Create skills repo and share with community
-2. **Report issues**: [GitHub Issues](https://github.com/dongitran/ai-agent-config/issues)
-3. **Submit PRs**: Improve the core tool
-
-## 🌟 Why ai-agent-config?
-
-- ✅ **Minimal & focused** - Only 2 core skills bundled, add what you need
-- ✅ **Full control** - No default external sources, you decide what to install
-- ✅ **User-configurable** - Add unlimited custom skill sources
-- ✅ **Team-friendly** - Export/import configs for collaboration
-- ✅ **Zero dependencies** - Lightweight, fast, secure
-- ✅ **Open & extensible** - Use any GitHub repo as skill source
-
-## 📊 Supported Platforms
-
-| Platform | Status | Skills Directory |
-|----------|--------|------------------|
-| Claude Code | ✅ Supported | `~/.claude/skills/` |
-| Antigravity IDE | ✅ Supported | `~/.gemini/antigravity/skills/` |
-| Cursor | ✅ Supported | `~/.cursor/skills/` |
-| Windsurf | ✅ Supported | `~/.windsurf/skills/` |
-| Codex CLI | ✅ Supported | `~/.codex/skills/` |
-
-## 📄 License
-
-MIT © [Dong Tran](https://github.com/dongitran)
-
-## 🔗 Links
-
-- **NPM**: https://www.npmjs.com/package/ai-agent-config
-- **GitHub**: https://github.com/dongitran/ai-agent-config
-- **Issues**: https://github.com/dongitran/ai-agent-config/issues
-- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
-
----
+## License
 
-**Keywords**: AI coding assistant, Claude Code, Antigravity, Cursor, Windsurf, AI skills, code automation, developer tools, coding standards, best practices, AI agent config, skill management, team collaboration, custom skills, GitHub integration
+MIT

package/bin/cli.js

@@ -8,6 +8,7 @@ const installer = require("../scripts/installer");
 const platforms = require("../scripts/platforms");
 const migration = require("../scripts/migration");
 const externalSync = require("../scripts/external-sync");
+const secretManager = require("../scripts/secret-manager");
 
 const VERSION = require("../package.json").version;
 
@@ -39,6 +40,9 @@ const COMMANDS = {
   "config import": "Import config",
   "config reset": "Reset to defaults",
 
+  // Secret Management
+  "secrets sync": "Sync MCP secrets from Bitwarden",
+
   // Original Commands (updated)
   install: "Install skills to detected platforms",
   update: "Update skills from all sources",
@@ -93,6 +97,9 @@ Usage: ai-agent <command> [options]
   push [--message <msg>]      Push skills to GitHub
   pull                        Pull skills from GitHub
 
+🔐 Secret Management:
+  secrets sync                Sync MCP secrets from Bitwarden
+
 🔍 External Skills:
   sync-external [opts]        Sync skills from external sources
   list-external               List available external skills
@@ -707,6 +714,20 @@ function update(args) {
   }
 
   try {
+    const SyncManager = require("../scripts/sync-manager");
+    const config = configManager.loadConfig();
+    const syncManager = new SyncManager(config);
+
+    // 1. Pull latest from repository first
+    console.log("📥 Pulling latest from repository...\n");
+    const pullResult = syncManager.pull();
+    if (pullResult.pulled) {
+      console.log("   ✓ Repository up to date\n");
+    } else {
+      console.log(`   ⊗ Pull: ${pullResult.reason || "failed"}\n`);
+    }
+
+    // 2. Sync external skills
     const result = externalSync.syncAll(options);
 
     console.log(`\n✓ Updated from ${result.synced} source(s)`);
@@ -716,17 +737,19 @@ function update(args) {
       console.log(`  Failed: ${result.failed} source(s)`);
     }
 
-    // Auto-push after successful sync
+    // 3. Push changes to repository
     if (result.copied > 0) {
-      console.log("\n📤 Auto-pushing synced skills to repository...\n");
-      const SyncManager = require("../scripts/sync-manager");
-      const config = configManager.loadConfig();
-      const syncManager = new SyncManager(config);
-      
+      console.log("\n📤 Pushing synced skills to repository...\n");
+
       const skillNames = options.skill || "external skills";
       const message = `chore: sync ${skillNames} from external sources`;
-      
-      syncManager.push({ message });
+
+      const pushResult = syncManager.push({ message });
+      if (pushResult.pushed) {
+        console.log("   ✓ Pushed to repository");
+      } else {
+        console.log(`   ⊗ ${pushResult.reason}`);
+      }
     }
 
     console.log("");
@@ -899,117 +922,142 @@ function listExternal() {
   }
 }
 
-// Main
-const args = process.argv.slice(2);
-const command = args[0];
-const subcommand = args[1];
-
-// Handle multi-word commands
-if (command === "source") {
-  switch (subcommand) {
-    case "add":
-      sourceAdd(args.slice(2));
-      break;
-    case "remove":
-      sourceRemove(args.slice(2));
-      break;
-    case "list":
-      sourceList(args.slice(2));
-      break;
-    case "enable":
-      sourceToggle(args.slice(2), true);
-      break;
-    case "disable":
-      sourceToggle(args.slice(2), false);
-      break;
-    case "info":
-      sourceInfo(args.slice(2));
-      break;
-    default:
-      console.error(`Unknown source command: ${subcommand}`);
-      console.log('Run "ai-agent help" for usage information.');
-      process.exit(1);
-  }
-} else if (command === "config") {
-  switch (subcommand) {
-    case "get":
-      configGet(args.slice(2));
-      break;
-    case "set":
-      configSet(args.slice(2));
-      break;
-    case "edit":
-      configEdit(args.slice(2));
-      break;
-    case "validate":
-      configValidate(args.slice(2));
-      break;
-    case "export":
-      configExport(args.slice(2));
-      break;
-    case "import":
-      configImport(args.slice(2));
-      break;
-    case "reset":
-      configReset(args.slice(2));
-      break;
-    default:
-      console.error(`Unknown config command: ${subcommand}`);
-      console.log('Run "ai-agent help" for usage information.');
-      process.exit(1);
-  }
-} else {
-  // Single-word commands
-  switch (command) {
-    case "init":
-      init(args.slice(1));
-      break;
-    case "migrate":
-      migrateCmd(args.slice(1));
-      break;
-    case "push":
-      push(args.slice(1));
-      break;
-    case "pull":
-      pull(args.slice(1));
-      break;
-    case "install":
-      install(args.slice(1));
-      break;
-    case "update":
-      update(args.slice(1));
-      break;
-
-    case "sync-external":
-      // Backward compatibility - alias for update
-      update(args.slice(1));
-      break;
-    case "list":
-      listSkills();
-      break;
-    case "list-external":
-      listExternal(args.slice(1));
-      break;
-    case "platforms":
-      showPlatforms();
-      break;
-    case "uninstall":
-      uninstall(args.slice(1));
-      break;
-    case "version":
-    case "--version":
-    case "-v":
-      console.log(`v${VERSION}`);
-      break;
-    case "help":
-    case "--help":
-    case "-h":
-    case undefined:
-      showHelp();
-      break;
-    default:
-      console.error(`Unknown command: ${command}`);
-      console.log('Run "ai-agent help" for usage information.');
-      process.exit(1);
+/**
+ * Sync secrets from Bitwarden
+ */
+async function secretsSync() {
+  try {
+    await secretManager.syncSecrets();
+  } catch (error) {
+    console.error(`\n❌ Secrets sync failed: ${error.message}`);
+    process.exit(1);
   }
 }
+
+// Main
+(async () => {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const subcommand = args[1];
+
+  // Handle multi-word commands
+  if (command === "source") {
+    switch (subcommand) {
+      case "add":
+        sourceAdd(args.slice(2));
+        break;
+      case "remove":
+        sourceRemove(args.slice(2));
+        break;
+      case "list":
+        sourceList(args.slice(2));
+        break;
+      case "enable":
+        sourceToggle(args.slice(2), true);
+        break;
+      case "disable":
+        sourceToggle(args.slice(2), false);
+        break;
+      case "info":
+        sourceInfo(args.slice(2));
+        break;
+      default:
+        console.error(`Unknown source command: ${subcommand}`);
+        console.log('Run "ai-agent help" for usage information.');
+        process.exit(1);
+    }
+  } else if (command === "config") {
+    switch (subcommand) {
+      case "get":
+        configGet(args.slice(2));
+        break;
+      case "set":
+        configSet(args.slice(2));
+        break;
+      case "edit":
+        configEdit(args.slice(2));
+        break;
+      case "validate":
+        configValidate(args.slice(2));
+        break;
+      case "export":
+        configExport(args.slice(2));
+        break;
+      case "import":
+        configImport(args.slice(2));
+        break;
+      case "reset":
+        configReset(args.slice(2));
+        break;
+      default:
+        console.error(`Unknown config command: ${subcommand}`);
+        console.log('Run "ai-agent help" for usage information.');
+        process.exit(1);
+    }
+  } else if (command === "secrets") {
+    switch (subcommand) {
+      case "sync":
+        await secretsSync();
+        break;
+      default:
+        console.error(`Unknown secrets command: ${subcommand}`);
+        console.log('Run "ai-agent help" for usage information.');
+        process.exit(1);
+    }
+  } else {
+    // Single-word commands
+    switch (command) {
+      case "init":
+        init(args.slice(1));
+        break;
+      case "migrate":
+        migrateCmd(args.slice(1));
+        break;
+      case "push":
+        push(args.slice(1));
+        break;
+      case "pull":
+        pull(args.slice(1));
+        break;
+      case "install":
+        install(args.slice(1));
+        break;
+      case "update":
+        update(args.slice(1));
+        break;
+
+      case "sync-external":
+        // Backward compatibility - alias for update
+        update(args.slice(1));
+        break;
+      case "list":
+        listSkills();
+        break;
+      case "list-external":
+        listExternal(args.slice(1));
+        break;
+      case "platforms":
+        showPlatforms();
+        break;
+      case "uninstall":
+        uninstall(args.slice(1));
+        break;
+      case "version":
+      case "--version":
+      case "-v":
+        console.log(`v${VERSION}`);
+        break;
+      case "help":
+      case "--help":
+      case "-h":
+      case undefined:
+        showHelp();
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.log('Run "ai-agent help" for usage information.');
+        process.exit(1);
+    }
+  }
+})();
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agent-config",
-  "version": "2.4.9",
+  "version": "2.5.2",
   "description": "Universal skill & workflow manager for AI coding assistants with bi-directional GitHub sync",
   "main": "index.js",
   "bin": {
@@ -38,6 +38,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "inquirer": "^9.2.12"
+  },
   "files": [
     "bin/",
     "scripts/",

package/scripts/postinstall.js

@@ -37,6 +37,54 @@ function main() {
   console.log("   4. Update & install additional skills:");
   console.log("      $ ai-agent update && ai-agent install\n");
   console.log("📦 Repository: https://github.com/dongitran/ai-agent-config\n");
+
+  // Auto-install Bitwarden MCP server to Antigravity
+  const fs = require("fs");
+  const path = require("path");
+  const os = require("os");
+
+  const antigravityMcpPath = path.join(
+    os.homedir(),
+    ".gemini",
+    "antigravity",
+    "mcp_config.json"
+  );
+
+  if (fs.existsSync(path.dirname(antigravityMcpPath))) {
+    try {
+      let mcpConfig = { mcpServers: {} };
+
+      // Read existing config if it exists
+      if (fs.existsSync(antigravityMcpPath)) {
+        const content = fs.readFileSync(antigravityMcpPath, "utf-8");
+        if (content.trim()) {
+          mcpConfig = JSON.parse(content);
+        }
+      }
+
+      // Add Bitwarden MCP server (enabled by default)
+      if (!mcpConfig.mcpServers.bitwarden) {
+        mcpConfig.mcpServers.bitwarden = {
+          command: "npx",
+          args: ["-y", "@bitwarden/mcp-server"],
+          env: {
+            BW_CLIENTID: "${BW_CLIENTID}",
+            BW_CLIENTSECRET: "${BW_CLIENTSECRET}",
+          },
+        };
+
+        fs.writeFileSync(
+          antigravityMcpPath,
+          JSON.stringify(mcpConfig, null, 2),
+          "utf-8"
+        );
+        console.log("🔐 Bitwarden MCP server added to Antigravity (✓ enabled)");
+        console.log("   Config: ~/.gemini/antigravity/mcp_config.json\n");
+      }
+    } catch (error) {
+      // Silent fail - not critical
+    }
+  }
 }
 
 main();

package/scripts/secret-manager.js

@@ -0,0 +1,352 @@
+/**
+ * Secret Manager Module
+ * Manages MCP secrets using Bitwarden integration
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync, spawnSync } = require("child_process");
+const inquirer = require("inquirer");
+const os = require("os");
+
+const HOME = os.homedir();
+const BITWARDEN_FOLDER = "MCP Secrets";
+
+/**
+ * Validate that Bitwarden CLI is installed
+ */
+function validateBitwardenCLI() {
+    try {
+        execSync("which bw", { stdio: "pipe" });
+        return { valid: true };
+    } catch (error) {
+        return {
+            valid: false,
+            message: "Bitwarden CLI not found. Install with: npm install -g @bitwarden/cli",
+        };
+    }
+}
+
+/**
+ * Validate that Bitwarden API credentials are set
+ */
+function validateBitwardenAuth() {
+    const clientId = process.env.BW_CLIENTID;
+    const clientSecret = process.env.BW_CLIENTSECRET;
+
+    if (!clientId || !clientSecret) {
+        return {
+            valid: false,
+            message:
+                "Bitwarden API credentials not set. Add to ~/.zshrc:\n" +
+                "  export BW_CLIENTID=\"user.xxx\"\n" +
+                "  export BW_CLIENTSECRET=\"yyy\"",
+        };
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Prompt user for Bitwarden master password
+ */
+async function promptPassword() {
+    const answers = await inquirer.prompt([
+        {
+            type: "password",
+            name: "masterPassword",
+            message: "Enter Bitwarden master password:",
+            mask: "*",
+        },
+    ]);
+
+    return answers.masterPassword;
+}
+
+/**
+ * Unlock Bitwarden vault with password
+ * Returns session key or null if failed
+ * Uses spawnSync to avoid shell injection
+ */
+function unlockBitwarden(password) {
+    try {
+        // Use spawnSync with stdin to avoid shell injection
+        const result = spawnSync("bw", ["unlock", "--passwordstdin", "--raw"], {
+            input: password + "\n",
+            encoding: "utf-8",
+        });
+
+        if (result.status === 0 && result.stdout) {
+            return { success: true, sessionKey: result.stdout.trim() };
+        } else {
+            const errorMsg = result.stderr || result.stdout || "Unknown error";
+            return {
+                success: false,
+                message: `Failed to unlock vault: ${errorMsg.trim()}`,
+            };
+        }
+    } catch (error) {
+        return {
+            success: false,
+            message: `Failed to unlock vault: ${error.message}`,
+        };
+    }
+}
+
+/**
+ * Discover required secrets from MCP configs
+ * Scans ~/.gemini/antigravity/mcp_config.json for ${VAR} patterns
+ */
+function discoverRequiredSecrets() {
+    const platforms = require("./platforms");
+    const antigravity = platforms.getByName("antigravity");
+
+    if (!antigravity) {
+        return { found: false, secrets: [], reason: "Antigravity platform not detected" };
+    }
+
+    const mcpConfigPath = path.join(antigravity.configPath, "mcp_config.json");
+
+    if (!fs.existsSync(mcpConfigPath)) {
+        return { found: false, secrets: [], reason: "MCP config not found" };
+    }
+
+    try {
+        const content = fs.readFileSync(mcpConfigPath, "utf-8");
+
+        // Extract all ${VAR_NAME} patterns (supports mixed/lowercase)
+        const regex = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+        const matches = [...content.matchAll(regex)];
+        const secretNames = [...new Set(matches.map((m) => m[1]))];
+
+        return { found: true, secrets: secretNames };
+    } catch (error) {
+        return { found: false, secrets: [], reason: error.message };
+    }
+}
+
+/**
+ * Fetch secrets from Bitwarden vault
+ * Only searches in "MCP Secrets" folder
+ */
+function fetchSecretsFromBitwarden(sessionKey, secretNames) {
+    const results = {
+        found: [],
+        missing: [],
+    };
+
+    try {
+        // Step 1: Get folder ID for "MCP Secrets"
+        const foldersJson = execSync(`bw list folders --session ${sessionKey}`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const folders = JSON.parse(foldersJson);
+        const mcpFolder = folders.find((f) => f.name === BITWARDEN_FOLDER);
+
+        if (!mcpFolder) {
+            console.warn(`\n⚠️  Folder "${BITWARDEN_FOLDER}" not found in Bitwarden vault`);
+            console.warn(`   Create folder "${BITWARDEN_FOLDER}" and add your secrets there\n`);
+            // All secrets are missing since folder doesn't exist
+            secretNames.forEach((name) => results.missing.push(name));
+            return results;
+        }
+
+        // Step 2: List all items in "MCP Secrets" folder
+        const itemsJson = execSync(`bw list items --folderid ${mcpFolder.id} --session ${sessionKey}`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const items = JSON.parse(itemsJson);
+
+        // Step 3: Match secrets by name
+        for (const secretName of secretNames) {
+            const item = items.find((i) => i.name === secretName);
+
+            if (item && item.login && item.login.password) {
+                results.found.push({
+                    name: secretName,
+                    value: item.login.password,
+                });
+            } else {
+                results.missing.push(secretName);
+            }
+        }
+    } catch (error) {
+        console.error(`\n❌ Error fetching from Bitwarden: ${error.message}\n`);
+        // On error, mark all as missing
+        secretNames.forEach((name) => results.missing.push(name));
+    }
+
+    return results;
+}
+
+/**
+ * Detect shell profile file
+ */
+function detectShellProfile() {
+    const shell = process.env.SHELL || "";
+
+    if (shell.includes("zsh")) {
+        return path.join(HOME, ".zshrc");
+    } else if (shell.includes("bash")) {
+        return path.join(HOME, ".bashrc");
+    }
+
+    // Default to zsh on macOS
+    return path.join(HOME, ".zshrc");
+}
+
+/**
+ * Write secrets to shell profile
+ */
+function writeToShellProfile(secrets) {
+    const profilePath = detectShellProfile();
+    const timestamp = new Date().toISOString();
+
+    const startMarker = "# === AI Agent MCP Secrets (auto-generated, do not edit manually) ===";
+    const endMarker = `# === End AI Agent MCP Secrets (last updated: ${timestamp}) ===`;
+
+    let profileContent = "";
+    if (fs.existsSync(profilePath)) {
+        profileContent = fs.readFileSync(profilePath, "utf-8");
+    }
+
+    // Build secrets block
+    const secretsBlock = secrets.map((s) => `export ${s.name}="${s.value}"`).join("\n");
+    const fullBlock = `${startMarker}\n${secretsBlock}\n${endMarker}`;
+
+    // Check if markers already exist
+    const startIndex = profileContent.indexOf(startMarker);
+    const endIndex = profileContent.indexOf("# === End AI Agent MCP Secrets");
+
+    if (startIndex !== -1 && endIndex !== -1) {
+        // Replace existing block
+        const beforeBlock = profileContent.substring(0, startIndex);
+        const afterBlock = profileContent.substring(
+            profileContent.indexOf("\n", endIndex) + 1
+        );
+        profileContent = beforeBlock + fullBlock + "\n" + afterBlock;
+    } else {
+        // Append new block
+        profileContent += "\n" + fullBlock + "\n";
+    }
+
+    fs.writeFileSync(profilePath, profileContent, "utf-8");
+
+    return { path: profilePath, count: secrets.length };
+}
+
+/**
+ * Main sync function
+ */
+async function syncSecrets() {
+    let sessionKey = null;
+
+    try {
+        console.log("\n🔐 Bitwarden Secret Sync\n");
+
+        // 1. Validate Bitwarden CLI
+        const cliCheck = validateBitwardenCLI();
+        if (!cliCheck.valid) {
+            console.error(`❌ ${cliCheck.message}\n`);
+            process.exit(1);
+        }
+
+        // 2. Validate API credentials
+        const authCheck = validateBitwardenAuth();
+        if (!authCheck.valid) {
+            console.error(`❌ ${authCheck.message}\n`);
+            process.exit(1);
+        }
+
+        // 3. Prompt for password
+        const password = await promptPassword();
+
+        // 4. Unlock vault
+        console.log("\n🔓 Unlocking vault...");
+        const unlockResult = unlockBitwarden(password);
+
+        if (!unlockResult.success) {
+            console.error(`❌ ${unlockResult.message}\n`);
+            process.exit(1);
+        }
+
+        console.log("✓ Vault unlocked\n");
+        sessionKey = unlockResult.sessionKey;
+
+        // 5. Discover required secrets
+        console.log("🔍 Scanning MCP configs for required secrets...");
+        const discovery = discoverRequiredSecrets();
+
+        if (!discovery.found) {
+            console.log(`⚠️  ${discovery.reason}`);
+            console.log("\n💡 No secrets to sync. MCP configs will be available after implementing Plan 01.\n");
+            return;
+        }
+
+        if (discovery.secrets.length === 0) {
+            console.log("No environment variables found in MCP configs.\n");
+            return;
+        }
+
+        console.log(`Found ${discovery.secrets.length} secret(s):`);
+        discovery.secrets.forEach((name) => {
+            console.log(`  • ${name}`);
+        });
+
+        // 6. Fetch secrets from Bitwarden
+        console.log(`\n🔐 Fetching from Bitwarden (folder: ${BITWARDEN_FOLDER})...`);
+        const fetchResults = fetchSecretsFromBitwarden(sessionKey, discovery.secrets);
+
+        fetchResults.found.forEach((secret) => {
+            console.log(`✓ ${secret.name} (found)`);
+        });
+
+        fetchResults.missing.forEach((name) => {
+            console.log(`⚠ ${name} (not found in vault)`);
+        });
+
+        // 7. Write to shell profile
+        if (fetchResults.found.length > 0) {
+            console.log("\n💾 Writing secrets to shell profile...");
+            const writeResult = writeToShellProfile(fetchResults.found);
+            console.log(`✓ Added ${writeResult.count} environment variable(s) to ${writeResult.path}`);
+        }
+
+        // 8. Summary
+        console.log("\n✅ Secrets synced successfully!\n");
+
+        console.log("ℹ️  Next steps:");
+        console.log("   1. Restart terminal or run: source ~/.zshrc");
+
+        if (fetchResults.missing.length > 0) {
+            console.log(`   2. Missing secrets: ${fetchResults.missing.join(", ")}`);
+            console.log("      Add them to Bitwarden or set manually");
+        }
+
+        console.log("");
+    } finally {
+        // Cleanup: Lock vault to invalidate session key
+        if (sessionKey) {
+            try {
+                execSync("bw lock", { stdio: "pipe" });
+            } catch (e) {
+                // Silent fail - vault may already be locked
+            }
+            sessionKey = null;
+        }
+    }
+}
+
+module.exports = {
+    syncSecrets,
+    validateBitwardenCLI,
+    validateBitwardenAuth,
+    promptPassword,
+    unlockBitwarden,
+    discoverRequiredSecrets,
+    fetchSecretsFromBitwarden,
+    detectShellProfile,
+    writeToShellProfile,
+};