@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.
- package/dist/skills.gen.js +2 -2
- package/package.json +10 -7
- package/skills/pikku-a11y/SKILL.md +5 -3
- package/skills/pikku-addon/SKILL.md +8 -9
- package/skills/pikku-addon/references/addon-package-manifest.md +53 -0
- package/skills/pikku-agent/SKILL.md +16 -13
- package/skills/pikku-agent/references/runner-vercel.md +1 -1
- package/skills/pikku-architect/SKILL.md +7 -10
- package/skills/pikku-auth/SKILL.md +16 -20
- package/skills/pikku-auth/references/better-auth.md +74 -37
- package/skills/pikku-auth/references/sessions.md +8 -0
- package/skills/pikku-build/SKILL.md +36 -68
- package/skills/pikku-build/references/app.md +27 -828
- package/skills/pikku-build/references/feature.md +3 -5
- package/skills/pikku-build/references/phase-1-what-it-is.md +167 -0
- package/skills/pikku-build/references/phase-2-people-and-apps.md +133 -0
- package/skills/pikku-build/references/phase-3-plan.md +62 -0
- package/skills/pikku-build/references/phase-4-build.md +253 -0
- package/skills/pikku-build/references/phase-5-prove-and-ship.md +148 -0
- package/skills/pikku-build/references/platform.md +5 -6
- package/skills/pikku-build/references/quick.md +2 -2
- package/skills/pikku-build/references/ship.md +11 -5
- package/skills/pikku-changes/SKILL.md +13 -7
- package/skills/pikku-concepts/SKILL.md +26 -258
- package/skills/pikku-concepts/references/cli.md +63 -0
- package/skills/pikku-concepts/references/functions.md +117 -0
- package/skills/pikku-concepts/references/language.md +5 -5
- package/skills/pikku-concepts/references/packages.md +6 -4
- package/skills/pikku-concepts/references/testing.md +14 -0
- package/skills/pikku-convert-screen/SKILL.md +7 -1
- package/skills/pikku-deploy/SKILL.md +29 -30
- package/skills/pikku-deploy/references/ws.md +1 -1
- package/skills/pikku-emails/SKILL.md +7 -3
- package/skills/pikku-guide/SKILL.md +7 -10
- package/skills/pikku-i18n/SKILL.md +18 -19
- package/skills/pikku-i18n/references/messages.md +6 -8
- package/skills/pikku-knowledge/SKILL.md +42 -45
- package/skills/pikku-kysely/SKILL.md +50 -13
- package/skills/pikku-list-query/SKILL.md +27 -14
- package/skills/pikku-meta/SKILL.md +13 -16
- package/skills/pikku-meta/references/audit.md +1 -45
- package/skills/pikku-meta/references/versioning.md +1 -1
- package/skills/pikku-middleware/SKILL.md +23 -13
- package/skills/pikku-middleware/references/middleware-patterns.md +2 -2
- package/skills/pikku-n8n-import/SKILL.md +7 -8
- package/skills/pikku-permissions/SKILL.md +14 -8
- package/skills/pikku-react/SKILL.md +7 -6
- package/skills/pikku-realtime/SKILL.md +16 -11
- package/skills/pikku-report/SKILL.md +8 -10
- package/skills/pikku-scenario/SKILL.md +8 -12
- package/skills/pikku-scenario/references/steps.md +3 -4
- package/skills/pikku-scenario/references/virtual-users.md +1 -1
- package/skills/pikku-seo/SKILL.md +16 -8
- package/skills/pikku-service-backends/SKILL.md +26 -28
- package/skills/pikku-services/SKILL.md +8 -9
- package/skills/pikku-services/references/services.md +1 -1
- package/skills/pikku-software-archaeology/README.md +12 -1
- package/skills/pikku-software-archaeology/SKILL.md +9 -2
- package/skills/pikku-software-archaeology/references/pikku-mapping.md +1 -1
- package/skills/pikku-software-archaeology/references/sources/express.md +75 -0
- package/skills/pikku-software-archaeology/references/sources/laravel.md +77 -0
- package/skills/pikku-software-archaeology/references/sources/nestjs.md +73 -0
- package/skills/pikku-software-archaeology/references/sources/rails.md +72 -0
- package/skills/pikku-software-archaeology/references/tests-to-scenarios.md +72 -0
- package/skills/pikku-tailwind/SKILL.md +15 -16
- package/skills/pikku-theme/SKILL.md +15 -17
- package/skills/pikku-ui/SKILL.md +4 -3
- package/skills/pikku-webhook/SKILL.md +10 -11
- package/skills/pikku-wiring/SKILL.md +45 -47
- package/skills/pikku-wiring/references/channel.md +1 -1
- package/skills/pikku-wiring/references/scheduler.md +1 -1
- package/skills/pikku-wiring/references/trigger.md +24 -1
- package/skills/pikku-workflow/SKILL.md +7 -8
|
@@ -1,17 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pikku-wiring
|
|
3
3
|
description: >-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
|
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
|
|
74
|
-
|
|
|
75
|
-
| `wireHTTP`, `defineHTTPRoutes`, `wireHTTPRoutes`
|
|
76
|
-
| `wireChannel`, `defineChannelRoutes`
|
|
77
|
-
| `wireQueueWorker`
|
|
78
|
-
| `wireScheduler`
|
|
79
|
-
| `wireTrigger`, `wireTriggerSource`, `pikkuTriggerFunc`
|
|
80
|
-
| `wireCLI`, `pikkuCLICommand`, `pikkuCLIRender`
|
|
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
|
|
86
|
-
|
|
|
87
|
-
| **HTTP**
|
|
88
|
-
| **Channel**
|
|
89
|
-
| **Realtime**
|
|
90
|
-
| **RPC**
|
|
91
|
-
| **Queue**
|
|
92
|
-
| **Scheduler** | Recurring work on a cron expression
|
|
93
|
-
| **Trigger**
|
|
94
|
-
| **MCP**
|
|
95
|
-
| **CLI**
|
|
96
|
-
| **Gateway**
|
|
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
|
|
108
|
-
|
|
|
109
|
-
| HTTP, Channel, Queue, CLI, MCP | `pikkuFunc` / `pikkuSessionlessFunc` | Ordinary request/response
|
|
110
|
-
| Scheduler
|
|
111
|
-
| Trigger
|
|
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
|
|
149
|
-
|
|
|
150
|
-
| Trigger
|
|
151
|
-
| Queue
|
|
152
|
-
| Scheduler | Depends on the runtime — see below
|
|
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
|
|
164
|
-
|
|
|
165
|
-
| `pikku enable rpc`
|
|
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`
|
|
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 `
|
|
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
|
-
|
|
5
|
-
|
|
6
|
-
and
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
|