@pikku/skills 0.12.60 → 0.12.62

package/package.json

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

package/skills/pikku-addon/SKILL.md

@@ -47,10 +47,12 @@ wireAddon({
   name: string,                    // Namespace for addon functions (e.g. 'todos')
   package: string,                 // NPM package name (e.g. '@pikku/addon-todos')
   rpcEndpoint?: string,            // Optional remote RPC endpoint for distributed execution
+  uses?: Record<string, string>,   // alias the addon declared → name this app wired it under (only declared aliases; PKU355)
   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
+  ui?: boolean,                    // Mount the screens the addon declares with pikkuStudio
   scopes?: string[],               // Required of every function, on top of its own
   secretOverrides?: Record<string, string>,      // Remap secret names (and grant them)
   variableOverrides?: Record<string, string>,    // Remap variable names
@@ -159,6 +161,12 @@ export const createSingletonServices = pikkuAddonServices(
 )
 ```
 
+Export the call as it is. A cast around it (`pikkuAddonServices(...) as unknown
+as CreateSingletonServices<...>`, `<T>`, `!`) hides the factory
+from the inspector, which would leave it unregistered and the addon's workflows
+failing at runtime; the build fails with `PKU564` instead. Fix the type the cast
+was hiding. `satisfies` and parentheses are fine: the inspector reads through them.
+
 `secrets` and `variables` arrive **typed against the addon's own declarations**,
 and a secret is a `SecretValue` — `.reveal()` is the only way to the plaintext
 (see `pikku-services`). `pikkuAddonConfig` is the matching factory for the addon's
@@ -279,6 +287,155 @@ 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.
+
+### Calling another addon
+
+Declare it in the addon's **package.json** (not pikku.config.json), by the
+alias your code calls it by and a range:
+
+```json
+"pikku": { "uses": { "stripe": "@pikkustudio/addon-stripe@^0.12.0" } }
+```
+
+Then call it typed, with no cast and no hand-written wrapper:
+
+```typescript
+const charge = await rpc.invoke('stripe:charge', { amountCents })
+await rpc.startWorkflow('stripe:refund', { chargeId: charge.chargeId })
+```
+
+`pikku all` in the addon types `stripe:*` from the dependency's SDK (its remote
+surface). A package in the same workspace is read from its own
+`<outDir>/sdk`, so run `pikku all` there first (PKU338 if missing, PKU354 if
+its version is outside the range); anything else is fetched from the registry
+and pinned in `pikku-addons.lock`. Never cast `rpc` or call by the package
+name; the alias is the only name that works.
+
+The app wiring your addon maps the alias with `uses`, local or remote alike:
+
+```typescript
+wireRemoteAddon({
+  name: 'payments',
+  package: '@pikkustudio/addon-stripe@^0.12.0',
+  serverUrl,
+})
+wireAddon({
+  name: 'billing',
+  package: '@acme/addon-billing',
+  uses: { stripe: 'payments' },
+})
+```
+
+| Code   | The app's `pikku all` fails when                                    |
+| ------ | ------------------------------------------------------------------- |
+| PKU348 | an alias the addon declared is not mapped                           |
+| PKU347 | it is mapped to a name not wired, or wired from another package     |
+| PKU355 | `uses` maps a name the addon did not declare                        |
+| PKU354 | the mapped instance's version is outside the range                  |
+| PKU356 | the addon's `pikku.uses` entry is malformed (alias, type, no range) |
+
+At runtime an unmapped alias, or the wired name called directly, throws
+`AddonNotUsedError` (403) for invoke, workflows and agents.
+
+### Studio screens
+
+An addon declares the screens it adds to Pikku Studio with `pikkuStudio`, in
+`src/screens.ts` (`pikku new addon-ui <name>` scaffolds one). It replaces
+`defineScreens`, which no longer exists.
+
+```typescript
+import { pikkuStudio } from '@pikku/core/addon'
+
+export default pikkuStudio({
+  title: 'invoices__title', // message key: the addon's name in Studio
+  screens: [
+    {
+      path: '/invoices',
+      title: 'invoices_list__title', // message key, also the nav label
+      scope: 'project', // 'studio' → /<path>, 'team' → /<team>/<path>,
+      // 'project' → /<team>/<project>[/<target>]/<path>
+      nav: {
+        area: 'project',
+        icon: 'receipt',
+        order: 30,
+        badge: 'unpaidCount',
+      },
+      needsApp: true, // project screens only; default false
+      scopes: ['invoices:read'], // hides the screen; NOT access control
+      component: () => import('./screens/Invoices.js'),
+    },
+    {
+      path: '/invoices/print',
+      title: 'invoices_print__title',
+      scope: 'project',
+      layout: 'bare',
+      app: 'print',
+    },
+  ],
+})
+```
+
+- A screen is a lazy `component` or an `app`, never both. `nav` is optional:
+  without it the screen is routed but not listed. `nav.area` is `'rail'`,
+  `'team'`, `'project'` or `'account'`; `badge` names one of the addon's
+  functions that returns a count.
+- `replaces: true` takes over the core screen at the same path (first-party
+  addons only; Studio enforces that). `layout: 'bare'` renders without the shell.
+- Titles are message keys in the addon's `messages/{locale}.json`, found by
+  convention next to its `package.json`; there is no field for them.
+- `scopes` only hide the screen. The addon's functions must enforce the same
+  scopes.
+
+The inspector reads every field statically, so each must be a literal.
+`pikku all` fails on:
+
+| Code   | When                                                         |
+| ------ | ------------------------------------------------------------ |
+| PKU345 | a field is not a literal (variable, call, spread, bad value) |
+| PKU357 | two screens of the addon use the same path                   |
+| PKU358 | a title key is missing from `messages/en.json`               |
+| PKU359 | `nav.badge` names no function of the addon                   |
+
+A key missing from another locale's catalog is a warning.
+
 ### Database tables
 
 An addon may **ship** tables. It must never **create** them: it runs inside the
@@ -361,6 +518,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 +545,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

@@ -81,6 +81,12 @@ package that declared them, and the extra segment is what stops a linked addon's
 }
 ```
 
+**`pikku.uses` names the addons this addon calls**, as
+`{ "<alias>": "<package>@<range>" }`. The addon calls `<alias>:<fn>`, typed from
+that package's SDK, and the app wiring it maps each alias with `wireAddon`
+`uses` (see "Calling another addon" in the skill). The older list form,
+`["kysely"]`, names keys the app must map, with no SDK or version check.
+
 **`imports` names `dist`, never the source tree.** `files: ["dist"]` is the whole
 published package, and `pikku dist` copies `.pikku` and `types` into it — so a
 `#pikku/*` target under `./.pikku/` resolves for the author and for nobody else.

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

@@ -74,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-services/SKILL.md

@@ -74,6 +74,12 @@ service's paths and size limit; omitting it does not disable it.
 - **Do not take `services` as a named parameter and cast in the body.** The
   inspector reads the destructuring pattern to build the manifest; a cast makes
   the service invisible to it, so tree-shaking drops what the function needs.
+- **Do not cast a service factory.** `pikkuServices(...) as X` (or `as unknown
+as`, `!`, `<X>`) hides the call from the inspector,
+  so the factory would not be registered; the build fails with `PKU564`
+  instead. Export the direct `pikkuServices(...)` / `pikkuWireServices(...)` /
+  `pikkuConfig(...)` call and fix the type mismatch the cast was hiding.
+  `satisfies` and parentheses are fine: the inspector reads through them.
 - **Do not hand-roll an audit table.** `auditLog.write()` on an `audit: true`
   function enriches the event with the function id, wire type, trace id and user
   identity; an `insertInto('audit_log')` of your own gets none of that, and a

package/skills/pikku-wiring/SKILL.md

@@ -167,6 +167,36 @@ cron expression can decide which tasks fire. `pikku-deploy` has the comparison.
 Enabling the RPC endpoint says the endpoint exists, not who may call it — each
 `expose: true` function is still gated by its own `auth`, permissions and scopes.
 
+## A function nothing uses: wire it or disable it
+
+`pikku verify` fails on an app function that is not wired, exposed, or called
+by name (`rpc.invoke`, a workflow step, an agent tool) — `[PKU563]`, naming the
+function and its file. `pikku all` still builds; only verify fails. Addon
+functions are never flagged, in the addon or in an app that uses it.
+
+Workflows are checked too. A workflow is used when it is wired, exposed, or
+started by a literal name: `rpc.startWorkflow('name')`,
+`workflowService.startWorkflow` / `runToCompletion('name')`,
+`rpc.invoke('name')`, another workflow's step, or a client helper. A workflow
+started only through a computed name is flagged.
+
+To keep a function in the source but out of the build, mark it `disabled`:
+
+```typescript
+export const oldReport = pikkuSessionlessFunc({
+  disabled: 'replaced by liveReport', // or `true`
+  func: async () => 'old',
+})
+```
+
+A disabled function is left out of everything: meta, RPC maps, clients, MCP,
+CLI, HTTP, addon SDKs. It cannot be registered at runtime either. Anything
+that still references it — a wiring, an `rpc.invoke('oldReport')`, a workflow
+step, an agent tool — fails the build with `[PKU562]`, naming both sides.
+`pikku all` lists the disabled functions once, with file and reason.
+
+The value must be `true` or a string literal; a computed value is refused.
+
 ## What NOT to do
 
 - Do not import a wiring factory from `@pikku/core/*`. It compiles and silently

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.