@pikku/skills 0.12.58 → 0.12.60

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/skills.gen.js +2 -2
  2. package/package.json +10 -7
  3. package/skills/pikku-a11y/SKILL.md +5 -3
  4. package/skills/pikku-addon/SKILL.md +8 -9
  5. package/skills/pikku-addon/references/addon-package-manifest.md +53 -0
  6. package/skills/pikku-agent/SKILL.md +16 -13
  7. package/skills/pikku-agent/references/runner-vercel.md +1 -1
  8. package/skills/pikku-architect/SKILL.md +7 -10
  9. package/skills/pikku-auth/SKILL.md +16 -20
  10. package/skills/pikku-auth/references/better-auth.md +74 -37
  11. package/skills/pikku-auth/references/sessions.md +8 -0
  12. package/skills/pikku-build/SKILL.md +36 -68
  13. package/skills/pikku-build/references/app.md +27 -828
  14. package/skills/pikku-build/references/feature.md +3 -5
  15. package/skills/pikku-build/references/phase-1-what-it-is.md +167 -0
  16. package/skills/pikku-build/references/phase-2-people-and-apps.md +133 -0
  17. package/skills/pikku-build/references/phase-3-plan.md +62 -0
  18. package/skills/pikku-build/references/phase-4-build.md +253 -0
  19. package/skills/pikku-build/references/phase-5-prove-and-ship.md +148 -0
  20. package/skills/pikku-build/references/platform.md +5 -6
  21. package/skills/pikku-build/references/quick.md +2 -2
  22. package/skills/pikku-build/references/ship.md +11 -5
  23. package/skills/pikku-changes/SKILL.md +13 -7
  24. package/skills/pikku-concepts/SKILL.md +26 -258
  25. package/skills/pikku-concepts/references/cli.md +63 -0
  26. package/skills/pikku-concepts/references/functions.md +117 -0
  27. package/skills/pikku-concepts/references/language.md +5 -5
  28. package/skills/pikku-concepts/references/packages.md +6 -4
  29. package/skills/pikku-concepts/references/testing.md +14 -0
  30. package/skills/pikku-convert-screen/SKILL.md +7 -1
  31. package/skills/pikku-deploy/SKILL.md +29 -30
  32. package/skills/pikku-deploy/references/ws.md +1 -1
  33. package/skills/pikku-emails/SKILL.md +7 -3
  34. package/skills/pikku-guide/SKILL.md +7 -10
  35. package/skills/pikku-i18n/SKILL.md +18 -19
  36. package/skills/pikku-i18n/references/messages.md +6 -8
  37. package/skills/pikku-knowledge/SKILL.md +42 -45
  38. package/skills/pikku-kysely/SKILL.md +50 -13
  39. package/skills/pikku-list-query/SKILL.md +27 -14
  40. package/skills/pikku-meta/SKILL.md +13 -16
  41. package/skills/pikku-meta/references/audit.md +1 -45
  42. package/skills/pikku-meta/references/versioning.md +1 -1
  43. package/skills/pikku-middleware/SKILL.md +23 -13
  44. package/skills/pikku-middleware/references/middleware-patterns.md +2 -2
  45. package/skills/pikku-n8n-import/SKILL.md +7 -8
  46. package/skills/pikku-permissions/SKILL.md +14 -8
  47. package/skills/pikku-react/SKILL.md +7 -6
  48. package/skills/pikku-realtime/SKILL.md +16 -11
  49. package/skills/pikku-report/SKILL.md +8 -10
  50. package/skills/pikku-scenario/SKILL.md +8 -12
  51. package/skills/pikku-scenario/references/steps.md +3 -4
  52. package/skills/pikku-scenario/references/virtual-users.md +1 -1
  53. package/skills/pikku-seo/SKILL.md +16 -8
  54. package/skills/pikku-service-backends/SKILL.md +26 -28
  55. package/skills/pikku-services/SKILL.md +8 -9
  56. package/skills/pikku-services/references/services.md +1 -1
  57. package/skills/pikku-software-archaeology/README.md +12 -1
  58. package/skills/pikku-software-archaeology/SKILL.md +9 -2
  59. package/skills/pikku-software-archaeology/references/pikku-mapping.md +1 -1
  60. package/skills/pikku-software-archaeology/references/sources/express.md +75 -0
  61. package/skills/pikku-software-archaeology/references/sources/laravel.md +77 -0
  62. package/skills/pikku-software-archaeology/references/sources/nestjs.md +73 -0
  63. package/skills/pikku-software-archaeology/references/sources/rails.md +72 -0
  64. package/skills/pikku-software-archaeology/references/tests-to-scenarios.md +72 -0
  65. package/skills/pikku-tailwind/SKILL.md +15 -16
  66. package/skills/pikku-theme/SKILL.md +15 -17
  67. package/skills/pikku-ui/SKILL.md +4 -3
  68. package/skills/pikku-webhook/SKILL.md +10 -11
  69. package/skills/pikku-wiring/SKILL.md +45 -47
  70. package/skills/pikku-wiring/references/channel.md +1 -1
  71. package/skills/pikku-wiring/references/scheduler.md +1 -1
  72. package/skills/pikku-wiring/references/trigger.md +24 -1
  73. package/skills/pikku-workflow/SKILL.md +7 -8
@@ -1,17 +1,15 @@
1
1
  ---
2
2
  name: pikku-wiring
3
3
  description: >-
4
- Use when exposing a Pikku function over a transport — HTTP routes and SSE, WebSocket channels,
5
- typed realtime pub/sub, internal and exposed RPC, queue workers, cron schedules, event triggers,
6
- MCP tools/resources/prompts, CLI commands, or a Slack gateway. Covers choosing the wiring, what
7
- every wiring shares, and what differs: function type, session source, and which calls throw
8
- instead of returning. TRIGGER when: code uses wireHTTP, defineHTTPRoutes, wireChannel,
9
- wireQueueWorker, wireScheduler, wireTrigger, wireTriggerSource, wireCLI, wireMCPResource,
10
- wireMCPPrompt, `mcp: true`, `sse: true`, `expose: true`, rpc.invoke, SlackGatewayAdapter, or the
11
- user asks how to expose, route, schedule, queue, stream or publish a function. DO NOT TRIGGER
12
- when: writing the function body (use pikku-concepts), authorization (use pikku-permissions), serving on
13
- a runtime (use pikku-deploy), building a live-updating view (use pikku-realtime), or sending
14
- outgoing webhooks (use pikku-webhook).
4
+ Exposing a Pikku function over a transport: HTTP and SSE, WebSocket channels, typed pub/sub, RPC,
5
+ queue workers, cron, event triggers, MCP tools/resources/prompts, CLI commands, Slack gateway;
6
+ choosing the wiring and what differs by function type, session source and throw-vs-return. TRIGGER
7
+ when: code uses wireHTTP, defineHTTPRoutes, wireChannel, wireQueueWorker, wireScheduler,
8
+ wireTrigger, wireTriggerSource, wireCLI, wireMCPResource, wireMCPPrompt, `mcp: true`, `sse: true`,
9
+ `expose: true`, rpc.invoke or SlackGatewayAdapter, or asked how to expose, route, schedule, queue,
10
+ stream or publish a function. DO NOT TRIGGER for function bodies (use pikku-concepts),
11
+ authorization (use pikku-permissions), runtimes (use pikku-deploy), live views (use
12
+ pikku-realtime) or outgoing webhooks (use pikku-webhook).
15
13
  installGroups: [core]
16
14
  ---
17
15
 
@@ -55,7 +53,7 @@ Three consequences that hold for every wiring below:
55
53
  - **Permissions are never declared on the wiring.** Wire-level permissions were
56
54
  removed in #972 — declare them on the function (`pikkuFunc({ permissions })`,
57
55
  see `pikku-permissions`) or app-wide via `addGlobalPermission`. Tags and
58
- patterns now target *middleware* only.
56
+ patterns now target _middleware_ only.
59
57
  - **The wire is the third argument**, not a service. `channel`, `rpc`, `session`,
60
58
  `setSession`, `mcp`, `queue`, `scheduledTask` and `cli` all live there.
61
59
 
@@ -70,30 +68,30 @@ exactly the typing that makes the wiring worth having, silently.
70
68
  naming the `#pikku` leaf to use instead. `@pikku/core/services` is the one
71
69
  subpath it exempts — the service implementations bootstrap picks.
72
70
 
73
- | Wiring | Import from |
74
- | --- | --- |
75
- | `wireHTTP`, `defineHTTPRoutes`, `wireHTTPRoutes` | `#pikku/http` |
76
- | `wireChannel`, `defineChannelRoutes` | `#pikku/channel` |
77
- | `wireQueueWorker` | `#pikku/queue` |
78
- | `wireScheduler` | `#pikku/scheduler` |
79
- | `wireTrigger`, `wireTriggerSource`, `pikkuTriggerFunc` | `#pikku/trigger` |
80
- | `wireCLI`, `pikkuCLICommand`, `pikkuCLIRender` | `#pikku/cli` |
81
- | `pikkuMCPToolFunc`, `pikkuMCPResourceFunc`, `pikkuMCPPromptFunc`, `wireMCPResource`, `wireMCPPrompt` | `#pikku/mcp` |
71
+ | Wiring | Import from |
72
+ | ---------------------------------------------------------------------------------------------------- | ------------------ |
73
+ | `wireHTTP`, `defineHTTPRoutes`, `wireHTTPRoutes` | `#pikku/http` |
74
+ | `wireChannel`, `defineChannelRoutes` | `#pikku/channel` |
75
+ | `wireQueueWorker` | `#pikku/queue` |
76
+ | `wireScheduler` | `#pikku/scheduler` |
77
+ | `wireTrigger`, `wireTriggerSource`, `pikkuTriggerFunc` | `#pikku/trigger` |
78
+ | `wireCLI`, `pikkuCLICommand`, `pikkuCLIRender` | `#pikku/cli` |
79
+ | `pikkuMCPToolFunc`, `pikkuMCPResourceFunc`, `pikkuMCPPromptFunc`, `wireMCPResource`, `wireMCPPrompt` | `#pikku/mcp` |
82
80
 
83
81
  ## Pick a wiring
84
82
 
85
- | Reach for | When | Reference |
86
- | --- | --- | --- |
87
- | **HTTP** | REST endpoints, web APIs, and SSE streams (`sse: true`, `get` only) | `references/http.md`; every field in `references/http-options.md` |
88
- | **Channel** | A hand-designed WebSocket protocol with your own action routing | `references/channel.md` |
89
- | **Realtime** | Typed pub/sub push — the scaffolded `/events` channel and SSE topics, plus subscribing to any other `sse: true` route or channel from the client | `references/realtime.md` |
90
- | **RPC** | One function calling another, or dispatching a name from outside | `references/rpc.md` |
91
- | **Queue** | Reliable background work that must survive a crash and retry | `references/queue.md` |
92
- | **Scheduler** | Recurring work on a cron expression | `references/scheduler.md` |
93
- | **Trigger** | Reacting in-process to an external event source (Redis pub/sub, PG LISTEN) | `references/trigger.md` |
94
- | **MCP** | Exposing functions to an AI assistant as tools, resources or prompts | `references/mcp.md` |
95
- | **CLI** | A terminal program with commands, subcommands and options | `references/cli.md`; end-to-end walkthrough in `references/cli-complete-example.md` |
96
- | **Gateway** | An inbound integration from a third-party product — Slack is the shipped adapter | `references/gateway-slack.md` |
83
+ | Reach for | When | Reference |
84
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
85
+ | **HTTP** | REST endpoints, web APIs, and SSE streams (`sse: true`, `get` only) | `references/http.md`; every field in `references/http-options.md` |
86
+ | **Channel** | A hand-designed WebSocket protocol with your own action routing | `references/channel.md` |
87
+ | **Realtime** | Typed pub/sub push — the scaffolded `/events` channel and SSE topics, plus subscribing to any other `sse: true` route or channel from the client | `references/realtime.md` |
88
+ | **RPC** | One function calling another, or dispatching a name from outside | `references/rpc.md` |
89
+ | **Queue** | Reliable background work that must survive a crash and retry | `references/queue.md` |
90
+ | **Scheduler** | Recurring work on a cron expression | `references/scheduler.md` |
91
+ | **Trigger** | Reacting in-process to an external event source (Redis pub/sub, PG LISTEN) | `references/trigger.md` |
92
+ | **MCP** | Exposing functions to an AI assistant as tools, resources or prompts | `references/mcp.md` |
93
+ | **CLI** | A terminal program with commands, subcommands and options | `references/cli.md`; end-to-end walkthrough in `references/cli-complete-example.md` |
94
+ | **Gateway** | An inbound integration from a third-party product — Slack is the shipped adapter | `references/gateway-slack.md` |
97
95
 
98
96
  Realtime and Channel are the pair most often confused. If the shape is "server
99
97
  pushes typed events to subscribers", use Realtime — `pikku enable events`
@@ -104,11 +102,11 @@ only when the client also sends structured messages you need to route on.
104
102
 
105
103
  ### Each wiring demands a particular function type
106
104
 
107
- | Wiring | Function type | Why |
108
- | --- | --- | --- |
109
- | HTTP, Channel, Queue, CLI, MCP | `pikkuFunc` / `pikkuSessionlessFunc` | Ordinary request/response |
110
- | Scheduler | **`pikkuVoidFunc`** | A cron has no input and no caller to return to |
111
- | Trigger *source* | **`pikkuTriggerFunc`** | Runs **once at startup**, not once per event |
105
+ | Wiring | Function type | Why |
106
+ | ------------------------------ | ------------------------------------ | ---------------------------------------------- |
107
+ | HTTP, Channel, Queue, CLI, MCP | `pikkuFunc` / `pikkuSessionlessFunc` | Ordinary request/response |
108
+ | Scheduler | **`pikkuVoidFunc`** | A cron has no input and no caller to return to |
109
+ | Trigger _source_ | **`pikkuTriggerFunc`** | Runs **once at startup**, not once per event |
112
110
 
113
111
  A trigger source is the one that surprises people: it sets up a listener, calls
114
112
  `trigger.invoke(...)` per event, and returns a teardown function. It receives
@@ -145,11 +143,11 @@ logging them as errors.
145
143
 
146
144
  ### Delivery semantics differ, and that is usually the real choice
147
145
 
148
- | Wiring | Delivery | Runs where |
149
- | --- | --- | --- |
150
- | Trigger | **At-most-once**, synchronous | In-process, alongside the listener |
151
- | Queue | **At-least-once** with retries and a dead-letter queue | Distributed workers |
152
- | Scheduler | Depends on the runtime — see below | Wherever the scheduler service runs |
146
+ | Wiring | Delivery | Runs where |
147
+ | --------- | ------------------------------------------------------ | ----------------------------------- |
148
+ | Trigger | **At-most-once**, synchronous | In-process, alongside the listener |
149
+ | Queue | **At-least-once** with retries and a dead-letter queue | Distributed workers |
150
+ | Scheduler | Depends on the runtime — see below | Wherever the scheduler service runs |
153
151
 
154
152
  Reach for a trigger to react immediately, and a queue when the work must not be
155
153
  lost. A trigger that must not drop events is a queue with extra steps.
@@ -160,11 +158,11 @@ cron expression can decide which tasks fire. `pikku-deploy` has the comparison.
160
158
 
161
159
  ### Codegen owns several wirings — do not hand-write them
162
160
 
163
- | Turn it on | Codegen writes | Never hand-write |
164
- | --- | --- | --- |
165
- | `pikku enable rpc` | `rpc-public.gen.ts` — the `POST /rpc/:rpcName` route | A second route on the same path collides |
161
+ | Turn it on | Codegen writes | Never hand-write |
162
+ | --------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
163
+ | `pikku enable rpc` | `rpc-public.gen.ts` — the `POST /rpc/:rpcName` route | A second route on the same path collides |
166
164
  | `pikku enable events` | `events.gen.ts` — the `/events` channel and `GET /events/:topic` | A hand-rolled `/events` misses disconnect cleanup |
167
- | `wireCLI` | `<program>-channel.gen.ts` — the same commands over a channel | It is regenerated on every build |
165
+ | `wireCLI` | `<program>-channel.gen.ts` — the same commands over a channel | It is regenerated on every build |
168
166
 
169
167
  Enabling the RPC endpoint says the endpoint exists, not who may call it — each
170
168
  `expose: true` function is still gated by its own `auth`, permissions and scopes.
@@ -44,7 +44,7 @@ permissions were removed in #972. Authorization lives on the function's own
44
44
  ### `pikkuChannelMiddleware(fn)`
45
45
 
46
46
  ```typescript
47
- import { pikkuChannelMiddleware } from '@pikku/core'
47
+ import { pikkuChannelMiddleware } from '@pikku/core/middleware'
48
48
 
49
49
  const middleware = pikkuChannelMiddleware(async (services, event, next) => {
50
50
  // Transform or filter events before/after
@@ -38,7 +38,7 @@ wireScheduler({
38
38
  })
39
39
  ```
40
40
 
41
- `runScheduledTask` builds its wire with a `sessionService`, so a `setSession`
41
+ `runScheduledTask` builds its wire with a `sessionService`, so a `setInitialSession`
42
42
  here is the session the function is frozen with. See the machine-auth section of
43
43
  `pikku-middleware` for the factory and for why a cron is not a user row.
44
44
 
@@ -77,6 +77,29 @@ The config-object form (`pikkuTriggerFunc({ func, title, description, tags,
77
77
  input, output })`) is also accepted when you want schemas or metadata on the
78
78
  source.
79
79
 
80
+ ### Events that belong to a user
81
+
82
+ A source that watches something on a user's behalf — polling each connected
83
+ user's mailbox, say — names that user as the second argument to `invoke`:
84
+
85
+ ```typescript
86
+ for (const userId of await credentialService.getUsersWithCredential('gmail')) {
87
+ for (const message of await fetchNewMessages(userId)) {
88
+ trigger.invoke(message, { pikkuUserId: userId })
89
+ }
90
+ }
91
+ ```
92
+
93
+ The target then runs as that user, exactly like a queue job or workflow run
94
+ carrying a `pikkuUserId`: its `type: 'wire'` credentials and its stored session
95
+ resolve for them, and a workflow target records them on the run. Without the
96
+ option the target runs as nobody.
97
+
98
+ The user is the source's assertion, not the event's — it is a separate argument
99
+ so nothing in the event data can set it. Pass only a user the source has
100
+ established itself, such as the one whose credential it just polled with, and
101
+ never an id read out of the event.
102
+
80
103
  ## Starting triggers
81
104
 
82
105
  Nothing fires until a `TriggerService` is started. For a single process,
@@ -84,7 +107,7 @@ Nothing fires until a `TriggerService` is started. For a single process,
84
107
  target and sets it up:
85
108
 
86
109
  ```typescript
87
- import { InMemoryTriggerService } from '@pikku/core/services'
110
+ import { InMemoryTriggerService } from '@pikku/core/services/in-memory-trigger'
88
111
 
89
112
  const triggerService = new InMemoryTriggerService()
90
113
  await triggerService.start()
@@ -1,14 +1,13 @@
1
1
  ---
2
2
  name: pikku-workflow
3
3
  description: >-
4
- Use when building multi-step, durable workflows with Pikku — pikkuWorkflowFunc,
5
- pikkuWorkflowGraph, workflow.do / sleep / suspend / approval, retries, compensate, sub-workflows,
6
- and starting or resuming runs. Includes deciding whether something should be a workflow at all.
7
- TRIGGER when: code uses pikkuWorkflowFunc or pikkuWorkflowGraph, or the user asks about
8
- workflows, multi-step processes, durable execution, suspend/resume, approval gates, sagas or DAG
9
- orchestration. DO NOT TRIGGER when: the user wants a single background job (use the queue
10
- reference in pikku-wiring) or a cron task (use the scheduler reference in pikku-wiring), or is
11
- converting an n8n export (use pikku-n8n-import).
4
+ Multi-step durable workflows with Pikku: pikkuWorkflowFunc, pikkuWorkflowGraph,
5
+ workflow.do/sleep/suspend/approval, retries, compensate, sub-workflows, starting/resuming runs,
6
+ and deciding whether something should be a workflow at all. TRIGGER when: code uses
7
+ pikkuWorkflowFunc or pikkuWorkflowGraph, or asked about workflows, multi-step processes, durable
8
+ execution, suspend/resume, approval gates, sagas or DAG orchestration. DO NOT TRIGGER for a single
9
+ background job or cron task (use pikku-wiring's queue/scheduler references) or n8n exports (use
10
+ pikku-n8n-import).
12
11
  installGroups: [core]
13
12
  ---
14
13