@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-mcp/SKILL.md

@@ -0,0 +1,237 @@
+---
+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).'
+installGroups: [core]
+---
+
+# Pikku MCP Wiring
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+Expose Pikku functions as Model Context Protocol (MCP) tools, resources, and prompts for AI assistants like Claude, ChatGPT, and others.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions that could become MCP tools
+pikku info tags --verbose        # Understand project organization
+```
+
+See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### MCP Tools (simplest approach)
+
+Add `mcp: true` to any existing `pikkuFunc` to expose it as an MCP tool:
+
+```typescript
+const myFunc = pikkuFunc({
+  description: string,      // Used as MCP tool description
+  input: ZodSchema,         // Becomes MCP tool input schema
+  output: ZodSchema,        // Return type
+  mcp: true,                // ← Expose as MCP tool
+  func: async (services, data) => { ... },
+})
+```
+
+### MCP Resources (`pikkuMCPResourceFunc`)
+
+```typescript
+import { pikkuMCPResourceFunc } from '#pikku'
+
+const resource = pikkuMCPResourceFunc({
+  uri: string,              // URI template, e.g. 'todos/{id}'
+  title: string,            // Human-readable title
+  description?: string,
+  func: async (services, data, { mcp }) => {
+    // Must return array of { uri, text } or { uri, blob, mimeType }
+    return [{ uri: mcp.uri!, text: JSON.stringify(result) }]
+  },
+})
+```
+
+### MCP Prompts (`pikkuMCPPromptFunc`)
+
+```typescript
+import { pikkuMCPPromptFunc } from '#pikku'
+
+const prompt = pikkuMCPPromptFunc({
+  name: string,
+  description: string,
+  func: async (services, data) => {
+    // Must return array of MCP messages
+    return [
+      {
+        role: 'user',
+        content: { type: 'text', text: '...' },
+      },
+    ]
+  },
+})
+```
+
+### MCP Wire Object
+
+Inside MCP-enabled functions, `wire.mcp` provides:
+
+```typescript
+mcp.uri // Current resource URI (for resources)
+mcp.sendResourceUpdated(uri) // Notify clients a resource changed
+mcp.enableTools({ toolName: true }) // Dynamically enable/disable tools
+```
+
+## Usage Patterns
+
+### Expose Existing Functions as MCP Tools
+
+The simplest path — add `mcp: true` to any function:
+
+```typescript
+export const createTodo = pikkuFunc({
+  description: 'Create a new todo item',
+  input: CreateTodoInput,
+  output: CreateTodoOutput,
+  mcp: true,
+  func: async ({ db }, { text, priority }) => {
+    return await db.createTodo({ text, priority })
+  },
+})
+```
+
+### MCP Resources with URI Templates
+
+```typescript
+export const getTodo = pikkuMCPResourceFunc({
+  uri: 'todos/{id}',
+  title: 'Todo Details',
+  description: 'Get a todo by ID',
+  func: async ({ db }, { id }, { mcp }) => {
+    const todo = await db.getTodo(id)
+    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
+  },
+})
+```
+
+### MCP Prompts
+
+```typescript
+export const codeReview = pikkuMCPPromptFunc({
+  name: 'codeReview',
+  description: 'Generate a code review prompt',
+  func: async ({}, { filePath, context }) => {
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Review ${filePath}. Context: ${context}`,
+        },
+      },
+    ]
+  },
+})
+```
+
+### Dynamic Tool Control
+
+```typescript
+export const manageTodos = pikkuFunc({
+  description: 'Manage todo items',
+  input: ManageTodosInput,
+  output: ManageTodosOutput,
+  mcp: true,
+  func: async ({ db }, { action, id }, { mcp }) => {
+    if (action === 'delete') {
+      await db.deleteTodo(id)
+      mcp.sendResourceUpdated(`todos/${id}`)
+      await mcp.enableTools({ archiveTodos: true })
+      return { deleted: true }
+    }
+  },
+})
+```
+
+### MCP Server Setup
+
+```typescript
+// start.ts
+import { PikkuMCPServer } from '@pikku/modelcontextprotocol'
+
+const server = new PikkuMCPServer(config, singletonServices, createWireServices)
+await server.init()
+await server.start()
+```
+
+## Complete Example
+
+```typescript
+// functions/todos.functions.ts
+export const listTodos = pikkuSessionlessFunc({
+  description: 'List all todo items',
+  input: ListTodosInput,
+  output: ListTodosOutput,
+  mcp: true,
+  func: async ({ db }, { status }) => {
+    return { todos: await db.listTodos(status) }
+  },
+})
+
+export const createTodo = pikkuFunc({
+  description: 'Create a new todo item',
+  input: CreateTodoInput,
+  output: CreateTodoOutput,
+  mcp: true,
+  func: async ({ db }, { text, priority }) => {
+    return await db.createTodo({ text, priority })
+  },
+})
+
+export const completeTodo = pikkuFunc({
+  description: 'Mark a todo as complete',
+  input: CompleteTodoInput,
+  output: CompleteTodoOutput,
+  mcp: true,
+  func: async ({ db }, { todoId }) => {
+    return await db.completeTodo(todoId)
+  },
+})
+
+// functions/todos.mcp.ts
+export const getTodoResource = pikkuMCPResourceFunc({
+  uri: 'todos/{id}',
+  title: 'Todo Details',
+  description: 'Get details of a specific todo',
+  func: async ({ db }, { id }, { mcp }) => {
+    const todo = await db.getTodo(id)
+    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
+  },
+})
+
+export const planDayPrompt = pikkuMCPPromptFunc({
+  name: 'planDay',
+  description: 'Create a daily plan based on pending todos',
+  func: async ({ db }, {}) => {
+    const { todos } = await db.listTodos('pending')
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Plan my day. Here are my pending todos:\n${todos.map((t) => `- ${t.text} (${t.priority})`).join('\n')}`,
+        },
+      },
+    ]
+  },
+})
+```

package/skills/pikku-mongodb/SKILL.md

@@ -0,0 +1,102 @@
+---
+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).'
+---
+
+# Pikku MongoDB
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+`@pikku/mongodb` provides MongoDB-backed implementations of Pikku's core service interfaces.
+
+## Installation
+
+```bash
+yarn add @pikku/mongodb
+```
+
+## API Reference
+
+### `PikkuMongoDB` (Connection Wrapper)
+
+```typescript
+import { PikkuMongoDB } from '@pikku/mongodb'
+
+const mongo = new PikkuMongoDB(
+  logger: Logger,
+  clientOrUri: MongoClient | string,
+  dbName: string,
+  options?: MongoClientOptions
+)
+
+await mongo.init()
+mongo.db  // Db instance for queries
+await mongo.close()
+```
+
+### Available Services
+
+| Service                     | Interface                             | Purpose                                        |
+| --------------------------- | ------------------------------------- | ---------------------------------------------- |
+| `MongoDBChannelStore`       | `ChannelStore`                        | WebSocket channel state persistence            |
+| `MongoDBEventHubStore`      | `EventHubStore`                       | Event hub state persistence                    |
+| `MongoDBWorkflowService`    | `PikkuWorkflowService`                | Workflow definition storage                    |
+| `MongoDBWorkflowRunService` | `WorkflowRunService`                  | Workflow execution tracking                    |
+| `MongoDBDeploymentService`  | `DeploymentService`                   | Deployment state management                    |
+| `MongoDBAIStorageService`   | `AIStorageService, AIRunStateService` | AI conversation/run storage                    |
+| `MongoDBAgentRunService`    | `AgentRunService`                     | Agent execution tracking                       |
+| `MongoDBSecretService`      | `SecretService`                       | Encrypted secret storage (envelope encryption) |
+
+All services take a `Db` instance in their constructor and have an `init()` method that creates collections/indexes.
+
+### Secret Service
+
+```typescript
+import { MongoDBSecretService } from '@pikku/mongodb'
+
+const secrets = new MongoDBSecretService(mongo.db, {
+  kekSecret: 'your-key-encryption-key',
+  salt: 'your-salt',
+})
+await secrets.init()
+
+await secrets.setSecretJSON('api-key', { key: 'sk-...' })
+const value = await secrets.getSecretJSON<{ key: string }>('api-key')
+await secrets.rotateKEK()
+```
+
+## Usage Patterns
+
+### Full Setup
+
+```typescript
+import {
+  PikkuMongoDB,
+  MongoDBChannelStore,
+  MongoDBWorkflowService,
+} from '@pikku/mongodb'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const mongo = new PikkuMongoDB(logger, config.mongoUri, 'myapp')
+  await mongo.init()
+
+  const channelStore = new MongoDBChannelStore(mongo.db)
+  await channelStore.init()
+
+  const workflowService = new MongoDBWorkflowService(mongo.db)
+  await workflowService.init()
+
+  return { config, logger, database: mongo, channelStore, workflowService }
+})
+```

package/skills/pikku-n8n-addon-map/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: pikku-n8n-addon-map
+description: 'Use when mapping n8n integration stubs (gmailTool, slackTool, googleSheetsTool, plain gmail/slack action nodes, etc.) emitted by @pikku/n8n-import to real `@pikku/addon-*` functions. Triggered when the user points at a `<workflow>.integrations.json` manifest produced by `pikku-n8n-import`, says ''map the n8n integrations'', ''wire up the gmail/slack stubs'', ''replace these stubs with addon refs'', or opens a stub file generated from an n8n integration node (the stub''s JSDoc says `STUB — generated from n8n node "..." (type "n8n-nodes-base.<service>...")`). For n8n **Code** node stubs use `pikku-n8n-code-translate` instead.'
+metadata:
+  version: 1.0.0
+---
+
+# n8n Integration Stub → Pikku Addon Mapper
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+You are translating n8n integration nodes (`gmailTool`, `slackTool`, `googleSheetsTool`, plain `gmail` / `slack` action nodes, etc.) that `@pikku/n8n-import` left as throwing stubs into real `ref('<addonRpc>')` references that point at functions in installed `@pikku/addon-*` packages.
+
+This skill is **per-stub mechanical**. You do not invent business logic, you do not chain calls, you do not "improve" the workflow. You read one entry from a manifest, find the matching addon function, and rewrite the stub.
+
+## Inputs
+
+1. **Manifest file** — `<workflow>.integrations.json` next to the workflow `.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** — anything matching `@pikku/addon-*` in the project's `package.json` `dependencies`. The mapping is _only_ allowed against installed packages. If the addon for a given n8n type is not installed, surface that — do not silently skip and do not pick a vaguely-named function from another addon.
+
+## What you actually do, in order
+
+For **each** entry in the manifest:
+
+### Step 1 — identify the target addon
+
+Map `n8nType` to a `@pikku/addon-*` package by reading its source. Common shapes:
+
+| n8n type prefix                            | typical addon package candidate(s) |
+| ------------------------------------------ | ---------------------------------- |
+| `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`       |
+
+**These are guesses, not authoritative.** Always verify by reading the installed addon's `src/functions/**` to confirm the exported function names exist. If you cannot find an installed addon that plausibly covers this n8n type, stop and tell the user — do not pick a wrong addon.
+
+### Step 2 — pick the function (resource + operation → fn name)
+
+n8n integration nodes use a `(resource, operation)` pair to disambiguate. The mapping rubric:
+
+- `resource` defaults to the integration's primary noun if absent (gmail → `message`, slack → `message`, sheets → `spreadsheet`, etc.). Look at the addon's folder structure (`messages/`, `drafts/`, `channels/`) to see what nouns exist.
+- `operation` is usually a verb (`get`, `getAll`, `send`, `delete`, `addLabels`, `markAsRead`, `create`).
+- The pikku addon function name is almost always `<resource><Verb>` in camelCase, matching the file's `export const` (e.g. `messageList` for `messages/list.function.ts`, `draftCreate` for `drafts/create.function.ts`).
+
+Verify by `grep -h "^export const" <addonPkg>/src/functions/**/*.ts` and matching by name.
+
+Conventions seen in `@pikku/addon-email-gmail` (use as a sanity reference, **not** as a fallback if the addon is something else):
+
+- `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` (drafts/labels) → `<resource>Create`
+
+If the addon has a `node:` block on the function, prefer matching on that block's `category`/`displayName` over guessing — read the source.
+
+### Step 3 — rewrite the stub
+
+The stub file currently looks like:
+
+```ts
+import { z } from 'zod'
+import { pikkuSessionlessFunc } from '#pikku'
+
+export const AgentGmailtoolSendAMessageInGmailInput = z.object({
+  items: z.array(z.unknown()).optional(),
+})
+export const AgentGmailtoolSendAMessageInGmailOutput = z.object({
+  items: z.array(z.unknown()),
+})
+
+/** STUB — generated from n8n node "Send a message in Gmail" (type "n8n-nodes-base.gmailTool"). … */
+export const agentGmailtool__sendAMessageInGmail = pikkuSessionlessFunc({
+  func: async () => {
+    throw new Error('agentGmailtool__sendAMessageInGmail — implement me')
+  },
+})
+```
+
+**There are two outcomes**, depending on `isAgentTool`:
+
+#### A) `isAgentTool: true` — the stub is consumed by an agent via `ref()`
+
+The agent file references the stub by its export name. The cleanest path is:
+
+1. **Delete the stub file entirely.**
+2. In the agent file (look in the same emitted directory or `src/functions`), update the agent's `tools: [...]` array — replace `ref('agentGmailtool__sendAMessageInGmail')` with `ref('messageSend')` (or whichever addon function name you resolved).
+3. Make sure the addon package is imported wherever pikku scans functions (typically already handled by pikku CLI scanning `node_modules/@pikku/addon-*`).
+
+If you cannot delete the stub safely (e.g. it has multiple consumers, or the user wants to keep a thin wrapper for renaming), leave a _one-line_ re-export wrapper instead:
+
+```ts
+import { messageSend } from '@pikku/addon-email-gmail'
+export const agentGmailtool__sendAMessageInGmail = messageSend
+```
+
+But the default is delete + retarget. Wrappers add maintenance burden.
+
+#### B) `isAgentTool: false` — the stub is part of the workflow graph proper
+
+1. Open the workflow `.graph.ts` file.
+2. Find the entry in `nodes: { … }` whose value is the stub's rpc name (e.g. `'agentGmailtool__sendAMessageInGmail'`).
+3. Replace the value with the addon function name (e.g. `'messageSend'`).
+4. If the workflow's `config: { <id>: { input: … } }` block has an `input` expression that produces an `{ items }` envelope, rewrite it to produce the addon's actual input schema (read the addon function's `input: z.object({...})` to know the shape).
+5. Delete the stub file.
+
+### Step 4 — port hard-coded parameters
+
+n8n parameters fall into two camps:
+
+- **Hardcoded values** (e.g. `"limit": 20`, `"labelIds": ["INBOX"]`, `"sendTo": "alice@example.com"`) — these were user choices in the n8n UI. Preserve them in the workflow's `input` expression (case B), or, for agent tools (case A), document them in the agent's tool list comment so the user knows what was lost. **Agent tools cannot carry hardcoded params** — the LLM fills the args at call time. If the user _needs_ a hardcoded value baked in, they must keep a wrapper function. Surface this trade-off explicitly.
+- **`$fromAI('Name', '', 'string')` placeholders** — these are LLM-filled. They map naturally to addon function input fields the LLM will populate via the `pikkuAIAgent`'s tool-calling. No action needed beyond deleting the placeholder string; the addon's Zod schema becomes the tool schema.
+
+### Step 5 — credentials
+
+Each entry's `credentials: { gmailOAuth2: { id, name } }` is the n8n credential reference. Pikku addons typically expect a service (e.g. `services.gmail`) wired in `services.ts`. Do **not** attempt to auto-wire — append a one-line note for the user:
+
+> `// TODO: wire services.gmail using credential "Personal Gmail" (n8n id: gmail_cred_1) — see @pikku/addon-email-gmail/README.md`
+
+…either at the top of the workflow file or printed in your final summary.
+
+## What you must NOT do
+
+- **Do not invent functions** in addon packages that don't exist. Grep first.
+- **Do not pick the wrong addon** because the right one isn't installed. Stop and tell the user `npm i @pikku/addon-<x>` is required.
+- **Do not bake per-mapping tables into `@pikku/n8n-import`.** That package is intentionally addon-agnostic. All mapping logic lives here in this skill.
+- **Do not modify the manifest file.** It's an audit artifact. Leave it alone.
+- **Do not chain calls** ("send and then mark as read"). Each manifest entry maps to _one_ addon function. If the n8n graph composed multiple steps, the n8n-import already represented that as multiple stubs / multiple workflow nodes.
+- **Do not silently drop hardcoded params.** If the addon function has no place to put a value, surface it in the summary.
+
+## After you finish
+
+Print a short summary to the user:
+
+```
+Mapped 3 of 5 stubs:
+  ✓ agentGmailtool__sendAMessageInGmail → ref('messageSend')      [agent tool: Inbox Assistant]
+  ✓ agentGmailtool__getManyMessagesInGmail → ref('messageList')   [agent tool: Inbox Assistant]
+  ✓ workflow node 'updateRow' → 'sheetRowAppend'                  [graph node]
+
+Unmapped:
+  ✗ slackTool 'Post to channel'  — @pikku/addon-chat-slack not installed (npm i @pikku/addon-chat-slack)
+  ✗ notionTool 'Create page'     — no `pageCreate` in @pikku/addon-docs-notion (only `pageGet`, `pageUpdate`)
+
+Hardcoded params worth knowing:
+  • Get many messages in Gmail had limit=20, labelIds=["INBOX"] — agent tools cannot pin these; if you need them fixed, add a thin wrapper function.
+
+Credential wiring TODOs added to the top of agentGmailtool.graph.ts.
+```
+
+Be terse. The user already knows the workflow context — they pointed you at the manifest.

package/skills/pikku-n8n-code-translate/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: pikku-n8n-code-translate
+description: "Use when translating an n8n Code node body into a real Pikku function body. Triggered when the user opens or points at a stub generated by @pikku/n8n-import (look for `STUB — generated from n8n Code node` in the file's JSDoc), or when the user says 'translate this n8n code', 'port this n8n code node', 'finish the codeStub__... function', etc. The stub file is a `pikkuSessionlessFunc` with a Zod input/output, a JSDoc preserving the original n8n JavaScript verbatim, and a `throw new Error('… — implement me')` body."
+metadata:
+  version: 1.0.0
+---
+
+# n8n Code Node → Pikku Function Translator
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+You are translating an n8n **Code node** body into a Pikku `pikkuSessionlessFunc` body. The original JavaScript is preserved verbatim in the JSDoc above the function. Your job: replace the `throw new Error(...)` body with a faithful TypeScript reimplementation, keep the function signature and the JSDoc intact, and only widen the Zod input/output if the original code's data shape demands it.
+
+This is a **narrow, mechanical translation**. Do not "improve" the logic, refactor for style, add error handling, or invent fields. The goal is behavioral parity, not better code.
+
+## Process
+
+1. **Read the file** the user points you at. Identify:
+   - The exported input schema (e.g. `CodeStubCustomCodeInput`)
+   - The exported output schema (e.g. `CodeStubCustomCodeOutput`)
+   - The verbatim JavaScript inside the JSDoc block
+   - The function name and `pikkuSessionlessFunc` shape
+2. **Determine the n8n mode** from the original n8n JSON if available (the importer leaves the JSON on disk in `fixtures/` or you can ask the user). The two modes:
+   - `runOnceForAllItems` (default) — code runs once with `items: Array<{ json, binary, pairedItem }>` in scope, returns an array of envelopes.
+   - `runOnceForEachItem` — code runs once per input item, with `$json` / `$input.item.json` in scope, returns a single envelope.
+     If you can't determine the mode, infer from the code: bare `items.X` → all-items; bare `$json.X` or `$input.item.X` → each-item.
+3. **Apply the rubric below** to translate.
+4. **Edit the file** to replace only the function body. Leave the import block, schema definitions, JSDoc, function name, description, and Zod refs untouched unless step 5 forces a change.
+5. **If the schemas are wrong** (e.g. the code reads `$json.userId: string` but the input schema is `items: z.array(z.unknown())`), tighten the schemas with the smallest change that lets the code compile. Prefer `z.unknown()` over `z.any()`. Never widen output to `z.any()`.
+6. **Add a one-line comment at the top of the body** noting the n8n mode you assumed: `// translated from n8n Code node, mode: runOnceForAllItems`. This is the _only_ comment you may add.
+7. **Run the test/typecheck** if available (`yarn tsc` from the package root). Fix any type errors with the smallest viable change.
+
+## Translation rubric
+
+### Envelope unwrapping (all-items mode)
+
+The n8n `items` is an array of `{ json, binary, pairedItem }` envelopes. In Pikku, the input is typed — `data.items` is the payload array. Translate by treating `items[i]` as the payload directly.
+
+| 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` (assuming 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 output schema expects it |
+
+### n8n built-ins and helpers — do NOT auto-translate
+
+If the code references **any** of the following, **stop**, leave the body as a stub, and ask the user how to handle it (or annotate with a `// TODO:` line and explain in your reply):
+
+- `this.helpers.*` (binary buffers, HTTP requests, prepareBinaryData, etc.)
+- `$node['Some Node'].json` (cross-node references — these need to be resolved via Pikku's `ref()` upstream wiring, not in the function body)
+- `$workflow`, `$execution`, `$item()`, `$items('Other Node')`
+- `$now`, `$today`, `$env.X` — translate to `new Date()`, `new Date()`, and `services.variables.get('X')` respectively, but only if the function signature lets you reach `services` (it does — first param). NOTE: `process.env` is forbidden per Pikku house rules; always use `services.variables.get()`.
+- `getBinaryDataBuffer` / `getStaticData` — Pikku has no equivalent, leave a TODO
+- `require()` / dynamic `import()` — flag and stop
+
+### Async
+
+- If the original uses `await`, the Pikku body is already `async` — keep all `await` calls intact.
+- If the original references `this.helpers.httpRequest(...)`, **do not translate** — the user should use a separate `httpRequest` rpc node in the workflow, not embed the call. Leave a `// TODO:` and explain.
+
+### Types
+
+- Cast incoming `items` as `any[]` only if the schema is `z.array(z.unknown())`. If the user has tightened the schema, use the inferred type.
+- Never use `as any` on the _return_ value. If the return doesn't match the output schema, the schema is wrong — fix it (step 5).
+
+## Example
+
+### Before (stub the importer emitted)
+
+```ts
+import { z } from 'zod'
+import { pikkuSessionlessFunc } from '#pikku'
+
+export const CodeStubCustomCodeInput = z.object({
+  items: z.array(z.unknown()),
+})
+
+export const CodeStubCustomCodeOutput = z.object({
+  items: z.array(z.unknown()),
+})
+
+/**
+ * STUB — generated from n8n Code node "Custom Code".
+ *
+ * Original n8n JavaScript (preserved verbatim for reference; rewrite for Pikku semantics):
+ *
+ *   const total = items.reduce((acc, i) => acc + i.json.amount, 0);
+ *   return [{ json: { total } }];
+ *
+ * TODO: re-implement in TypeScript. ...
+ */
+export const codeStubCustomCode = pikkuSessionlessFunc({
+  description: 'Stub: ported from n8n Code node "Custom Code"',
+  input: CodeStubCustomCodeInput,
+  output: CodeStubCustomCodeOutput,
+  func: async (_services, _data) => {
+    throw new Error(
+      'Stub: ported from n8n Code node "Custom Code" — implement me'
+    )
+  },
+})
+```
+
+### After (your output)
+
+```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 }] }
+  },
+})
+```
+
+## What you should report back to the user
+
+A short summary, no fluff:
+
+- The mode you inferred and why (one sentence).
+- The literal translations you applied from the rubric (e.g. `items[i].json.amount → items[i].amount`).
+- Anything you flagged as a TODO and why.
+- Any schema tightening you did (with before → after).
+
+Do **not**:
+
+- Add tests
+- Refactor surrounding code
+- Edit other files unless the user asked
+- "Improve" the logic
+- Wrap things in `try/catch` unless the original did
+
+If the original is empty, contains only comments, or is so dependent on n8n internals (binary, cross-node refs, helpers) that no honest translation is possible, leave the stub in place and tell the user which n8n features are blocking it.