@pikku/cli 0.12.91 → 0.12.93

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

@@ -1,109 +0,0 @@
----
-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

@@ -1,84 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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

@@ -1,87 +0,0 @@
-# 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.

package/skills/pikku-paraglide/SKILL.md

@@ -1,117 +0,0 @@
----
-name: pikku-paraglide
-description: 'Generate typed, static enum-label maps for a Paraglide i18n frontend with `@pikku/paraglide`, and reconcile them against the database enum columns so a label can never silently drift from a DB value. Enum-valued labels live under a reserved `enum__<group>__<member>` message namespace; the generator emits `i18n-enum.gen.ts` typed `satisfies EnumLabel<DbEnum>`. TRIGGER when: labelling an enum/status/kind/role value in a Paraglide app, replacing a dynamic `mKey(...)`/`m[...]` lookup with a static map, wiring `@pikku/paraglide` into Vite, or reconciling i18n against `CHECK (col IN (...))` / Postgres enum columns. DO NOT TRIGGER for plain free-text UI copy (that is a normal `m.some_key()` message), backend errors, or logs.'
-installGroups: [core]
----
-
-# Pikku Paraglide enum labels
-
-## Agent Operating Procedure
-
-Use this as an execution checklist, not reference material.
-
-1. **Is the value an enum (a closed set — a status/kind/role/tag from a DB column or a fixed union)?** Then its label is a static map entry, never a dynamic lookup. Add `enum__<group>__<member>` keys to the catalog (`messages/en.json`) and read the value through the generated map: `group[value]()`.
-2. **Is the value free text or a one-off literal** (a heading, a button, a never-indexed label)? Then it is a normal Paraglide message — call `m.<key>()` directly. Do **not** invent an enum group for something that is always a literal.
-3. **Wire the generator** (`@pikku/paraglide/vite` or the CLI) so `i18n-enum.gen.ts` is regenerated from the catalog, and point it at the DB enums module (`enums.gen.ts`) so the maps are typed against the database.
-4. **Validate with the app's own `tsc`.** Reconciliation is enforced purely by types: a missing key or a dropped DB member is a compile error, and the deploy gate runs `tsc` before building. A clean `vite build` alone does not type-check.
-
-## The rules that don't change
-
-- **Never resolve an enum key dynamically.** No `mKey('status.' + value)`, no `m['enum__status__' + value]()`, no `mExists`/`mList` helpers. Dynamic keys can't be type-checked or tree-shaken. Everything is a static `m.<literal>()` reference, generated into the map.
-- **The `enum__<group>__<member>` namespace.** `__` separates the prefix / group / member segments; a single `_` joins words *within* a segment (`enum__booking_status__form_received`). The prefix (`enum`) and separator (`__`) are configurable but leave them at the defaults.
-- **Members must be valid JS identifiers.** Spell out leading digits — `two_guests`, not `2_guests`. The generator quotes an invalid member as a fallback but warns you to rename it.
-- **`asI18n(...)` is only for opaque server data** (names, slugs, ids returned from the API). Never `asI18n()` a hardcoded English string or an enum value — an enum value goes through its label map.
-
-## The generated module
-
-`i18n-enum.gen.ts` is **AUTO-GENERATED — do not edit.** It exports, per enum group:
-
-```ts
-import { m } from './messages.js'
-import type { I18nString } from '@pikku/react'
-import type { BookingStatus } from '#pikku/db/enums.gen' // when reconciled
-
-export type I18nMessage = () => I18nString
-export type EnumLabel<E extends string> = Record<E, I18nMessage>
-
-export const bookingStatus = {
-  enquiry:   m.enum__booking_status__enquiry,
-  reserved:  m.enum__booking_status__reserved,
-  confirmed: m.enum__booking_status__confirmed,
-} satisfies EnumLabel<BookingStatus>
-export type BookingStatusKey = keyof typeof bookingStatus
-```
-
-- Each value is an `I18nMessage` — a `() => I18nString` accessor. **Call it at render time** so the label tracks the active locale.
-- App code: `import { bookingStatus } from './i18n/i18n-enum.gen'` then `bookingStatus[value]()`.
-- For an open server value, gate it: `value in bookingStatus ? bookingStatus[value as BookingStatusKey]() : asI18n(value)`.
-
-### Module-scope hazard — store the accessor, don't call it
-
-A label used in a config built at module load (nav items, column defs) must hold the **accessor**, not the result — calling `m.foo()` at module scope freezes the label to the locale that was active at import:
-
-```ts
-// nav.config.ts
-const items = [{ label: m.common__nav__items__dashboard /* ← reference */ }]
-// at render: <span>{item.label()}</span>   // ← call here
-```
-
-## Reconciliation against the database
-
-The DB column is the real source of truth for what an enum can be. The pikku CLI's db codegen emits a bare unions module — `.pikku/db/enums.gen.ts` — covering **both** Postgres native enums and SQLite `CHECK (col IN ('a','b',…))` constraints:
-
-```ts
-export type BookingStatus = 'enquiry' | 'reserved' | 'confirmed' | 'ended' | 'cancelled'
-```
-
-Point `@pikku/paraglide` at that file (`enumsFile`) and each catalog group whose member set **exactly matches** a DB enum is typed `satisfies EnumLabel<DbEnum>`. The label map then **is** the reconciliation — no separate assertion:
-
-- catalog drops a DB member, or `en.json` is missing the key → `m.enum__…` doesn't exist / `Record<DbEnum,…>` isn't exhaustive → **`tsc` error naming the gap**.
-- a DB enum with **no** catalog group → `unmatchedDbEnums: 'emit'` (default) generates a label map referencing `enum__<table>_<column>__<member>` keys, so `tsc` tells you exactly which keys to add; `'warn'` only reports it.
-- a group with a member the DB lacks (a *derived* UI state, e.g. a `waitlisted` view of a `pending` row) → a drift warning. Make that a **standalone `m.<key>()` message**, not an enum member — the enum group must mirror the DB column exactly.
-
-Labelling an enum that's never rendered costs nothing: Paraglide compiles only the messages actually referenced, so unused labels are tree-shaken away. So label every DB enum; don't add an opt-out.
-
-**To make a column an enum**, give it a closed domain in the migration so codegen can see it:
-- SQLite: `status TEXT NOT NULL CHECK (status IN ('enquiry','reserved','confirmed'))`
-- Postgres: a native `CREATE TYPE … AS ENUM (…)` column.
-
-## Wiring
-
-### Vite (dev + build)
-
-Place `paraglideEnums` **after** `paraglideVitePlugin` (the generated file imports the compiled `m`). It regenerates on catalog/enums edits and only writes on change, so it never loops HMR.
-
-```ts
-import { paraglideVitePlugin } from '@inlang/paraglide-js'
-import { paraglideEnums } from '@pikku/paraglide/vite'
-
-export default defineConfig({
-  plugins: [
-    paraglideVitePlugin({ project: './project.inlang', outdir: './src/paraglide' }),
-    paraglideEnums({
-      catalog: './messages/en.json',
-      outFile: './src/i18n/i18n-enum.gen.ts',
-      enumsFile: './packages/functions/.pikku/db/enums.gen.ts', // reconcile against the DB
-      // enumsImport: '#pikku/db/enums.gen',  // explicit specifier; defaults to a relative path
-    }),
-  ],
-})
-```
-
-### CLI (CI / non-Vite), run right after `paraglide-js compile`
-
-```sh
-# paraglide-enums <catalog.json> <out.gen.ts> [messagesImport] [enums.gen.ts]
-paraglide-enums ./messages/en.json ./src/i18n/i18n-enum.gen.ts ./messages.js ./packages/functions/.pikku/db/enums.gen.ts
-```
-
-`i18n-enum.gen.ts` is generated — gitignore it once the plugin/CLI runs in the build.
-
-## What NOT to do
-
-- Don't write `mKey`/`mList`/`mExists` or any `m[expr]()` dynamic lookup — every enum label is a static generated reference.
-- Don't introduce a literal-key indirection helper (`k('approve_enquiry')`); a literal is `m.approve_enquiry()` directly.
-- Don't call `m.foo()` at module scope for config built at import time — store `m.foo` and call it at render.
-- Don't put an extra UI-only member into an enum group to match a derived state — make it a standalone message and keep the group an exact mirror of the DB column.
-- Don't hand-edit `i18n-enum.gen.ts` or `enums.gen.ts` — fix the catalog / the migration and regenerate.