@startanaicompany/cli 1.0.0 → 1.3.0

package/CLAUDE.md

@@ -0,0 +1,358 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SAAC CLI is the official command-line interface for StartAnAiCompany.com, enabling users to deploy AI recruitment sites through a wrapper API that interfaces with Coolify. The CLI is built with Node.js and uses the Commander.js framework for command structure.
+
+## Key Commands
+
+### Development
+```bash
+# Run CLI locally during development
+npm run dev
+
+# Lint code
+npm run lint
+
+# Link for local testing
+npm link
+```
+
+### After linking, test with:
+```bash
+saac --help
+saac register
+saac login
+```
+
+## Architecture
+
+### Configuration System (Dual-Level)
+
+The CLI maintains two separate configuration files:
+
+1. **Global Config** (`~/.config/startanaicompany/config.json`)
+   - Managed by the `conf` package with custom cwd path
+   - Stores user credentials (email, userId, sessionToken, expiresAt)
+   - Stores API URLs (wrapper API, Git server)
+   - Persists across all projects
+   - Note: Uses explicit path to avoid `-nodejs` suffix that Conf adds by default
+
+2. **Project Config** (`.saac/config.json` in project directory)
+   - Manually managed via fs operations
+   - Stores application-specific data (applicationUuid, applicationName, subdomain, gitRepository)
+   - Required for deployment commands
+
+**Important Pattern**: Commands check both configs:
+- Authentication commands → global config only
+- Deployment/management commands → require BOTH global config (for auth) and project config (for app UUID)
+
+### API Client (`src/lib/api.js`)
+
+Creates axios instances with:
+- Base URL from global config
+- X-API-Key header automatically injected from global config
+- 30-second timeout
+- All API functions are async and return response.data
+
+**API Wrapper Endpoints**:
+- `/register` - Create new user account
+- `/users/verify` - Email verification
+- `/users/me` - Get current user info
+- `/applications` - CRUD operations for apps
+- `/applications/:uuid/deploy` - Trigger deployment
+- `/applications/:uuid/logs` - Fetch logs
+- `/applications/:uuid/env` - Manage environment variables
+- `/applications/:uuid/domain` - Update domain settings
+
+### Logger (`src/lib/logger.js`)
+
+Centralized logging utility using chalk, ora, and boxen:
+- `logger.success()` - Green checkmark messages
+- `logger.error()` - Red X messages
+- `logger.warn()` - Yellow warning symbol
+- `logger.info()` - Blue info symbol
+- `logger.spinner(text)` - Returns ora spinner instance
+- `logger.section(title)` - Bold cyan headers with underline
+- `logger.field(key, value)` - Key-value pair display
+- `logger.box(message, options)` - Boxed messages
+
+**Pattern**: Use spinners for async operations:
+```javascript
+const spin = logger.spinner('Processing...').start();
+try {
+  await someAsyncOperation();
+  spin.succeed('Done!');
+} catch (error) {
+  spin.fail('Failed');
+  throw error;
+}
+```
+
+### Command Structure
+
+All commands follow this pattern:
+1. **Validate required flags** - Show usage if missing (commands are non-interactive by default)
+2. Import required libraries (api, config, logger)
+3. Check authentication with `isAuthenticated()` (validates session token expiration)
+4. Check project config if needed with `getProjectConfig()`
+5. Execute operation with spinner feedback
+6. Handle errors and exit with appropriate code
+
+**Important:** Commands require flags and do NOT use interactive prompts. This makes them LLM and automation-friendly.
+
+**Examples:**
+```bash
+# ✅ Correct - with flags
+saac register -e user@example.com
+saac login -e user@example.com -k cw_api_key
+
+# ❌ Wrong - will show usage error
+saac register
+saac login
+```
+
+**Command Files**:
+- Authentication: `register.js`, `login.js`, `verify.js`, `logout.js`, `whoami.js`
+- App Management: `create.js`, `init.js`, `deploy.js`, `delete.js`, `list.js`, `status.js`
+- Configuration: `env.js`, `domain.js`
+- Logs: `logs.js`
+
+### Entry Point (`bin/saac.js`)
+
+Uses Commander.js to define:
+- Commands with options and aliases
+- Nested commands (e.g., `env set`, `env get`, `domain set`)
+- Help text and version info
+- Error handling for invalid commands
+
+## Important Patterns
+
+### Authentication Flow
+
+**Session Token Flow (Primary):**
+1. User registers with email → API returns session token (1 year expiration)
+2. Session token stored in global config with expiration timestamp
+3. Verification code sent to MailHog (not real email)
+4. User verifies → verified flag set to true
+5. All subsequent API requests include X-Session-Token header
+6. Token expires after 1 year → user must login again
+
+**API Key Flow (CI/CD & Scripts):**
+1. User logs in with email + API key → API returns session token
+2. Environment variable `SAAC_API_KEY` can override stored credentials
+3. Useful for automation, scripts, and CI/CD pipelines
+
+**Authentication Priority:**
+```javascript
+// In api.js createClient()
+if (process.env.SAAC_API_KEY) {
+  headers['X-API-Key'] = SAAC_API_KEY;  // 1st priority
+} else if (user.sessionToken) {
+  headers['X-Session-Token'] = sessionToken;  // 2nd priority
+} else if (user.apiKey) {
+  headers['X-API-Key'] = apiKey;  // 3rd priority (backward compat)
+}
+```
+
+### Application Lifecycle
+
+1. **Create/Init** → applicationUuid saved to `.saac/config.json`
+2. **Deploy** → POST to `/applications/:uuid/deploy`
+3. **Monitor** → GET `/applications/:uuid/logs`
+4. **Update** → PATCH environment or domain
+5. **Delete** → DELETE `/applications/:uuid`
+
+### Error Handling Convention
+
+All commands use try-catch with:
+```javascript
+try {
+  // command logic
+} catch (error) {
+  logger.error(error.response?.data?.message || error.message);
+  process.exit(1);
+}
+```
+
+This pattern extracts API error messages or falls back to generic error message.
+
+## Development Notes
+
+### Session Token Implementation
+
+The CLI now uses session tokens instead of storing permanent API keys:
+
+**Config Storage** (`~/.saac/config.json`):
+```json
+{
+  "user": {
+    "email": "user@example.com",
+    "userId": "uuid",
+    "sessionToken": "st_...",
+    "expiresAt": "2026-01-25T12:00:00Z",
+    "verified": true
+  }
+}
+```
+
+**Token Validation Functions** (in `config.js`):
+- `isAuthenticated()` - Checks if user has valid, non-expired token
+- `isTokenExpired()` - Checks if session token has expired
+- `isTokenExpiringSoon()` - Checks if token expires within 7 days
+
+**Backend Requirements:**
+- `POST /auth/login` - Accepts `X-API-Key` + email, returns session token
+- Middleware must accept both `X-Session-Token` and `X-API-Key` headers
+- Session tokens expire after 1 year
+
+### Create Command Implementation
+
+The `create` command is fully implemented with ALL backend features:
+
+**Required Options:**
+- `-s, --subdomain` - Subdomain for the application
+- `-r, --repository` - Git repository URL (SSH format)
+- `-t, --git-token` - Git API token for repository access
+
+**Optional Basic Configuration:**
+- `-b, --branch` - Git branch (default: master)
+- `-d, --domain-suffix` - Domain suffix (default: startanaicompany.com)
+- `-p, --port` - Port to expose (default: 3000)
+
+**Build Pack Options:**
+- `--build-pack` - Build system: dockercompose, nixpacks, dockerfile, static
+- `--install-cmd` - Custom install command (e.g., "pnpm install")
+- `--build-cmd` - Custom build command (e.g., "npm run build")
+- `--start-cmd` - Custom start command (e.g., "node server.js")
+- `--pre-deploy-cmd` - Pre-deployment hook (e.g., "npm run migrate")
+- `--post-deploy-cmd` - Post-deployment hook (e.g., "npm run seed")
+
+**Resource Limits:**
+- `--cpu-limit` - CPU limit (e.g., "1", "2.5")
+- `--memory-limit` - Memory limit (e.g., "512M", "2G")
+- Note: Free tier limited to 1 vCPU, 1024M RAM
+
+**Health Checks:**
+- `--health-check` - Enable health checks
+- `--health-path` - Health check endpoint (default: /health)
+- `--health-interval` - Check interval in seconds
+- `--health-timeout` - Check timeout in seconds
+- `--health-retries` - Number of retries (1-10)
+
+**Environment Variables:**
+- `--env KEY=VALUE` - Can be used multiple times (max 50 variables)
+
+**Examples:**
+```bash
+# Basic application
+saac create my-app -s myapp -r git@git.startanaicompany.com:user/repo.git -t abc123
+
+# With build pack and custom port
+saac create api -s api -r git@git... -t abc123 --build-pack nixpacks --port 8080
+
+# With health checks and pre-deployment migration
+saac create web -s web -r git@git... -t abc123 \
+  --health-check \
+  --pre-deploy-cmd "npm run migrate" \
+  --env NODE_ENV=production \
+  --env LOG_LEVEL=info
+```
+
+**Implementation Details:**
+- Validates all required fields before API call
+- Shows configuration summary before creation
+- Handles tier-based quota errors (403)
+- Handles validation errors (400) with field-specific messages
+- Saves project config to `.saac/config.json` after successful creation
+- Displays next steps and useful commands
+
+### Update Command Implementation
+
+The `update` command allows modifying application configuration after deployment using `PATCH /api/v1/applications/:uuid`.
+
+**All Configuration Fields Can Be Updated:**
+- Basic: name, branch, port
+- Build pack and custom commands
+- Resource limits (CPU, memory) - capped at tier limits
+- Health checks (enable/disable, path, interval, timeout, retries)
+- Restart policy (always, on-failure, unless-stopped, no)
+- Environment variables
+
+**Important Notes:**
+- Only fields you specify will be updated (partial updates)
+- Resource limits are enforced by user tier (free: 1 vCPU, 1GB RAM)
+- Changes require redeployment to take effect: `saac deploy`
+- Requires project config (`.saac/config.json`)
+
+**Examples:**
+```bash
+# Update port and enable health checks
+saac update --port 8080 --health-check --health-path /api/health
+
+# Switch to Nixpacks and update resource limits
+saac update --build-pack nixpacks --cpu-limit 2 --memory-limit 2G
+
+# Update custom commands
+saac update --pre-deploy-cmd "npm run migrate" --start-cmd "node dist/server.js"
+
+# Disable health checks
+saac update --no-health-check
+
+# Update environment variables
+saac update --env NODE_ENV=production --env LOG_LEVEL=debug
+
+# Change restart policy
+saac update --restart on-failure
+```
+
+**Response Behavior:**
+- Shows which fields were updated
+- Warns if tier limits were applied (resource caps)
+- Reminds user to redeploy for changes to take effect
+
+### Incomplete Commands
+
+Several commands still need implementation:
+- `src/commands/init.js` - Not implemented
+- `src/commands/env.js` - Not implemented
+
+These need full implementation following the pattern from completed commands like `create.js` or `login.js`.
+
+**Implementation Pattern for New Commands:**
+1. Require flags, no interactive prompts
+2. Show usage info if required flags missing
+3. Validate inputs before API calls
+4. Use spinners for async operations
+5. Handle errors with descriptive messages
+
+### MailHog Integration
+
+The system uses MailHog for email verification in development:
+- URL: https://mailhog.goryan.io
+- Users must manually retrieve verification codes
+- Production would use real SMTP
+
+### Domain Configuration
+
+Default domain suffix: `startanaicompany.com`
+Applications are accessible at: `{subdomain}.startanaicompany.com`
+
+### Git Repository Integration
+
+The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gitea instance:
+- Gitea URL: https://git.startanaicompany.com
+- During registration, Gitea username can be auto-detected or manually provided
+- Applications reference repositories in the format: `git@git.startanaicompany.com:user/repo.git`
+
+## Testing Considerations
+
+When implementing new commands:
+1. Test both with flags and interactive prompts
+2. Verify error handling for missing authentication
+3. Verify error handling for missing project config
+4. Test API error responses
+5. Ensure proper exit codes (0 for success, 1 for errors)
+6. Check that spinners succeed/fail appropriately

package/README.md

@@ -24,10 +24,10 @@ npm install -g @startanaicompany/cli
 
 ```bash
 # 1. Register for an account
-saac register
+saac register --email user@example.com
 
 # 2. Verify your email (check MailHog)
-saac verify <code>
+saac verify 123456
 
 # 3. Create a new application
 saac create my-recruitment-site
@@ -44,18 +44,28 @@ saac deploy
 Register for a new account
 
 ```bash
-saac register
 saac register --email user@example.com
+saac register -e user@example.com --gitea-username myuser
 ```
 
+**Required:**
+- `-e, --email <email>` - Your email address
+
+**Optional:**
+- `--gitea-username <username>` - Your Gitea username (auto-detected if not provided)
+
 #### `saac login`
 Login with existing credentials
 
 ```bash
-saac login
 saac login --email user@example.com --api-key cw_...
+saac login -e user@example.com -k cw_...
 ```
 
+**Required:**
+- `-e, --email <email>` - Your email address
+- `-k, --api-key <key>` - Your API key
+
 #### `saac verify <code>`
 Verify your email address
 
@@ -66,12 +76,32 @@ saac verify 123456
 **Note:** Check MailHog at https://mailhog.goryan.io for verification codes
 
 #### `saac logout`
-Clear saved credentials
+Logout from current device (revokes session token)
 
 ```bash
 saac logout
 ```
 
+#### `saac logout-all`
+Logout from all devices (revokes all session tokens)
+
+```bash
+saac logout-all
+saac logout-all --yes  # Skip confirmation
+```
+
+**Options:**
+- `-y, --yes` - Skip confirmation prompt
+
+#### `saac sessions`
+List all active sessions
+
+```bash
+saac sessions
+```
+
+Shows all devices where you're currently logged in with creation date, last used time, IP address, and expiration date.
+
 ### Application Management
 
 #### `saac init`
@@ -82,19 +112,73 @@ saac init
 saac init --name myapp --subdomain myapp
 ```
 
-#### `saac create [name]`
+#### `saac create <name>`
 Create a new application
 
 ```bash
-saac create
-saac create my-site --subdomain mysite
+# Basic application
+saac create my-app -s myapp -r git@git.startanaicompany.com:user/repo.git -t abc123
+
+# Advanced with health checks and migration
+saac create api -s api -r git@git... -t abc123 \
+  --build-pack nixpacks \
+  --port 8080 \
+  --pre-deploy-cmd "npm run migrate" \
+  --health-check \
+  --health-path /api/health \
+  --env NODE_ENV=production
 ```
 
-Options:
-- `-s, --subdomain <subdomain>` - Subdomain for your site
-- `-d, --domain-suffix <suffix>` - Domain suffix (default: startanaicompany.com)
-- `-r, --repository <url>` - Git repository URL
+**Required:**
+- `<name>` - Application name
+- `-s, --subdomain <subdomain>` - Subdomain for your app
+- `-r, --repository <url>` - Git repository URL (SSH format)
+- `-t, --git-token <token>` - Git API token
+
+**Optional:**
 - `-b, --branch <branch>` - Git branch (default: master)
+- `-d, --domain-suffix <suffix>` - Domain suffix (default: startanaicompany.com)
+- `-p, --port <port>` - Port to expose (default: 3000)
+- `--build-pack <pack>` - Build pack: dockercompose, nixpacks, dockerfile, static
+- `--install-cmd <command>` - Install command
+- `--build-cmd <command>` - Build command
+- `--start-cmd <command>` - Start command
+- `--pre-deploy-cmd <command>` - Pre-deployment command (e.g., migrations)
+- `--post-deploy-cmd <command>` - Post-deployment command (e.g., seeding)
+- `--cpu-limit <limit>` - CPU limit (e.g., "1", "2.5")
+- `--memory-limit <limit>` - Memory limit (e.g., "512M", "2G")
+- `--health-check` - Enable health checks
+- `--health-path <path>` - Health check path (default: /health)
+- `--health-interval <seconds>` - Health check interval in seconds
+- `--health-timeout <seconds>` - Health check timeout in seconds
+- `--health-retries <count>` - Health check retries (1-10)
+- `--env <KEY=VALUE>` - Environment variable (can be used multiple times)
+
+**Note:** Free tier limited to 1 vCPU, 1024M RAM
+
+#### `saac update`
+Update application configuration
+
+```bash
+# Update port and enable health checks
+saac update --port 8080 --health-check --health-path /api/health
+
+# Switch to Nixpacks and update resource limits
+saac update --build-pack nixpacks --cpu-limit 2 --memory-limit 2G
+
+# Update custom commands
+saac update --pre-deploy-cmd "npm run migrate"
+
+# Disable health checks
+saac update --no-health-check
+```
+
+**Options:** All options from `create` command can be updated individually
+
+**Important:** Configuration changes require redeployment to take effect:
+```bash
+saac deploy
+```
 
 #### `saac deploy`
 Deploy your application
@@ -193,7 +277,7 @@ saac rm            # Alias
 
 ### Global Configuration
 
-Stored in `~/.saac/config.json`:
+Stored in `~/.config/startanaicompany/config.json`:
 
 ```json
 {
@@ -225,7 +309,7 @@ Stored in `.saac/config.json` in your project:
 
 ```bash
 # Step 1: Register and verify
-saac register --email dev@company.com
+saac register -e dev@company.com
 # Check MailHog for code
 saac verify 123456