@pikku/skills 0.12.61 → 0.12.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.61",
+  "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[],     // 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
@@ -318,6 +326,116 @@ 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

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-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