@scemoon/cdh 1.0.8 → 1.0.9-beta.2

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

@@ -0,0 +1,230 @@
+# TCB CLI: Database Management
+
+## When to Use Database Commands
+
+| Goal | Command | Notes |
+|------|---------|-------|
+| List collections | `tcb db list` | DocDB only |
+| Query documents | `tcb db query` | DocDB (Mongoose-like syntax) |
+| Run migrations | `tcb db migrate` | SQL migrations (MySQL) |
+| Import data | `tcb db import` | JSON import to DocDB |
+| Export data | `tcb db export` | DocDB to JSON |
+
+## Decision Tree for Database Operations
+
+```
+Need to work with database?
+├── DocDB (NoSQL)
+│   ├── List collections → tcb db list
+│   ├── Query data → tcb db query
+│   ├── Import/Export → tcb db import/export
+│   └── Complex operations → Use SDK or REST API
+├── MySQL (RDBMS)
+│   ├── Run migrations → tcb db migrate
+│   ├── Admin queries → tcb db query (use carefully)
+│   └── Application queries → MySQL client in functions
+└── Schema changes → Migration files (see ci-cd.md)
+```
+
+## DocDB Operations
+
+### List Collections
+
+```bash
+tcb db list --env $TCB_ENV_ID
+```
+
+Output:
+```
+┌─────────────────┬────────────┬──────────────────┐
+│ Collection      │ Documents  │ Indexes          │
+├─────────────────┼────────────┼──────────────────┤
+│ users           │ 1,234      │ 2                │
+│ orders          │ 5,678      │ 3                │
+│ products        │ 890        │ 1                │
+└─────────────────┴────────────┴──────────────────┘
+```
+
+### Query Documents
+
+```bash
+tcb db query "SELECT * FROM users WHERE status = 'active'" --env $TCB_ENV_ID
+```
+
+#### Query Syntax Reference
+
+| SQL-like | Description |
+|----------|-------------|
+| `SELECT * FROM collection` | Get all documents |
+| `WHERE field = 'value'` | Equality filter |
+| `WHERE field > 10` | Comparison |
+| `WHERE field IN ('a','b')` | In list |
+| `WHERE field LIKE '%pattern%'` | Regex ( DocDB uses `LIKE` with regex) |
+| `ORDER BY field ASC/DESC` | Sort |
+| `LIMIT n SKIP m` | Pagination |
+| `SELECT field1, field2` | Project specific fields |
+
+#### Query Examples
+
+```bash
+# Simple query
+tcb db query "SELECT * FROM users" --env $TCB_ENV_ID
+
+# With filter
+tcb db query "SELECT * FROM users WHERE status = 'active'" --env $TCB_ENV_ID
+
+# With comparison
+tcb db query "SELECT * FROM orders WHERE amount > 100" --env $TCB_ENV_ID
+
+# With pagination
+tcb db query "SELECT * FROM users LIMIT 20 SKIP 40" --env $TCB_ENV_ID
+
+# Ordered
+tcb db query "SELECT * FROM users ORDER BY createdAt DESC" --env $TCB_ENV_ID
+```
+
+### Import Data
+
+```bash
+tcb db import --collection users --file ./users.json --env $TCB_ENV_ID
+```
+
+Format: JSON array of documents
+
+```json
+[
+  { "name": "Alice", "email": "alice@example.com" },
+  { "name": "Bob", "email": "bob@example.com" }
+]
+```
+
+### Export Data
+
+```bash
+tcb db export --collection users --file ./backup.json --env $TCB_ENV_ID
+```
+
+## MySQL Operations
+
+### Run Migrations
+
+```bash
+tcb db migrate --env $TCB_ENV_ID
+```
+
+Migrations run SQL files in `migrations/` directory.
+
+### Migration File Structure
+
+```
+migrations/
+├── 001_create_users.sql
+├── 002_add_index.sql
+└── 003_alter_orders.sql
+```
+
+### Migration File Example
+
+```sql
+-- migrations/001_create_users.sql
+
+-- UP migration
+CREATE TABLE IF NOT EXISTS users (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  openid VARCHAR(64) UNIQUE NOT NULL,
+  nickname VARCHAR(128),
+  status TINYINT DEFAULT 1,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- DOWN migration (for rollback)
+-- DROP TABLE users;
+```
+
+### Run Specific Migration
+
+```bash
+tcb db migrate --up --name 001_create_users --env $TCB_ENV_ID
+```
+
+### Rollback Last Migration
+
+```bash
+tcb db migrate --down --env $TCB_ENV_ID
+```
+
+### Check Migration Status
+
+```bash
+tcb db migrate --status --env $TCB_ENV_ID
+```
+
+Output:
+```
+┌──────┬────────────────────────────────┬──────────┐
+│ File │ Name                           │ Status   │
+├──────┼────────────────────────────────┼──────────┤
+│ 001  │ create_users                   │ applied  │
+│ 002  │ add_index                      │ applied  │
+│ 003  │ alter_orders                   │ pending  │
+└──────┴────────────────────────────────┴──────────┘
+```
+
+## Agent Workflows
+
+### Workflow: Query DocDB from Agent
+
+```bash
+# List available collections first
+tcb db list --env $TCB_ENV_ID
+
+# Query specific collection
+tcb db query "SELECT * FROM users WHERE status = 'active'" --env $TCB_ENV_ID
+```
+
+For complex queries, use SDK in a function:
+
+```bash
+# Create debug function
+tcb fn invoke --name db-debug --params '{"query": "SELECT * FROM users"}' --env $TCB_ENV_ID
+```
+
+### Workflow: Data Migration
+
+```bash
+# 1. Create migration file
+cat > migrations/004_add_email_index.sql << 'EOF'
+CREATE INDEX idx_email ON users(email);
+EOF
+
+# 2. Run migration
+tcb db migrate --env staging
+
+# 3. Verify
+tcb db query "SELECT * FROM __migrations" --env staging
+
+# 4. Deploy to production (via deploy_stack)
+deploy_stack --env production --provider tcb
+```
+
+### Workflow: Backup and Restore
+
+```bash
+# Backup
+tcb db export --collection users --file ./backup/users_$(date +%Y%m%d).json --env $TCB_ENV_ID
+
+# Restore (careful!)
+tcb db import --collection users --file ./backup/users_latest.json --env $TCB_ENV_ID
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `Collection not found` | Wrong name | `tcb db list` to see collections |
+| `Query syntax error` | Invalid query syntax | Check DocDB query syntax |
+| `Import failed` | Invalid JSON format | Verify JSON array format |
+| `Migration failed` | SQL error | Check migration file syntax |
+| `Permission denied` | No write access | Check environment permissions |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

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

@@ -0,0 +1,207 @@
+# TCB Environment Management
+
+## What is a TCB Environment
+
+A TCB Environment is an isolated namespace containing:
+- CloudBase Functions
+- CloudBase Database (DocDB)
+- MySQL instance
+- COS storage bucket
+- CloudBase Hosting
+- CloudBase Run services
+
+**Each environment has a unique `envId`** (e.g., `env-8a9b6c5d`) used to scope all operations.
+
+## When to Create Environments
+
+| Scenario | Action |
+|----------|--------|
+| New project | Create dev environment first |
+| Team member onboarding | Each developer gets personal dev sandbox |
+| Feature branch testing | Deploy to preview environment |
+| Pre-production validation | Use staging environment |
+| Production release | Use production environment |
+
+## Environment Strategy
+
+### Recommended Structure
+
+| Environment | Purpose | Access | Per-Component Deploy |
+|-------------|---------|--------|---------------------|
+| `dev-{username}` | Personal dev | Developer only | Allowed |
+| `preview` | Integration testing | Team | Stack deploy only |
+| `staging` | Pre-production | Team | Stack deploy only |
+| `production` | Live traffic | Public | Stack deploy + approval |
+
+## CLI Commands
+
+### List Environments
+
+```bash
+tcb env list
+```
+
+Output:
+```
+┌──────────────┬────────────────┬─────────────┐
+│ Environment  │ Region         │ Status      │
+├──────────────┼────────────────┼─────────────┤
+│ env-xxxxx    │ ap-shanghai    │ running     │
+│ env-yyyyy    │ ap-beijing     │ running     │
+│ dev-sandbox  │ ap-shanghai    │ running     │
+└──────────────┴────────────────┴─────────────┘
+```
+
+### Create Environment
+
+```bash
+tcb env create dev-test --region ap-shanghai
+```
+
+**Note:** Environment creation takes 1-2 minutes.
+
+### Switch Environment
+
+```bash
+tcb env use env-xxxxx
+```
+
+Sets as default for subsequent commands.
+
+### View Environment Info
+
+```bash
+tcb env info
+```
+
+Shows:
+- Environment ID
+- Region
+- Status
+- Created time
+- Service quotas
+
+### Delete Environment
+
+```bash
+tcb env delete env-xxxxx
+```
+
+**Warning:** Deletes all resources in the environment. Cannot be undone.
+
+## Environment Variables in Commands
+
+Most CLI commands accept `--env <envId>` or `-e <envId>`:
+
+```bash
+tcb fn list --env env-xxxxx
+tcb hosting deploy --env env-xxxxx --dir ./dist
+```
+
+Or set default via `cloudbaserc.json`:
+
+```json
+{
+  "envId": "env-xxxxx"
+}
+```
+
+## Agent Decision Guide
+
+```
+Need to deploy to a shared environment?
+├── No (personal dev) → dev-{username} (per-component allowed)
+└── Yes (team/shared) → preview/staging/production (stack deploy only)
+
+Deploy command decision:
+├── Single function update → tcb fn deploy (per-component OK for dev)
+├── Database schema change → tcb db migrate
+├── Full stack update → deploy_stack --preview --provider tcb
+└── Anything to shared env → deploy_stack (not individual commands)
+```
+
+## Personal Dev Sandbox
+
+### Create Personal Sandbox
+
+```bash
+tcb env create dev-$USER --region ap-shanghai
+```
+
+### Per-Component Workflow
+
+```bash
+# Work on a single function
+tcb fn deploy --name hello --dir ./functions --env dev-$USER
+
+# Work on hosting
+tcb hosting deploy --env dev-$USER --dir ./dist
+
+# Test with local frontend
+# Frontend points to preview stack URL
+```
+
+### Cleanup
+
+When done with personal sandbox:
+
+```bash
+# Option 1: Keep for later use (costs money)
+# Option 2: Delete to save money
+tcb env delete dev-$USER
+```
+
+## Shared Environment Workflow
+
+### Preview Environment
+
+```bash
+# Deploy full stack to preview
+deploy_stack --preview --provider tcb
+
+# Result:
+# STACK_URL=https://{env-id}.tcb-preview.com
+# WEB_URL=https://{env-id}-{project}.tcb-preview.com
+```
+
+### Staging Environment
+
+```bash
+# Deploy after PR merge
+deploy_stack --env staging --provider tcb
+
+# Run e2e tests
+pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL
+```
+
+### Production Environment
+
+```bash
+# Deploy with human approval
+deploy_stack --env production --provider tcb
+
+# After validation
+# Smoke test + BVT
+```
+
+## Environment Quotas
+
+| Resource | Limit per Environment |
+|----------|----------------------|
+| Functions | 100 |
+| Collections (DocDB) | 100 |
+| Storage (COS) | 50GB |
+| Database (DocDB) | 2GB |
+| Database (MySQL) | 20GB |
+| CloudBase Run | 10 services |
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `Environment not found` | Wrong env ID | `tcb env list` to see valid IDs |
+| `Permission denied` | No access to environment | Request access from environment owner |
+| `Environment creating` | Creation in progress | Wait 1-2 minutes |
+| `Resource quota exceeded` | Hit environment limits | Delete unused resources or create new env |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

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

@@ -0,0 +1,276 @@
+# TCB CLI: Functions Management
+
+## When to Use Function Commands
+
+| Goal | Command | Per-Component Allowed |
+|------|---------|----------------------|
+| Deploy a function | `tcb fn deploy` | dev sandbox only |
+| Invoke a function | `tcb fn invoke` | any env |
+| View logs | `tcb fn logs` | any env |
+| List functions | `tcb fn list` | any env |
+| Create trigger | `tcb fn trigger` | dev sandbox only |
+| Delete function | `tcb fn delete` | dev sandbox only |
+
+**For shared environments (preview/staging/production), always use `deploy_stack` instead.**
+
+## Decision Tree for Function Operations
+
+```
+Need to work with functions?
+├── Deploying to shared env → deploy_stack --preview --provider tcb
+├── Deploying to personal dev → tcb fn deploy
+├── Testing/debugging function → tcb fn invoke
+├── Viewing logs → tcb fn logs
+├── Checking status → tcb fn list
+└── Deleting function → tcb fn delete (dev only)
+```
+
+## Deploy Functions
+
+### Standard Deployment
+
+```bash
+tcb fn deploy --name hello --dir ./functions --env $TCB_ENV_ID
+```
+
+Requirements:
+- Directory must contain `cloudbaserc.json` or `package.json`
+- Entry point must export `main` function
+
+### Deploy All Functions
+
+```bash
+tcb fn deploy --all --env $TCB_ENV_ID
+```
+
+Deploys all functions defined in `cloudbaserc.json`.
+
+### HTTP Function
+
+```bash
+tcb fn deploy --name api --httpFn --env $TCB_ENV_ID
+```
+
+Makes function accessible via HTTP.
+
+### With WebSocket
+
+```bash
+tcb fn deploy --name ws-handler --httpFn --ws --env $TCB_ENV_ID
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--name <name>` | Function name |
+| `--dir <path>` | Function directory |
+| `--env <envId>` | Target environment |
+| `--httpFn` | Deploy as HTTP function |
+| `--ws` | Enable WebSocket |
+| `--deployMode <mode>` | Upload mode: `cos` (default), `zip`, `image` |
+| `--force` | Overwrite existing |
+| `--yes` | Skip confirmation |
+
+## Invoke Functions
+
+### Sync Invocation
+
+```bash
+tcb fn invoke --name hello --params '{}' --env $TCB_ENV_ID
+```
+
+Returns function output directly.
+
+### With Parameters
+
+```bash
+tcb fn invoke --name hello \
+  --params '{"userId": "123", "action": "getProfile"}' \
+  --env $TCB_ENV_ID
+```
+
+### Async Invocation (background)
+
+```bash
+tcb fn invoke --name hello --params '{}' --async --env $TCB_ENV_ID
+```
+
+Returns immediately without waiting for result.
+
+## View Logs
+
+### Recent Logs
+
+```bash
+tcb fn logs --name hello --env $TCB_ENV_ID
+```
+
+### Logs with Limit
+
+```bash
+tcb fn logs --name hello --limit 100 --env $TCB_ENV_ID
+```
+
+### Logs with Filter
+
+```bash
+tcb fn logs --name hello --keyword error --env $TCB_ENV_ID
+```
+
+### Follow Logs (tail -f)
+
+```bash
+tcb fn logs --name hello --tail --env $TCB_ENV_ID
+```
+
+## List Functions
+
+```bash
+tcb fn list --env $TCB_ENV_ID
+```
+
+Output:
+```
+┌──────────────┬────────────┬─────────┬───────────────┐
+│ Name         │ Runtime    │ Status  │ Modified      │
+├──────────────┼────────────┼─────────┼───────────────┤
+│ hello        │ Nodejs16.13│ active  │ 2024-01-15    │
+│ api-users    │ Nodejs16.13│ active  │ 2024-01-14    │
+│ ws-handler   │ Nodejs16.13│ active  │ 2024-01-13    │
+└──────────────┴────────────┴─────────┴───────────────┘
+```
+
+## Function Details
+
+```bash
+tcb fn detail --name hello --env $TCB_ENV_ID
+```
+
+Shows:
+- Runtime version
+- Memory limit
+- Timeout
+- Trigger configuration
+- Environment variables
+- Last deployment time
+
+## Delete Function
+
+```bash
+tcb fn delete --name hello --env $TCB_ENV_ID
+```
+
+**Warning:** Deletes function and all associated triggers. Cannot be undone.
+
+## Triggers
+
+### Create Timer Trigger
+
+```bash
+tcb fn trigger create \
+  --name hello \
+  --trigger cron-daily \
+  --type timer \
+  --config "0 0 * * * *" \
+  --env $TCB_ENV_ID
+```
+
+### Create COS Trigger
+
+```bash
+tcb fn trigger create \
+  --name process-image \
+  --trigger image-upload \
+  --type cos \
+  --config '{"bucket":"my-bucket","filter":{"prefix":"images/"}}' \
+  --env $TCB_ENV_ID
+```
+
+### List Triggers
+
+```bash
+tcb fn trigger list --name hello --env $TCB_ENV_ID
+```
+
+### Delete Trigger
+
+```bash
+tcb fn trigger delete --name hello --trigger cron-daily --env $TCB_ENV_ID
+```
+
+## Common Workflows
+
+### Workflow: Deploy New Function
+
+```bash
+# 1. Create function directory
+mkdir -p functions/hello
+cd functions/hello
+
+# 2. Create entry point
+cat > index.js << 'EOF'
+exports.main = async (event, context) => {
+  return { message: "Hello, World!" };
+};
+EOF
+
+# 3. Create package.json
+cat > package.json << 'EOF'
+{ "name": "hello", "version": "1.0.0" }
+EOF
+
+# 4. Create function config
+cat > cloudbaserc.json << 'EOF'
+{
+  "functions": [{
+    "name": "hello",
+    "timeout": 10,
+    "memory": 256
+  }]
+}
+EOF
+
+# 5. Deploy
+tcb fn deploy --name hello --dir . --env $TCB_ENV_ID
+
+# 6. Test
+tcb fn invoke --name hello --params '{}' --env $TCB_ENV_ID
+```
+
+### Workflow: Update Production Function
+
+```bash
+# NEVER update directly in production
+# Always use deploy_stack
+
+deploy_stack --env production --provider tcb
+```
+
+### Workflow: Debug Function Error
+
+```bash
+# 1. Get recent logs
+tcb fn logs --name hello --limit 50 --env $TCB_ENV_ID
+
+# 2. Invoke with test params
+tcb fn invoke --name hello --params '{"debug": true}' --env $TCB_ENV_ID
+
+# 3. Check detailed logs
+tcb fn logs --name hello --keyword error --env $TCB_ENV_ID
+
+# 4. View function config
+tcb fn detail --name hello --env $TCB_ENV_ID
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `Function not found` | Wrong name or env | `tcb fn list` to verify |
+| `Deploy failed: timeout` | Slow upload | Check network, reduce package size |
+| `Invoke failed: timeout` | Function taking too long | Increase timeout, optimize function |
+| `Memory exceeded` | Memory limit too low | Increase memory in cloudbaserc.json |
+| `Trigger not firing` | Wrong trigger config | Verify cron expression, check logs |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`