sre-lua

Files (1)

• SKILL.md

SKILL.md (first lines)

# Writing Flows — Sandbox, Built-in API, ctx Globals

## Flow File Structure

Every flow file lives at `{ns}.{name}/fl/{flow}.lua`. Flow ID format: `{ns}-{name}:{flow}` (dots→dashes).
Example: `sn.core-agent/fl/assistant.lua` → `sn-core-agent:assistant`

The harness supports **two flow patterns**. Both are first-class.

### Pattern A — Lifecycle Hooks (4 required hooks)

Used by the main execution path: cron, webhook, event triggers, and manual `/fl/{id}/run` calls.

```lua
-- Optional: declare triggers (synced at load time)
triggers = {
  cron("*/5 * * * *"),
  webhook("/hook/path"),
}

-- Required hooks
function setup()   end   -- initialization; error here → failed() → cleanup()
function main(params) end -- core logic; params table from trigger; return value stored as result
function cleanup() end   -- always runs, even on error
function failed()  end   -- runs when setup/main/cleanup errors

-- Optional hook
function timeout() end   -- runs if execution exceeds deadline
```

All four hooks (`setup`, `main`, `cleanup`, `failed`) are **required**. `timeout` is optional.
`main(params)` receives a Lua table with trigger-specific fields (see sre-triggers skill for per-trigger params).
For webhook/manual triggers, merged query+body fields are available as `params.*` keys, and also via `ctx.params` (table) and `ctx.req` (request metadata).

Lifecycle order:
- Success: `setup → main → cleanup`
- Setup fails: `setup → failed → cleanup`
- Main fails: `setup → main → failed → cleanup`
- Cleanup fails: `setup → main → cleanup → failed`
- Timeout: `setup → main → timeout [→ failed if timeout errors] → cleanup`

### Pattern B — Trigger-Return (return table with `run` function)

Used by the form execution path (`ExecuteFlowWithFormContext`, `ExecuteFlowWithKitContext`).
The script **returns** a table with `triggers` and a `run(ctx)` function. No global hooks needed.

```lua
-- Flow returns a table instead of defining global hooks
return {
  triggers = {
    event("fm.contact"),
    cron("0 * * * *"),
  },

  run = function(ctx)
    -- ctx.trigger = { type = "form", event = "fm.contact" }
    -- ctx.form    = { ... form field data ... }
    -- ctx.kit     = { namespace, kit_name, form_name, page } (kit forms only)
    -- ctx.log(level, msg)
    ctx.log("info", "Received: " .. ctx.trigger.event)
    return {status = "ok"}
  end,
}
```

**When to use which:**
- **Pattern A** — Standard flows triggered by cron, webhooks, events, or manual run. All four hooks required.
- **Pattern B** — Flows wired to form submissions. Receives form data via `ctx.form`. No lifecycle hooks; the `run(ctx)` function handles everything.

---

## Sandbox

**Allowed libraries**: `base` (print/pairs/ipairs/type/tostring/tonumber/error/pcall/xpcall), `table`, `string`, `math`

**Blocked**: `io.*`, `os.*`, `debug.*`, `loadfile`, `dofile`, `load`

Use `sn.*` APIs for all I/O, networking, and system operations.

---

## ctx Globals

```lua
ctx.log(level, msg, ...)       -- levels: "debug","info","warn","error"
ctx.secret("key")              -- read from vault (never log the return value)
ctx.pg("name")                 -- get page renderer for page named "name"

-- STUBS (state KV store not yet wired)
ctx.get("ns:key")              -- STUB: always returns nil
ctx.set("ns:key", val)         -- STUB: no-op

-- Execution metadata (read-only)
ctx.execution_id               -- UUID of current execution
ctx.flow_name                  -- e.g. "sn-core-agent:assistant"
ctx.trigger_type               -- "cron"|"webhook"|"event"|"manual"|"form"
ctx.started_at                 -- RFC3339 timestamp

-- Trigger context (webhook/manual only, read-only)
ctx.params                     -- table of merged query+body fields (string values)
ctx.req                        -- {method, path, headers (lowercase keys), files}
ctx.req.headers["content-type"] -- header access example

-- Form context (read-only, set by form submission)
ctx.fm["kf.{ns}.{name}.{form}"].{field}  -- e.g. ctx.fm["kf.sn.mykit.contact"].email
ctx.data.{field}               -- shortcut: ctx.data.email (same data, no stub key)
```

**Note:** `ctx.get()`/`ctx.set()` are stubs — they compile but do nothing. Use `params` argument to `main()` for trigger data, `ctx.params`/`ctx.req` for webhook/manual request details, and `ctx.fm` for form data.

---

## sn Namespace

### JSON
```lua
local s = sn.json.enc(table)   -- table → JSON string
local t = sn.json.dec(string)  -- JSON string → table

From ndx-au/sre-init, MIT.

More from ndx-au/sre-init