@pikku/cli 0.12.20 → 0.12.22

package/skills/pikku-workflow/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: pikku-workflow
+description: 'Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku. Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
+TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows, multi-step processes, durable execution, suspend/resume, or DAG orchestration.
+DO NOT TRIGGER when: user asks about simple background jobs (use pikku-queue) or scheduled tasks (use pikku-cron).'
+installGroups: [core]
+---
+
+# Pikku Workflow 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.
+
+Build durable, multi-step workflows with automatic retry, sleep, suspend/resume, and parallel execution. Steps are cached for replay safety.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions that can be workflow steps
+pikku info tags --verbose        # Understand project organization
+```
+
+See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### `pikkuWorkflowFunc<TInput, TOutput>(fn)`
+
+```typescript
+import { pikkuWorkflowFunc } from '#pikku'
+
+const myWorkflow = pikkuWorkflowFunc<InputType, OutputType>(
+  async (services, data, { workflow }) => {
+    // workflow.do(), workflow.sleep(), workflow.suspend()
+    return result
+  }
+)
+```
+
+### Workflow Step Types
+
+```typescript
+// RPC step — execute a Pikku function as a queue job
+// workflow.do(stepName, funcName, data, options?)
+const result = await workflow.do(
+  'Create profile',
+  'createUserProfile',
+  {
+    email: data.email,
+  },
+  { retries: 3, retryDelay: '1s' }
+)
+
+// Inline step — immediate execution, cached for replay
+// workflow.do(stepName, asyncFn)
+const result = await workflow.do('Generate message', async () => {
+  return `Welcome, ${data.email}!`
+})
+
+// Sleep — durable pause (duration: '5min', '1h', '30s', '1d')
+await workflow.sleep('Wait 5 minutes', '5min')
+
+// Suspend — pause until externally resumed
+await workflow.suspend('Awaiting approval')
+```
+
+### `pikkuWorkflowGraph(config)` — DAG Workflows
+
+```typescript
+import { pikkuWorkflowGraph } from '#pikku'
+
+pikkuWorkflowGraph({
+  description: 'Onboard a new user',
+  nodes: {
+    createProfile: 'createUserProfile', // nodeName → Pikku function name
+    sendWelcome: 'sendEmail',
+  },
+  config: {
+    createProfile: {
+      next: ['sendWelcome'], // Nodes to run after this one (parallel)
+    },
+    sendWelcome: {
+      input: (ref) => ({
+        // Transform input using refs to prior node outputs
+        to: ref('createProfile', 'email'),
+        subject: 'Welcome!',
+      }),
+    },
+  },
+})
+```
+
+### HTTP Workflow Wiring
+
+```typescript
+// Start a workflow
+wireHTTP({
+  method: 'post',
+  route: '/workflow/onboard',
+  func: workflowStart('workflowName'),
+})
+
+// Execute workflow steps (called by orchestrator)
+wireHTTP({
+  method: 'post',
+  route: '/workflow/onboard/run',
+  func: workflow('workflowName'),
+})
+
+// Check workflow status
+wireHTTP({
+  method: 'get',
+  route: '/workflow/status/:runId',
+  func: workflowStatus('workflowName'),
+})
+```
+
+## Usage Patterns
+
+### Sequential Workflow
+
+```typescript
+const onboardUser = pikkuWorkflowFunc<
+  { email: string; userId: string },
+  { success: boolean }
+>(async ({}, data, { workflow }) => {
+  const user = await workflow.do('Create profile', 'createUserProfile', {
+    email: data.email,
+    userId: data.userId,
+  })
+
+  const message = await workflow.do(
+    'Generate welcome',
+    async () => `Welcome, ${data.email}!`
+  )
+
+  await workflow.sleep('Wait 5 minutes', '5min')
+
+  await workflow.do('Send email', 'sendEmail', {
+    to: data.email,
+    subject: 'Welcome!',
+    body: message,
+  })
+
+  return { success: true }
+})
+```
+
+### Parallel Execution (Fan-out)
+
+```typescript
+const users = await Promise.all(
+  data.userIds.map(
+    async (userId) =>
+      await workflow.do(`Get user ${userId}`, 'userGet', { userId })
+  )
+)
+```
+
+### Retry with Backoff
+
+```typescript
+const payment = await workflow.do(
+  'Process payment',
+  'processPayment',
+  { amount: 100 },
+  { retries: 3, retryDelay: '1s' }
+)
+```
+
+### Conditional Branching
+
+```typescript
+if (user.plan === 'pro') {
+  await workflow.do('Apply discount', 'applyDiscount', { userId })
+}
+```
+
+### Suspend and Resume
+
+```typescript
+const approval = pikkuWorkflowFunc<
+  { requestId: string },
+  { approved: boolean }
+>(async ({}, data, { workflow }) => {
+  await workflow.do('Submit request', 'submitRequest', data)
+  await workflow.suspend('Awaiting approval')
+  // Workflow pauses here until externally resumed
+  const result = await workflow.do('Check result', 'getApprovalResult', data)
+  return { approved: result.approved }
+})
+```
+
+### Graph Workflow (DAG)
+
+```typescript
+const userOnboarding = pikkuWorkflowGraph({
+  description: 'Onboard a new user',
+  nodes: {
+    createProfile: 'createUserProfile',
+    sendWelcome: 'sendEmail',
+    setupDefaults: 'createDefaultTodos',
+  },
+  config: {
+    createProfile: {
+      next: ['sendWelcome', 'setupDefaults'], // Run in parallel
+    },
+    sendWelcome: {
+      input: (ref) => ({
+        to: ref('createProfile', 'email'),
+        subject: 'Welcome!',
+      }),
+    },
+  },
+})
+```
+
+## Complete Example
+
+```typescript
+// functions/onboarding.workflow.ts
+export const onboardUser = pikkuWorkflowFunc<
+  { email: string; userId: string; plan: string },
+  { success: boolean }
+>(async ({}, data, { workflow }) => {
+  // Step 1: Create user profile
+  const user = await workflow.do('Create profile', 'createUserProfile', {
+    email: data.email,
+    userId: data.userId,
+  })
+
+  // Step 2: Set up defaults based on plan
+  if (data.plan === 'pro') {
+    await workflow.do('Apply pro features', 'enableProFeatures', {
+      userId: data.userId,
+    })
+  }
+
+  // Step 3: Send welcome email
+  await workflow.do('Send welcome', 'sendEmail', {
+    to: data.email,
+    subject: 'Welcome!',
+    body: `Welcome to our platform, ${user.name}!`,
+  })
+
+  // Step 4: Wait then send follow-up
+  await workflow.sleep('Wait 1 day', '1d')
+
+  await workflow.do('Send follow-up', 'sendEmail', {
+    to: data.email,
+    subject: 'Getting started',
+    body: 'Here are some tips to get started...',
+  })
+
+  return { success: true }
+})
+
+// wirings/workflow.wiring.ts
+wireHTTP({
+  method: 'post',
+  route: '/onboard',
+  func: workflowStart('onboardUser'),
+})
+
+wireHTTP({
+  method: 'post',
+  route: '/onboard/run',
+  func: workflow('onboardUser'),
+})
+
+wireHTTP({
+  method: 'get',
+  route: '/onboard/status/:runId',
+  func: workflowStatus('onboardUser'),
+})
+```

package/skills/pikku-workflows-client/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: pikku-workflows-client
+description: 'Run Pikku workflows from a React frontend and track their progress. Covers `useRunWorkflow` (run-and-wait), `useStartWorkflow` (fire-and-poll), and `useWorkflowStatus` (live status). TRIGGER when: a React component needs to invoke or display the status of a Pikku workflow, the user mentions long-running tasks / background jobs / progress UI tied to a workflow, or asks how to start/track a workflow from the client. DO NOT TRIGGER when: the user is wiring the workflow itself (use pikku-workflow) or only making regular RPC calls (use pikku-react-query).'
+installGroups: [core]
+---
+
+# Pikku Workflows — Client Hooks
+
+## 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.
+
+When a project has `pikkuWorkflowGraph` workflows, three React Query
+hooks are auto-generated alongside the standard RPC hooks. They handle
+the two common shapes: **run-and-wait** (short workflows where the
+client waits for the result) and **fire-and-poll** (long workflows where
+the client gets a `runId` and polls status).
+
+## Discover what workflows exist
+
+```bash
+yarn pikku meta clients --json | jq '.workflows'
+```
+
+Each entry has `name`, `description`, `mode` (inline | distributed), plus
+`input` / `output` type names. Pass the workflow **name** to the hooks
+below.
+
+## Setup
+
+These hooks are generated into the same `api.gen.ts` as `usePikkuQuery` —
+no extra setup beyond `PikkuProvider` + `QueryClientProvider` (see the
+**pikku-react** and **pikku-react-query** skills).
+
+## `useRunWorkflow(name, options?)` — run and wait
+
+For short, synchronous-feeling workflows. Returns a mutation that
+resolves to the workflow's output.
+
+```tsx
+import { useRunWorkflow } from './pikku/api.gen'
+
+function ChargeButton({ orderId }: { orderId: string }) {
+  const run = useRunWorkflow('chargeOrder', {
+    onSuccess: (output) => toast.success(`Charged: $${output.amount}`),
+  })
+  return (
+    <button onClick={() => run.mutate({ orderId })} disabled={run.isPending}>
+      {run.isPending ? 'Charging…' : 'Charge'}
+    </button>
+  )
+}
+```
+
+Use this when the workflow finishes in seconds and the UI can hold open
+a loading state until done.
+
+## `useStartWorkflow(name, options?)` — fire-and-poll
+
+Returns a mutation that resolves to `{ runId: string }` immediately. The
+workflow keeps running on the server. Pair with `useWorkflowStatus` to
+render progress.
+
+```tsx
+const start = useStartWorkflow('processVideo', {
+  onSuccess: ({ runId }) => setActiveRunId(runId),
+})
+
+start.mutate({ videoId: '123' })
+```
+
+Use this for long-running workflows (uploads, batch jobs, AI generation,
+anything you'd want a progress bar for).
+
+## `useWorkflowStatus(workflowName, runId, options?)` — observe
+
+Polls the workflow runtime for a run's status. Returns a typed status
+object with `status`, optional `output`, and optional `error`.
+
+```tsx
+import { useWorkflowStatus } from './pikku/api.gen'
+
+function VideoStatus({ runId }: { runId: string }) {
+  const { data: status } = useWorkflowStatus('processVideo', runId, {
+    refetchInterval: (query) =>
+      query.state.data?.status === 'running' ? 1000 : false,
+  })
+
+  if (!status) return null
+  if (status.status === 'running') return <Spinner />
+  if (status.status === 'completed') return <Result {...status.output} />
+  if (status.status === 'failed')
+    return <Error message={status.error?.message} />
+  return null
+}
+```
+
+Status values: `'running' | 'suspended' | 'completed' | 'failed' | 'cancelled'`.
+
+The hook stops auto-polling when the run reaches a terminal state (set
+`refetchInterval` to false in those cases — pattern shown above).
+
+## Putting it together — start + observe
+
+```tsx
+function ProcessVideoFlow({ videoId }: { videoId: string }) {
+  const [runId, setRunId] = useState<string>()
+  const start = useStartWorkflow('processVideo', {
+    onSuccess: ({ runId }) => setRunId(runId),
+  })
+  const status = useWorkflowStatus('processVideo', runId)
+
+  if (!runId) {
+    return (
+      <button
+        onClick={() => start.mutate({ videoId })}
+        disabled={start.isPending}
+      >
+        Start
+      </button>
+    )
+  }
+  return <ProgressBar status={status.data?.status} />
+}
+```
+
+## Backend: streaming richer progress
+
+The status hook returns a coarse-grained state machine (`running`,
+`completed`, etc.). For step-by-step updates inside a long workflow,
+publish events from the workflow itself via `eventHub` or open a
+WebSocket channel — out of scope for this skill (see workflow + channel
+docs).
+
+## What NOT to do
+
+- Don't poll status manually — use `useWorkflowStatus` with
+  `refetchInterval`. It dedupes and stops on terminal states.
+- Don't call `useRunWorkflow` for workflows that take more than a few
+  seconds. The user-facing component will hold a long-running pending
+  state with no progress indication; use start + status instead.
+- Don't use these hooks for non-workflow RPCs — they only resolve
+  workflow-shaped names. Regular RPCs go through `usePikkuQuery` /
+  `usePikkuMutation`.

package/skills/pikku-ws/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pikku-ws
+description: 'Use when setting up a WebSocket server with the ws library in a Pikku app. Covers the ws runtime adapter for Pikku channels.
+TRIGGER when: code uses @pikku/ws, user asks about ws library WebSocket server, or Node.js WebSocket runtime.
+DO NOT TRIGGER when: user asks about WebSocket wiring/channels (use pikku-websocket) or uWebSockets (use pikku-deploy-uws).'
+---
+
+# Pikku WS (WebSocket Server Runtime)
+
+## 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/ws` provides a WebSocket server runtime using the [ws](https://github.com/websockets/ws) library, connecting Pikku's channel system to a Node.js WebSocket server.
+
+## Installation
+
+```bash
+yarn add @pikku/ws ws
+```
+
+## Usage Patterns
+
+### Basic Setup
+
+```typescript
+import { PikkuWSServer } from '@pikku/ws'
+
+const wsServer = new PikkuWSServer({
+  server: httpServer, // Node.js HTTP server
+  singletonServices,
+  createWireServices,
+  channelStore,
+})
+
+await wsServer.init()
+```
+
+This runtime bridges the `ws` WebSocket library with Pikku's channel wiring. See `pikku-websocket` for channel wiring details and `pikku-deploy-fastify`/`pikku-deploy-express` for integrating with HTTP servers.