@startanaicompany/cli 1.1.0 → 1.3.1

package/CLAUDE.md

@@ -33,11 +33,12 @@ saac login
 
 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)
+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
@@ -207,14 +208,149 @@ The CLI now uses session tokens instead of storing permanent API keys:
 - 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
+
+### Init Command Implementation
+
+The `init` command links an existing SAAC application to the current directory.
+
+**Primary Use Case:** When you clone a Git repository or have an existing project and want to link it to a SAAC application for deployment.
+
+**How It Works:**
+1. Checks if directory is already initialized (has `.saac/config.json`)
+2. Fetches all user applications from the API
+3. Shows interactive list to select which application to link
+4. Saves selected application info to `.saac/config.json`
+
+**Usage:**
+```bash
+# Interactive mode - select from existing applications
+cd my-project
+saac init
+# Select application from list
+```
+
+**Behavior:**
+- If directory is already initialized, asks for confirmation to re-link
+- If user has no applications, suggests using `saac create`
+- After initialization, shows available commands (deploy, logs, status, update)
+
+**Note:** The `init` command options (`-n, --name`, etc.) are currently not implemented. To create a new application, use `saac create` instead.
+
 ### 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
+Several commands still need implementation:
+- `src/commands/env.js` - Not implemented (partial stub)
+- `src/commands/domain.js` - Not implemented (partial stub)
+- `src/commands/logs.js` - Not implemented (partial stub)
+- `src/commands/delete.js` - Not implemented (partial stub)
+- `src/commands/list.js` - Not implemented (partial stub)
+- `src/commands/whoami.js` - Not implemented (partial stub)
 
-These need full implementation following the pattern from completed commands like `deploy.js` or `login.js`.
+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

package/README.md

@@ -105,26 +105,91 @@ Shows all devices where you're currently logged in with creation date, last used
 ### Application Management
 
 #### `saac init`
-Initialize SAAC in an existing project
+Link an existing SAAC application to the current directory
 
 ```bash
+# Interactive mode - select from your applications
+cd my-project
 saac init
-saac init --name myapp --subdomain myapp
 ```
 
-#### `saac create [name]`
+**Use Case:** When you clone a Git repository or have an existing project and want to link it to a SAAC application.
+
+**What it does:**
+1. Shows all your SAAC applications
+2. Let you select which one to link to this directory
+3. Saves the link to `.saac/config.json`
+4. Now you can use `saac deploy`, `saac logs`, etc.
+
+**Note:** To create a new application, use `saac create` instead.
+
+#### `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
@@ -223,7 +288,7 @@ saac rm            # Alias
 
 ### Global Configuration
 
-Stored in `~/.saac/config.json`:
+Stored in `~/.config/startanaicompany/config.json`:
 
 ```json
 {

package/bin/saac.js

@@ -18,6 +18,7 @@ const logoutAll = require('../src/commands/logoutAll');
 const sessions = require('../src/commands/sessions');
 const init = require('../src/commands/init');
 const create = require('../src/commands/create');
+const update = require('../src/commands/update');
 const deploy = require('../src/commands/deploy');
 const logs = require('../src/commands/logs');
 const env = require('../src/commands/env');
@@ -83,12 +84,68 @@ program
 program
   .command('create [name]')
   .description('Create a new application')
+  // Required options
   .option('-s, --subdomain <subdomain>', 'Subdomain')
-  .option('-d, --domain-suffix <suffix>', 'Domain suffix', 'startanaicompany.com')
-  .option('-r, --repository <url>', 'Git repository URL')
+  .option('-r, --repository <url>', 'Git repository URL (SSH format)')
+  .option('-t, --git-token <token>', 'Git API token')
+  // Basic options
   .option('-b, --branch <branch>', 'Git branch', 'master')
+  .option('-d, --domain-suffix <suffix>', 'Domain suffix', 'startanaicompany.com')
+  .option('-p, --port <port>', 'Port to expose (default: 3000)')
+  // Build configuration
+  .option('--build-pack <pack>', 'Build pack: dockercompose, nixpacks, dockerfile, static')
+  .option('--install-cmd <command>', 'Install command')
+  .option('--build-cmd <command>', 'Build command')
+  .option('--start-cmd <command>', 'Start command')
+  .option('--pre-deploy-cmd <command>', 'Pre-deployment command')
+  .option('--post-deploy-cmd <command>', 'Post-deployment command')
+  // Resource limits
+  .option('--cpu-limit <limit>', 'CPU limit (e.g., "1", "2.5")')
+  .option('--memory-limit <limit>', 'Memory limit (e.g., "512M", "2G")')
+  // Health checks
+  .option('--health-check', 'Enable health checks')
+  .option('--health-path <path>', 'Health check path')
+  .option('--health-interval <seconds>', 'Health check interval in seconds')
+  .option('--health-timeout <seconds>', 'Health check timeout in seconds')
+  .option('--health-retries <count>', 'Health check retries (1-10)')
+  // Environment variables
+  .option('--env <KEY=VALUE>', 'Environment variable (can be used multiple times)', (val, prev) => {
+    return prev ? [...prev, val] : [val];
+  }, [])
   .action(create);
 
+program
+  .command('update')
+  .description('Update application configuration')
+  // Basic options
+  .option('-n, --name <name>', 'Application name')
+  .option('-b, --branch <branch>', 'Git branch')
+  .option('-p, --port <port>', 'Port to expose')
+  // Build configuration
+  .option('--build-pack <pack>', 'Build pack: dockercompose, nixpacks, dockerfile, static')
+  .option('--install-cmd <command>', 'Install command')
+  .option('--build-cmd <command>', 'Build command')
+  .option('--start-cmd <command>', 'Start command')
+  .option('--pre-deploy-cmd <command>', 'Pre-deployment command')
+  .option('--post-deploy-cmd <command>', 'Post-deployment command')
+  // Resource limits
+  .option('--cpu-limit <limit>', 'CPU limit (e.g., "1", "2.5")')
+  .option('--memory-limit <limit>', 'Memory limit (e.g., "512M", "2G")')
+  // Health checks
+  .option('--health-check', 'Enable health checks')
+  .option('--no-health-check', 'Disable health checks')
+  .option('--health-path <path>', 'Health check path')
+  .option('--health-interval <seconds>', 'Health check interval in seconds')
+  .option('--health-timeout <seconds>', 'Health check timeout in seconds')
+  .option('--health-retries <count>', 'Health check retries (1-10)')
+  // Restart policy
+  .option('--restart <policy>', 'Restart policy: always, on-failure, unless-stopped, no')
+  // Environment variables
+  .option('--env <KEY=VALUE>', 'Environment variable (can be used multiple times)', (val, prev) => {
+    return prev ? [...prev, val] : [val];
+  }, [])
+  .action(update);
+
 program
   .command('deploy')
   .description('Deploy current application')