@sembix/cli 0.1.0

package/README.md

@@ -0,0 +1,698 @@
+# Sembix CLI
+
+A terminal-based CLI tool for managing Sembix products. An intuitive command-line interface designed for technical users.
+
+## Features
+
+- 🚀 **Interactive Setup** - Guided prompts for environment configuration with detailed explanations
+- 📝 **Config File Support** - YAML configuration files for version-controlled, repeatable setups
+- 🎯 **50+ CLI Flags** - Complete automation support with flags for every configuration option
+- 🔐 **GitHub Integration** - Direct GitHub API integration for environment and secrets management
+- ✅ **Validation** - Real-time input validation for AWS resources, IAM roles, and more
+- 🔄 **Update Command** - Modify existing environments without recreation
+- 🔗 **Hub Integration** - Built-in Hub configuration as part of the main workflow
+- 🎨 **Beautiful UI** - Clean, colorful terminal interface with spinners and status updates
+- ⚡ **Priority Chain** - CLI flags > Config file > Interactive prompts > Defaults
+
+## Prerequisites
+
+- **Node.js** 20 or higher
+- **GitHub Personal Access Token** with the following scopes:
+  - `repo` - Full control of private repositories
+  - `workflow` - Update GitHub Action workflows
+- **Deployment Repository** - A GitHub repository set up for Sembix Studio deployments
+
+## Installation
+
+### From npm (Recommended)
+
+```bash
+npm install -g @sembix/cli
+```
+
+### From Source
+
+```bash
+npm install
+npm run build
+
+# Link globally for development
+npm link
+```
+
+### Development Mode
+
+```bash
+npm install
+npm run dev -- studio create
+```
+
+## Configuration
+
+### Option 1: Environment Variables (.env file)
+
+Create a `.env` file in the project root directory:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and add your GitHub token:
+
+```env
+# GitHub Personal Access Token
+GITHUB_TOKEN=ghp_your_token_here
+
+# Optional: Default GitHub organization
+DEFAULT_GITHUB_ORG=your-org
+```
+
+### Option 2: Config File (Recommended for Automation)
+
+Create a YAML config file for your environment:
+
+```yaml
+# production.yaml
+repository:
+  owner: acme-corp
+  repo: sembix-deployment
+
+environmentName: client-abc-production
+awsAccountId: "123456789012"
+awsRegion: us-east-1
+customerRoleArn: arn:aws:iam::123456789012:role/GitHubActionsDeployRole
+terraformStateBucket: my-terraform-state-bucket
+
+database:
+  name: sembix_studio
+  user: sembix_studio_user
+
+# ... see config.example.yaml for complete structure
+```
+
+See [`config.example.yaml`](./config.example.yaml) for a complete configuration example.
+
+### Creating a GitHub Token
+
+1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Click "Generate new token (classic)"
+3. Select scopes:
+   - ✅ `repo` (all sub-scopes)
+   - ✅ `workflow`
+4. Generate and copy the token
+5. Add to `.env` file or use `--token` flag
+
+## Usage
+
+### Quick Start
+
+```bash
+# Fully interactive (beginner-friendly)
+sembix studio create
+
+# Fast setup with config file
+sembix studio create --config production.yaml
+
+# Fully automated with CLI flags
+sembix studio create production \
+  --repo acme/deploy \
+  --aws-account-id 123456789012 \
+  --aws-region us-east-1 \
+  --customer-role-arn arn:aws:iam::123456789012:role/Deploy \
+  --terraform-state-bucket my-tf-state \
+  # ... (all other flags)
+```
+
+## Commands
+
+### `sembix studio create`
+
+Create a new Sembix Studio environment with complete configuration.
+
+**Syntax:**
+
+```bash
+sembix studio create [environment-name] [options]
+```
+
+**Options:**
+
+```bash
+# General
+-t, --token <token>           GitHub personal access token
+-c, --config <path>           Path to YAML configuration file
+-r, --repo <repo>             Target repository (owner/repo format)
+-e, --env <environment>       Environment name (alternative to positional arg)
+
+# AWS Basic Configuration
+--aws-account-id <id>         AWS Account ID (12 digits)
+--aws-region <region>         AWS Region (e.g., us-east-1)
+--customer-role-arn <arn>     GitHub Actions IAM role ARN
+--terraform-state-bucket <bucket>  S3 bucket for Terraform state
+
+# Database
+--database-name <name>        PostgreSQL database name
+--database-user <user>        PostgreSQL database user
+
+# Networking
+--enable-vpc-endpoints <boolean>     Enable VPC endpoints (true/false)
+--use-custom-networking <boolean>    Use existing VPC (true/false)
+--vpc-cidr <cidr>                    VPC CIDR block (e.g., 10.0.0.0/16)
+--public-subnet-cidrs <json>         Public subnet CIDRs (JSON array)
+--private-subnet-cidrs <json>        Private subnet CIDRs (JSON array)
+--az-count <count>                   Number of AZs (2 or 3)
+--custom-vpc-id <id>                 Existing VPC ID
+--custom-public-subnet-ids <ids>     Existing public subnet IDs (comma-separated)
+--custom-private-subnet-ids <ids>    Existing private subnet IDs (comma-separated)
+
+# Security - Security Groups
+--use-custom-security-groups <boolean>  Use custom security groups (true/false)
+--sg-workflow-engine <id>            Workflow Engine security group ID
+--sg-aurora <id>                     Aurora database security group ID
+--sg-rds-proxy <id>                  RDS Proxy security group ID
+--sg-bff-ecs <id>                    BFF ECS service security group ID
+--sg-bastion <id>                    Bastion host security group ID
+--sg-bff-alb <id>                    BFF ALB security group ID
+
+# Security - IAM Roles
+--use-custom-iam-roles <boolean>     Use custom IAM roles (true/false)
+--iam-workflow-engine-exec <arn>     Workflow Engine execution role ARN
+--iam-workflow-engine-task <arn>     Workflow Engine task role ARN
+--iam-bff-ecs-exec <arn>             BFF ECS task execution role ARN
+--iam-bff-ecs-task <arn>             BFF ECS task role ARN
+--iam-rds-proxy <arn>                RDS Proxy role ARN
+--iam-studio-memory <arn>            Studio Memory role ARN
+--iam-studio-notification <arn>      Studio Notification role ARN
+
+# TLS/DNS
+--cloudfront-domain <domain>         CloudFront custom domain
+--cloudfront-cert-arn <arn>          CloudFront SSL certificate ARN (must be in us-east-1)
+--bff-alb-cert-arn <arn>             BFF ALB SSL certificate ARN
+--hosted-zone-id <id>                Route53 hosted zone ID
+
+# Feature Flags
+--deploy-studio-memory <boolean>     Deploy Studio Memory service (true/false)
+--deploy-studio-notifications <boolean>  Deploy Studio Notifications (true/false)
+--enable-bff-waf <boolean>           Enable WAF for BFF (true/false)
+
+# Frontend
+--github-app-client-id <id>          GitHub App OAuth client ID
+--github-app-name <name>             GitHub App name
+--jira-client-id <id>                Jira OAuth client ID
+
+# Hub Integration (Step 9)
+--skip-hub                           Skip Hub integration configuration
+--hub-engine-execution-role <arn>    Hub Engine Execution Role ARN
+--hub-consumer-role <arn>            Hub Consumer Role ARN
+--hub-admin-role <arn>               Hub Admin Role ARN
+--hub-appconfig-role <arn>           Hub AppConfig Role ARN
+--hub-appconfig-app-id <id>          Hub AppConfig Application ID
+--hub-appconfig-env-id <id>          Hub AppConfig Environment ID
+--hub-appconfig-profile-id <id>      Hub AppConfig Profile ID
+```
+
+**Examples:**
+
+```bash
+# Interactive mode (prompts for everything)
+sembix studio create
+
+# Specify environment name
+sembix studio create production
+
+# With repository
+sembix studio create production --repo acme/deploy
+
+# Using config file
+sembix studio create --config production.yaml
+
+# Config file with overrides
+sembix studio create --config base.yaml \
+  --env client-abc-production \
+  --aws-account-id 123456789012
+
+# Skip Hub integration (add later)
+sembix studio create production --repo acme/deploy --skip-hub
+
+# Fully automated with all flags
+sembix studio create production \
+  --repo acme/deploy \
+  --aws-account-id 123456789012 \
+  --aws-region us-east-1 \
+  --customer-role-arn arn:aws:iam::123456789012:role/Deploy \
+  --terraform-state-bucket my-tf-state \
+  --database-name sembix_studio \
+  --database-user sembix_studio_user \
+  --cloudfront-domain studio.acme.com \
+  --cloudfront-cert-arn arn:aws:acm:us-east-1:123456789012:certificate/abc \
+  --bff-alb-cert-arn arn:aws:acm:us-east-1:123456789012:certificate/def \
+  --hosted-zone-id Z1234567890ABC \
+  --github-app-client-id Iv1.0123456789abcdef \
+  --github-app-name sembix-studio-app \
+  --jira-client-id abc123def456
+```
+
+**What it does:**
+
+1. Validates repository and environment name
+2. Walks through 9 configuration steps (or uses provided config):
+   - Repository selection
+   - Basic AWS configuration
+   - Database configuration
+   - Networking (VPC, subnets)
+   - Security (security groups, IAM roles, KMS)
+   - DNS & TLS (CloudFront, ALB certificates)
+   - Feature flags (Memory, Notifications, WAF)
+   - Frontend configuration (GitHub App, Jira)
+   - **Hub integration (optional)**
+3. Creates GitHub Actions environment
+4. Sets environment variables and encrypted secrets
+5. Provides next steps for deployment
+
+### `sembix studio update`
+
+Update an existing Sembix Studio environment.
+
+**Syntax:**
+
+```bash
+sembix studio update [environment-name] [options]
+```
+
+**Options:** Same as `create` command
+
+**Examples:**
+
+```bash
+# Interactive update (re-prompts for all config)
+sembix studio update production --repo acme/deploy
+
+# Add Hub integration to existing environment
+sembix studio update production --repo acme/deploy \
+  --hub-engine-execution-role arn:aws:iam::123456789012:role/HubEngine \
+  --hub-consumer-role arn:aws:iam::123456789012:role/HubConsumer \
+  --hub-admin-role arn:aws:iam::123456789012:role/HubAdmin
+
+# Update specific fields only
+sembix studio update production --repo acme/deploy \
+  --deploy-studio-memory true \
+  --enable-bff-waf true
+
+# Update via config file
+sembix studio update --config production-updates.yaml
+
+# Update database credentials
+sembix studio update production --repo acme/deploy \
+  --database-name new_db_name \
+  --database-user new_db_user
+```
+
+**What it does:**
+
+- Validates environment exists
+- Updates only the fields you provide (partial updates)
+- Interactive mode re-collects all configuration
+- Preserves existing settings for fields not specified
+
+### `sembix studio list`
+
+List GitHub Actions environments in a repository.
+
+**Syntax:**
+
+```bash
+sembix studio list [repository] [options]
+```
+
+**Examples:**
+
+```bash
+# List all your repositories
+sembix studio list
+
+# List environments in specific repository
+sembix studio list acme-corp/sembix-deployment
+
+# With custom token
+sembix studio list acme/deploy --token ghp_custom_token
+```
+
+### `sembix studio add-hub` [DEPRECATED]
+
+**⚠️ This command is deprecated.** Use `sembix studio update` instead.
+
+Hub integration is now part of the main `create` workflow (Step 9) and can be added/updated using the `update` command.
+
+## Workflow
+
+### Complete Setup Process
+
+```
+┌─────────────────────────────────────────────────┐
+│  1. Run: sembix studio create                   │
+│     • Configure environment (Steps 1-8)         │
+│     • Optionally configure Hub (Step 9)         │
+│     • Creates GitHub environment + secrets      │
+└─────────────────────────────────────────────────┘
+                      ↓
+┌─────────────────────────────────────────────────┐
+│  2. Deploy via GitHub Actions                   │
+│     • Go to repo → Actions                      │
+│     • Run deployment workflow                   │
+│     • Copy Hub ARNs from output (if needed)     │
+└─────────────────────────────────────────────────┘
+                      ↓
+┌─────────────────────────────────────────────────┐
+│  3. Run: sembix studio update (if Hub skipped)  │
+│     • Add Hub role ARNs                         │
+│     • Add AppConfig configuration               │
+└─────────────────────────────────────────────────┘
+                      ↓
+┌─────────────────────────────────────────────────┐
+│  4. Deploy Again (with Hub integration)         │
+│     • Full Sembix Studio deployment             │
+│     • Cross-account access enabled              │
+└─────────────────────────────────────────────────┘
+```
+
+## Configuration Priority
+
+The CLI follows this priority chain for configuration values:
+
+```
+CLI Flags > Config File > Interactive Prompts > Defaults
+```
+
+**Examples:**
+
+```bash
+# Config file provides base, CLI flags override specific values
+sembix studio create --config base.yaml --env custom-name
+
+# Interactive prompts only for missing values
+sembix studio create --repo acme/deploy --aws-account-id 123456789012
+# Will prompt for all other fields
+
+# Fully automated (no prompts)
+sembix studio create --config complete.yaml
+# No prompts if config file is complete
+```
+
+## Config File Reference
+
+See [`config.example.yaml`](./config.example.yaml) for a complete, documented example.
+
+**Minimal config:**
+
+```yaml
+repository:
+  owner: acme-corp
+  repo: sembix-deployment
+
+environmentName: production
+awsAccountId: "123456789012"
+awsRegion: us-east-1
+customerRoleArn: arn:aws:iam::123456789012:role/GitHubActionsDeployRole
+terraformStateBucket: my-terraform-state-bucket
+
+database:
+  name: sembix_studio
+  user: sembix_studio_user
+
+tls:
+  cloudfrontDomain: studio.acme.com
+  cloudfrontCertArn: arn:aws:acm:us-east-1:123456789012:certificate/abc123
+  bffAlbCertificateArn: arn:aws:acm:us-east-1:123456789012:certificate/def456
+  hostedZoneId: Z1234567890ABC
+
+frontend:
+  githubAppClientId: Iv1.0123456789abcdef
+  githubAppName: sembix-studio-app
+  jiraClientId: abc123def456
+```
+
+**Complete config with all options:**
+
+```yaml
+# See config.example.yaml for:
+# - Networking configuration (VPC, subnets)
+# - Custom security groups
+# - Custom IAM roles
+# - Feature flags
+# - Hub integration
+# - All advanced options
+```
+
+## Use Cases
+
+### 1. First-Time Setup (Interactive Learning)
+
+Perfect for understanding all configuration options:
+
+```bash
+sembix studio create
+```
+
+Follow all 9 steps with detailed explanations.
+
+### 2. Rapid Iteration (Config Files)
+
+For creating multiple similar environments:
+
+```bash
+# Create base config once
+cp config.example.yaml clients/base.yaml
+# Edit base.yaml with common settings
+
+# Create client-specific environments
+sembix studio create --config clients/base.yaml --env client-abc-prod
+sembix studio create --config clients/base.yaml --env client-xyz-prod
+```
+
+### 3. CI/CD Automation
+
+For automated environment creation in pipelines:
+
+```bash
+#!/bin/bash
+CLIENT_NAME=$1
+sembix studio create "${CLIENT_NAME}-production" \
+  --config ci/base-config.yaml \
+  --token "$GITHUB_TOKEN" \
+  --aws-account-id "$CLIENT_AWS_ACCOUNT" \
+  --cloudfront-domain "studio.${CLIENT_NAME}.example.com"
+```
+
+### 4. Infrastructure as Code
+
+Version control your environment configurations:
+
+```
+configs/
+├── base.yaml              # Common settings
+├── production.yaml        # Production overrides
+├── staging.yaml           # Staging overrides
+└── development.yaml       # Dev overrides
+```
+
+```bash
+# Create from version-controlled configs
+sembix studio create --config configs/production.yaml
+sembix studio create --config configs/staging.yaml
+```
+
+### 5. Hub Integration After Deployment
+
+Add Hub configuration after initial deployment:
+
+```bash
+# Step 1: Create without Hub
+sembix studio create production --repo acme/deploy --skip-hub
+
+# Step 2: Deploy and get Hub ARNs
+
+# Step 3: Add Hub integration
+sembix studio update production --repo acme/deploy \
+  --hub-engine-execution-role arn:aws:iam::123456789012:role/HubEngine \
+  --hub-consumer-role arn:aws:iam::123456789012:role/HubConsumer \
+  --hub-admin-role arn:aws:iam::123456789012:role/HubAdmin
+```
+
+## Development
+
+### Project Structure
+
+```
+sembix-cli/
+├── src/
+│   ├── commands/              # Command implementations
+│   │   ├── setup.ts           # Environment create command
+│   │   ├── update.ts          # Environment update command
+│   │   └── hub-integration.ts # Deprecated hub command
+│   ├── prompts/               # Interactive prompts
+│   │   ├── environment-setup.ts     # Main setup prompts
+│   │   ├── hub-integration-step.ts  # Hub integration prompts
+│   │   └── hub-integration.ts       # Deprecated hub prompts
+│   ├── utils/                 # Utility modules
+│   │   ├── github.ts          # GitHub API client
+│   │   ├── ui.ts              # Terminal UI utilities
+│   │   └── config-loader.ts   # Config file loading & merging
+│   ├── types.ts               # TypeScript types
+│   ├── config-schema.ts       # Zod schemas for config validation
+│   ├── config.ts              # Configuration management
+│   └── index.ts               # CLI entry point
+├── config.example.yaml        # Example config file
+├── package.json
+├── tsconfig.json
+├── .env.example
+└── README.md
+```
+
+### Scripts
+
+```bash
+npm run build       # Compile TypeScript to JavaScript
+npm run dev         # Run in development mode with tsx
+npm run type-check  # Type check without emitting files
+```
+
+### Adding New Commands
+
+1. Create a new file in `src/commands/`
+2. Implement the command logic
+3. Add prompts in `src/prompts/` if needed
+4. Register the command in `src/index.ts`
+
+Example:
+
+```typescript
+// src/commands/my-command.ts
+export async function myCommand(githubToken: string, options: Record<string, any>): Promise<void> {
+  // Command implementation
+}
+
+// src/index.ts
+studio
+  .command('my-command')
+  .description('Description of my command')
+  .option('-r, --repo <repo>', 'Target repository')
+  .action(async (options) => {
+    const { myCommand } = await import('./commands/my-command.js');
+    await myCommand(config.githubToken, options);
+  });
+```
+
+## Troubleshooting
+
+### "GITHUB_TOKEN environment variable is required"
+
+Make sure you have a `.env` file in the project root directory with your token:
+
+```env
+GITHUB_TOKEN=ghp_your_token_here
+```
+
+Or pass the token via CLI:
+
+```bash
+sembix studio create --token ghp_your_token_here
+```
+
+### "Failed to create environment: Bad credentials"
+
+Your GitHub token may be invalid or missing required scopes. Create a new token with `repo` and `workflow` scopes.
+
+### "Failed to encrypt secret"
+
+The `libsodium-wrappers` library is required for encrypting GitHub secrets. Make sure dependencies are installed:
+
+```bash
+npm install
+```
+
+### "No repositories found"
+
+Make sure your GitHub token has access to the repositories you want to manage. Check the token's permissions and organization access.
+
+### "Invalid YAML syntax"
+
+When using config files, validate your YAML syntax:
+
+```bash
+# Use a YAML validator
+npm install -g js-yaml
+js-yaml config.yaml
+```
+
+### "Environment already exists"
+
+Use the `update` command instead of `create`:
+
+```bash
+sembix studio update production --repo acme/deploy
+```
+
+Or delete the environment in GitHub and recreate it.
+
+## Advanced Topics
+
+### Partial Updates
+
+The `update` command supports partial updates - only provide the flags you want to change:
+
+```bash
+# Only update feature flags
+sembix studio update prod --repo acme/deploy \
+  --deploy-studio-memory true \
+  --enable-bff-waf false
+
+# Only update Hub integration
+sembix studio update prod --repo acme/deploy \
+  --hub-consumer-role arn:aws:iam::123456789012:role/NewConsumer
+```
+
+### Config File Inheritance
+
+Create a base config and override specific values:
+
+```bash
+# base.yaml has common settings
+# production.yaml imports and overrides
+
+sembix studio create --config base.yaml --config production.yaml
+# (Note: Multiple --config flags not yet supported, use CLI flags for overrides)
+
+# Current approach:
+sembix studio create --config base.yaml \
+  --env production \
+  --cloudfront-domain studio.prod.acme.com
+```
+
+### Batch Operations
+
+Create multiple environments with a script:
+
+```bash
+#!/bin/bash
+for CLIENT in client-a client-b client-c; do
+  sembix studio create "${CLIENT}-production" \
+    --config base.yaml \
+    --cloudfront-domain "studio.${CLIENT}.example.com" \
+    --aws-account-id "${CLIENT_AWS_ACCOUNTS[$CLIENT]}"
+done
+```
+
+## License
+
+Proprietary - Sembix AI
+
+## Support
+
+For issues or questions, contact the Sembix team or open an issue in the repository.
+
+## See Also
+
+- [QUICKSTART.md](./QUICKSTART.md) - 5-minute quick start guide
+- [USAGE-EXAMPLES.md](./USAGE-EXAMPLES.md) - Real-world usage examples
+- [COMMANDS.md](./COMMANDS.md) - Detailed command reference
+- [config.example.yaml](./config.example.yaml) - Complete config file example