@pikku/cli 0.12.82 → 0.12.85

package/skills/pikku-kysely/SKILL.md

@@ -1,8 +1,16 @@
 ---
 name: pikku-kysely
-description: 'Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku function body, or when setting up SQL database services with Kysely. Covers the query builder API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if, transactions, jsonArrayFrom relation helpers) AND @pikku/kysely service setup (channel stores, workflow services, secret services, AI storage, deployment services).
-TRIGGER when: writing any non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or conditional query), the injected `kysely` service is used in a function body, or code uses PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks about SQL setup with Pikku.
-DO NOT TRIGGER when: user asks about MongoDB (use pikku-mongodb) or Redis (use pikku-redis).'
+description: >-
+  Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku
+  function body, or when setting up SQL database services with Kysely. Covers the query builder
+  API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if,
+  transactions, jsonArrayFrom relation helpers) AND @pikku/kysely service setup (channel stores,
+  workflow services, secret services, AI storage, deployment services). TRIGGER when: writing any
+  non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or
+  conditional query), the injected `kysely` service is used in a function body, or code uses
+  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks
+  about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB (use pikku-mongodb) or
+  Redis (use pikku-redis).
 installGroups: [core]
 ---
 
@@ -156,8 +164,8 @@ const secrets = new PgKyselySecretService(db.kysely, {
 })
 await secrets.init()
 
-await secrets.setSecretJSON('api-key', { key: 'sk-...' })
-const value = await secrets.getSecretJSON<{ key: string }>('api-key')
+await secrets.setSecret('api-key', { key: 'sk-...' })
+const value = await secrets.getSecret<{ key: string }>('api-key')
 await secrets.rotateKEK() // Re-encrypt all secrets with new KEK
 ```
 

package/skills/pikku-machine-auth/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: pikku-machine-auth
-description: 'Use when authenticating a CLI/agent/service against a Pikku server, adding machine-to-machine (M2M) auth, issuing scoped API keys for sandboxes/agents/workers, or wiring better-auth sessions into Pikku middleware. Covers `pikku login` (device-authorization), the better-auth API Key plugin, machine identities, and `betterAuthSession` with the api-key branch.
-TRIGGER when: user asks about CLI login, `pikku login`, machine agents, service-to-service auth, API keys, client credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function.
-DO NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).'
+description: >-
+  Use when authenticating a CLI/agent/service against a Pikku server, adding machine-to-machine
+  (M2M) auth, issuing scoped API keys for sandboxes/agents/workers, or wiring better-auth sessions
+  into Pikku middleware. Covers `pikku login` (device-authorization), the better-auth API Key
+  plugin, machine identities, and `betterAuthSession` with the api-key branch. TRIGGER when: user
+  asks about CLI login, `pikku login`, machine agents, service-to-service auth, API keys, client
+  credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function. DO
+  NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the
+  app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).
 ---
 
 # Pikku Machine Auth

package/skills/pikku-mcp/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-mcp
-description: 'Use when exposing Pikku functions as MCP tools, resources, or prompts for AI assistants. Covers mcp: true flag, pikkuMCPResourceFunc, pikkuMCPPromptFunc, and MCP wire object.
-TRIGGER when: code uses mcp: true or pikkuMCPResourceFunc/pikkuMCPPromptFunc, user asks about MCP, Model Context Protocol, AI tool integration, or exposing functions to Claude/ChatGPT.
-DO NOT TRIGGER when: user asks about AI agents (use pikku-ai-agent) or general function definitions (use pikku-concepts).'
+description: >-
+  Use when exposing Pikku functions as MCP tools, resources, or prompts for AI assistants. Covers
+  mcp: true flag, pikkuMCPResourceFunc, pikkuMCPPromptFunc, and MCP wire object. TRIGGER when:
+  code uses mcp: true or pikkuMCPResourceFunc/pikkuMCPPromptFunc, user asks about MCP, Model
+  Context Protocol, AI tool integration, or exposing functions to Claude/ChatGPT. DO NOT TRIGGER
+  when: user asks about AI agents (use pikku-ai-agent) or general function definitions (use
+  pikku-concepts).
 installGroups: [core]
 ---
 

package/skills/pikku-middleware/SKILL.md

@@ -1,8 +1,13 @@
 ---
 name: pikku-middleware
-description: 'Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware (including service-to-service bearer auth), per-route middleware, session-setting middleware, or understanding middleware execution order and priority.
-TRIGGER when: user wants middleware on some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global interceptors, or middleware priority/order questions.
-DO NOT TRIGGER when: user asks about permissions/authorization checks (use pikku-permissions), auth strategies like authBearer/authCookie (use pikku-security), or deployment.'
+description: >-
+  Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware
+  (including service-to-service bearer auth), per-route middleware, session-setting middleware, or
+  understanding middleware execution order and priority. TRIGGER when: user wants middleware on
+  some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global
+  interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about
+  permissions/authorization checks (use pikku-permissions), auth strategies like
+  authBearer/authCookie (use pikku-security), or deployment.
 installGroups: [core]
 ---
 
@@ -13,7 +18,7 @@ installGroups: [core]
 1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info tags --json` to understand the existing middleware and tag landscape.
 2. Identify the source files that own the behavior — wirings files, not generated output.
 3. Register middleware at module load time — in a `wirings/*.ts` file, never inside a function body.
-4. Validate: run `pikku all` after adding or changing middleware; run `pikku tsc` to confirm type safety.
+4. Validate: run `pikku all --tsc` after adding or changing middleware — it regenerates and then confirms type safety in one pass.
 
 ## The `pikkuMiddleware` Factory
 
@@ -221,6 +226,6 @@ export const myFunc = pikkuSessionlessFunc({
 ## After Changes
 
 ```bash
-pikku all        # regenerate metadata so new tags are picked up
-pikku tsc        # type-check
+pikku all              # regenerate metadata so new tags are picked up
+pikku all --tsc        # regenerate, then type-check (fails on type errors)
 ```

package/skills/pikku-mongodb/SKILL.md

@@ -1,8 +1,11 @@
 ---
 name: pikku-mongodb
-description: 'Use when setting up MongoDB database services in a Pikku app. Covers PikkuMongoDB connection, channel stores, workflow services, secret services, AI storage, agent runs, and deployment services.
-TRIGGER when: code uses PikkuMongoDB, MongoDBChannelStore, MongoDBWorkflowService, MongoDBSecretService, or user asks about MongoDB setup with Pikku.
-DO NOT TRIGGER when: user asks about SQL databases (use pikku-kysely) or Redis (use pikku-redis).'
+description: >-
+  Use when setting up MongoDB database services in a Pikku app. Covers PikkuMongoDB connection,
+  channel stores, workflow services, secret services, AI storage, agent runs, and deployment
+  services. TRIGGER when: code uses PikkuMongoDB, MongoDBChannelStore, MongoDBWorkflowService,
+  MongoDBSecretService, or user asks about MongoDB setup with Pikku. DO NOT TRIGGER when: user
+  asks about SQL databases (use pikku-kysely) or Redis (use pikku-redis).
 ---
 
 # Pikku MongoDB
@@ -70,8 +73,8 @@ const secrets = new MongoDBSecretService(mongo.db, {
 })
 await secrets.init()
 
-await secrets.setSecretJSON('api-key', { key: 'sk-...' })
-const value = await secrets.getSecretJSON<{ key: string }>('api-key')
+await secrets.setSecret('api-key', { key: 'sk-...' })
+const value = await secrets.getSecret<{ key: string }>('api-key')
 await secrets.rotateKEK()
 ```
 

package/skills/pikku-n8n-import/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: pikku-n8n-import
+description: 'Use to import an n8n workflow JSON export into a runnable Pikku workflow. Triggers when the user says "import this n8n workflow", "convert this n8n export to pikku", points at an n8n `.json` export or a directory of them, or picks up after `pikku import n8n` left throwing stub functions (`STUB — generated from n8n …`, `— implement me`) or a `<workflow>.integrations.json` manifest. Owns the whole flow: run the importer, triage what it could not map, fill each stub, report any missing `@pikku/addon-*` integrations, and verify the result compiles and runs with no surviving stubs. DO NOT TRIGGER for hand-written addon wiring unrelated to an n8n import (use pikku-addon), or for authoring workflows from scratch (use pikku-workflow).'
+metadata:
+  version: 1.0.0
+---
+
+# n8n → Pikku Import
+
+Take an n8n export all the way to a compiling, stub-free Pikku workflow. The
+`@pikku/n8n-import` package (invoked by `pikku import n8n`) is **frozen**: it does
+the provable, mechanical conversion and leaves everything it cannot prove as a
+typed stub that throws at runtime. This skill runs that package, then fills the
+remainder with judgment, reports what needs a human decision, and verifies.
+
+Never re-do what the importer already did, and never hand-edit generated files to
+paper over a stub — fix the source cause (the stub function, the graph node, or a
+missing dependency).
+
+## Agent Operating Procedure
+
+1. Discover before editing. Prefer `pikku-meta`/`pikku meta ... --json` when
+   available; inspect only the focused output you need.
+2. Identify the source file that owns the behavior. Do not start from generated
+   output, `.pikku`, `node_modules`, or vendored packages.
+3. Make the smallest source change that satisfies the task. Keep generated files
+   generated.
+4. Validate with the narrowest relevant command first, then `pikku all` /
+   `pikku-verify` when functions, wirings, or schemas changed.
+5. If validation fails, fix the source cause and rerun. Never edit generated
+   files to hide an error.
+
+## Workflow
+
+### 1 — Run the importer (do as much as possible, cheaply)
+
+```bash
+pikku import n8n <export.json> [outDir]
+```
+
+It writes `<slug>.graph.ts` (+ `.agent.ts` for AI workflows), `<slug>.addons.gen.ts`,
+a `<slug>.integrations.json` manifest, and one stub function per node it could not
+map. It **exits 1** on an un-importable input (a cross-workflow sub-workflow
+reference, a dynamic workflow target, a mid-flow `respondToWebhook`) with a
+`[reason] message` — relay that to the user; do not fake a partial scaffold.
+
+For a directory of exports, run it per file.
+
+### 2 — Triage what it left
+
+Every unmapped node is a stub that throws `… — implement me`. Classify each by its
+JSDoc marker and route to the matching reference:
+
+| Stub marker / signal | Handle via |
+|---|---|
+| `STUB — generated from n8n node "…" (type "n8n-nodes-base.<svc>…")` | `references/addon-mapping.md` |
+| `STUB — generated from n8n Code node "…"` | `references/code-translation.md` |
+| A `control` stub — Loop Over Items / **splitInBatches**, Switch expr-mode | `references/loops-and-control.md` |
+| `STUB — … vector-store … #902` | rare now (RAG ships as `<store>:query`/`:ingest`); a residual one = an unmapped store → report it, don't guess |
+| Importer `diagnostics` (already exited 1) | explain the reason; the workflow is un-importable as-is |
+
+Read a reference file only when you actually hit that stub class.
+
+### 3 — Fill each stub
+
+Work the manifest + stub files per the routed reference. The mechanical classes
+(addon, code) are near-deterministic; the loop/control class needs judgment
+(map vs reduce, done-branch semantics) — reference `loops-and-control.md` tells you
+when to decide vs ask.
+
+### 4 — Report missing integrations (first-class output)
+
+An addon stub can only be wired to an **installed** `@pikku/addon-*`. When the
+package for an n8n service is not in `dependencies`, do not guess a lookalike —
+collect it. Give the user one upfront list:
+
+```
+Missing integrations — install these or the nodes stay stubs:
+  • slackTool "Post to channel"   → npm i @pikku/addon-chat-slack
+  • hubspot "Create contact"      → no @pikku/addon-hubspot exists yet
+```
+
+### 5 — Verify it works
+
+1. `pikku all` (regenerate) → `yarn tsc` from the package root; fix the source
+   cause of any error and rerun.
+2. Grep the emitted functions for any surviving `— implement me`
+   / `throw new Error('Stub:`. **Any survivor means the import is not done** —
+   list them by node name.
+3. Green tsc **and** zero surviving stubs = success.
+
+## References
+
+| Open when you need to… | Read |
+|---|---|
+| map an integration stub (gmailTool, slackTool, googleSheets, plain action nodes) to an installed addon `ref(...)` | `references/addon-mapping.md` |
+| translate an n8n Code node body into a Pikku function body | `references/code-translation.md` |
+| lower a Loop Over Items / splitInBatches loop, or a Switch that stayed a stub | `references/loops-and-control.md` |
+
+## Final summary
+
+Report, terse:
+
+- Files written and workflow shape (`pure-graph` / `agent`).
+- Stubs filled, by class.
+- **Missing integrations** (the step-4 list) — the thing the user must act on.
+- Anything left as a `// TODO:` and why (credentials to wire, a loop deferred, an
+  unmapped store).
+- Verification: `tsc` status + surviving-stub count (must be 0).

package/skills/pikku-n8n-import/SPEC.md

@@ -0,0 +1,84 @@
+# n8n → Pikku Import Specification
+
+## Intent
+
+Take an n8n workflow JSON export all the way to a compiling, stub-free, runnable
+Pikku workflow. The `@pikku/n8n-import` package is treated as **frozen**: it does
+the provable mechanical conversion and leaves everything it cannot prove as a typed,
+throwing stub. This skill owns the end-to-end flow around it — run it, fill the
+remainder with judgment, report gaps that need a human decision, and verify.
+
+## Scope
+
+In scope:
+- Running `pikku import n8n` and triaging its output.
+- Filling integration stubs (→ addon refs), Code stubs (→ function bodies), and
+  loop/control stubs (→ `graph:map`/reduce/branch).
+- Reporting missing `@pikku/addon-*` integrations as a first-class output.
+- Verifying via `pikku all` + `tsc` + a zero-surviving-stub check.
+
+Out of scope:
+- Extending `@pikku/n8n-import` itself (it is frozen; do not add per-service tables
+  or new compiler rules to it).
+- Authoring workflows from scratch (`pikku-workflow`) or hand-written addon wiring
+  unrelated to an import (`pikku-addon`).
+- Inventing batching primitives or guessing ambiguous loop semantics — surface them.
+
+## Users And Trigger Context
+
+- Primary users: developers importing their own n8n workflows into a Pikku app,
+  usually inside an agentic session.
+- Common requests: "import this n8n workflow", "convert this n8n export to pikku",
+  finishing `— implement me` stubs, wiring a `*.integrations.json` manifest.
+- Should not trigger for: from-scratch workflow authoring, or addon wiring with no
+  n8n import involved.
+
+## Runtime Contract
+
+- Required first action: run `pikku import n8n <export.json> [outDir]` (per file for
+  a directory); relay any exit-1 diagnostic instead of scaffolding a partial.
+- Required outputs: filled stubs, a missing-integrations list, verification status.
+- Non-negotiable: never hand-edit generated files to hide a stub; map only to
+  installed addons; zero surviving `— implement me` stubs at success.
+- Bundled files loaded at runtime: `references/addon-mapping.md`,
+  `references/code-translation.md`, `references/loops-and-control.md` — each only
+  when its stub class appears.
+
+## Source And Evidence Model
+
+Authoritative sources:
+- `@pikku/n8n-import` codegen (stub markers, manifest shape, `import-n8n` command).
+- `@pikku/addon-graph` function contracts (`graph:map`/`fanout`, `branch`).
+- Installed `@pikku/addon-*` source (function names verified by grep, never guessed).
+
+Useful improvement sources: real imported workflows, harness coverage deltas,
+addon catalogue changes.
+
+Data that must not be stored: credential secrets, customer data, private ids beyond
+what a manifest already records for reproduction.
+
+## Reference Architecture
+
+- `SKILL.md`: the run → triage → fill → report → verify workflow + router.
+- `references/`: per-stub-class depth (addon mapping, code translation, loops/control).
+
+## Validation
+
+- Lightweight: `yarn tsc` from the package root after each fill.
+- Deeper: `pikku all` regeneration; grep emitted functions for surviving stub throws.
+- Acceptance gates: green tsc **and** zero surviving `— implement me` stubs.
+
+## Known Limitations
+
+- `splitInBatches` with `batchSize > 1` and reduce-style accumulators have no direct
+  primitive — surfaced, not auto-converted.
+- Missing addons block their nodes; the skill reports, it does not install.
+- Cross-workflow sub-workflow references fail import at the package level.
+
+## Maintenance Notes
+
+- Update `SKILL.md` when the import command, stub taxonomy, or verify gates change.
+- Update a reference when an addon convention, the `graph:map` contract, or a rubric
+  changes.
+- This skill supersedes the former `pikku-n8n-addon-map` and `pikku-n8n-code-translate`
+  skills (folded into `references/addon-mapping.md` and `references/code-translation.md`).

package/skills/pikku-n8n-import/references/addon-mapping.md

@@ -0,0 +1,121 @@
+# Integration stub → Pikku addon
+
+Translate n8n integration nodes (`gmailTool`, `slackTool`, `googleSheetsTool`, plain
+`gmail` / `slack` action nodes, etc.) that the importer left as throwing stubs into
+real `ref('<addonRpc>')` references pointing at functions in **installed**
+`@pikku/addon-*` packages.
+
+This is **per-stub mechanical**. Do not invent business logic, chain calls, or
+"improve" the workflow. Read one manifest entry, find the matching addon function,
+rewrite the stub.
+
+## Inputs
+
+1. **Manifest** — `<workflow>.integrations.json` next to the `.graph.ts`. Each entry:
+   ```jsonc
+   {
+     "rpcName": "agentGmailtool__sendAMessageInGmail",
+     "n8nType": "n8n-nodes-base.gmailTool",
+     "n8nName": "Send a message in Gmail",
+     "parameters": { "sendTo": "...", "message": "...", "subject": "..." },
+     "credentials": { "gmailOAuth2": { "id": "...", "name": "Personal Gmail" } },
+     "isAgentTool": true,
+     "agentName": "Inbox Assistant"
+   }
+   ```
+2. **Installed addons** — `@pikku/addon-*` in the project's `package.json`
+   `dependencies`. Map **only** against installed packages. If the addon for an n8n
+   type is not installed, surface it (see SKILL step 4) — never silently skip and
+   never pick a vaguely-named function from another addon.
+
+## Per entry, in order
+
+### Step 1 — identify the target addon
+
+Map `n8nType` to a package by reading its source. Common shapes (**guesses, not
+authoritative** — always verify against installed source):
+
+| n8n type prefix | typical addon candidate |
+|---|---|
+| `n8n-nodes-base.gmail` / `gmailTool` | `@pikku/addon-email-gmail` |
+| `n8n-nodes-base.slack` / `slackTool` | `@pikku/addon-chat-slack` |
+| `n8n-nodes-base.googleSheets` / `…Tool` | `@pikku/addon-sheets-google` |
+| `n8n-nodes-base.notion` / `notionTool` | `@pikku/addon-docs-notion` |
+| `n8n-nodes-base.telegram` / `telegramTool` | `@pikku/addon-chat-telegram` |
+
+If no installed addon plausibly covers the n8n type, stop and report it — do not
+pick a wrong addon.
+
+### Step 2 — pick the function (resource + operation → fn name)
+
+n8n nodes use a `(resource, operation)` pair. Rubric:
+
+- `resource` defaults to the integration's primary noun if absent (gmail →
+  `message`, slack → `message`, sheets → `spreadsheet`). Read the addon's folder
+  structure (`messages/`, `drafts/`, `channels/`) to see what nouns exist.
+- `operation` is usually a verb (`get`, `getAll`, `send`, `delete`, `addLabels`).
+- The pikku function name is almost always `<resource><Verb>` in camelCase, matching
+  the file's `export const` (`messageList` for `messages/list.function.ts`).
+
+Verify: `grep -h "^export const" <addonPkg>/src/functions/**/*.ts` and match by name.
+Conventions in `@pikku/addon-email-gmail` (a **sanity reference**, not a fallback):
+
+- `getAll → <resource>List`, `get → <resource>Get`, `send → <resource>Send`,
+  `delete → <resource>Delete`, `reply → <resource>Reply`
+- `addLabels → <resource>AddLabel` (singular!), `removeLabels → <resource>RemoveLabel`
+- `markAsRead / markAsUnread → <resource>MarkRead / <resource>MarkUnread`
+- `create → <resource>Create`
+
+If the function has a `node:` block, prefer matching its `category`/`displayName`
+over guessing.
+
+### Step 3 — rewrite the stub
+
+Two outcomes, by `isAgentTool`:
+
+**A) `isAgentTool: true`** — the stub is an agent tool referenced via `ref()`:
+1. Delete the stub file.
+2. In the agent file, replace `ref('agentGmailtool__sendAMessageInGmail')` in
+   `tools: [...]` with `ref('messageSend')` (the resolved addon function).
+3. Ensure the addon is where pikku scans functions (usually automatic via
+   `node_modules/@pikku/addon-*`).
+
+If you can't delete safely, leave a one-line re-export instead of a stub:
+```ts
+import { messageSend } from '@pikku/addon-email-gmail'
+export const agentGmailtool__sendAMessageInGmail = messageSend
+```
+Default is delete + retarget; wrappers add maintenance burden.
+
+**B) `isAgentTool: false`** — the stub is a graph node:
+1. Open `<workflow>.graph.ts`.
+2. In `nodes: { … }` find the entry whose value is the stub rpc name.
+3. Replace it with the addon function name (`'messageSend'`).
+4. If `config: { <id>: { input } }` produces an `{ items }` envelope, rewrite it to
+   the addon function's real input schema (read its `input: z.object({...})`).
+5. Delete the stub file.
+
+### Step 4 — port hard-coded parameters
+
+- **Hardcoded values** (`"limit": 20`, `"labelIds": ["INBOX"]`) were user choices.
+  Preserve them in the graph node's `input` (case B). **Agent tools cannot carry
+  hardcoded params** (the LLM fills args at call time) — surface the trade-off; if
+  the user needs a value pinned, they keep a thin wrapper.
+- **`$fromAI('Name', '', 'string')`** placeholders are LLM-filled — the addon's Zod
+  schema becomes the tool schema. Just drop the placeholder string; no other action.
+
+### Step 5 — credentials
+
+`credentials: { gmailOAuth2: { id, name } }` is the n8n credential ref. Pikku addons
+expect a wired service (`services.gmail`). Do **not** auto-wire — leave a TODO:
+
+> `// TODO: wire services.gmail using credential "Personal Gmail" (n8n id: gmail_cred_1) — see @pikku/addon-email-gmail/README.md`
+
+## Never
+
+- Invent functions that don't exist — grep first.
+- Pick a wrong addon because the right one isn't installed — report `npm i @pikku/addon-<x>`.
+- Bake per-mapping tables into `@pikku/n8n-import` — it is addon-agnostic; mapping lives here.
+- Modify the manifest — it's an audit artifact.
+- Chain calls — each entry maps to exactly one addon function.
+- Silently drop a hardcoded param — surface it.

package/skills/pikku-n8n-import/references/code-translation.md

@@ -0,0 +1,121 @@
+# n8n Code node → Pikku function
+
+Replace a Code-node stub's `throw new Error(...)` body with a faithful TypeScript
+reimplementation. The original JS is preserved verbatim in the JSDoc above the
+function. Keep the signature and JSDoc intact; only widen the Zod input/output if
+the code's data shape demands it.
+
+**Narrow, mechanical translation** — behavioral parity, not better code. Do not
+refactor, add error handling, or invent fields.
+
+## Process
+
+1. **Read the file.** Identify the input schema, output schema, the verbatim JS in
+   the JSDoc, and the `pikkuSessionlessFunc` shape.
+2. **Determine the n8n mode** from the original JSON if available (importer leaves it
+   in `fixtures/`, or ask). Two modes:
+   - `runOnceForAllItems` (default) — code runs once with `items: Array<{ json, binary, pairedItem }>`, returns an array of envelopes.
+   - `runOnceForEachItem` — runs once per item, `$json` / `$input.item.json` in scope, returns a single envelope.
+   - If unknown, infer: bare `items.X` → all-items; bare `$json.X` / `$input.item.X` → each-item.
+3. **Apply the rubric.**
+4. **Edit only the function body.** Leave imports, schemas, JSDoc, name, description, refs untouched unless step 5 forces it.
+5. **If the schemas are wrong** (code reads `$json.userId: string` but input is `items: z.array(z.unknown())`), tighten with the smallest change. Prefer `z.unknown()` over `z.any()`. Never widen output to `z.any()`.
+6. **Add one comment** at the top of the body noting the mode: `// translated from n8n Code node, mode: runOnceForAllItems`. This is the *only* comment you may add.
+7. **Typecheck** (`yarn tsc` from the package root); fix errors with the smallest change.
+
+## Rubric
+
+### Envelope unwrapping — all-items mode
+
+| n8n | Pikku |
+|---|---|
+| `items` | `(data.items ?? []) as any[]` (or typed if known) |
+| `items[i].json.X` | `items[i].X` |
+| `items[i].json` | `items[i]` |
+| `items[i].binary` | **NOT supported** — leave a TODO and explain |
+| `items.length` | `items.length` |
+| `items.map(i => i.json.X)` | `items.map((i: any) => i.X)` |
+
+### Envelope unwrapping — each-item mode
+
+| n8n | Pikku |
+|---|---|
+| `$json.X` / `$input.item.json.X` | `data.X` (input is the item itself) |
+| `$input.item.json` | `data` |
+| `$input.all()` | not available per-item — change to all-items mode |
+
+### Return statement
+
+| n8n | Pikku |
+|---|---|
+| `return [{ json: X }]` | `return { items: [X] }` |
+| `return items.map(i => ({ json: ... }))` | `return { items: items.map(...) }` |
+| `return [{ json: X }, { json: Y }]` | `return { items: [X, Y] }` |
+| `return { json: X }` (each-item) | `return X` |
+| `return [...]` (already plain) | wrap in `{ items: [...] }` only if the output schema expects it |
+
+### Built-ins — do NOT auto-translate
+
+If the code references any of these, **stop**, leave the body a stub, and annotate
+`// TODO:` + explain:
+
+- `this.helpers.*` (binary buffers, HTTP requests, prepareBinaryData)
+- `$node['Some Node'].json` (cross-node refs — resolve via Pikku `ref()` upstream, not in the body)
+- `$workflow`, `$execution`, `$item()`, `$items('Other Node')`
+- `getBinaryDataBuffer` / `getStaticData` — no equivalent, TODO
+- `require()` / dynamic `import()` — flag and stop
+
+Translate these only when reachable: `$now`/`$today` → `new Date()`; `$env.X` →
+`services.variables.get('X')` (never `process.env` — Pikku house rule; `services` is
+the first param).
+
+### Async / types
+
+- Original uses `await` → the body is already `async`; keep every `await`.
+- `this.helpers.httpRequest(...)` → do NOT inline; the user should use a separate
+  `httpRequest` rpc node. Leave a `// TODO:` and explain.
+- Cast `items` as `any[]` only if the schema is `z.array(z.unknown())`; use the
+  inferred type if tightened. Never `as any` on the return — fix the schema instead.
+
+## Example
+
+Before (stub):
+```ts
+/**
+ * STUB — generated from n8n Code node "Custom Code".
+ *   const total = items.reduce((acc, i) => acc + i.json.amount, 0);
+ *   return [{ json: { total } }];
+ */
+export const codeStubCustomCode = pikkuSessionlessFunc({
+  input: CodeStubCustomCodeInput,
+  output: CodeStubCustomCodeOutput,
+  func: async (_services, _data) => {
+    throw new Error('Stub: ported from n8n Code node "Custom Code" — implement me')
+  },
+})
+```
+
+After:
+```ts
+export const codeStubCustomCode = pikkuSessionlessFunc({
+  description: 'Ported from n8n Code node "Custom Code"',
+  input: CodeStubCustomCodeInput,
+  output: CodeStubCustomCodeOutput,
+  func: async (_services, data) => {
+    // translated from n8n Code node, mode: runOnceForAllItems
+    const items = (data.items ?? []) as any[]
+    const total = items.reduce((acc, i) => acc + i.amount, 0)
+    return { items: [{ total }] }
+  },
+})
+```
+
+## Report
+
+Terse: the mode you inferred (one sentence), the literal rubric translations
+applied, anything flagged TODO and why, any schema tightening (before → after).
+
+Do not add tests, refactor, edit other files, "improve" the logic, or add
+try/catch unless the original did. If the code is empty, comment-only, or so
+dependent on n8n internals that no honest translation is possible, leave the stub
+and tell the user which n8n features block it.

package/skills/pikku-n8n-import/references/loops-and-control.md

@@ -0,0 +1,87 @@
+# Loops & control stubs
+
+The importer maps the mechanical control flow (IF/Filter/Switch it can normalize →
+`graph:branch`) but leaves the **semantic** cases as `control` stubs — chiefly
+**Loop Over Items / splitInBatches** and Switch in expression mode. These need
+judgment, which is why they are not compiled. Read the loop body and the workflow
+around it; decide, or ask.
+
+## Loop Over Items / splitInBatches
+
+n8n's loop node has two outputs: **loop** (output 1, fires per batch) and **done**
+(output 0, fires once when iteration finishes). The loop body flows from the loop
+output back into the node — a cycle. Pikku graphs are a DAG, so **the loop becomes a
+`graph:map`** (`@pikku/addon-graph`) and the back-edge disappears:
+
+```ts
+theLoop: "graph:map",   // (graph:fanout) — one child invocation per item
+// config:
+theLoop: {
+  input: (ref) => ({
+    items: ref("<predecessor>"),        // what fed the loop
+    child: "<childRpc-or-subGraph>",    // the loop body
+    childInput: { /* $item-rebound body input */ },
+    stepPrefix: "theLoop",
+  }),
+  next: "<done-branch target>",          // output 0
+}
+```
+
+Inside `childInput`, references rebind to the current element: the body's `$json` /
+predecessor and any `$('<loop node>')` become `$item`.
+
+### Decide the shape first
+
+| Loop body does… | Emit |
+|---|---|
+| transform each item independently (enrich, format, call one thing) | `graph:map` — child = the body |
+| accumulate across items (running total, build one object/array) | a **reduce**: a single generated function over the whole array, not a map — `graph:map` collects per-item results and *loses* the accumulator |
+| pure side-effect per item, nothing downstream consumes results | `graph:map` with **no `next`** (done branch empty) — the safest, unambiguous case |
+
+### Child arity
+
+- **Single-node body** → `child: "<that node's rpc>"`, its input as `childInput`.
+- **Multi-node body** → the child must be a per-item **sub-graph**. Lift the body
+  into its own `pikkuWorkflowGraph` (see `pikku-workflow`) and set `child` to that
+  workflow's registered name. If the body references nodes **outside** the loop
+  (not just the item), that value has to be threaded in as `childInput` — if you
+  can't do it cleanly, stop and ask rather than emit something subtly wrong.
+
+### Done-branch semantics (ask if it matters)
+
+n8n's done output is version-dependent: it may carry the *original* items or the
+*accumulated* results. `graph:map`'s `next` receives the array of child results.
+If a downstream node reads that array's shape and the distinction matters, add:
+
+```ts
+// TODO(n8n): done branch receives collected loop results (not original items) — confirm this matches intent
+```
+
+and call it out in your summary. When the done branch is empty, there's nothing to
+decide.
+
+### batchSize > 1
+
+`graph:map` is one-item-at-a-time. A real numeric `batchSize` (chunk into groups,
+run the body per chunk) has no direct primitive — leave the stub, and tell the user
+this loop batches N-at-a-time and needs a manual pass (or a `graph:chunk` +
+`graph:map` composition if the body is chunk-shaped).
+
+## Switch / control stubs the importer couldn't normalize
+
+A Switch in **expression mode** (routing by an arbitrary JS expression rather than
+comparable conditions) stays a `control` stub. Options, in order of preference:
+
+1. If the expression is really a set of value comparisons, rewrite the node as a
+   `graph:branch` by hand (see `pikku-workflow` for the `branch` shape) and wire the
+   emitted `next` keys to the branch targets.
+2. If it's genuinely computed routing, translate the stub into a small function that
+   returns the branch key, then feed it a `graph:branch`.
+3. If neither is faithful, leave the stub and explain what the Switch does.
+
+## Never
+
+- Emit a `graph:map` for an accumulator loop — you'll silently drop the running state.
+- Guess the done-branch semantics when a downstream node depends on the shape — mark
+  it and surface it.
+- Invent a batching primitive — say what's unsupported instead.