@pikku/skills 0.12.59 → 0.12.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.59",
+  "version": "0.12.61",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-addon/SKILL.md

@@ -49,7 +49,7 @@ wireAddon({
   rpcEndpoint?: string,            // Optional remote RPC endpoint for distributed execution
   auth?: boolean,                  // Require a session for every function in the addon
   mcp?: boolean | string[],        // true: every function the addon declared mcp: true; a list: the tools this app offers, typed against the addon's function names
-  expose?: boolean | string[],     // what rpc.exposed / POST /rpc may reach: unset/true = the addon's own expose: true, false = none, a list = exactly those (typed; PKU343 on unknown names)
+  expose?: boolean | string[],     // opt-in: what rpc.exposed / POST /rpc may reach. true = every function the addon declared expose: true, a list = those of them named (typed; PKU343 on unknown or undeclared names), unset/false = none
   tags?: string[],                 // Tags applied to all addon functions
   scopes?: string[],               // Required of every function, on top of its own
   secretOverrides?: Record<string, string>,      // Remap secret names (and grant them)
@@ -279,6 +279,45 @@ everything else. Leave it out and the addon installs fine and fails to typecheck
 in every app that depends on it, which is what `pikku validate` is there to
 catch before you publish.
 
+### Remote functions and the SDK
+
+A `remote: true` function is called over the wire by apps that use
+`wireRemoteAddon`. Those apps build against the addon's SDK, not its source, so
+**a remote function's input and output must be exported zod schemas**. If it
+uses generics (`pikkuSessionlessFunc<In, Out>`) or returns a type declared in
+`src/`, codegen fails with PKU922. Functions that are not remote can keep their
+generics.
+
+```typescript
+// src/functions/listNotes.schemas.ts
+import { z } from 'zod'
+
+export const NoteRows = z.array(z.object({ id: z.string(), body: z.string() }))
+```
+
+```typescript
+// src/functions/listNotes.function.ts
+import { pikkuSessionlessFunc } from '#pikku/addon/function'
+import { NoteRows } from './listNotes.schemas.js'
+
+export const listNotes = pikkuSessionlessFunc({
+  output: NoteRows,
+  func: async ({ kysely }) =>
+    kysely.selectFrom('notes').select(['id', 'body']).execute(),
+  remote: true,
+})
+```
+
+```bash
+yarn pikku all            # also writes .pikku/sdk/ + <scope>-<name>-<version>.sdk.tgz
+yarn pikku versions check # fails on a remote contract changed without a new version
+```
+
+In an addon, `pikku all` packs the SDK on every run, at the package.json
+version. The SDK carries only the remote RPCs, the `expose: true` workflows and
+the types they reach. Changing a published `remote: true` contract needs a new
+`version` on the function, which `pikku versions check` enforces.
+
 ### Database tables
 
 An addon may **ship** tables. It must never **create** them: it runs inside the
@@ -361,6 +400,13 @@ covered, and writes only the delta after an addon upgrade. An addon wired with
 `wireRemoteAddon` contributes no schema at all: its tables belong to the
 deployment that runs its functions.
 
+A `wireRemoteAddon` whose `package` carries a range (`'@scope/name@^1.4.0'`)
+is not installed at all: `pikku all` downloads its SDK into
+`.pikku/remote` and pins it in `pikku-addons.lock` (commit the lock). If
+codegen reports PKU338 for one, run `pikku all`, not an install; to move
+to a newer SDK, edit the range by hand (`pikku update` prints the file:line
+and the new literal; it never rewrites source), then run `pikku all`.
+
 ### Call via RPC
 
 ```typescript
@@ -381,9 +427,10 @@ and the frontend calls `rpc.invoke('todos:listTodos', …)` (over HTTP,
 Use `ref('todos:listTodos')` on an HTTP or MCP wiring only when the addon needs
 a route of its own. Don't write an app function that calls `rpc.invoke` and
 returns the result unchanged: it's a second name and a second schema for the
-same thing, and it drifts. `expose: true` exposes only what the addon itself
-declared `expose: true` — an OpenAPI-generated addon declares none, so list
-the names.
+same thing, and it drifts. Nothing in an addon is reachable over `/rpc` until
+the wiring opts in, and it can only open what the addon itself declared
+`expose: true` — an OpenAPI-generated addon declares every operation, so list
+the ones the frontend needs.
 
 Write your own function when the app needs the data narrowed, typed, or
 combined (a flag the upstream sends as `"0"`, a total summed from several

package/skills/pikku-addon/references/addon-package-manifest.md

@@ -5,6 +5,7 @@
 - Package Structure
 - pikku.config.json
 - package.json (key fields)
+- Platform service contributors (`pikku.contributors`)
 - tsconfig.json (key fields)
 
 `npx pikku new addon` scaffolds these files. You rarely hand-edit them — consult this when wiring exports or config by hand.
@@ -98,6 +99,58 @@ live in a file that never imports `#pikku` — see "Functions" in the skill.
 writes `@my-org/addon-todos/.pikku/rpc/...`, exactly as it would in an
 application, and the leaf stays the package's own business.
 
+## Platform service contributors (`pikku.contributors`)
+
+An addon can ship code that runs in the **host's** generated
+`createPlatformServices` — a log source over the host's database, a client
+built from a host secret. `wireAddon` has no field for it; the package declares
+it in its own `package.json`, the same shape as the host's `dev.contributors`:
+
+```json
+{
+  "exports": {
+    "./contributors": {
+      "types": "./dist/src/contributors.d.ts",
+      "import": "./dist/src/contributors.js"
+    }
+  },
+  "pikku": {
+    "contributors": [
+      { "module": "@my-org/addon-logs/contributors", "export": "logSources" }
+    ]
+  }
+}
+```
+
+`module` resolves from the addon's package directory. Every app that wires the
+addon (not `wireRemoteAddon`) picks the contributors up: `pikku all` emits them
+into `.pikku/pikku-dev-platform-services.gen.ts` for `pikku dev`, and
+`pikku deploy plan` / `apply` hands them to the provider adapter, after the
+app's own `deploy.contributors`.
+
+Declare what a contributor reads and sets, rather than relying on list order:
+
+```ts
+export const logSources: PlatformServiceContributor = {
+  name: 'log-sources',
+  needs: ['kysely'], // runtime.kysely, or a contributor's services.kysely
+  provides: ['logSources', 'logSources.workspace'],
+  imports: [`import { kyselyLogSource } from '@my-org/addon-logs/log-source'`],
+  emit: () => [
+    `  services.logSources = { workspace: kyselyLogSource(runtime.kysely) }`,
+  ],
+}
+```
+
+Contributors are sorted so each runs after every contributor providing one of
+its `needs`; a dotted need (`logSources.stage`) is met by a provider of the key
+or of its prefix. Emitted lines read services the entry built before them as
+`runtime.<name>` — `pikku dev` has logger, variables, secrets, schema and (with
+`db`) kysely; the standalone entry has logger, kysely (with a database) and its
+scheduler/queue/workflow/trigger services and event hub. Codegen **fails** on a
+need nothing meets, on two contributors providing the same key, and on a cycle,
+naming the contributors involved.
+
 ## tsconfig.json (key fields)
 
 ```json

package/skills/pikku-build/references/phase-4-build.md

@@ -179,8 +179,12 @@ in the repo, green or red on every future run.
 }
 ```
 
-The module exports a `PlatformServiceContributor` (`{ name, imports?, emit }`, the
-type `@pikku/deploy` takes). `pikku all` writes `.pikku/pikku-dev-platform-services.gen.ts`
+The module exports a `PlatformServiceContributor` (`{ name, needs?, provides?, imports?, emit }`, the
+type `@pikku/deploy` takes). Addons the project wires add their own, declared in their
+package.json as `pikku.contributors` (see the pikku-addon skill's package manifest
+reference). Contributors run in the order their `needs`/`provides` require, and the
+generated `createPlatformServices(env, runtime)` gets the local services as `runtime`;
+an unmet need, a key provided twice or a cycle fails `pikku all`. `pikku all` writes `.pikku/pikku-dev-platform-services.gen.ts`
 from them, and `pikku dev` merges what it returns over the local services before
 `createSingletonServices` runs, so a contributed `emailService` beats
 `LocalEmailService` (and the test-mode spy). Nothing is written without

package/skills/pikku-build/references/platform.md

@@ -60,7 +60,7 @@ Most surfaces are switched on by the CLI rather than hand-wired:
 bunx --bun pikku enable workflow      # workflow workers
 bunx --bun pikku enable agent         # public agent endpoints
 bunx --bun pikku enable events        # realtime events channel + SSE stream
-bunx --bun pikku enable remote-rpc    # internal RPC queue worker + HTTP endpoint
+bunx --bun pikku enable mesh-rpc      # mesh RPC queue worker + HTTP endpoint
 bunx --bun pikku enable webhook       # outgoing webhook delivery queue worker
 bunx --bun pikku enable scenarios     # scenario instrumentation
 bunx --bun pikku enable rpc           # public RPC endpoint

package/skills/pikku-build/references/ship.md

@@ -25,6 +25,13 @@ with Node, or a self-contained executable compiled with `bun build --compile`.
 factories the deploy codegen expects, and hand-rolling an `ExportedHandler` is
 how a worker deploy fails at runtime instead of at build.
 
+Platform services a host injects into the bundle come from contributors:
+`deploy.contributors` in `pikku.config.json` (`[{ "module", "export"? }]`, the
+same shape as `dev.contributors`) plus the `pikku.contributors` every wired addon
+declares in its package.json. `plan` and `apply` pass them all to the adapter,
+which orders them by `needs`/`provides` and, on standalone, runs them after the
+database is open, with `runtime.logger` and `runtime.kysely` in reach.
+
 Always run `plan` before `apply`, and read it. It names what will be created,
 updated and deleted — the deletions are the reason to look.
 
@@ -67,7 +74,7 @@ builds anyway (`config`, `logger`, `variables`, `schema`, `secrets`, and the
 per-request `rpc`/`mcp`/`channel`/`userSession`). Units are named for that set —
 `svc-todo-store`, `svc-event-hub-todo-store`, `svc-base` for functions needing
 nothing else — and each records it as `servicesKey` in the manifest. On the
-`templates/functions` app it turns 44 units into 10.
+`recipes/functions` app it turns 44 units into 10.
 
 The deploy target is part of the key, so a `server` unit is named `-server` and
 can never merge with its serverless twin. That is what keeps `services` from

package/skills/pikku-concepts/SKILL.md

@@ -124,6 +124,13 @@ Config lives in `pikku.config.json`:
 }
 ```
 
+A config can `extends` another (`"extends": "./pikku.config.json"`) and state only
+what differs. The child merges into the parent: objects merge key by key,
+`srcDirectories` is the parent's list plus the child's new entries, every other
+array and value the child sets replaces the parent's, and `null` removes a
+parent value. Each file's paths are relative to that file, and `rootDir` is
+inherited unless the child sets its own.
+
 ## Project Structure Convention
 
 ```text

package/skills/pikku-wiring/references/rpc.md

@@ -13,14 +13,14 @@
 | Method                           | Purpose                                   |
 | -------------------------------- | ----------------------------------------- |
 | `rpc.invoke(name, data)`         | Internal call to any wired function       |
-| `rpc.remote(name, data)`         | Remote call via DeploymentService         |
+| `rpc.mesh(name, data)`           | Mesh call via DeploymentService           |
 | `rpc.exposed(name, data)`        | Call functions marked with `expose: true` |
 | `rpc.startWorkflow(name, input)` | Start a workflow (see `pikku-workflow`)   |
 | `rpc.agent.run/stream(...)`      | Run an AI agent (see `pikku-agent`)       |
 | `rpc.agent.resume/approve(...)`  | Answer a tool-approval interrupt          |
 | `rpc.agent.interrupt(runId)`     | Stop an in-flight run                     |
 
-`rpc.invoke`, `rpc.remote` and `rpc.startWorkflow` are typed off the generated
+`rpc.invoke`, `rpc.mesh` and `rpc.startWorkflow` are typed off the generated
 RPC map, so the name and the payload are checked. `rpc.exposed` is deliberately
 `(name: string, data: any) => Promise<any>` — it exists to dispatch a name that
 arrived from outside, which by definition cannot be checked at compile time.