594 lines
15 KiB
Markdown
594 lines
15 KiB
Markdown
---
|
||
description: Configure ACE server connection settings interactively
|
||
argument-hint: [--global] [--project]
|
||
---
|
||
|
||
# Configure ACE Connection
|
||
|
||
Interactive configuration wizard using ce-ace CLI v1.0.2+ features with Claude Code native UI.
|
||
|
||
## What This Does
|
||
|
||
**Two-step configuration:**
|
||
1. **Global Config**: Uses `ce-ace config validate` + `ce-ace config` with flags
|
||
2. **Project Config**: Creates `.claude/settings.json` with orgId and projectId
|
||
|
||
## Instructions for Claude
|
||
|
||
When the user runs `/ace:configure`, follow these steps:
|
||
|
||
### Step 1: Check ce-ace CLI Version and Dependencies
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
set -euo pipefail
|
||
|
||
# Check for jq (required for JSON parsing)
|
||
if ! command -v jq >/dev/null 2>&1; then
|
||
echo "❌ jq not found (required for JSON parsing)"
|
||
echo ""
|
||
echo "Installation instructions:"
|
||
echo " macOS: brew install jq"
|
||
echo " Linux: apt-get install jq or yum install jq"
|
||
echo " Windows: Download from https://stedolan.github.io/jq/download/"
|
||
echo ""
|
||
exit 1
|
||
fi
|
||
|
||
# Check for ce-ace CLI
|
||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||
echo "❌ ce-ace CLI not found"
|
||
echo ""
|
||
echo "Installation required:"
|
||
echo " npm install -g @ace-sdk/cli"
|
||
echo ""
|
||
exit 1
|
||
fi
|
||
|
||
VERSION=$(ce-ace --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
|
||
echo "✅ ce-ace CLI found (version: $VERSION)"
|
||
|
||
# Check version >= 1.0.2
|
||
REQUIRED_VERSION="1.0.2"
|
||
if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$VERSION" | sort -V | head -n1)" != "$REQUIRED_VERSION" ]; then
|
||
echo "⚠️ ce-ace v$VERSION found, but v1.0.2+ required for non-interactive config"
|
||
echo ""
|
||
echo "Please upgrade:"
|
||
echo " npm install -g @ace-sdk/cli@latest"
|
||
echo ""
|
||
exit 1
|
||
fi
|
||
|
||
echo ""
|
||
```
|
||
|
||
### Step 2: Detect Scope
|
||
|
||
```bash
|
||
# Parse arguments
|
||
SCOPE="both"
|
||
if [ "${1:-}" == "--global" ]; then
|
||
SCOPE="global"
|
||
elif [ "${1:-}" == "--project" ]; then
|
||
SCOPE="project"
|
||
else
|
||
# Auto-detect: If in a git repo, do both; otherwise just global
|
||
if git rev-parse --show-toplevel 2>/dev/null; then
|
||
SCOPE="both"
|
||
else
|
||
SCOPE="global"
|
||
fi
|
||
fi
|
||
|
||
echo "📋 Configuration scope: $SCOPE"
|
||
echo ""
|
||
```
|
||
|
||
### Step 3: Global Configuration (if needed)
|
||
|
||
**If SCOPE is "global" or "both", use AskUserQuestion to gather inputs, then configure:**
|
||
|
||
1. **Ask for Server URL**:
|
||
Use AskUserQuestion tool:
|
||
```javascript
|
||
{
|
||
questions: [
|
||
{
|
||
question: "ACE Server URL?",
|
||
header: "Server URL",
|
||
multiSelect: false,
|
||
options: [
|
||
{
|
||
label: "Production (ace-api.code-engine.app)",
|
||
description: "Official ACE production server (recommended)"
|
||
},
|
||
{
|
||
label: "Localhost (localhost:9000)",
|
||
description: "Local development server"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Map user selection to URL:
|
||
- "Production" → `https://ace-api.code-engine.app`
|
||
- "Localhost" → `http://localhost:9000`
|
||
- "Other" → Prompt for custom URL
|
||
|
||
2. **Ask for API Token**:
|
||
Use AskUserQuestion tool:
|
||
```javascript
|
||
{
|
||
questions: [
|
||
{
|
||
question: "Enter your ACE API token (starts with 'ace_')?",
|
||
header: "API Token",
|
||
multiSelect: false,
|
||
options: [
|
||
{
|
||
label: "I have a token",
|
||
description: "Enter token in the next step"
|
||
},
|
||
{
|
||
label: "I need to get a token",
|
||
description: "Visit https://ace.code-engine.app/settings/tokens"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
If user selects "I have a token", they'll provide it in the "Other" field.
|
||
If "I need to get a token", show them the URL and exit.
|
||
|
||
3. **Validate Token and Get Org/Project Info**:
|
||
```bash
|
||
echo "🔍 Validating token with ACE server..."
|
||
echo " Server: $SERVER_URL"
|
||
echo ""
|
||
|
||
# Use subshell to avoid polluting parent environment
|
||
# Workaround: ce-ace config validate doesn't accept --server-url flag properly
|
||
# Use environment variables instead
|
||
VALIDATION_OUTPUT=$(
|
||
ACE_SERVER_URL="$SERVER_URL" \
|
||
ACE_API_TOKEN="$API_TOKEN" \
|
||
ce-ace config validate --json 2>&1
|
||
)
|
||
VALIDATION_EXIT_CODE=$?
|
||
|
||
if [ $VALIDATION_EXIT_CODE -ne 0 ]; then
|
||
echo "❌ Token validation failed"
|
||
echo ""
|
||
echo "Error details:"
|
||
echo "$VALIDATION_OUTPUT"
|
||
echo ""
|
||
echo "Common issues:"
|
||
echo " - Invalid or expired token"
|
||
echo " - Network connectivity problems"
|
||
echo " - Server URL incorrect"
|
||
echo ""
|
||
echo "Please verify your token at: https://ace.code-engine.app/settings"
|
||
exit 1
|
||
fi
|
||
|
||
# Verify we got valid JSON back
|
||
if ! echo "$VALIDATION_OUTPUT" | jq empty 2>/dev/null; then
|
||
echo "❌ Invalid response from ACE server (not valid JSON)"
|
||
echo ""
|
||
echo "Response:"
|
||
echo "$VALIDATION_OUTPUT"
|
||
exit 1
|
||
fi
|
||
|
||
# Parse validation response
|
||
ORG_ID=$(echo "$VALIDATION_OUTPUT" | jq -r '.org_id // empty')
|
||
ORG_NAME=$(echo "$VALIDATION_OUTPUT" | jq -r '.org_name // empty')
|
||
PROJECTS_JSON=$(echo "$VALIDATION_OUTPUT" | jq -c '.projects // []')
|
||
|
||
# Verify required fields
|
||
if [ -z "$ORG_ID" ] || [ -z "$ORG_NAME" ]; then
|
||
echo "❌ Validation response missing required fields (org_id, org_name)"
|
||
echo ""
|
||
echo "Response:"
|
||
echo "$VALIDATION_OUTPUT"
|
||
exit 1
|
||
fi
|
||
|
||
# Check if user has any projects
|
||
PROJECT_COUNT=$(echo "$PROJECTS_JSON" | jq 'length')
|
||
if [ "$PROJECT_COUNT" -eq 0 ]; then
|
||
echo "⚠️ No projects found for organization: $ORG_NAME"
|
||
echo ""
|
||
echo "Please create a project first at: https://ace.code-engine.app/projects"
|
||
exit 1
|
||
fi
|
||
|
||
echo "✅ Validated! Organization: $ORG_NAME ($ORG_ID)"
|
||
echo " Projects available: $PROJECT_COUNT"
|
||
echo ""
|
||
```
|
||
|
||
4. **Ask User to Select Project** (use AskUserQuestion):
|
||
```javascript
|
||
// Parse projects from PROJECTS_JSON
|
||
// Build options dynamically from project list
|
||
{
|
||
questions: [
|
||
{
|
||
question: "Which project should be configured?",
|
||
header: "Project",
|
||
multiSelect: false,
|
||
options: [
|
||
// For each project in PROJECTS_JSON:
|
||
{
|
||
label: "project.project_name",
|
||
description: "project.project_id"
|
||
}
|
||
// ... more projects
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Extract project_id from user selection.
|
||
|
||
5. **Configure with ce-ace CLI**:
|
||
```bash
|
||
echo "💾 Saving global configuration..."
|
||
|
||
# Determine config location (respect XDG_CONFIG_HOME)
|
||
GLOBAL_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/ace/config.json"
|
||
GLOBAL_CONFIG_DIR=$(dirname "$GLOBAL_CONFIG")
|
||
|
||
# Ensure config directory exists
|
||
if [ ! -d "$GLOBAL_CONFIG_DIR" ]; then
|
||
echo "📁 Creating config directory: $GLOBAL_CONFIG_DIR"
|
||
mkdir -p "$GLOBAL_CONFIG_DIR"
|
||
if [ $? -ne 0 ]; then
|
||
echo "❌ Failed to create config directory: $GLOBAL_CONFIG_DIR"
|
||
exit 1
|
||
fi
|
||
fi
|
||
|
||
# Save configuration
|
||
ce-ace config \
|
||
--server-url "$SERVER_URL" \
|
||
--api-token "$API_TOKEN" \
|
||
--project-id "$PROJECT_ID" \
|
||
--json
|
||
|
||
if [ $? -ne 0 ]; then
|
||
echo "❌ Failed to save global configuration (ce-ace config command failed)"
|
||
exit 1
|
||
fi
|
||
|
||
# Verify config file was created
|
||
if [ ! -f "$GLOBAL_CONFIG" ]; then
|
||
echo "❌ Global config was not created at expected location"
|
||
echo " Expected: $GLOBAL_CONFIG"
|
||
echo " Please check ce-ace CLI logs for details"
|
||
exit 1
|
||
fi
|
||
|
||
# Verify config is valid JSON
|
||
if ! jq empty "$GLOBAL_CONFIG" 2>/dev/null; then
|
||
echo "❌ Global config is not valid JSON"
|
||
echo " Location: $GLOBAL_CONFIG"
|
||
echo " Please check file contents"
|
||
exit 1
|
||
fi
|
||
|
||
# Verify required fields are present
|
||
if ! jq -e '.serverUrl and .apiToken' "$GLOBAL_CONFIG" >/dev/null 2>&1; then
|
||
echo "❌ Global config is missing required fields (serverUrl, apiToken)"
|
||
echo " Location: $GLOBAL_CONFIG"
|
||
exit 1
|
||
fi
|
||
|
||
echo "✅ Global configuration saved and verified:"
|
||
echo " Location: $GLOBAL_CONFIG"
|
||
echo " Server: $SERVER_URL"
|
||
echo " Project: $PROJECT_ID"
|
||
echo ""
|
||
```
|
||
|
||
### Step 4: Project Configuration (if needed)
|
||
|
||
**If SCOPE is "project" or "both":**
|
||
|
||
1. **Get Project Root**:
|
||
```bash
|
||
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||
PROJECT_CONFIG="$PROJECT_ROOT/.claude/settings.json"
|
||
|
||
echo "📂 Project root: $PROJECT_ROOT"
|
||
echo ""
|
||
```
|
||
|
||
2. **Check Existing Config**:
|
||
```bash
|
||
if [ -f "$PROJECT_CONFIG" ]; then
|
||
EXISTING_ORG=$(jq -r '.env.ACE_ORG_ID // empty' "$PROJECT_CONFIG" 2>/dev/null || echo "")
|
||
EXISTING_PROJECT=$(jq -r '.env.ACE_PROJECT_ID // empty' "$PROJECT_CONFIG" 2>/dev/null || echo "")
|
||
|
||
if [ -n "$EXISTING_ORG" ] && [ -n "$EXISTING_PROJECT" ]; then
|
||
echo "ℹ️ Found existing project configuration:"
|
||
echo " Organization ID: $EXISTING_ORG"
|
||
echo " Project ID: $EXISTING_PROJECT"
|
||
echo ""
|
||
# Ask user what they want to do - STOP HERE AND PROMPT
|
||
EXISTING_CONFIG="true"
|
||
fi
|
||
fi
|
||
```
|
||
|
||
3. **Prompt for Action** (if existing config found):
|
||
|
||
If existing configuration was detected, use AskUserQuestion:
|
||
```javascript
|
||
{
|
||
questions: [
|
||
{
|
||
question: "Found existing ACE configuration. What would you like to do?",
|
||
header: "Config Action",
|
||
multiSelect: false,
|
||
options: [
|
||
{
|
||
label: "Keep existing configuration",
|
||
description: "No changes - use current org and project settings"
|
||
},
|
||
{
|
||
label: "Update project only",
|
||
description: "Keep organization, select a different project"
|
||
},
|
||
{
|
||
label: "Reconfigure everything",
|
||
description: "Fresh setup - change both organization and project"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Based on user's choice:
|
||
- **"Keep existing configuration"** → Exit early:
|
||
```bash
|
||
echo "✅ Keeping existing configuration"
|
||
echo " Organization: $EXISTING_ORG"
|
||
echo " Project: $EXISTING_PROJECT"
|
||
exit 0
|
||
```
|
||
- **"Update project only"** → Skip to Step 5 (project selection), reuse $EXISTING_ORG
|
||
- **"Reconfigure everything"** → Continue with Step 4 (full flow)
|
||
|
||
4. **Read Global Config**:
|
||
```bash
|
||
GLOBAL_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/ace/config.json"
|
||
|
||
if [ ! -f "$GLOBAL_CONFIG" ]; then
|
||
echo "⚠️ No global config found at $GLOBAL_CONFIG"
|
||
echo " Run /ace:configure --global first"
|
||
exit 1
|
||
fi
|
||
|
||
# Check if multi-org mode
|
||
HAS_ORGS=$(jq 'has("orgs")' "$GLOBAL_CONFIG" 2>/dev/null || echo "false")
|
||
```
|
||
|
||
4. **Multi-Org Mode** (if HAS_ORGS is true):
|
||
|
||
Use AskUserQuestion to select organization:
|
||
```javascript
|
||
// Parse orgs from global config
|
||
// For each org in config.orgs:
|
||
{
|
||
questions: [
|
||
{
|
||
question: "Which organization should this project use?",
|
||
header: "Organization",
|
||
multiSelect: false,
|
||
options: [
|
||
{
|
||
label: "org.orgName",
|
||
description: "org_id"
|
||
}
|
||
// ... more orgs
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Then ask for project from that org's project list.
|
||
|
||
5. **Single-Org Mode** (if HAS_ORGS is false):
|
||
|
||
Just ask for project ID directly using AskUserQuestion.
|
||
|
||
6. **Write .claude/settings.json**:
|
||
```bash
|
||
mkdir -p "$PROJECT_ROOT/.claude"
|
||
|
||
if [ -n "$ORG_ID" ]; then
|
||
# Multi-org: include ACE_ORG_ID in env
|
||
cat > "$PROJECT_CONFIG" <<EOF
|
||
{
|
||
"env": {
|
||
"ACE_ORG_ID": "$ORG_ID",
|
||
"ACE_PROJECT_ID": "$PROJECT_ID"
|
||
}
|
||
}
|
||
EOF
|
||
echo "✅ Project configuration saved:"
|
||
echo " Organization ID: $ORG_ID"
|
||
echo " Project ID: $PROJECT_ID"
|
||
else
|
||
# Single-org: just ACE_PROJECT_ID in env
|
||
cat > "$PROJECT_CONFIG" <<EOF
|
||
{
|
||
"env": {
|
||
"ACE_PROJECT_ID": "$PROJECT_ID"
|
||
}
|
||
}
|
||
EOF
|
||
echo "✅ Project configuration saved:"
|
||
echo " Project ID: $PROJECT_ID"
|
||
fi
|
||
|
||
echo " Location: $PROJECT_CONFIG"
|
||
echo ""
|
||
```
|
||
|
||
### Step 5: Show Summary
|
||
|
||
```bash
|
||
echo ""
|
||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||
echo "✅ ACE Configuration Complete!"
|
||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||
echo ""
|
||
|
||
if [ "$SCOPE" = "global" ] || [ "$SCOPE" = "both" ]; then
|
||
GLOBAL_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/ace/config.json"
|
||
echo "Global Config: $GLOBAL_CONFIG ✓"
|
||
fi
|
||
|
||
if [ "$SCOPE" = "project" ] || [ "$SCOPE" = "both" ]; then
|
||
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||
echo "Project Config: $PROJECT_ROOT/.claude/settings.json ✓"
|
||
fi
|
||
|
||
echo ""
|
||
echo "Next steps:"
|
||
echo "1. Run: /ace:status to verify connection"
|
||
echo "2. Optional: /ace:bootstrap to populate playbook from codebase"
|
||
echo "3. Start coding - hooks will auto-search patterns!"
|
||
echo ""
|
||
```
|
||
|
||
## Implementation Notes for Claude
|
||
|
||
**Key Points:**
|
||
1. **Always use AskUserQuestion** for user input (not bash read or prompts)
|
||
2. **Parse JSON responses** from `ce-ace config validate --json`
|
||
3. **Build dynamic options** from validation response (orgs/projects)
|
||
4. **Map user selections** to actual values (e.g., "Production" → URL)
|
||
5. **Handle both single-org and multi-org modes** based on global config
|
||
|
||
**Error Handling:**
|
||
- Check jq availability (required for JSON parsing)
|
||
- Check ce-ace version >= 1.0.2
|
||
- Validate token before saving (with detailed error messages)
|
||
- Verify global config file was created and is valid JSON
|
||
- Verify global config has required fields (serverUrl, apiToken)
|
||
- Check user has at least one project in organization
|
||
- Handle missing global config for project-only mode
|
||
- Use subshell for environment variables (avoid pollution)
|
||
|
||
**User Experience:**
|
||
- Show progress messages at each step
|
||
- Display org/project names (not just IDs) in selections
|
||
- Provide helpful error messages with next steps
|
||
- Summarize what was configured
|
||
|
||
## What Gets Configured
|
||
|
||
### Global Config (~/.config/ace/config.json)
|
||
|
||
**Single-Org Mode:**
|
||
```json
|
||
{
|
||
"serverUrl": "https://ace-api.code-engine.app",
|
||
"apiToken": "ace_xxxxx",
|
||
"projectId": "prj_xxxxx",
|
||
"cacheTtlMinutes": 120
|
||
}
|
||
```
|
||
|
||
**Multi-Org Mode:**
|
||
```json
|
||
{
|
||
"serverUrl": "https://ace-api.code-engine.app",
|
||
"orgs": {
|
||
"org_xxxxx": {
|
||
"orgName": "My Organization",
|
||
"apiToken": "ace_xxxxx",
|
||
"projects": ["prj_123", "prj_456"]
|
||
}
|
||
},
|
||
"cacheTtlMinutes": 120
|
||
}
|
||
```
|
||
|
||
### Project Config (.claude/settings.json)
|
||
|
||
**Multi-Org:**
|
||
```json
|
||
{
|
||
"env": {
|
||
"ACE_ORG_ID": "org_xxxxx",
|
||
"ACE_PROJECT_ID": "prj_xxxxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Single-Org:**
|
||
```json
|
||
{
|
||
"env": {
|
||
"ACE_PROJECT_ID": "prj_xxxxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Usage Examples
|
||
|
||
### First-Time Setup (Both Global + Project)
|
||
|
||
```
|
||
/ace:configure
|
||
```
|
||
|
||
**Flow:**
|
||
1. Asks for server URL (production/localhost/custom)
|
||
2. Asks for API token
|
||
3. Validates token, fetches org/projects
|
||
4. Asks which project to configure
|
||
5. Saves global config (~/.config/ace/config.json)
|
||
6. Saves project config (.claude/settings.json)
|
||
|
||
### Update Global Config Only
|
||
|
||
```
|
||
/ace:configure --global
|
||
```
|
||
|
||
**Flow:**
|
||
1. Reconfigures global settings
|
||
2. Validates token
|
||
3. Updates ~/.config/ace/config.json
|
||
|
||
### Update Project Config Only
|
||
|
||
```
|
||
/ace:configure --project
|
||
```
|
||
|
||
**Flow:**
|
||
1. Reads existing global config
|
||
2. Asks which org/project for THIS project
|
||
3. Updates .claude/settings.json
|
||
|
||
## See Also
|
||
|
||
- `/ace:status` - Verify configuration
|
||
- `/ace:bootstrap` - Initialize playbook
|
||
- `ce-ace config --help` - CLI config help
|
||
- `ce-ace config show` - View current config
|