@codemation/agent-skills 0.4.0 → 0.5.1

package/skills/builder/rest-node/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: rest-node
+description: Wrap a plain REST/HTTP service as a reusable workflow node with defineRestNode — declare a base URL, an endpoint + method, a credential slot, and input→request / response→output mappers, then use node.create(...) in a builder chain. Reach for this when a step talks to an external API that has no specialized node and no MCP server.
+compatibility: Codemation core-nodes. Requires @codemation/core-nodes import.
+tags: rest, http, api, integration, defineRestNode, node, credential, connect, external
+uses: "@codemation/core-nodes, @codemation/core, zod"
+---
+
+# Codemation REST Node (`defineRestNode`)
+
+`defineRestNode` (from `@codemation/core-nodes`) turns one REST endpoint into a thin, reusable workflow
+node — without a hand-rolled `Callback` + raw `fetch`. You declare a base URL, a path + method, an
+optional credential slot, and two small mappers (item input → request, HTTP response → output). It is a
+declarative wrapper over `defineNode`, so the result is used exactly like any built-in node:
+`node.create(config, label, nodeId)` in a `createWorkflowBuilder()` chain.
+
+**When to reach for it.** This is route 3 of the integration-routing hierarchy (see
+`connect-external-systems`): use `defineRestNode` for a plain REST/HTTP service when there is **no
+specialized node package** (route 1 — check `search_skills`) and **no MCP server** (route 2 — check
+`list_mcp_servers`). It is the right tool the moment you would otherwise hand-roll `fetch` against a
+JSON API — and it is strictly preferred over that. Only drop to a raw `Callback` when even
+`defineRestNode` can't express the call (see Gotchas).
+
+**Discipline:** author straight from this file, then run `verify_workflow` and fix only what it flags.
+Use `workflow-dsl` for the surrounding builder, trigger, and flow-control surface.
+
+## The shape — one node per endpoint
+
+`defineRestNode({...})` takes:
+
+- **`key`** / **`title`** — stable node key (e.g. `"widgets.create"`) and canvas title.
+- **`api`** — `{ baseUrl, path, method? }`. `path` may carry `{name}` placeholders, substituted from
+  `input` keys before the request (method defaults to `GET`).
+- **`credentials`** — a slot map, e.g. `{ auth: bearerTokenCredentialType }`. The session applies auth
+  to every request (Bearer header, API-key header/query, Basic). The operator binds it via the canvas;
+  you only declare the slot. Omit `credentials` for an unauthenticated API.
+- **`inputSchema`** — a Zod schema for per-item input, validated before the request runs.
+- **`request({ input })`** — returns `{ body?, query?, headers?, pathParams? }`. For a JSON body pass
+  `{ kind: "json", data: {...} }`.
+- **`response({ json, text, status, ok, input, ... })`** — maps the HTTP result to the node's output
+  JSON. Omit it to emit the raw `{ status, ok, json, text, ... }` response context.
+- **`errorPolicy`** — `"throw"` (default — non-2xx throws) or `"passthrough"` (return the result and
+  branch on `ok` downstream).
+
+Credential types come from `@codemation/core-nodes`: `bearerTokenCredentialType`,
+`apiKeyCredentialType`, `basicAuthCredentialType` (or any custom `defineCredential`).
+
+## A complete REST-backed workflow
+
+A generic "widgets API": list widgets nightly (API-key auth), fan the array into one item per widget,
+then create a record back in the same API (Bearer auth). Each node is defined once, then used with
+`.create(config, label, nodeId)` — the `config` is `{}` here because the per-item input flows from the
+chain, not static config.
+
+```typescript
+import { z } from "zod";
+import {
+  createWorkflowBuilder,
+  CronTrigger,
+  Split,
+  defineRestNode,
+  apiKeyCredentialType,
+  bearerTokenCredentialType,
+} from "@codemation/core-nodes";
+import type { Item } from "@codemation/core";
+
+// List widgets — GET with an API-key credential, no request body.
+const listWidgets = defineRestNode({
+  key: "widgets.list",
+  title: "List widgets",
+  icon: "mdi:widgets",
+  api: { baseUrl: "https://api.widgets.example.com", path: "/v1/widgets" },
+  credentials: { auth: apiKeyCredentialType },
+  response: ({ json }) => ({ widgets: (json as { items: { name: string; color: string }[] }).items }),
+});
+
+// Create a widget — POST with a JSON body built from the item input.
+const createWidget = defineRestNode({
+  key: "widgets.create",
+  title: "Create widget",
+  icon: "mdi:widgets",
+  api: { baseUrl: "https://api.widgets.example.com", path: "/v1/widgets", method: "POST" },
+  credentials: { auth: bearerTokenCredentialType },
+  inputSchema: z.object({ name: z.string(), color: z.string() }),
+  request: ({ input }) => ({
+    body: { kind: "json", data: { name: input.name, color: input.color } },
+  }),
+  response: ({ json }) => ({ widgetId: (json as { id: string }).id }),
+});
+
+export default createWorkflowBuilder({ id: "wf.widgets-sync", name: "Sync widgets" })
+  .trigger(new CronTrigger("Nightly", { schedule: "0 2 * * *", timezone: "Europe/Amsterdam" }))
+  .then(listWidgets.create({}, "List widgets", "list-widgets"))
+  .then(
+    new Split<{ widgets: { name: string; color: string }[] }, { name: string; color: string }>(
+      "Per widget",
+      (item: Item<{ widgets: { name: string; color: string }[] }>) => item.json.widgets,
+      "per-widget",
+    ),
+  )
+  .then(createWidget.create({}, "Create widget", "create-widget"))
+  .build();
+```
+
+## Path placeholders and per-item input
+
+`path` `{name}` placeholders are substituted from `input` keys (and any `pathParams` you return from
+`request`). So a per-record GET reads its id straight off the item:
+
+```typescript
+import { z } from "zod";
+import { defineRestNode, bearerTokenCredentialType } from "@codemation/core-nodes";
+
+// GET /v1/widgets/{widgetId} — `widgetId` is filled from the item input.
+export const getWidget = defineRestNode({
+  key: "widgets.get",
+  title: "Get widget",
+  api: { baseUrl: "https://api.widgets.example.com", path: "/v1/widgets/{widgetId}" },
+  credentials: { auth: bearerTokenCredentialType },
+  inputSchema: z.object({ widgetId: z.string() }),
+  response: ({ json, status }) => ({ widget: json, status }),
+});
+```
+
+## Gotchas
+
+- **`.create({}, label, id)` — config is empty; input flows from the chain.** `defineRestNode` puts
+  per-call data on the **item input** (validated by `inputSchema`), not static config — so the first
+  `.create` arg is `{}`. The node reads each item's `json` as its `input`. Give every node an explicit
+  stable `nodeId` (third arg), same as the rest of the DSL.
+- **The output is the `response` mapper's return — not the input item.** Like `HttpRequest`, a REST node
+  replaces the item payload. Carry forward anything you still need before the call, or return it from
+  `response`.
+- **Non-2xx throws by default.** Set `errorPolicy: "passthrough"` and branch on `item.json.ok` with an
+  `If` when you want to handle failures inline instead of failing the run.
+- **Bind the credential slot before activation.** Declaring `credentials: { auth: ... }` surfaces a
+  bindable slot; the operator binds an instance via the canvas dropdown (the concierge handles this —
+  separate skill). An unauthenticated API: omit `credentials`.
+- **Last resort is a raw `Callback`.** Only hand-roll `fetch`/JSON-RPC inside a `Callback` when the call
+  genuinely can't be expressed as one endpoint + auth + mappers (e.g. multi-step JSON-RPC, streaming).
+  See `connect-external-systems` for the full hierarchy.
+
+## Read next when needed
+
+- `connect-external-systems` — the full routing hierarchy; when `defineRestNode` is (and isn't) the right route.
+- `workflow-dsl` — builder, triggers, flow control, the per-item contract.
+- `custom-node-development` — `defineNode` for logic richer than one REST call (own execute body, ports).
+- `credential-development` — author a custom credential type when Bearer/API-key/Basic don't fit.

package/skills/builder/testing/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: testing
+description: Make a workflow safe to dry-run on real inputs — drive it from a TestTrigger fixture source, guard side effects with IsTestRun, and record pass/fail with Assertion. The dry-run path asserts while the live path performs the real write. Read this to make any side-effecting workflow testable before it goes live.
+compatibility: Designed for Codemation workflows authored with @codemation/core-nodes.
+tags: testing, test, assertion, dry-run, istestrun, testtrigger
+uses: "@codemation/core-nodes, @codemation/core"
+---
+
+# Codemation Testing
+
+A workflow isn't done until it's testable: a way to run it on real inputs with the side effects guarded, plus assertions on the result. Three primitives do this, and you bake them in from the start:
+
+- **`TestTrigger`** — a fixture source that feeds items through the _same_ pipeline. The Tests tab runs one workflow per yielded item, with the test context set. It's a **second, separate trigger export** — the live trigger stays the only `.trigger(...)` on the chain.
+- **`IsTestRun`** — a per-item router on ports `"true"` / `"false"`. It's `true` when the run carries a test context (a TestTrigger or the Tests tab), `false` for every live/manual/cron/webhook activation. Branch the real write off it so a dry run never sends a real email or charges a card.
+- **`Assertion`** — records one or more pass/fail results per item (`score: 1` = pass, `0` = fail) as `TestAssertion` rows the Tests tab aggregates.
+
+The pattern: **dry-run asserts, live performs.** Put the real side effect on the `false` branch and the `Assertion` on the `true` branch. See `workflow-dsl` for the surrounding chain.
+
+## The nodes — one-liners
+
+`IsTestRun` and `TestTrigger` take positional / options args; `Assertion` takes an options object. `IsTestRun` routes on ports, so branch it with `.when`, never a bare `.then`.
+
+```typescript
+import { IsTestRun, Assertion, TestTrigger } from "@codemation/core-nodes";
+
+type Draft = { reply: string };
+
+// Router — ports "true" (test run) / "false" (live run). Payload is unchanged.
+const guard = new IsTestRun<Draft>("Is this a test run?");
+
+// Assertion — one row per returned result; score 1 = pass, 0 = fail.
+const check = new Assertion<Draft>({
+  name: "Reply quality",
+  assertions: (item) => [
+    { name: "non-empty reply", score: item.json.reply.trim().length > 0 ? 1 : 0, actual: item.json.reply },
+  ],
+});
+
+// TestTrigger — a separate fixture source; generateItems is an async generator yielding one item per case.
+const fixtures = new TestTrigger<Draft>({
+  name: "Reply fixtures",
+  id: "reply-fixtures",
+  async *generateItems() {
+    yield { json: { reply: "Thanks for your order!" } };
+  },
+  caseLabel: (item) => item.json.reply, // human label in the Tests tab
+});
+```
+
+## One realistic complete example
+
+Webhook receives an order → `IsTestRun` splits dry-run from live → the `true` branch asserts the payload, the `false` branch performs the real notification. A companion `TestTrigger` is exported separately to feed fixtures through the same pipeline. Keep the fixture json shape identical to the live payload so the pipeline stays coherent. This folds in the former `istestrun` / `testtrigger-assertion` examples.
+
+```typescript
+import {
+  createWorkflowBuilder,
+  WebhookTrigger,
+  TestTrigger,
+  IsTestRun,
+  Assertion,
+  HttpRequest,
+} from "@codemation/core-nodes";
+
+type Order = { orderId: string; customerEmail: string; total: number };
+
+// Companion fixture source — a SEPARATE export, not a second .trigger(). Same json shape as the live payload.
+export const orderFixtures = new TestTrigger<Order>({
+  name: "Order fixtures",
+  id: "order-fixtures",
+  async *generateItems() {
+    yield { json: { orderId: "fixture-1", customerEmail: "a@example.com", total: 42 } };
+    yield { json: { orderId: "fixture-2", customerEmail: "b@example.com", total: 0 } };
+  },
+  caseLabel: (item) => item.json.orderId,
+});
+
+export default createWorkflowBuilder({ id: "wf.order-confirm", name: "Order confirmation (testable)" })
+  .trigger(new WebhookTrigger("Order placed", { endpointKey: "order-placed", methods: ["POST"] }))
+  // Guard the side effect: true = dry run (assert only), false = live run (real notification).
+  .then(new IsTestRun<Order>("Is this a test run?", "is-test-run"))
+  .when({
+    true: [
+      new Assertion<Order>({
+        name: "Order payload",
+        id: "assert-order-payload",
+        assertions: (item) => [
+          { name: "has email", score: item.json.customerEmail.includes("@") ? 1 : 0, actual: item.json.customerEmail },
+          { name: "positive total", score: item.json.total > 0 ? 1 : 0, actual: item.json.total },
+        ],
+      }),
+    ],
+    false: [
+      new HttpRequest<Order>("Send confirmation", {
+        method: "POST",
+        url: "https://api.example.com/notify/order-confirmation",
+        body: { kind: "json", data: { event: "order.confirmed", orderId: "${item.json.orderId}" } },
+        id: "send-confirmation",
+      }),
+    ],
+  })
+  .build();
+```
+
+## Design principle: test on REAL data, not fabricated fixtures
+
+For IO/trigger-bound workflows the right test source is **real data in the same shape the live trigger emits** — not something fabricated or pre-processed. The rule: pick the test source by trigger type.
+
+- **Mailbox / inbox workflow** — read from a **designated test folder or label** (e.g. `orders-test`). The owner drops ~5 real order emails there; the `TestTrigger` reads them via the integration's read capability. Fabricating email fixtures here is an **anti-pattern**: it proves the fabricated item, not the actual input the workflow will see.
+- **Webhook workflow** — replay real captured payloads (record one live hit, feed it back).
+- **Pure-logic / transform step with no external IO** — hard-coded fixtures are acceptable; there is nothing real to sample.
+
+**"Test items raw, processing shared."** The `TestTrigger` must yield items in the same raw shape the live trigger emits — unprocessed, uncanonicalized. All parsing, OCR, recognition, and matching must live _downstream_ of the trigger node and therefore run in both the test path and the live path. If the test source pre-processes or returns an already-canonical shape, the test asserts nothing meaningful.
+
+**Place `IsTestRun` after the processing, not before it.** The correct topology is:
+
+```
+trigger → [OCR / extraction / matching] → IsTestRun → {
+  true  (test):  assert the PROCESSING OUTCOME
+  false (live):  all side-effects
+}
+```
+
+A workflow that places `IsTestRun` right after the trigger and forks before the extraction step is wrong in two ways: the test path never exercises the processing logic, and the only thing left to assert is the raw trigger payload — which proves nothing about whether the workflow actually works. Put `IsTestRun` as late as possible: after all processing, just before the first external write.
+
+**Assert the processing outcome, not the raw trigger payload.** The `Assertion` on the `true` branch must check what the processing steps produced — e.g. that an extraction recognised a customer name (non-empty) or pulled at least one line item (length > 0). Asserting that an email has a subject or that a webhook body is non-null proves only that the trigger fired, not that the workflow does anything useful.
+
+**`IsTestRun` gates only side-effects — and ALL of them.** Both the live and test paths must flow through the same downstream nodes. The `IsTestRun` branch guards external writes (email replies, label changes, ERP mutations) — it must never be used to skip data or processing steps. Gate every side-effect on the `false` branch together: a single gated label change while the reply or ERP write runs unconditionally defeats the purpose.
+
+**If the designated test folder/label was not provided in the build task** → call `report_flag({ kind: "gap" })` and build the rest of what you can. Never fabricate a label id or silently fall back to hard-coded fixtures for an IO-bound workflow.
+
+For the concrete mechanism of reading from a Gmail label as a test source, see the `gmail` integration skill.
+
+## Gotchas
+
+- **One `.trigger()`, the live one.** A `TestTrigger` is a separate top-level `export const`, never a second `.trigger(...)`. The Tests tab discovers it; the live trigger stays in the chain.
+- **`IsTestRun` routes on ports.** Branch its `"true"`/`"false"` ports with `.when`, not a bare `.then`. Put the real write on `false`, the `Assertion` on `true`.
+- **Fixture shape == live payload shape.** If the fixture json doesn't match what the live trigger emits, the shared pipeline won't typecheck or behave the same.
+- **`score` is 1 or 0.** `Assertion` rows are pass (`1`) / fail (`0`); return an array so you can record several checks per item.
+- **Every node must be connected — including TestTrigger.** A node or TestTrigger that is constructed but
+  never wired is a defect: normal nodes connect via `.then()`/`.when()`; a `TestTrigger` is "wired" by
+  being a top-level `export const` (the Tests tab discovers exports, not orphaned `new TestTrigger(…)`
+  calls). If you construct a node and don't connect it, the graph silently ignores it — it will never run.