Initial commit

2025-11-29 18:08:19 +08:00
commit d03c46038c
21 changed files with 4951 additions and 0 deletions
--- a/commands/ace-install-cli.md
+++ b/commands/ace-install-cli.md
@@ -0,0 +1,275 @@
+---
+description: Install and verify ce-ace CLI tool (smart, non-noisy installation wizard)
+argument-hint:
+---
+
+# ACE CLI Installation Wizard
+
+This command provides a smart, interactive installation wizard for the `ce-ace` CLI tool.
+
+## Behavior
+
+- **Silent if already installed correctly** (no noise!)
+- **Interactive wizard** only when action needed
+- **Multi-package-manager support** (npm, pnpm, yarn)
+- **Verification** of installation + server connectivity
+- **Troubleshooting** guidance on failures
+
+## Instructions for Execution
+
+When the user invokes this command, follow these steps in order:
+
+### Phase 1: Detection (Always Run, But Silent If OK)
+
+Use the Bash tool to check current installation status. **IMPORTANT**: Break this into simple, single-purpose commands to avoid eval parse errors.
+
+**Step 1.1**: Check if ce-ace command exists:
+```bash
+command -v ce-ace && echo "FOUND" || echo "NOT_INSTALLED"
+```
+
+**Step 1.2**: If FOUND, get version:
+```bash
+ce-ace --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1
+```
+
+**Handle results**:
+
+- **If Step 1.1 output contains `FOUND`** and Step 1.2 returns a version:
+  - Check if version >= 1.0.0
+  - If yes: Show `✅ ce-ace v{VERSION} installed and working` and EXIT (silent success!)
+  - If no: Show `⚠️ ce-ace v{VERSION} installed (outdated)` and ask `Would you like to upgrade? (Y/n)`
+    - If yes → proceed to Phase 2 (Installation)
+    - If no → EXIT
+
+- **If Step 1.1 output contains `NOT_INSTALLED`**:
+  - Show: `❌ ce-ace CLI not found`
+  - Proceed to Phase 2 (Installation)
+
+### Phase 2: Package Manager Detection
+
+Use the Bash tool to detect available package managers. **IMPORTANT**: Use simple, separate commands to avoid parse errors.
+
+**Step 2.1**: Check for npm:
+```bash
+command -v npm >/dev/null 2>&1 && npm --version 2>/dev/null || echo "NOT_FOUND"
+```
+
+**Step 2.2**: Check for pnpm:
+```bash
+command -v pnpm >/dev/null 2>&1 && pnpm --version 2>/dev/null || echo "NOT_FOUND"
+```
+
+**Step 2.3**: Check for yarn:
+```bash
+command -v yarn >/dev/null 2>&1 && yarn --version 2>/dev/null || echo "NOT_FOUND"
+```
+
+**Build list of available managers** from the results above. For each manager that didn't return "NOT_FOUND", add it to a list with its version number.
+
+**Handle results**:
+
+- **If ALL managers returned `NOT_FOUND`**:
+  - Show error message:
+    ```
+    ❌ No package managers found (npm, pnpm, or yarn required)
+
+    Please install Node.js and npm first:
+    - macOS: brew install node
+    - Linux: https://nodejs.org/en/download/package-manager
+    - Windows: https://nodejs.org/en/download
+    ```
+  - EXIT with error
+
+- **If at least ONE manager was found**:
+  - Display numbered list with versions (e.g., "1. npm (v11.1.0)")
+  - Proceed to Phase 3 with the list of available managers
+
+### Phase 3: User Selection
+
+Present package manager options to the user and ask them to choose:
+
+**If only one manager available** (e.g., just `npm`):
+- Auto-select that manager
+- Show: `📦 Using npm for installation`
+
+**If multiple managers available**:
+- Show the numbered list from Phase 2
+- Ask: `Which package manager would you like to use? [1-{N}]:`
+- Wait for user input (number selection)
+- Validate input is a valid number
+
+**Store selected manager** in a variable for Phase 4.
+
+### Phase 4: Installation Command Construction
+
+Based on the selected package manager, construct the installation command:
+
+**npm**:
+```bash
+npm install -g @ace-sdk/cli
+```
+
+**pnpm**:
+```bash
+pnpm add -g @ace-sdk/cli
+```
+
+**yarn**:
+```bash
+yarn global add @ace-sdk/cli
+```
+
+**Show the command to the user**:
+```
+📥 Installation command:
+{COMMAND}
+
+Proceed with installation? (Y/n):
+```
+
+**Wait for user confirmation**:
+- If `n` or `N` → EXIT (user cancelled)
+- If `Y`, `y`, or Enter → proceed to Phase 5
+
+### Phase 5: Execute Installation
+
+Use the Bash tool to run the installation command:
+
+```bash
+# Run installation command (use the selected manager)
+{INSTALL_COMMAND}
+```
+
+**Handle results**:
+
+- **If exit code = 0** (success):
+  - Show: `✅ Installation completed successfully!`
+  - Proceed to Phase 6 (Verification)
+
+- **If exit code != 0** (failure):
+  - Show error message with common troubleshooting:
+    ```
+    ❌ Installation failed!
+
+    Common issues:
+
+    1. Permission errors:
+       - Try: sudo {INSTALL_COMMAND}
+       - Or use: npx @ace-sdk/cli (run without install)
+
+    2. Network errors:
+       - Check internet connection
+       - Try: npm config set registry https://registry.npmjs.org/
+
+    3. PATH issues:
+       - After install, close and reopen terminal
+       - Or add npm bin to PATH: export PATH="$(npm bin -g):$PATH"
+
+    Full error output:
+    {ERROR_OUTPUT}
+    ```
+  - EXIT with error
+
+### Phase 6: Verify Installation
+
+Use the Bash tool to verify the installation worked. **IMPORTANT**: Use simple, separate commands.
+
+**Step 6.1**: Check if command exists:
+```bash
+command -v ce-ace
+```
+
+**Step 6.2**: Get version (if Step 6.1 succeeded):
+```bash
+ce-ace --version
+```
+
+**Step 6.3**: Get OS info:
+```bash
+uname -s
+```
+
+**Process results**:
+- If Step 6.1 returns a path: ✅ ce-ace found
+- If Step 6.1 fails: ❌ Not found (PATH issue, may need to restart terminal)
+- Extract version number from Step 6.2 output
+- Check OS from Step 6.3: Linux/Darwin = supported, Windows = suggest WSL
+
+**Show verification results** to the user with a summary:
+```
+🔍 Installation Verification:
+{OUTPUT_FROM_VERIFICATION}
+
+🎉 All set! The ce-ace CLI tool is installed and ready to use.
+
+Next steps:
+1. Run /ace:ace-configure to set up your organization and project
+2. Run /ace:ace-status to check your playbook
+3. Start using ACE for automatic pattern learning!
+```
+
+### Phase 7: Optional Server Connectivity Test
+
+**Ask user** if they want to test server connectivity:
+```
+Would you like to test connection to the ACE server? (Y/n):
+```
+
+**If yes**, use simple Bash commands:
+
+**Step 7.1**: Check if global config exists:
+```bash
+test -f ~/.config/ace/config.json && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
+```
+
+**Step 7.2**: If config exists, get server URL:
+```bash
+jq -r '.serverUrl // "https://ace-api.code-engine.app"' ~/.config/ace/config.json
+```
+
+**Step 7.3**: Test connectivity (using URL from Step 7.2):
+```bash
+curl -s --connect-timeout 5 {SERVER_URL}/health
+```
+
+**Process results**:
+- If NO_CONFIG: Show "ℹ️  No ACE configuration found - Run /ace-configure"
+- If Step 7.3 succeeds: ✅ Server connectivity OK
+- If Step 7.3 fails: ⚠️ Could not reach server (normal if not configured)
+
+**Show connectivity results** and exit with success.
+
+---
+
+## Error Handling Guidelines
+
+**Always provide actionable guidance** when errors occur:
+
+1. **Permission errors**: Suggest `sudo` or `npx` alternative
+2. **Network errors**: Check internet, suggest registry config
+3. **PATH errors**: Explain how to add npm bin to PATH
+4. **Version conflicts**: Suggest uninstall old version first
+5. **OS compatibility**: Warn about Windows, recommend WSL
+
+**Use clear status indicators**:
+- ✅ Success (green)
+- ⚠️ Warning (yellow)
+- ❌ Error (red)
+- ℹ️ Info (blue)
+- 🔍 Checking/verifying
+- 📦 Package manager
+- 📥 Installing
+- 🎉 Complete
+
+---
+
+## Important Notes
+
+1. **Be non-noisy**: If already installed correctly, just show "✅ installed" and exit
+2. **Be interactive**: Ask for user confirmation before installing
+3. **Be helpful**: Provide clear troubleshooting for common issues
+4. **Be thorough**: Verify installation after completion
+5. **Be informative**: Show next steps after successful install
+
+Execute these phases in order, handling each result appropriately.