@startanaicompany/cli 1.0.0 → 1.1.0

package/CLAUDE.md

@@ -0,0 +1,253 @@
+# 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** (`~/.saac/config.json`)
+   - Managed by the `conf` package
+   - Stores user credentials (email, userId, apiKey)
+   - Stores API URLs (wrapper API, Gitea)
+   - Persists across all projects
+
+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
+
+### Incomplete Commands
+
+Several commands are stubbed with TODO comments:
+- `src/commands/create.js` - Not implemented
+- `src/commands/init.js` - Not implemented
+- `src/commands/env.js` - Not implemented
+
+These need full implementation following the pattern from completed commands like `deploy.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`
@@ -225,7 +255,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