decoupled-cli 2.0.0

package/README.md

@@ -0,0 +1,416 @@
+# DrupalCloud CLI (decoupled-cli)
+
+A command-line interface for managing DrupalCloud spaces, monitoring usage, and interacting with the DrupalCloud API using personal access tokens.
+
+## Installation
+
+```bash
+npm install -g decoupled-cli
+```
+
+## Authentication
+
+### Initial Setup
+
+Before using the CLI, you need to authenticate with your DrupalCloud personal access token:
+
+```bash
+decoupled-cli auth login
+```
+
+This will:
+1. Open your browser to the DrupalCloud authentication page
+2. Allow you to sign in and create a personal access token
+3. Display the token for you to copy
+4. Prompt you to paste the token in the CLI
+
+Alternatively, you can use manual token entry:
+
+```bash
+decoupled-cli auth login --manual
+```
+
+This will prompt you for:
+- **API Base URL**: Your DrupalCloud instance URL (e.g., `https://app.drupalcloud.com` or `http://localhost:3333`)
+- **Personal Access Token**: Your personal access token (format: `dc_tok_...`)
+
+The CLI will verify the token and store the credentials securely in your system keychain or config directory.
+
+### Token Management
+
+```bash
+# View current authentication status
+decoupled-cli auth status
+
+# Switch to a different token/instance
+decoupled-cli auth login --url https://staging.drupalcloud.com
+
+# Logout (remove stored credentials)
+decoupled-cli auth logout
+
+# Test authentication
+decoupled-cli auth test
+```
+
+**Note**: Token creation and management must be done through the web interface at `/organization/tokens` for security reasons.
+
+### Configuration
+
+The CLI stores configuration in `~/.decoupled-cli/config.json`:
+
+```json
+{
+  "currentProfile": "default",
+  "profiles": {
+    "default": {
+      "baseUrl": "https://app.drupalcloud.com",
+      "tokenHash": "sha256_hash_of_token"
+    },
+    "staging": {
+      "baseUrl": "https://staging.drupalcloud.com",
+      "tokenHash": "sha256_hash_of_token"
+    }
+  }
+}
+```
+
+Actual tokens are stored securely using the system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
+
+## Commands
+
+### Spaces Management
+
+#### List Spaces
+```bash
+# List all spaces
+decoupled-cli spaces list
+
+# List with additional details
+decoupled-cli spaces list --detailed
+
+# Filter by status
+decoupled-cli spaces list --status active
+decoupled-cli spaces list --status creating
+decoupled-cli spaces list --archived
+
+# Output as JSON
+decoupled-cli spaces list --json
+```
+
+#### Get Space Details
+```bash
+# Get space by ID
+decoupled-cli spaces get 123
+
+# Get space by name
+decoupled-cli spaces get my-space-name
+
+# Output as JSON
+decoupled-cli spaces get 123 --json
+```
+
+#### Create Space
+```bash
+# Create a new space
+decoupled-cli spaces create "My New Space" --type pro --template dcloud
+
+# Available templates: drupal, drupalx, next-drupal, drupalx-decoupled, dcloud
+# Available types: starter, pro, premium
+
+# With all options
+decoupled-cli spaces create "E-commerce Site" \
+  --type premium \
+  --template drupalx-decoupled \
+  --description "New e-commerce platform"
+```
+
+#### Update Space
+```bash
+# Update space name
+decoupled-cli spaces update 123 --name "Updated Space Name"
+
+# Update space type
+decoupled-cli spaces update 123 --type premium
+```
+
+#### Clone Space
+```bash
+# Clone a space
+decoupled-cli spaces clone 123 --name "Cloned Space"
+
+# Clone with different type
+decoupled-cli spaces clone 123 --name "Development Copy" --type starter
+```
+
+#### Archive/Unarchive Space
+```bash
+# Archive a space
+decoupled-cli spaces archive 123
+
+# Unarchive a space
+decoupled-cli spaces unarchive 123
+```
+
+#### Delete Space
+```bash
+# Delete a space (with confirmation)
+decoupled-cli spaces delete 123
+
+# Force delete without confirmation
+decoupled-cli spaces delete 123 --force
+```
+
+#### Space Operations
+```bash
+# Get Drupal one-time login link
+decoupled-cli spaces login 123
+
+# Check if space is ready
+decoupled-cli spaces status 123
+
+# Retry space creation (if failed)
+decoupled-cli spaces retry 123
+
+# Refresh space usage data
+decoupled-cli spaces refresh-usage 123
+```
+
+### Usage Monitoring
+
+#### Organization Usage
+```bash
+# Get overall organization usage
+decoupled-cli usage
+
+# Get usage with space breakdown
+decoupled-cli usage --breakdown
+
+# Output as JSON
+decoupled-cli usage --json
+
+# Get usage for specific date range
+decoupled-cli usage --from 2025-01-01 --to 2025-01-31
+```
+
+#### Space-specific Usage
+```bash
+# Get usage for a specific space
+decoupled-cli usage space 123
+
+# Get usage history
+decoupled-cli usage space 123 --history
+
+# Export usage data
+decoupled-cli usage export --format csv --output usage-report.csv
+decoupled-cli usage export --format json --output usage-report.json
+```
+
+### Token Management
+
+**Token management is not available through the CLI for security reasons.**
+
+To create, update, or delete tokens:
+1. Visit the web interface at `/organization/tokens`
+2. Sign in with your account credentials
+3. Use the token management interface
+
+This ensures tokens can only be managed through secure, authenticated web sessions.
+
+### Organization Management
+
+#### Organization Info
+```bash
+# Get organization details
+decoupled-cli org info
+
+# Get organization members
+decoupled-cli org members
+
+# Get security settings
+decoupled-cli org security
+```
+
+#### User Management
+```bash
+# List organization users
+decoupled-cli users list
+
+# Invite new user
+decoupled-cli users invite user@example.com --role developer
+
+# Update user role
+decoupled-cli users update 789 --role admin
+
+# Available roles: owner, admin, developer, member
+```
+
+### Utility Commands
+
+#### Health Check
+```bash
+# Check API connectivity
+decoupled-cli health
+
+# Verbose health check
+decoupled-cli health --verbose
+```
+
+#### Configuration
+```bash
+# Show current configuration
+decoupled-cli config show
+
+# Set configuration values
+decoupled-cli config set output json
+decoupled-cli config set timeout 30
+
+# Reset configuration to defaults (with confirmation)
+decoupled-cli config reset
+
+# Reset configuration to defaults (skip confirmation)
+decoupled-cli config reset --confirm
+
+# Available settings:
+# - output: table, json, yaml
+# - timeout: API request timeout in seconds
+# - color: true, false (enable/disable colored output)
+```
+
+### Global Options
+
+All commands support these global options:
+
+```bash
+--profile <name>    # Use specific profile instead of default
+--json             # Output response as JSON
+--quiet            # Suppress non-essential output
+--verbose          # Show detailed output and debug information
+--no-color         # Disable colored output
+--timeout <seconds> # Override default request timeout
+```
+
+## Examples
+
+### Daily Workflows
+
+```bash
+# Check overall status
+decoupled-cli usage && decoupled-cli spaces list --status creating
+
+# Create a development environment
+decoupled-cli spaces create "Feature Branch Test" --type starter --template drupal
+
+# Get login link for debugging
+decoupled-cli spaces login 123
+
+# Monitor space creation
+watch decoupled-cli spaces status 123
+
+# Export monthly usage report
+decoupled-cli usage export --format csv --from 2025-01-01 --to 2025-01-31
+```
+
+### CI/CD Integration
+
+```bash
+# Create a dedicated CI token through the web interface at /organization/tokens
+# Then use it in CI scripts:
+export DECOUPLED_TOKEN="dc_tok_..."
+decoupled-cli spaces create "PR-${PR_NUMBER}" --template drupal --type starter
+SPACE_ID=$(decoupled-cli spaces list --json | jq -r '.spaces[] | select(.name=="PR-'${PR_NUMBER}'") | .id')
+decoupled-cli spaces status $SPACE_ID
+```
+
+### Monitoring Scripts
+
+```bash
+# Check for spaces stuck in 'creating' status
+decoupled-cli spaces list --status creating --json | jq -r '.spaces[] | select((.createdAt | fromnow) > 3600) | .name'
+
+# Get usage alerts
+decoupled-cli usage --json | jq -r 'select(.usagePercentages.storage > 80) | "Storage usage: " + (.usagePercentages.storage | tostring) + "%"'
+```
+
+## Error Handling
+
+The CLI returns appropriate exit codes:
+- `0`: Success
+- `1`: General error
+- `2`: Authentication error
+- `3`: Permission error
+- `4`: Not found error
+- `5`: Validation error
+
+## Environment Variables
+
+- `DECOUPLED_TOKEN`: Override stored token (useful for CI/CD)
+- `DECOUPLED_BASE_URL`: Override base URL
+- `DECOUPLED_PROFILE`: Use specific profile
+- `DECOUPLED_TIMEOUT`: Request timeout in seconds
+- `DECOUPLED_NO_COLOR`: Disable colored output
+
+## Security
+
+- Tokens are stored securely using the system keychain
+- Sensitive data is never logged or displayed in plain text
+- API requests use HTTPS with proper authentication headers
+- Token permissions are validated on each request
+
+## Troubleshooting
+
+### Common Issues
+
+```bash
+# Token authentication failed
+decoupled-cli auth test
+decoupled-cli auth login
+
+# API connectivity issues
+decoupled-cli health --verbose
+
+# Permission denied
+decoupled-cli tokens list  # Check your token permissions
+
+# Timeout errors
+decoupled-cli config set timeout 60
+```
+
+### Debug Mode
+
+```bash
+# Enable debug output
+decoupled-cli --verbose spaces list
+
+# Check configuration
+decoupled-cli config show
+
+# Test token permissions
+decoupled-cli auth test --permissions
+```
+
+## API Integration
+
+The CLI directly uses the DrupalCloud API with these endpoints:
+
+- `GET /api/spaces` - List spaces
+- `POST /api/spaces` - Create space
+- `GET /api/spaces/{id}` - Get space details
+- `PATCH /api/spaces/{id}` - Update space
+- `DELETE /api/spaces/{id}` - Delete space
+- `POST /api/spaces/{id}/clone` - Clone space
+- `POST /api/spaces/{id}/archive` - Archive space
+- `POST /api/spaces/{id}/unarchive` - Unarchive space
+- `GET /api/usage` - Get usage data
+- Token management endpoints (web interface only)
+
+## Contributing
+
+The CLI is built with:
+- Node.js/TypeScript
+- Commander.js for CLI framework
+- Axios for HTTP requests
+- Keytar for secure credential storage
+- Chalk for colored output
+- CLI-table3 for formatted tables
+
+For development and contribution guidelines, see the CLI repository.

package/bin/decoupled-cli

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/index.js');

package/dist/commands/auth.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const authCommand: Command;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2JpC,eAAO,MAAM,WAAW,SACmB,CAAC"}