@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/zoho-patterns/catalyst/appsail-deployment.md

@@ -0,0 +1,349 @@
+# Catalyst AppSail Deployment
+
+## Overview
+
+AppSail provides full-stack application hosting on Zoho Catalyst with support for Node.js, Python, and Java runtimes. It handles SSL, scaling, and deployment via CLI.
+
+## Supported Runtimes
+
+| Runtime | Versions | Use Case |
+|---------|----------|----------|
+| Node.js | 16, 18, 20 | React widgets, Express APIs, Next.js |
+| Python | 3.8, 3.9, 3.10 | Flask/FastAPI APIs, ML models |
+| Java | 11, 17 | Spring Boot, enterprise integrations |
+
+## Project Structure
+
+```
+my-catalyst-app/
+├── catalyst.json              # Project configuration
+├── app/                       # AppSail application
+│   ├── Dockerfile            # Container configuration
+│   ├── package.json          # (Node.js) dependencies
+│   ├── index.js              # (Node.js) entry point
+│   ├── requirements.txt      # (Python) dependencies
+│   ├── app.py                # (Python) entry point
+│   └── static/               # Static files
+├── functions/                 # Catalyst Functions (serverless)
+│   └── my-function/
+│       ├── index.js
+│       └── catalyst-config.json
+└── client/                    # Client-side assets (optional)
+    └── index.html
+```
+
+## PORT Binding (CRITICAL)
+
+> **WARNING:** Your application MUST bind to the port specified by `process.env.X_ZOHO_CATALYST_LISTEN_PORT` (Node.js) or the equivalent environment variable. Hardcoding ports will cause deployment failure.
+
+### Node.js (Express)
+
+```javascript
+const express = require("express");
+const app = express();
+
+// MANDATORY: Use the Catalyst-provided port
+const PORT = process.env.X_ZOHO_CATALYST_LISTEN_PORT || 9000;
+
+app.get("/health", (req, res) => {
+    res.status(200).json({ status: "healthy", timestamp: new Date().toISOString() });
+});
+
+app.get("/api/data", async (req, res) => {
+    try {
+        // Your business logic here
+        const data = await fetchData();
+        res.json({ success: true, data });
+    } catch (error) {
+        res.status(500).json({ success: false, error: error.message });
+    }
+});
+
+app.listen(PORT, () => {
+    console.log(`AppSail server running on port ${PORT}`);
+});
+```
+
+### Python (Flask)
+
+```python
+import os
+from flask import Flask, jsonify
+
+app = Flask(__name__)
+
+# MANDATORY: Use the Catalyst-provided port
+PORT = int(os.environ.get("X_ZOHO_CATALYST_LISTEN_PORT", 9000))
+
+@app.route("/health")
+def health():
+    return jsonify({"status": "healthy"}), 200
+
+@app.route("/api/data")
+def get_data():
+    try:
+        data = fetch_data()
+        return jsonify({"success": True, "data": data}), 200
+    except Exception as e:
+        return jsonify({"success": False, "error": str(e)}), 500
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=PORT)
+```
+
+## Dockerfile Configuration
+
+### Node.js Dockerfile
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy package files first (layer caching)
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Copy application code
+COPY . .
+
+# Expose the Catalyst port
+EXPOSE 9000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:${X_ZOHO_CATALYST_LISTEN_PORT}/health || exit 1
+
+# Start command
+CMD ["node", "index.js"]
+```
+
+### Python Dockerfile
+
+```dockerfile
+FROM python:3.10-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 9000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:${X_ZOHO_CATALYST_LISTEN_PORT}/health')" || exit 1
+
+CMD ["python", "app.py"]
+```
+
+## Environment Variables
+
+Set via CLI or Catalyst Console:
+
+```bash
+# Set environment variable
+catalyst env:set MY_API_KEY=abc123 --environment production
+
+# Set multiple variables
+catalyst env:set DB_HOST=mysql.example.com DB_PORT=3306 DB_NAME=mydb
+
+# List current variables
+catalyst env:list
+
+# Remove variable
+catalyst env:unset MY_API_KEY
+```
+
+### Accessing in Code
+
+```javascript
+// Node.js
+const apiKey = process.env.MY_API_KEY;
+const dbConfig = {
+    host: process.env.DB_HOST,
+    port: parseInt(process.env.DB_PORT || "3306"),
+    database: process.env.DB_NAME
+};
+```
+
+> **WARNING:** Never commit environment variables to git. Use `.env` locally and Catalyst environment settings for deployment.
+
+## Static File Serving
+
+```javascript
+const express = require("express");
+const path = require("path");
+const app = express();
+
+// Serve static files from /static directory
+app.use("/static", express.static(path.join(__dirname, "static")));
+
+// Serve React build for SPA
+app.use(express.static(path.join(__dirname, "client/build")));
+
+// SPA fallback - serve index.html for all non-API routes
+app.get("*", (req, res) => {
+    if (!req.path.startsWith("/api")) {
+        res.sendFile(path.join(__dirname, "client/build", "index.html"));
+    }
+});
+```
+
+## Custom Domains and SSL
+
+1. **Add domain in Catalyst Console:** Settings > Custom Domain
+2. **Configure DNS:** Add CNAME record pointing to your Catalyst subdomain
+3. **SSL:** Automatically provisioned (Let's Encrypt) after DNS verification
+
+```
+# DNS Configuration
+Type: CNAME
+Name: app
+Value: your-project-id.zohoappdev.com
+TTL: 300
+```
+
+> SSL certificates auto-renew. No manual intervention needed.
+
+## Health Checks
+
+Catalyst checks `/health` endpoint. Your app MUST respond with 200:
+
+```javascript
+app.get("/health", (req, res) => {
+    // Check dependencies
+    const checks = {
+        database: checkDbConnection(),
+        cache: checkCacheConnection(),
+        memory: process.memoryUsage().heapUsed < 500 * 1024 * 1024 // Under 500MB
+    };
+
+    const allHealthy = Object.values(checks).every(v => v === true);
+
+    res.status(allHealthy ? 200 : 503).json({
+        status: allHealthy ? "healthy" : "degraded",
+        checks: checks,
+        uptime: process.uptime()
+    });
+});
+```
+
+## Scaling Configuration
+
+Configure in `catalyst.json`:
+
+```json
+{
+    "appsail": {
+        "stack": "node18",
+        "memory": 512,
+        "scaling": {
+            "min_instances": 1,
+            "max_instances": 5,
+            "target_cpu_utilization": 70
+        },
+        "timeout": 120
+    }
+}
+```
+
+| Setting | Default | Max | Notes |
+|---------|---------|-----|-------|
+| Memory (MB) | 256 | 1024 | Increase for data-heavy apps |
+| Min Instances | 0 | 5 | Set 1+ to avoid cold starts |
+| Max Instances | 1 | 10 | Plan-dependent |
+| Request Timeout | 60s | 300s | Per-request limit |
+
+## Deployment via CLI
+
+```bash
+# Install Catalyst CLI
+npm install -g zcatalyst-cli
+
+# Login to your Zoho account
+catalyst login
+
+# Initialize project (first time)
+catalyst init
+
+# Deploy AppSail app
+catalyst deploy --only appsail
+
+# Deploy everything (functions + appsail + client)
+catalyst deploy
+
+# Deploy to specific environment
+catalyst deploy --env production
+
+# View deployment logs
+catalyst logs --type appsail --tail
+
+# Rollback to previous deployment
+catalyst rollback --version previous
+```
+
+### CI/CD Integration (GitHub Actions)
+
+```yaml
+name: Deploy to Catalyst
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "18"
+
+      - name: Install Catalyst CLI
+        run: npm install -g zcatalyst-cli
+
+      - name: Install dependencies
+        run: cd app && npm ci
+
+      - name: Run tests
+        run: cd app && npm test
+
+      - name: Deploy to Catalyst
+        env:
+          CATALYST_AUTH_TOKEN: ${{ secrets.CATALYST_AUTH_TOKEN }}
+          CATALYST_PROJECT_ID: ${{ secrets.CATALYST_PROJECT_ID }}
+        run: |
+          catalyst deploy --only appsail --token $CATALYST_AUTH_TOKEN --project $CATALYST_PROJECT_ID
+```
+
+## Common Deployment Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Port binding failure | Hardcoded port | Use `process.env.X_ZOHO_CATALYST_LISTEN_PORT` |
+| Build timeout | Large dependencies | Use multi-stage Dockerfile, prune dev deps |
+| Health check failing | No `/health` endpoint | Add health check route |
+| Cold start > 10s | Heavy initialization | Lazy-load modules, reduce bundle size |
+| Memory exceeded | Memory leak or large payloads | Profile with `--inspect`, add memory limits |
+| CORS errors from widget | Missing CORS headers | Add `cors` middleware with Zoho origins |
+
+### CORS for Widget Integration
+
+```javascript
+const cors = require("cors");
+
+// Allow Creator widgets to call this AppSail app
+app.use(cors({
+    origin: [
+        "https://creator.zoho.com",
+        "https://creator.zohocloud.ca",
+        "https://creatorapp.zohopublic.com",
+        /\.zoho\.(com|eu|in|com\.au|jp)$/
+    ],
+    credentials: true
+}));
+```

package/skills/zoho-patterns/catalyst/context-close-patterns.md

@@ -0,0 +1,354 @@
+# Catalyst context.close() Patterns
+
+## Why context.close() is MANDATORY
+
+> **CRITICAL:** Every Catalyst function MUST call `context.close()` before exiting. If missed:
+> - The function will hang until timeout (30s for I/O, 15min for Cron)
+> - Resources (DB connections, file handles) will leak
+> - You will be billed for the full timeout duration
+> - Concurrent execution limits will be consumed by hung functions
+
+## The Golden Rule
+
+**Every code path that can exit the function MUST call `context.close()`.** This includes:
+- Normal completion
+- Error/exception paths
+- Early returns
+- Conditional branches
+- After async operations complete or fail
+
+## Pattern 1: Try-Finally (Recommended)
+
+The safest pattern - `finally` block ALWAYS executes:
+
+```javascript
+const catalyst = require("zcatalyst-sdk-node");
+
+module.exports = async (req, res, context) => {
+    const app = catalyst.initialize(context);
+
+    try {
+        const data = await app.zcql().executeZCQLQuery("SELECT * FROM Users");
+        res.status(200).json({ success: true, data });
+    } catch (error) {
+        res.status(500).json({ success: false, error: error.message });
+    } finally {
+        context.close(); // ALWAYS executes, regardless of success or failure
+    }
+};
+```
+
+## Pattern 2: Multiple Return Points
+
+> **WARNING:** This is the most common source of missed `context.close()` calls. Every early return needs its own close.
+
+### WRONG (Missing context.close on early return):
+
+```javascript
+// BAD - context.close() missed on validation failure
+module.exports = async (req, res, context) => {
+    if (!req.body.email) {
+        res.status(400).json({ error: "Email required" });
+        return; // LEAKED! context.close() never called
+    }
+
+    // ... processing ...
+    res.status(200).json({ success: true });
+    context.close();
+};
+```
+
+### CORRECT (Try-finally covers all paths):
+
+```javascript
+// GOOD - finally block covers all exits
+module.exports = async (req, res, context) => {
+    try {
+        if (!req.body.email) {
+            res.status(400).json({ error: "Email required" });
+            return; // Safe - finally still executes
+        }
+
+        if (!req.body.name) {
+            res.status(400).json({ error: "Name required" });
+            return; // Safe - finally still executes
+        }
+
+        const result = await processData(req.body);
+        res.status(200).json({ success: true, data: result });
+
+    } catch (error) {
+        res.status(500).json({ success: false, error: error.message });
+    } finally {
+        context.close(); // Covers ALL paths above
+    }
+};
+```
+
+## Pattern 3: Async/Await with Error Handling
+
+```javascript
+module.exports = async (req, res, context) => {
+    const app = catalyst.initialize(context);
+
+    try {
+        // Multiple async operations
+        const user = await getUser(app, req.params.userId);
+        const orders = await getOrders(app, user.ROWID);
+        const analytics = await computeAnalytics(orders);
+
+        res.status(200).json({
+            user,
+            orders,
+            analytics
+        });
+
+    } catch (error) {
+        // Differentiate error types
+        if (error.code === "NOT_FOUND") {
+            res.status(404).json({ error: "User not found" });
+        } else if (error.code === "TIMEOUT") {
+            res.status(504).json({ error: "Database timeout" });
+        } else {
+            res.status(500).json({ error: "Internal error" });
+            console.error("Unhandled:", error);
+        }
+    } finally {
+        context.close();
+    }
+};
+```
+
+## Pattern 4: Cron Functions
+
+Cron functions have different signatures but same requirement:
+
+```javascript
+module.exports = async (cronDetails, context) => {
+    const app = catalyst.initialize(context);
+
+    try {
+        console.log("Cron started:", cronDetails.cron_name);
+
+        const results = await performBatchOperation(app);
+        console.log("Cron completed:", results);
+
+    } catch (error) {
+        console.error("Cron failed:", error.message);
+        // Notify admin - but don't let notification failure block close
+        try {
+            await notifyAdmin(app, error);
+        } catch (notifyError) {
+            console.error("Notification also failed:", notifyError.message);
+        }
+    } finally {
+        context.close();
+    }
+};
+```
+
+## Pattern 5: Event Functions
+
+```javascript
+module.exports = async (eventData, context) => {
+    const app = catalyst.initialize(context);
+
+    try {
+        const { event_type, data } = eventData;
+
+        switch (event_type) {
+            case "user_created":
+                await handleUserCreated(app, data);
+                break;
+            case "order_placed":
+                await handleOrderPlaced(app, data);
+                break;
+            default:
+                console.warn("Unknown event type:", event_type);
+        }
+
+    } catch (error) {
+        console.error("Event processing failed:", error);
+    } finally {
+        context.close();
+    }
+};
+```
+
+## Pattern 6: Nested Async Operations
+
+When you have nested promises or callbacks:
+
+```javascript
+module.exports = async (req, res, context) => {
+    const app = catalyst.initialize(context);
+
+    try {
+        // Parallel async operations
+        const [users, products, orders] = await Promise.all([
+            fetchUsers(app),
+            fetchProducts(app),
+            fetchOrders(app)
+        ]);
+
+        // Sequential dependent operations
+        const enrichedOrders = [];
+        for (const order of orders) {
+            const enriched = await enrichOrder(app, order, users, products);
+            enrichedOrders.push(enriched);
+        }
+
+        res.status(200).json({ data: enrichedOrders });
+
+    } catch (error) {
+        // Promise.all rejects on first failure
+        res.status(500).json({ error: error.message });
+    } finally {
+        context.close();
+    }
+};
+```
+
+## Pattern 7: Streaming/Chunked Response
+
+For long-running operations that stream responses:
+
+```javascript
+module.exports = async (req, res, context) => {
+    const app = catalyst.initialize(context);
+
+    try {
+        res.writeHead(200, { "Content-Type": "application/json" });
+
+        const stream = await getLargeDataset(app);
+        let first = true;
+
+        res.write("[");
+        for await (const chunk of stream) {
+            if (!first) res.write(",");
+            res.write(JSON.stringify(chunk));
+            first = false;
+        }
+        res.write("]");
+        res.end();
+
+    } catch (error) {
+        // If headers already sent, can't change status code
+        if (!res.headersSent) {
+            res.status(500).json({ error: error.message });
+        } else {
+            res.end(); // Close the stream
+        }
+    } finally {
+        context.close();
+    }
+};
+```
+
+## Anti-Patterns to Avoid
+
+### 1. context.close() in Callback (May Not Execute)
+
+```javascript
+// BAD - if callback never fires, context.close() never called
+someAsyncOperation((error, result) => {
+    if (error) { res.status(500).send(error); }
+    else { res.status(200).send(result); }
+    context.close();
+});
+
+// GOOD - wrap in promise, use try-finally
+try {
+    const result = await new Promise((resolve, reject) => {
+        someAsyncOperation((error, result) => {
+            if (error) reject(error);
+            else resolve(result);
+        });
+    });
+    res.status(200).send(result);
+} catch (error) {
+    res.status(500).send(error.message);
+} finally {
+    context.close();
+}
+```
+
+### 2. Conditional context.close()
+
+```javascript
+// BAD - context.close() only on success path
+if (success) {
+    res.status(200).send("OK");
+    context.close();
+}
+// What if success is false? Function hangs!
+
+// GOOD - unconditional in finally
+try {
+    if (success) {
+        res.status(200).send("OK");
+    } else {
+        res.status(400).send("Failed");
+    }
+} finally {
+    context.close();
+}
+```
+
+### 3. After setTimeout (Race Condition)
+
+```javascript
+// BAD - setTimeout may fire after function timeout
+setTimeout(() => {
+    context.close(); // May be too late!
+}, 5000);
+
+// GOOD - use await with promise-based delay
+try {
+    await new Promise(resolve => setTimeout(resolve, 5000));
+    // Do work after delay
+    res.status(200).send("Done");
+} finally {
+    context.close();
+}
+```
+
+## Testing for context.close() Coverage
+
+Before deploying, verify every function has proper close coverage:
+
+```javascript
+// Add this wrapper to catch missing context.close() in development
+function wrapHandler(handler) {
+    return async (req, res, context) => {
+        let closeCalled = false;
+        const originalClose = context.close.bind(context);
+
+        context.close = () => {
+            closeCalled = true;
+            originalClose();
+        };
+
+        await handler(req, res, context);
+
+        if (!closeCalled) {
+            console.error("WARNING: context.close() was not called!");
+            originalClose(); // Safety net
+        }
+    };
+}
+
+// Usage in development
+module.exports = wrapHandler(async (req, res, context) => {
+    // Your handler code
+});
+```
+
+## Checklist Before Deployment
+
+- [ ] Every function has `try-finally` with `context.close()` in `finally`
+- [ ] No early `return` statements outside the try block
+- [ ] No `context.close()` inside `setTimeout` or unresolved callbacks
+- [ ] Error notification code is wrapped in its own try-catch (won't block close)
+- [ ] All `Promise.all()` calls are inside the main try block
+- [ ] Cron functions close even on lock-acquisition failure