catalyst-functions

How It Works

Intent check — do this first:

• If the user is asking a how-to or conceptual question ("how do I write a function", "show me a Basic I/O handler", "how does Security Rules work"), answer directly with the correct code or explanation. Do NOT inspect the working directory, do NOT generate a CLAUDE.md, do NOT switch into codebase-analysis mode. Empty directory = fine for how-to questions.
• Only inspect the filesystem when the user explicitly asks to scaffold, add, or deploy something in their project.

1. Verify local scaffold (only when scaffolding, not for how-to questions) — both catalyst init and functions:add support non-interactive mode (CLI v1.27.0+). Check whether .catalystrc exists. If missing, use MCP tools to get the org ID and project ID, then run:

   catalyst init --org <orgId> -p <projectId> -ni
   

   Never ask the user to run catalyst init interactively. NI mode can only link an existing project — if none exists, tell the user to create one in the console first. catalyst.json does not exist yet after init -ni — that is expected. Add functions next (this creates catalyst.json):

   catalyst functions:add --name <name> --type <type> --stack <stack> -ni
   # e.g. catalyst functions:add --name api --type aio --stack node20 -ni
   

2. Identify the function type — Basic I/O for simple request/response, Advanced I/O for raw HTTP control, Event for trigger-based, Cron/Job for scheduled, Integration for Zoho service events, Browser Logic for Puppeteer.

3. Load references/functions-basics.md — for the matching handler signature, catalyst-config.json keys, SDK init pattern, and CORS setup.

4. Load references/functions-advanced.md — for file uploads (busboy), streaming responses, error handling, or chaining functions.

5. Load references/api-gateway.md — for routing rules, rate limiting, or gateway-level CORS.

6. Validate config — Confirm catalyst-config.json uses deployment + execution keys only. Never use function or entry_point.

Response Syntax Default

Always default to native Node.js response syntax. Advanced I/O exposes raw http.ServerResponse — Express methods (res.status(), res.json()) do not exist unless the user explicitly chose the Express template.

• Native (default): res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(data));
• Express (opt-in only): res.status(200).json(data) — only if the user has express installed and wired as middleware

If you don't know which template the user has, ask or default to native.

Security Checklist

• Functions are publicly accessible by default. Security Rules sets authentication to optional when a function is created — its URL is globally accessible to everyone with no restrictions. Set "authentication": "required" in the Security Rules JSON for any function that reads or writes user data or sensitive resources.
• API Gateway replaces Security Rules — do not use both. Enabling API Gateway automatically disables Security Rules. Pick one auth/routing layer per function.

Triggers

Use this skill for: "write a function", "catalyst function", "Basic I/O", "Advanced I/O", "Event function", "Cron function", "Browser Logic", catalyst-config.json, "function handler", "API Gateway", "rate limiting", "busboy", "file upload in function", catalyst deploy --only functions:<function-name>, catalyst functions:add, "function CORS", or any function type or function configuration question.

Deployment command note:

• Use catalyst deploy --only functions:<function-name> to deploy one function (where functions:<name> targets the function by its folder name).
• Use catalyst deploy --only functions to deploy all functions at once.

References

Reference	Load when the query is about…
references/functions-basics.md	Start here for any function question. Function type selection, Basic I/O and Advanced I/O handler signatures, catalyst-config.json, user-scope vs admin-scope, CORS, Security Rules, execution limits
references/functions-advanced.md	Advanced I/O patterns only. Express vs raw-http template differences, file uploads (busboy), streaming files from Stratus, error handling patterns, CORS for local dev, local testing, function chaining, ZCQL result unwrapping, HTTP payload limits
references/functions-templates.md	Event, Cron, Job, or Integration functions. Handler templates for all background/scheduled types, SDK component reference, retry behavior, cold start data, and the full common errors table
references/api-gateway.md	API Gateway config only. Enable/disable gateway, routing rules, rate limiting, CORS via gateway