@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/providers/tcb/cli/hosting.md

@@ -0,0 +1,219 @@
+# TCB CLI: Hosting Management
+
+## When to Use Hosting Commands
+
+| Goal | Command | Notes |
+|------|---------|-------|
+| Deploy static site | `tcb hosting deploy` | Main command |
+| List hosting projects | `tcb hosting list` | View current deployments |
+| Get hosting details | `tcb hosting detail` | See config and URLs |
+| Add custom domain | `tcb hosting domain add` | HTTPS auto-provisioned |
+| Delete hosting | `tcb hosting delete` | Removes all deployed files |
+
+## Decision Tree for Hosting Operations
+
+```
+Need to deploy static content?
+├── Deploy to shared env → deploy_stack --preview --provider tcb
+├── Deploy to personal dev → tcb hosting deploy
+├── Add custom domain → tcb hosting domain add
+└── Delete deployment → tcb hosting delete (dev only)
+```
+
+## Deploy Static Site
+
+### Basic Deployment
+
+```bash
+tcb hosting deploy --env $TCB_ENV_ID --dir ./dist
+```
+
+### With Build Environment Variables
+
+```bash
+tcb hosting deploy \
+  --env $TCB_ENV_ID \
+  --dir ./dist \
+  --build-env BACKEND_URL=$STACK_URL \
+  --build-env API_KEY=$API_KEY
+```
+
+### With Configuration File
+
+```json
+// cloudbaserc.json
+{
+  "hosting": {
+    "dev": {
+      "cloudPath": "./dist",
+      "envId": "env-xxxxx",
+      "ignore": ["*.map", "node_modules/**"]
+    }
+  }
+}
+```
+
+```bash
+tcb hosting deploy --env dev
+```
+
+### Deployment Options
+
+| Option | Description |
+|--------|-------------|
+| `--env <envId>` | Target environment |
+| `--dir <path>` | Local directory to deploy |
+| `--build-env <key=value>` | Environment variables for build |
+| `--force` | Overwrite existing files |
+| `--yes` | Skip confirmation |
+
+## List Hosting Projects
+
+```bash
+tcb hosting list --env $TCB_ENV_ID
+```
+
+Output:
+```
+┌──────────────┬────────────────────────────┬──────────────┐
+│ Environment  │ URL                        │ Status       │
+├──────────────┼────────────────────────────┼──────────────┤
+│ env-xxxxx    │ https://env-xxxxx.tcb-preview.com │ deployed │
+└──────────────┴────────────────────────────┴──────────────┘
+```
+
+## Get Hosting Details
+
+```bash
+tcb hosting detail --env $TCB_ENV_ID
+```
+
+Shows:
+- Current URL
+- Custom domains
+- Last deployment time
+- File count
+- Storage used
+
+## Add Custom Domain
+
+### Step 1: Add Domain
+
+```bash
+tcb hosting domain add --domain example.com --env $TCB_ENV_ID
+```
+
+Output shows DNS records to add:
+```
+Please add the following DNS record:
+Type: CNAME
+Name: example.com
+Value: env-xxxxx.tcb-ext.com
+```
+
+### Step 2: Configure DNS
+
+Add CNAME record in your DNS provider:
+```
+Type: CNAME
+Host: example.com
+Value: env-xxxxx.tcb-ext.com
+TTL: 600
+```
+
+### Step 3: Wait for SSL
+
+SSL certificate auto-provisions via Let's Encrypt (1-5 minutes).
+
+### Verify Domain
+
+```bash
+tcb hosting domain list --env $TCB_ENV_ID
+```
+
+### Domain HTTPS
+
+- Certificate auto-provisioned
+- Supports custom ports (443 only for HTTPS)
+- Redirect from HTTP to HTTPS automatic
+
+## Delete Hosting
+
+```bash
+tcb hosting delete --env $TCB_ENV_ID
+```
+
+**Warning:** Deletes all deployed files. Cannot be undone.
+
+## URL Patterns
+
+| Environment | URL Pattern |
+|-------------|-------------|
+| Preview | `https://{env-id}.tcb-preview.com` |
+| Custom Domain | `https://{your-domain.com}` |
+| Staging | `https://{env-id}.tcb-preview.com` |
+| Production | `https://{env-id}.tcb-ext.com` or custom domain |
+
+## Agent Workflows
+
+### Workflow: Deploy Web App with Backend URL
+
+```bash
+# 1. Get backend URL from stack
+export STACK_URL=$(deploy_stack --preview --provider tcb --output url)
+
+# 2. Deploy web with backend URL injected
+tcb hosting deploy \
+  --env $TCB_ENV_ID \
+  --dir ./dist \
+  --build-env BACKEND_URL=$STACK_URL
+
+# 3. Get web URL
+export WEB_URL=$(deploy_stack --preview --provider tcb --output web_url)
+
+# 4. Run e2e tests
+pytest apps/web/tests/e2e/ --base-url $WEB_URL --api-url $BACKEND_URL
+```
+
+### Workflow: Deploy with Cache Busting
+
+```bash
+# Deploy with --force to ensure all files uploaded
+tcb hosting deploy --env $TCB_ENV_ID --dir ./dist --force
+
+# Or use content-hashed filenames (handled by build tools like Vite)
+```
+
+### Workflow: Debug Deployment
+
+```bash
+# 1. Check hosting status
+tcb hosting detail --env $TCB_ENV_ID
+
+# 2. List deployed files
+tcb storage list --path /hosting --env $TCB_ENV_ID
+
+# 3. Verify index.html exists
+tcb storage list --path /hosting/index.html --env $TCB_ENV_ID
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `No index.html found` | Directory doesn't contain index.html | Ensure correct `--dir` path |
+| `Deployment failed` | Build error | Check build output for errors |
+| `404 on routes` | SPA routing not working | Should work automatically, check CDN |
+| `Stale content` | Cache not cleared | Deploy with `--force` |
+| `Domain not working` | DNS not propagated | Wait 5-10 min, verify CNAME |
+| `SSL not ready` | Certificate provisioning | Wait 1-5 minutes |
+
+### SPA Routing Issue
+
+CloudBase Hosting automatically handles SPA routing (rewrites 404 to index.html). If routes return 404:
+
+1. Verify `index.html` exists in deployed files
+2. Check CDN cache (deploy with `--force`)
+3. Verify your build tool outputs correct paths
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/tcb/cli/setup.md

@@ -0,0 +1,218 @@
+# TCB CLI Setup & Authentication
+
+## When to Use CLI vs MCP vs SDK
+
+**Use CLI when:**
+- Deploying functions, databases, hosting from CI/CD
+- Running one-off administrative tasks
+- Scripting cloud operations
+- Initial setup and configuration
+
+**Use MCP when:**
+- AI agent needs structured, composable tools
+- Need to chain multiple operations
+- Want type-safe parameter handling
+
+**Use SDK when:**
+- Building applications that interact with TCB
+- Need programmatic access from within functions
+- Complex business logic involving TCB services
+
+## Installation
+
+### Prerequisites
+
+- Node.js 16.x or later
+- npm or yarn
+
+### Install CloudBase CLI
+
+```bash
+npm install -g @cloudbase/cli
+```
+
+Verify installation:
+
+```bash
+tcb --version
+```
+
+### Update CLI
+
+```bash
+npm install -g @cloudbase/cli@latest
+```
+
+## Authentication Methods
+
+### Method 1: Interactive Login (Recommended for local dev)
+
+```bash
+tcb login
+```
+
+Opens browser for Tencent Cloud login. Session stored locally.
+
+**Pros:** No credentials stored in plain text
+**Cons:** Not suitable for CI/CD
+
+### Method 2: API Key Authentication (Recommended for CI/CD)
+
+```bash
+# Set environment variables
+export TENCENTCLOUD_SECRETID=your-secret-id
+export TENCENTCLOUD_SECRETKEY=your-secret-key
+
+# Or use TCB-specific credentials
+export TCB_SECRET_ID=your-secret-id
+export TCB_SECRET_KEY=your-secret-key
+```
+
+### Method 3: Configuration File
+
+Store credentials in `~/.tcbrc` (not recommended for production):
+
+```json
+{
+  "secretId": "your-secret-id",
+  "secretKey": "your-secret-key"
+}
+```
+
+### Method 4: Temporary Credentials via CDH
+
+```bash
+cdh cloudbase init --secret-id xxx --secret-key xxx
+```
+
+This stores credentials in `~/.cloud-harness-tokens.json` and auto-configures MCP.
+
+## Credential Selection Decision Tree
+
+```
+Need to run TCB commands?
+├── Local development
+│   └── tcb login (interactive)
+├── CI/CD pipeline
+│   ├── Use environment variables (TCB_SECRET_ID/KEY)
+│   └── Never commit credentials to git
+├── AI Agent (CDH)
+│   └── cdh cloudbase init (stores in ~/.cloud-harness-tokens.json)
+└── From within a function
+    └── Environment variables (injected by TCB)
+```
+
+## Verifying Authentication
+
+### Check Login Status
+
+```bash
+tcb env info
+```
+
+If authenticated, shows current environment info. If not, shows login prompt.
+
+### Check MCP Status (CDH)
+
+```bash
+cdh cloudbase status
+```
+
+Shows MCP server connection status and credential validity.
+
+## Environment Variables Reference
+
+| Variable | Description | Source |
+|----------|-------------|--------|
+| `TENCENTCLOUD_SECRETID` | Tencent Cloud root credential ID | Manual or `cdh cloudbase init` |
+| `TENCENTCLOUD_SECRETKEY` | Tencent Cloud root credential key | Manual or `cdh cloudbase init` |
+| `TCB_SECRET_ID` | TCB-specific credential ID | Manual or `cdh cloudbase init` |
+| `TCB_SECRET_KEY` | TCB-specific credential key | Manual or `cdh cloudbase init` |
+| `TCB_ENV_ID` | Target environment ID | Manual or `cdh cloudbase init` |
+
+## Project-Level Configuration
+
+For project-specific settings, create `cloudbaserc.json` in project root:
+
+```json
+{
+  "envId": "env-xxxxx",
+  "$schema": "https://raw.githubusercontent.com/TencentCloudBase/tcb-schema/main/schema.json",
+  "region": "ap-shanghai"
+}
+```
+
+### Environment-Specific Config
+
+```json
+{
+  "envId": "${TCB_ENV_ID}",
+  "region": "ap-shanghai",
+  "functionRoot": "./functions",
+  "functions": [
+    {
+      "name": "hello",
+      "timeout": 10,
+      "memory": 256
+    }
+  ],
+  "hosting": {
+    "dev": {
+      "cloudPath": "./dist",
+      "envId": "env-dev"
+    }
+  }
+}
+```
+
+## CLI Configuration
+
+### Set Default Region
+
+```bash
+tcb configure set region ap-shanghai
+```
+
+### Set Default Environment
+
+```bash
+tcb configure set envId env-xxxxx
+```
+
+### View Current Config
+
+```bash
+tcb configure list
+```
+
+## Security Best Practices
+
+1. **Never commit credentials** - Add `*.json` with credentials to `.gitignore`
+2. **Use environment variables in CI/CD** - Don't hardcode secrets
+3. **Rotate credentials regularly** - Use TCB_SECRET_ID/KEY instead of root credentials
+4. **Use least privilege** - Create dedicated API keys with minimal permissions
+5. **Don't use root credentials** - TCB-specific credentials are preferred
+
+### .gitignore Example
+
+```
+# TCB credentials
+cloudbaserc.json
+!.cloudbaserc.*.json
+.tcbrc
+
+# CDH tokens
+.cloud-harness-tokens.json
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| ` command not found: tcb` | CLI not installed | `npm install -g @cloudbase/cli` |
+| `Login required` | Not authenticated | `tcb login` or set env vars |
+| `Invalid credentials` | Wrong secret ID/key | Verify credentials in TCB console |
+| `Permission denied` | Insufficient permissions | Check API key permissions in TCB console |
+| `envId not found` | Wrong environment ID | `tcb env list` to see valid environments |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/tcb/cli/storage.md

@@ -0,0 +1,233 @@
+# TCB CLI: Storage Management
+
+## When to Use Storage Commands
+
+| Goal | Command | Notes |
+|------|---------|-------|
+| List files | `tcb storage list` | Path is case-sensitive |
+| Upload file | `tcb storage upload` | Max 50GB per file |
+| Download file | `tcb storage download` | From COS to local |
+| Delete file | `tcb storage delete` | Permanent deletion |
+| Get file URL | `tcb storage url` | Signed URL for private files |
+
+## Decision Tree for Storage Operations
+
+```
+Need to work with files?
+├── Upload user content → tcb storage upload
+├── Download backup/file → tcb storage download
+├── List directory → tcb storage list
+├── Delete old files → tcb storage delete
+├── Get public URL → tcb storage url
+└── Large file upload → Use server-side upload flow (see services/cloud-storage.md)
+```
+
+## List Files
+
+```bash
+tcb storage list --path /uploads --env $TCB_ENV_ID
+```
+
+Output:
+```
+┌────────────────────────────────┬──────────────┬──────────────────┐
+│ Path                           │ Size         │ Last Modified    │
+├────────────────────────────────┼──────────────┼──────────────────┤
+│ /uploads/avatar.jpg            │ 125 KB       │ 2024-01-15 10:30 │
+│ /uploads/doc.pdf               │ 2.3 MB       │ 2024-01-14 15:22 │
+│ /uploads/image.png             │ 450 KB       │ 2024-01-13 09:45 │
+└────────────────────────────────┴──────────────┴──────────────────┘
+```
+
+### List with Pagination
+
+```bash
+tcb storage list --path /uploads --num 20 --marker <next-token> --env $TCB_ENV_ID
+```
+
+### List Subdirectory
+
+```bash
+tcb storage list --path /uploads/2024/01 --env $TCB_ENV_ID
+```
+
+## Upload File
+
+### Basic Upload
+
+```bash
+tcb storage upload --local ./avatar.jpg --remote /uploads/avatar.jpg --env $TCB_ENV_ID
+```
+
+### With Content-Type
+
+```bash
+tcb storage upload \
+  --local ./document.pdf \
+  --remote /documents/report.pdf \
+  --content-type application/pdf \
+  --env $TCB_ENV_ID
+```
+
+### Upload with Progress
+
+```bash
+tcb storage upload \
+  --local ./large-file.zip \
+  --remote /backups/large-file.zip \
+  --env $TCB_ENV_ID
+# Shows progress bar
+```
+
+### Upload Options
+
+| Option | Description |
+|--------|-------------|
+| `--local <path>` | Local file path |
+| `--remote <path>` | Remote COS path |
+| `--content-type <type>` | MIME type (auto-detected if not specified) |
+| `--env <envId>` | Target environment |
+
+## Download File
+
+### Basic Download
+
+```bash
+tcb storage download --local ./download.jpg --remote /uploads/avatar.jpg --env $TCB_ENV_ID
+```
+
+### Download with Progress
+
+```bash
+tcb storage download \
+  --local ./backup.zip \
+  --remote /backups/latest.zip \
+  --env $TCB_ENV_ID
+```
+
+## Delete File
+
+### Delete Single File
+
+```bash
+tcb storage delete --remote /uploads/old-file.jpg --env $TCB_ENV_ID
+```
+
+### Delete Multiple Files
+
+```bash
+# Delete specific files
+tcb storage delete --remote /uploads/file1.jpg --env $TCB_ENV_ID
+tcb storage delete --remote /uploads/file2.jpg --env $TCB_ENV_ID
+
+# Or use pattern (via function)
+# Call function to delete files matching pattern
+```
+
+### Delete Folder Contents
+
+```bash
+# List first to verify
+tcb storage list --path /temp --env $TCB_ENV_ID
+
+# Delete each file
+for f in $(tcb storage list --path /temp --env $TCB_ENV_ID | grep -o '/temp/[^ ]*'); do
+  tcb storage delete --remote "$f" --env $TCB_ENV_ID
+done
+```
+
+## Get File URL
+
+### Get Signed URL (Private Files)
+
+```bash
+tcb storage url --remote /uploads/private.pdf --env $TCB_ENV_ID
+```
+
+Returns a signed URL valid for 1 hour.
+
+### Get URL with Custom Expiry
+
+```bash
+tcb storage url --remote /uploads/doc.pdf --expiry 3600 --env $TCB_ENV_ID
+```
+
+### URL Types
+
+| File Type | URL Type | Access |
+|-----------|----------|--------|
+| Public assets | Direct URL | Anyone with link |
+| Private files | Signed URL | Valid for expiry period |
+
+## Create/Delete Folder
+
+### Create Folder
+
+```bash
+tcb storage createFolder --path /uploads/2024 --env $TCB_ENV_ID
+```
+
+**Note:** In COS, "folders" are just empty objects with `/` suffix.
+
+### Delete Empty Folder
+
+```bash
+tcb storage deleteFolder --path /uploads/2024 --env $TCB_ENV_ID
+```
+
+**Note:** Folder must be empty.
+
+## Agent Workflows
+
+### Workflow: Upload User Avatar
+
+```bash
+# 1. Upload file
+tcb storage upload \
+  --local ./temp_avatar.jpg \
+  --remote /avatars/${userId}/avatar.jpg \
+  --env $TCB_ENV_ID
+
+# 2. Get public URL (if public bucket)
+tcb storage url --remote /avatars/${userId}/avatar.jpg --env $TCB_ENV_ID
+
+# 3. Return URL to frontend
+```
+
+### Workflow: Backup Database
+
+```bash
+# 1. Export database
+tcb db export --collection users --file ./backup/users.json --env $TCB_ENV_ID
+
+# 2. Upload to storage
+tcb storage upload \
+  --local ./backup/users.json \
+  --remote /backups/users_$(date +%Y%m%d).json \
+  --env $TCB_ENV_ID
+
+# 3. Cleanup local file
+rm ./backup/users.json
+```
+
+### Workflow: Cleanup Old Files
+
+```bash
+# 1. List files older than 30 days
+# (COS doesn't have native date filter, so list and filter in function)
+
+# 2. Delete old temp files
+tcb fn invoke --name cleanup-temp-files --params '{}' --env $TCB_ENV_ID
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `File not found` | Wrong path | Check path is case-sensitive |
+| `Upload failed` | File too large | Use server-side upload flow |
+| `Permission denied` | No write access | Check environment permissions |
+| `Invalid path` | Path format wrong | Use `/folder/file.jpg` format |
+| `Download failed` | File doesn't exist | Verify with `tcb storage list` |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`