@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/compliance-patterns/soc2/deluge-execution-logging.md

@@ -0,0 +1,407 @@
+# SOC 2 Deluge Execution Logging
+
+## Overview
+
+Zoho Creator does **NOT** automatically log Deluge function executions. There is no native audit trail for what custom code runs, what data it processes, or what errors it encounters. For SOC 2 compliance, you must custom-build execution logging into every Deluge function that touches regulated data.
+
+This document provides the standard logging framework for all CloudStream Deluge implementations.
+
+> **WARNING**: Without execution logging, you cannot prove to auditors what your code did, when it ran, or whether it succeeded. This is a SOC 2 control gap that will result in audit findings.
+
+---
+
+## What to Log
+
+### Mandatory Log Fields
+
+Every Deluge execution log entry MUST capture:
+
+| Field | Description | Example |
+|---|---|---|
+| Function Name | Identifier of the Deluge function | `processPaymentApproval` |
+| Execution ID | Unique ID per execution instance | `EXEC-20250115-143022-7829` |
+| User | Who triggered the execution | `user@client.com` |
+| Timestamp Start | When execution began (UTC) | `2025-01-15T14:30:22.000Z` |
+| Timestamp End | When execution completed | `2025-01-15T14:30:22.450Z` |
+| Duration (ms) | Execution time in milliseconds | `450` |
+| Input Parameters | Sanitized input data | `{record_id: 123, action: "approve"}` |
+| Output/Result | What the function produced | `{status: "approved", notification_sent: true}` |
+| Status | Success/Failure/Warning | `Success` |
+| Error Details | Error message if failed | `null` or error string |
+| Records Affected | IDs of modified records | `[123, 456]` |
+| Client ID | Client identifier for multi-tenant | `CLT-001` |
+
+---
+
+## Logging to a Dedicated Audit Form
+
+### Audit Form: Deluge_Execution_Log
+
+```
+Form: Deluge_Execution_Log
+Fields:
+  - Log_ID (Auto-number)
+  - Execution_ID (Single Line, indexed)
+  - Function_Name (Single Line, indexed)
+  - Trigger_Type (Picklist: User Action/Workflow/Schedule/API/Button)
+  - User_Email (Email)
+  - Timestamp_Start (DateTime)
+  - Timestamp_End (DateTime)
+  - Duration_MS (Number)
+  - Input_Params (Multi Line - JSON, encrypted if contains sensitive data)
+  - Output_Result (Multi Line - JSON)
+  - Status (Picklist: Success/Failure/Warning)
+  - Error_Message (Multi Line)
+  - Error_Stack (Multi Line)
+  - Records_Affected (Multi Line - JSON array of IDs)
+  - Form_Context (Single Line - which form triggered this)
+  - Client_ID (Lookup to Clients)
+  - Environment (Picklist: Production/Staging/Development)
+  - Severity (Picklist: Info/Warning/Error/Critical)
+```
+
+> **WARNING**: This form should be accessible ONLY to Admin/Auditor roles. Standard users must not be able to view, modify, or delete execution logs.
+
+---
+
+## Performance Impact Considerations
+
+### Logging Overhead
+
+| Approach | Overhead | Reliability | Recommendation |
+|---|---|---|---|
+| Synchronous insert | +50-100ms per log | High | Use for critical functions |
+| Async (standalone function) | +10-20ms trigger | Medium | Use for high-volume functions |
+| Batch (collect + periodic flush) | Minimal per-call | Lower | Use for non-critical logging |
+| External (Catalyst webhook) | +20-50ms | High | Use for cross-org logging |
+
+### Performance Guidelines
+
+- **Always log synchronously** for: Financial transactions, ePHI access, permission changes
+- **May log asynchronously** for: Report generation, bulk imports, scheduled tasks
+- **Batch logging acceptable** for: Read-only operations, analytics queries
+
+### Minimizing Impact
+
+```deluge
+// GOOD: Log only essential data, not full record contents
+logEntry = {
+    "record_id": input.ID,
+    "action": "update",
+    "fields_changed": ["Status", "Approved_By"]
+};
+
+// BAD: Logging entire record contents (slow + storage waste + potential PII exposure)
+logEntry = {
+    "full_record": input  // NEVER do this
+};
+```
+
+---
+
+## Sample Logging Function Template
+
+### Core Logging Utility
+
+```deluge
+// ============================================================
+// FUNCTION: logExecution
+// PURPOSE: Standard execution logging for SOC 2 compliance
+// USAGE: Call at start and end of every regulated function
+// ============================================================
+
+void logExecution(String functionName, String triggerType, String status,
+                  String inputParams, String outputResult, String errorMessage,
+                  List recordsAffected, DateTime startTime)
+{
+    endTime = zoho.currenttime;
+
+    // Calculate duration
+    durationMs = ((endTime.toLong() - startTime.toLong()));
+
+    // Generate execution ID
+    executionId = "EXEC-" + startTime.toString("yyyyMMdd-HHmmss") + "-" + (randomNumber(1000, 9999)).toString();
+
+    // Sanitize input params (remove sensitive fields)
+    sanitizedInput = sanitizeForLogging(inputParams);
+
+    // Insert log record
+    insert into Deluge_Execution_Log [
+        Execution_ID = executionId,
+        Function_Name = functionName,
+        Trigger_Type = triggerType,
+        User_Email = zoho.loginuserid,
+        Timestamp_Start = startTime,
+        Timestamp_End = endTime,
+        Duration_MS = durationMs,
+        Input_Params = sanitizedInput,
+        Output_Result = outputResult,
+        Status = status,
+        Error_Message = errorMessage,
+        Records_Affected = recordsAffected.toString(),
+        Form_Context = functionName.getSuffix("_"),
+        Environment = "Production",
+        Severity = if(status == "Failure", "Error", if(status == "Warning", "Warning", "Info"))
+    ];
+}
+
+// ============================================================
+// FUNCTION: sanitizeForLogging
+// PURPOSE: Remove sensitive data before logging
+// ============================================================
+
+String sanitizeForLogging(String rawInput)
+{
+    // Remove known sensitive field patterns
+    sanitized = rawInput;
+    sensitiveFields = {"SSN", "DOB", "Password", "CardNumber", "CVV", "AccountNumber"};
+
+    for each field in sensitiveFields {
+        if (sanitized.contains(field)) {
+            sanitized = sanitized.replaceAll("\"" + field + "\":\"[^\"]*\"", "\"" + field + "\":\"[REDACTED]\"");
+        }
+    }
+
+    return sanitized;
+}
+```
+
+### Usage Pattern in Business Functions
+
+```deluge
+// ============================================================
+// FUNCTION: processInvoiceApproval
+// PURPOSE: Approve invoice and trigger payment workflow
+// CONTEXT: Called on button click in Invoices form
+// ============================================================
+
+void processInvoiceApproval(int invoiceId, String approverEmail)
+{
+    // START: Capture execution start time
+    startTime = zoho.currenttime;
+    functionName = "processInvoiceApproval";
+    inputParams = "{\"invoiceId\":" + invoiceId + ",\"approver\":\"" + approverEmail + "\"}";
+    affectedRecords = List();
+
+    try {
+        // Business logic
+        invoice = zoho.creator.getRecordById("app", "Invoices", invoiceId);
+
+        if (invoice.Status != "Pending Approval") {
+            logExecution(functionName, "Button", "Warning", inputParams,
+                "{\"message\":\"Invoice not in pending state\"}", "", affectedRecords, startTime);
+            return;
+        }
+
+        // Update invoice
+        update = zoho.creator.updateRecord("app", "Invoices", invoiceId, {
+            "Status": "Approved",
+            "Approved_By": approverEmail,
+            "Approval_Date": zoho.currentdate
+        });
+
+        affectedRecords.add(invoiceId);
+
+        // Trigger payment workflow
+        paymentResult = triggerPaymentWorkflow(invoiceId);
+        affectedRecords.add(paymentResult.get("payment_id"));
+
+        // SUCCESS: Log completion
+        outputResult = "{\"status\":\"approved\",\"payment_initiated\":" + paymentResult.get("success") + "}";
+        logExecution(functionName, "Button", "Success", inputParams, outputResult, "", affectedRecords, startTime);
+
+    } catch (e) {
+        // FAILURE: Log error
+        logExecution(functionName, "Button", "Failure", inputParams, "", e.toString(), affectedRecords, startTime);
+
+        // Re-throw or handle gracefully
+        alert "Invoice approval failed. Error has been logged. Please contact support.";
+    }
+}
+```
+
+---
+
+## Log Rotation and Archival
+
+### Rotation Strategy
+
+| Age | Location | Action |
+|---|---|---|
+| 0-30 days | Creator form (active) | Full access for troubleshooting |
+| 30-90 days | Creator form (archived flag) | Read-only, excluded from default views |
+| 90-365 days | Creator form (compressed views) | Minimal UI access, API queryable |
+| 365+ days | BigQuery (long-term) | Monthly archival, Creator records deletable |
+
+### Archival Script
+
+```deluge
+// Monthly archival of execution logs older than 90 days
+// Scheduled via Catalyst Cron on Day 3 of each month
+
+cutoffDate = zoho.currentdate.subDay(90);
+
+oldLogs = zoho.creator.getRecords("app", "Deluge_Execution_Log",
+    "(Timestamp_Start < \"" + cutoffDate.toString("yyyy-MM-dd") + "\" && Archived == false)",
+    1, 200);
+
+for each log in oldLogs {
+    // Export to BigQuery via API
+    exportToBigQuery(log);
+
+    // Mark as archived
+    zoho.creator.updateRecord("app", "Deluge_Execution_Log", log.get("ID"), {
+        "Archived": true,
+        "Archive_Date": zoho.currentdate
+    });
+}
+```
+
+---
+
+## Integrating with BigQuery for Analysis
+
+### BigQuery Table Schema
+
+```sql
+CREATE TABLE `project.dataset.deluge_execution_logs` (
+  log_id INT64 NOT NULL,
+  execution_id STRING NOT NULL,
+  function_name STRING NOT NULL,
+  trigger_type STRING,
+  user_email STRING NOT NULL,
+  timestamp_start TIMESTAMP NOT NULL,
+  timestamp_end TIMESTAMP,
+  duration_ms INT64,
+  input_params STRING,  -- JSON
+  output_result STRING,  -- JSON
+  status STRING NOT NULL,
+  error_message STRING,
+  records_affected STRING,  -- JSON array
+  form_context STRING,
+  client_id STRING NOT NULL,
+  environment STRING,
+  severity STRING
+)
+PARTITION BY DATE(timestamp_start)
+CLUSTER BY client_id, function_name, status;
+```
+
+### Analysis Queries
+
+```sql
+-- Function execution frequency and failure rates
+SELECT
+  function_name,
+  COUNT(*) as total_executions,
+  COUNTIF(status = 'Failure') as failures,
+  ROUND(COUNTIF(status = 'Failure') * 100.0 / COUNT(*), 2) as failure_rate_pct,
+  AVG(duration_ms) as avg_duration_ms,
+  MAX(duration_ms) as max_duration_ms
+FROM `project.dataset.deluge_execution_logs`
+WHERE timestamp_start > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
+GROUP BY function_name
+ORDER BY failure_rate_pct DESC;
+
+-- Slowest function executions (performance degradation detection)
+SELECT function_name, execution_id, user_email, duration_ms, timestamp_start
+FROM `project.dataset.deluge_execution_logs`
+WHERE duration_ms > 5000  -- Functions taking more than 5 seconds
+  AND timestamp_start > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
+ORDER BY duration_ms DESC
+LIMIT 50;
+```
+
+---
+
+## Alerting on Anomalous Patterns
+
+### Alert Definitions
+
+| Alert | Condition | Severity | Response |
+|---|---|---|---|
+| High failure rate | >10% failures in 1 hour | Critical | Investigate immediately |
+| Function not running | Expected scheduled function missing | High | Check Catalyst cron |
+| Unusual user | Function executed by unexpected user | High | Verify authorization |
+| Performance degradation | Avg duration > 2x baseline | Medium | Performance review |
+| Volume anomaly | >3x normal execution volume | Medium | Investigate trigger |
+| After-hours execution | Execution outside business hours | Low | Review if expected |
+
+### Alert Implementation
+
+```deluge
+// Scheduled check: Run every hour
+// Count failures in the last hour
+
+failures = zoho.creator.getRecords("app", "Deluge_Execution_Log",
+    "(Status == \"Failure\" && Timestamp_Start >= \"" + zoho.currenttime.subHour(1).toString("yyyy-MM-dd HH:mm:ss") + "\")",
+    1, 200);
+
+totalLastHour = zoho.creator.getRecords("app", "Deluge_Execution_Log",
+    "(Timestamp_Start >= \"" + zoho.currenttime.subHour(1).toString("yyyy-MM-dd HH:mm:ss") + "\")",
+    1, 200);
+
+if (totalLastHour.size() > 0) {
+    failureRate = (failures.size() * 100) / totalLastHour.size();
+
+    if (failureRate > 10) {
+        sendmail [
+            to: "alerts@cloudstreamsoftware.com",
+            subject: "CRITICAL: High Deluge failure rate - " + failureRate + "%",
+            message: "Failure rate of " + failureRate + "% detected in the last hour.\n" +
+                     "Total executions: " + totalLastHour.size() + "\n" +
+                     "Failures: " + failures.size() + "\n" +
+                     "Investigate immediately."
+        ];
+    }
+}
+```
+
+---
+
+## Log Access Controls
+
+### Who Can Access Execution Logs
+
+| Role | View Logs | Export Logs | Delete Logs | Modify Logs |
+|---|---|---|---|---|
+| System Admin | YES | YES | NO (archival only) | NO |
+| Auditor | YES | YES | NO | NO |
+| Developer | YES (own executions) | NO | NO | NO |
+| Standard User | NO | NO | NO | NO |
+| Service Account | Write-only (insert) | NO | NO | NO |
+
+> **WARNING**: Execution logs must be immutable once written. No user, including administrators, should be able to modify or delete log entries. Configure form permissions accordingly -- remove Edit and Delete permissions for all roles on the Deluge_Execution_Log form.
+
+### Implementation
+
+```
+Creator → Form Properties → Deluge_Execution_Log → Permissions:
+  - Admin: View only (no Edit, no Delete)
+  - All other roles: No access
+  - Workflows: Add only (for logging functions)
+```
+
+---
+
+## Standards for New Deluge Functions
+
+### Every new Deluge function in a regulated application MUST:
+
+1. Call `logExecution()` on success
+2. Call `logExecution()` on failure (in catch block)
+3. Sanitize sensitive data before logging
+4. Include function name as a string constant
+5. Capture start time at function entry
+6. List all affected record IDs
+7. Include meaningful output description
+
+### Code Review Checklist for Logging
+
+- [ ] Function has try/catch with logging in both paths
+- [ ] Input parameters are sanitized (no PII/PHI in logs)
+- [ ] Execution ID is unique and traceable
+- [ ] Duration is captured accurately
+- [ ] All modified records are listed in affected records
+- [ ] Error messages are descriptive but not exposing internals
+- [ ] Log severity is appropriate (Info/Warning/Error/Critical)

package/skills/consultancy-workflows/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: consultancy-workflows
+description: CloudStream consultancy workflow patterns. Covers client isolation, time tracking, documentation automation, knowledge capture, and handoff procedures.
+version: 1.0.0
+status: active
+introduced: 1.0.0
+lastUpdated: 2026-01-25
+activation: Client context, billing, handoff tasks, new client setup, time tracking
+---
+
+# Consultancy Workflows
+
+Patterns for managing multiple client engagements at CloudStream Software LLC.
+
+## Core Principles
+- Every action is billable client work - track everything
+- Client data isolation is non-negotiable
+- Documentation enables smooth handoffs between partners
+- Knowledge capture benefits all future engagements

package/skills/consultancy-workflows/client-isolation.md

@@ -0,0 +1,21 @@
+# Client Isolation
+
+## Credential Separation
+- Each client has a dedicated .env.client file (gitignored)
+- Never mix Zoho org credentials across clients
+- Use /client-switch command to load correct context
+- Verify active client before any API operations
+
+## Repository Strategy
+- One repo per client engagement
+- Shared utilities in a private CloudStream npm package
+- Client-specific CLAUDE.md in each repo
+- Never reference other client data in commits
+
+## Context Switching
+When switching clients:
+1. Run /client-switch [client-id]
+2. Verify correct Zoho org ID loaded
+3. Confirm compliance mode is correct
+4. Check recent git log for context
+5. Load client-specific CLAUDE.md