@pikku/skills 0.12.21 → 0.12.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.21",
+  "version": "0.12.22",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-addon/SKILL.md

@@ -146,7 +146,7 @@ second argument is always present — an addon never falls back to its own logge
 variables or secrets; the consuming app supplies them:
 
 ```typescript
-import { pikkuAddonServices } from '#pikku/addon/setup'
+import { pikkuAddonServices } from '#pikku/setup'
 
 export const createSingletonServices = pikkuAddonServices(
   async (config, { secrets, logger }) => {
@@ -167,7 +167,7 @@ config object.
 Define per-request services for an addon package (created fresh per HTTP request, queue job, etc.):
 
 ```typescript
-import { pikkuAddonWireServices } from '#pikku/addon/setup'
+import { pikkuAddonWireServices } from '#pikku/setup'
 
 export const createWireServices = pikkuAddonWireServices(
   async (singletonServices, wire) => {
@@ -195,7 +195,7 @@ This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json
 
 ```typescript
 // src/services.ts
-import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/addon/setup'
+import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/setup'
 import { TodoStore } from './todo-store.service.js'
 
 export const createSingletonServices = pikkuAddonServices(async () => {
@@ -213,14 +213,15 @@ export const createWireServices = pikkuAddonWireServices(
 
 ### Functions
 
-An addon generates its whole tree under `#pikku/addon/*`, so it authors against
-`#pikku/addon/function`, `#pikku/addon/http` and so on. An application's leaves
-stay flat, which is what stops a linked addon resolving against its host.
+An addon's generated tree roots at `.pikku/addon/`, but its `imports` map points
+`#pikku/*` there, so it authors against the same subpaths an application does —
+`#pikku/function`, `#pikku/http`. The `addon` segment is the package's own
+business, never part of a specifier.
 
 ```typescript
 // src/functions/addTodo.function.ts
 import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku/addon/function'
+import { pikkuSessionlessFunc } from '#pikku/function'
 
 const AddTodoInput = z.object({ title: z.string() })
 const AddTodoOutput = z.object({ id: z.string(), title: z.string() })

package/skills/pikku-better-auth/SKILL.md

@@ -516,9 +516,9 @@ an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
 in as the personas the deployment provisioned when it started and refuses
 everything else (`No actor account exists for that address`), so holding the
 secret on such a stage does not let anyone invent identities. Those rows are
-written by `provisionPersonas` from `@pikku/better-auth`, called in the server's
-own lifecycle, so provisioning needs no actor secret and works on a stage whose
-endpoint is shut.
+written by the fabric plugin when an operator asks to act as an address the
+stage has no account for, so provisioning needs no actor secret and works on a
+stage whose endpoint is shut.
 
 **`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
 persona.** Provisioning grants declared roles to actor accounts, so an
@@ -544,30 +544,46 @@ This is the endpoint `pikku scenario` signs its actors in through, and the one
 the frontend dev switcher posts to — see `pikku-scenario` for declaring the
 actors and `pikku-react` for `useDevActors()`.
 
-### Provisioning personas (`provisionPersonas`)
+### Provisioning personas
 
-Anywhere but `pikku dev`, the accounts have to exist before anyone signs in.
-The deployment creates them itself, from its own lifecycle:
+Anywhere but `pikku dev`, the accounts have to exist before anyone signs in. The
+stage creates them itself, from the personas you hand `pikkuFabric`:
 
 ```ts
-import { provisionPersonas } from '@pikku/better-auth'
+import { pikkuFabric } from '@pikku/better-auth'
 import {
   personaConfigs,
   personaEnvironments,
 } from '#pikku/pikku-personas.gen.js'
 
-await provisionPersonas(singletonServices, {
-  personas: personaConfigs,
-  environments: personaEnvironments,
+pikkuFabric({
+  publicKey,
+  audience,
+  scopeService,
+  personas: {
+    personas: personaConfigs,
+    environments: personaEnvironments,
+  },
 })
 ```
 
-It runs where the database already is, which is the point: the CLI has no
-connection to a deployed environment's database — it resolves one from the local
-project config — so a `pikku persona sync staging` that wrote rows would write
-them to whatever database the checkout happened to point at. `pikku persona sync
-<environment>` still exists, and reports who that environment will provision and
-why anyone was skipped, which is what you run _before_ the deploy.
+There is nothing else to call and nothing to schedule. The plugin's operator
+endpoint resolves the address the caller wants to act as; a miss provisions the
+declaration and looks again. On a stage that already holds the persona that is
+one query, and the pass only runs when there is genuinely something absent to
+create.
+
+**Do not reach for `pikkuServerLifecycle`'s `afterStart` for this.** That hook is
+invoked by `pikku serve` and `pikku dev` and by nothing else — no deploy runtime
+calls it — so a stage on Workers or a serverless target that provisioned from
+`afterStart` provisioned nothing, and every persona signed in holding no roles.
+
+Provisioning runs where the database already is, which is the point: the CLI has
+no connection to a deployed environment's database — it resolves one from the
+local project config — so a `pikku persona sync staging` that wrote rows would
+write them to whatever database the checkout happened to point at. `pikku persona
+sync <environment>` still exists, and reports who that environment will provision
+and why anyone was skipped, which is what you run _before_ the deploy.
 
 It creates missing accounts as `actor: true`, applies the roles each persona
 declares, and is additive — it never revokes. `PIKKU_ENV` (or an explicit
@@ -583,10 +599,15 @@ open. By default provisioning warns about those accounts and changes nothing.
 `orphans: 'ban'` shuts them:
 
 ```ts
-await provisionPersonas(singletonServices, {
-  personas: personaConfigs,
-  environments: personaEnvironments,
-  orphans: 'ban',
+pikkuFabric({
+  publicKey,
+  audience,
+  scopeService,
+  personas: {
+    personas: personaConfigs,
+    environments: personaEnvironments,
+    orphans: 'ban',
+  },
 })
 ```
 

package/skills/pikku-build-app/SKILL.md

@@ -210,7 +210,7 @@ people the user named, and the roles they imply.
 
 ```typescript
 import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
-import { defineSystemRole } from '#pikku'
+import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
   owner: {
@@ -484,7 +484,7 @@ experiences it. Three ship in `packages/functions/test/scenarios/` — keep them
 green — and every milestone's gherkin block from §5 becomes one more.
 
 ```typescript
-import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
   title: 'A tenant reports a fault and the owner sees it',

package/skills/pikku-build-quick/SKILL.md

@@ -85,7 +85,7 @@ named:
 
 ```typescript
 import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
-import { defineSystemRole } from '#pikku'
+import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
   owner: { displayName: 'Owner', description: 'Sees only their own rows', scopes: [] },
@@ -199,7 +199,7 @@ Not the full ladder — one journey, end to end, as a real persona, so the app h
 at least one thing that stays true.
 
 ```typescript
-import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>({
   title: 'An owner creates a thing and sees it',

package/skills/pikku-concepts/SKILL.md

@@ -247,6 +247,8 @@ export const lifecycle = pikkuServerLifecycle<SingletonServices>({
 
 Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
 
+**Only `pikku dev` and `pikku serve` invoke these hooks.** No deploy runtime does, so anything a Workers or serverless stage needs done cannot live here — put it on the request path that needs it, guarded by a cheap check.
+
 **2. Bootstrap it yourself (required for a specific runtime)**
 
 Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
@@ -333,7 +335,7 @@ bottom.
 | Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
-| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                          |
+| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                      |
 | **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
 
 ### Identifiers are English, and nothing changes that

package/skills/pikku-fabric/SKILL.md

@@ -119,7 +119,7 @@ without it in production?"** If yes, it is configuration and belongs in a
 migration, however much it looks like sample data. A venue and its rooms, a
 product catalogue, a tenant, a country list, the organization the whole
 deployment hangs off — all configuration. Accounts and role grants are
-provisioning: `provisionPersonas` at deployment, or a migration. What is left
+provisioning: the fabric plugin's `personas`, or a migration. What is left
 over is the seed's job — the bookings, orders and messages a demo needs and a real
 environment starts without.
 
@@ -306,13 +306,13 @@ tells you nothing about whether it worked. `--sync` waits for a terminal state
 and exits non-zero unless the deployment went live, which is the only form worth
 running in CI:
 
-| exit | meaning |
-| ---- | ------- |
-| 0 | live (or queued, without `--sync`) |
-| 1 | the command could not run — not logged in, unsafe git state, bad flags |
-| 2 | the deployment failed, errored, timed out server-side, or was cancelled |
-| 3 | the deployment is blocked and nothing the CLI can do will unblock it |
-| 4 | the wait hit `--timeout` with the deployment still in flight |
+| exit | meaning                                                                 |
+| ---- | ----------------------------------------------------------------------- |
+| 0    | live (or queued, without `--sync`)                                      |
+| 1    | the command could not run — not logged in, unsafe git state, bad flags  |
+| 2    | the deployment failed, errored, timed out server-side, or was cancelled |
+| 3    | the deployment is blocked and nothing the CLI can do will unblock it    |
+| 4    | the wait hit `--timeout` with the deployment still in flight            |
 
 Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
 Why it parked is the whole story, and it is `statusReason`, not `status`:

package/skills/pikku-http/SKILL.md

@@ -226,7 +226,7 @@ export const getBook = pikkuFunc({
 })
 
 // wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
-import { addHTTPMiddleware } from '#pikku/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 import { cors, authBearer } from '@pikku/core/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])

package/skills/pikku-middleware/SKILL.md

@@ -23,7 +23,7 @@ installGroups: [core]
 ## The `pikkuMiddleware` Factory
 
 ```typescript
-import { pikkuMiddleware } from '#pikku/function'
+import { pikkuMiddleware } from '#pikku/middleware'
 
 // Simple: just a function
 const myMiddleware = pikkuMiddleware(async (services, wire, next) => {
@@ -139,7 +139,7 @@ Tags from the function definition and the wire object are merged — middleware
 ### Registering Tag Middleware
 
 ```typescript
-import { addTagMiddleware } from '#pikku/function'
+import { addTagMiddleware } from '#pikku/middleware'
 
 addTagMiddleware('machine-agent', [machineAgentBearerAuth])
 ```
@@ -277,7 +277,7 @@ export const getToken = () => _token
 ```typescript
 // wirings/http.wiring.ts
 import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '#pikku/function'
+import { addTagMiddleware, pikkuMiddleware } from '#pikku/middleware'
 import { UnauthorizedError } from '#pikku/error'
 import { getToken } from '../lib/host-token.js'
 

package/skills/pikku-permissions/SKILL.md

@@ -58,7 +58,7 @@ Use for checks that read the session but need no request data — and that asser
 something **beyond** merely having a session (a flag, a tier, a claim).
 
 ```typescript
-import { pikkuAuth } from '#pikku/function'
+import { pikkuAuth } from '#pikku/auth'
 
 // Good: a real gate on the session's contents, not just its existence.
 export const isVerified = pikkuAuth(
@@ -89,7 +89,7 @@ A permission answers "_may this user do this?_" (role, ownership, tier) — neve
 Use when authorization depends on the actual request data (e.g., resource ownership).
 
 ```typescript
-import { pikkuPermission } from '#pikku/function'
+import { pikkuPermission } from '#pikku/auth'
 
 export const isBookOwner = pikkuPermission(
   async ({ db }, { bookId }, { session }) => {
@@ -139,7 +139,7 @@ export const deleteBook = pikkuFunc({
 A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever _narrow_ access — it never grants access a function's own `permissions` would deny.
 
 ```typescript
-import { addGlobalPermission } from '#pikku/function'
+import { addGlobalPermission } from '#pikku/auth'
 
 addGlobalPermission([isEmployee]) // every function now also requires an employee session
 ```
@@ -248,7 +248,7 @@ declared, inspectable, and reusable.
 
 ```typescript
 // src/permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku/function'
+import { pikkuAuth, pikkuPermission } from '#pikku/auth'
 
 export const isVerified = pikkuAuth(
   async (_services, session) => !!session?.emailVerified

package/skills/pikku-scenario/SKILL.md

@@ -46,7 +46,7 @@ Scenarios live in `srcDirectories` like any other function — by convention `*.
 `pikkuScenario` comes from the **generated** workflow types, not `@pikku/core`:
 
 ```typescript
-import { pikkuScenario } from '#pikku/scenario'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const orderSupportScenario = pikkuScenario<
   { value?: number },
@@ -175,7 +175,7 @@ Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs
 `pikkuFeature` groups scenarios the way gherkin's `Feature:` groups `Scenario:`. Scenarios are referenced by **imported identifier**, so a renamed or deleted scenario is a compile error rather than a silent skip:
 
 ```typescript
-import { pikkuFeature } from '#pikku/scenario'
+import { pikkuFeature } from '#pikku/scenarios'
 import {
   credentialLazyLoadScenario,
   credentialRoundTripScenario,
@@ -240,7 +240,7 @@ Utilities are **not steps**. They are plain exported functions, they take the br
 
 ```typescript
 // shop.browser.ts — shared actions. Not steps: nothing here is an intent.
-import type { PikkuBrowserWire } from '#pikku/scenario'
+import type { PikkuBrowserWire } from '#pikku/scenarios'
 import type {} from '@pikku/playwright'
 
 /** Arrive on the shop, from wherever the browser happens to be. */
@@ -462,7 +462,7 @@ Assertions with no possible browser witness are a different thing and should not
 `scenario.do` can only name an RPC. A **step** is a named, typed unit of scenario behaviour whose body is an ordinary pikku function — so it can call several RPCs as its actor, assert, or drive a browser.
 
 ```typescript
-import { pikkuScenarioStep } from '#pikku/scenario'
+import { pikkuScenarioStep } from '#pikku/scenarios'
 
 export const buysAnApple = pikkuScenarioStep<
   { qty: number },

package/skills/pikku-security/SKILL.md

@@ -62,7 +62,7 @@ Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '#pikku/middleware'
-import { addHTTPMiddleware } from '#pikku/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 
 // JWT bearer token — reads Authorization header
 addHTTPMiddleware('*', [authBearer()])
@@ -118,7 +118,7 @@ response.
 
 ```typescript
 // permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku/function'
+import { pikkuAuth, pikkuPermission } from '#pikku/auth'
 
 export const isAuthenticated = pikkuAuth(
   async (_services, session) => !!session
@@ -129,7 +129,7 @@ export const isVerified = pikkuAuth(
 
 // wirings/auth.wiring.ts
 import { authCookie } from '#pikku/middleware'
-import { addHTTPMiddleware } from '#pikku/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 
 addHTTPMiddleware('*', [
   authCookie({

package/skills/pikku-services/SKILL.md

@@ -38,7 +38,7 @@ pikku info tags --verbose        # Understand project organization
 ### `pikkuServices(factory)` — singleton services (created once at startup)
 
 ```typescript
-import { pikkuServices } from '#pikku/function'
+import { pikkuServices } from '#pikku/setup'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'
 
@@ -61,7 +61,7 @@ export const createSingletonServices = pikkuServices(
 ### `pikkuWireServices(factory)` — per-request services (fresh per HTTP request, queue job, CLI command, etc.)
 
 ```typescript
-import { pikkuWireServices } from '#pikku/function'
+import { pikkuWireServices } from '#pikku/setup'
 
 export const createWireServices = pikkuWireServices(
   async (singletonServices, wire) => {
@@ -240,7 +240,7 @@ const createSingletonServices = pikkuServices(async (config) => {
 
 ```typescript
 // services.ts
-import { pikkuServices, pikkuWireServices } from '#pikku/function'
+import { pikkuServices, pikkuWireServices } from '#pikku/setup'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'
 

package/skills/pikku-workflow/SKILL.md

@@ -65,7 +65,7 @@ import {
 } from '#pikku/workflow/pikku-workflow-types.gen.js'
 
 // WRONG — the function leaf does not re-export them (TS2305)
-import { pikkuWorkflowFunc } from '#pikku/function'
+import { pikkuWorkflowFunc } from '#pikku/workflow'
 ```
 
 ## Defining a workflow