@pikku/skills 0.12.10 → 0.12.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.10",
+  "version": "0.12.11",
   "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",
@@ -26,11 +26,11 @@
     "skills"
   ],
   "devDependencies": {
-    "@types/node": "^24.11.0",
+    "@types/node": "^24.13.3",
     "typescript": "^6.0.3",
-    "yaml": "^2.8.2"
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/skills/pikku-addon/SKILL.md

@@ -40,7 +40,7 @@ See `pikku-concepts` for the core mental model.
 Register an addon in the consuming project:
 
 ```typescript
-import { wireAddon } from '#pikku'
+import { wireAddon } from '#pikku/addon'
 
 wireAddon({
   name: string,                    // Namespace for addon functions (e.g. 'todos')
@@ -123,7 +123,7 @@ Type-safe reference to a function — local or addon — for use in any wiring.
 returns a function config that proxies the call via RPC at runtime:
 
 ```typescript
-import { ref } from '#pikku'
+import { ref } from '#pikku/function'
 
 ref('todos:addTodo') // namespace:functionName for an addon function
 ref('myLocalFunc') // a local function by name
@@ -134,7 +134,7 @@ There is no `addon()` helper; `ref()` covers both. For an addon that publishes
 `refChannel` and `refCLI`, which carry the addon's own route/config metadata:
 
 ```typescript
-import { refHTTP } from '#pikku'
+import { refHTTP } from '#pikku/function'
 
 wireHTTP(refHTTP('todos:listTodos', { basePath: '/api' }))
 ```
@@ -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'
+import { pikkuAddonServices } from '#pikku/addon/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'
+import { pikkuAddonWireServices } from '#pikku/addon/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'
+import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/addon/setup'
 import { TodoStore } from './todo-store.service.js'
 
 export const createSingletonServices = pikkuAddonServices(async () => {
@@ -213,10 +213,14 @@ 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.
+
 ```typescript
 // src/functions/addTodo.function.ts
 import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku'
+import { pikkuSessionlessFunc } from '#pikku/addon/function'
 
 const AddTodoInput = z.object({ title: z.string() })
 const AddTodoOutput = z.object({ id: z.string(), title: z.string() })
@@ -269,7 +273,7 @@ yarn add @my-org/addon-todos
 
 ```typescript
 // wirings/todos.wirings.ts
-import { wireAddon } from '#pikku'
+import { wireAddon } from '#pikku/addon'
 
 wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
 ```
@@ -290,7 +294,8 @@ export const myFunc = pikkuFunc({
 ### Wire to HTTP
 
 ```typescript
-import { wireHTTP, ref } from '#pikku'
+import { wireHTTP } from '#pikku/http'
+import { ref } from '#pikku/function'
 
 wireHTTP({
   method: 'get',
@@ -303,7 +308,8 @@ wireHTTP({
 Or batch multiple addon routes with `defineHTTPRoutes` + `wireHTTPRoutes`:
 
 ```typescript
-import { wireHTTPRoutes, defineHTTPRoutes, ref } from '#pikku'
+import { wireHTTPRoutes, defineHTTPRoutes } from '#pikku/http'
+import { ref } from '#pikku/function'
 
 const todoRoutes = defineHTTPRoutes({
   tags: ['todos'],
@@ -321,7 +327,7 @@ wireHTTPRoutes({ basePath: '/api', routes: { todos: todoRoutes } })
 
 ```typescript
 import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku'
+import { ref } from '#pikku/function'
 
 export const todoAgent = pikkuAgent({
   name: 'todo-agent',

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

@@ -40,8 +40,8 @@ my-addon/
 {
   "name": "@my-org/addon-todos",
   "imports": {
-    "#pikku": "./.pikku/pikku-types.gen.ts",
-    "#pikku/*": "./.pikku/*"
+    "#pikku/*.js": "./.pikku/*.ts",
+    "#pikku/*": "./.pikku/*/index.ts"
   },
   "exports": {
     ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },

package/skills/pikku-agent/SKILL.md

@@ -41,7 +41,7 @@ Import it from the generated agent types file — `#pikku` does not re-export it
 
 ```typescript
 import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku/pikku-types.gen.js'
+import { ref } from '#pikku/function'
 
 pikkuAgent({
   name: string,                  // Unique agent identifier
@@ -179,7 +179,7 @@ than folding it into the parent's transcript.
 
 ```typescript
 import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku/pikku-types.gen.js'
+import { ref } from '#pikku/function'
 
 export const todoAgent = pikkuAgent({
   name: 'todo-agent',
@@ -283,7 +283,7 @@ export const completeTodo = pikkuFunc({
 
 // agents/todo-assistant.agent.ts
 import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku/pikku-types.gen.js'
+import { ref } from '#pikku/function'
 
 export const todoAssistant = pikkuAgent({
   name: 'todo-assistant',

package/skills/pikku-audit/SKILL.md

@@ -38,11 +38,13 @@ An event only persists when the function opts in with **`audit: true`** — othe
 ```typescript
 import { NoopAuditService, createInvocationAudit } from '@pikku/core/services'
 
-export const createSingletonServices = pikkuServices(async (config, existing) => {
-  // Prod platforms may inject a queue-backed sink as existing.audit.
-  const audit = existing?.audit ?? new NoopAuditService()
-  return { ...existing, config, /* ... */ audit }
-})
+export const createSingletonServices = pikkuServices(
+  async (config, existing) => {
+    // Prod platforms may inject a queue-backed sink as existing.audit.
+    const audit = existing?.audit ?? new NoopAuditService()
+    return { ...existing, config, /* ... */ audit }
+  }
+)
 
 // auditLog is created per invocation from the sink. Returned unconditionally so
 // a write from a function that forgot `audit: true` warns instead of vanishing.
@@ -67,12 +69,17 @@ Mark the function `audit: true` and call `auditLog?.write(...)`. Domain history
 
 ```typescript
 export const cancelInvoice = pikkuFunc({
-  audit: true,                       // REQUIRED — else write() is a no-op
+  audit: true, // REQUIRED — else write() is a no-op
   input: CancelInvoiceInput,
   output: CancelInvoiceOutput,
   func: async ({ kysely, auditLog }, { invoiceId }, { session }) => {
-    const inv = await kysely.selectFrom('invoice')/* ... */.executeTakeFirstOrThrow()
-    await kysely.updateTable('invoice').set({ status: 'cancelled' })/* ... */.execute()
+    const inv = await kysely
+      .selectFrom('invoice') /* ... */
+      .executeTakeFirstOrThrow()
+    await kysely
+      .updateTable('invoice')
+      .set({ status: 'cancelled' }) /* ... */
+      .execute()
 
     await auditLog?.write({
       type: 'invoice.update',
@@ -108,7 +115,10 @@ import { createAuditedKysely } from '@pikku/kysely'
 export const createWireServices = pikkuWireServices(async (services, wire) => {
   if (!services.audit) return {}
   const auditLog = createInvocationAudit(services.audit, wire)
-  return { auditLog, kysely: createAuditedKysely(services.kysely, { audit: auditLog }) }
+  return {
+    auditLog,
+    kysely: createAuditedKysely(services.kysely, { audit: auditLog }),
+  }
 })
 ```
 
@@ -172,15 +182,20 @@ const rows = await kysely
 
 ```typescript
 type AuditEvent = {
-  type: string                          // e.g. 'invoice.update'
+  type: string // e.g. 'invoice.update'
   source: 'auto' | 'explicit'
-  occurredAt: string                    // auto-filled by auditLog
+  occurredAt: string // auto-filled by auditLog
   eventId?: string
   outcome?: 'success' | 'failed' | 'denied'
-  functionId?; wireType?; wireId?; traceId?; transactionId?; queryId?  // auto
+  functionId?
+  wireType?
+  wireId?
+  traceId?
+  transactionId?
+  queryId? // auto
   userIdentity?: { userId?; orgId?; pikkuUserId? } // auto from wire session
   input?: unknown
-  metadata?: Record<string, unknown>    // your domain payload
+  metadata?: Record<string, unknown> // your domain payload
 }
 ```
 

package/skills/pikku-aws/SKILL.md

@@ -64,12 +64,12 @@ provision an S3 bucket per logical bucket — the config takes only one.
 
 ### Behaviours worth knowing before you rely on them
 
-- **`signURL` fails open.** A signing error is logged and the *unsigned* URL is
+- **`signURL` fails open.** A signing error is logged and the _unsigned_ URL is
   returned rather than thrown. If your CloudFront distribution is private the
   client then gets a 403; if it isn't, you have just handed out an unrestricted
   link. Check that `signConfig` is a valid CloudFront key pair at boot.
 - **`signContentKey` builds `https://<bucketName>/<bucket>/<contentKey>`** — it
-  uses `bucketName` as the *host*. For signed content the value must therefore be
+  uses `bucketName` as the _host_. For signed content the value must therefore be
   your CloudFront domain, not a plain bucket name, which also means the same
   config field is doing two jobs.
 - **Presigned upload URLs expire after a fixed 3600s.** It is not configurable

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

@@ -5,7 +5,8 @@ description: >-
   the generated catch-all auth routes, betterAuthSession middleware, OAuth/social providers,
   email+password credentials, database adapters, and session mapping. TRIGGER when: code uses
   pikkuBetterAuth, betterAuth, betterAuthSession, createAuthHandler, user asks about Better Auth,
-  OAuth/social providers, MFA, organizations, login/logout, or @pikku/better-auth. TRIGGER when:
+  OAuth/social providers, MFA, organizations, login/logout, or @pikku/better-auth. TRIGGER when: user asks
+  about the actor plugin, /sign-in/actor, signing in as a scenario persona, or SCENARIO_ACTOR_SECRET. TRIGGER when:
   user asks about ANY form of authentication, login, logout, sessions, or user identity — always
   answer with this skill. DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security)
   or custom session services (use pikku-services).
@@ -146,6 +147,11 @@ strings):
 | delete a user and their data                                         | `admin:users:remove`     |
 | revoke a user's sessions                                             | `admin:users:sessions`   |
 | set a user's password                                                | `admin:users:password`   |
+| read credential values and who holds them                            | `admin:credentials:read` |
+| set and delete credentials                                           | `admin:credentials:manage` |
+| view declared scopes, roles, and who holds them                      | `admin:scopes:read`      |
+| create roles, change their scopes, grant them                        | `admin:scopes:manage`    |
+| read the audit trail                                                 | `admin:audit:read`       |
 
 Holding the bare `admin` scope satisfies all of them — a parent grant covers
 everything nested beneath it — so `admin` is the direct replacement for the old
@@ -166,6 +172,8 @@ defineScope({
         description: 'Application-wide credentials',
         scopes: {
           link: { description: 'Bind a shared credential for every user' },
+          read: { description: 'Read credential values and who holds them' },
+          manage: { description: 'Set and delete credentials' },
         },
       },
       users: {
@@ -179,6 +187,27 @@ defineScope({
           password: { description: "Set a user's password" },
         },
       },
+      scopes: {
+        description: 'Authorization management',
+        scopes: {
+          read: {
+            description: 'View declared scopes, roles, and who holds them',
+          },
+          manage: {
+            description:
+              'Create and delete roles, change their scopes, and grant roles to users',
+          },
+        },
+      },
+      audit: {
+        description: 'The audit trail',
+        scopes: {
+          read: {
+            description:
+              'Read the audit trail — every recorded action, and which user took it',
+          },
+        },
+      },
     },
   },
 })
@@ -191,22 +220,32 @@ a scope, so nothing is authorized, and the denial is logged at `warn` because
 that is a configuration bug rather than a permissions decision. Pass your own
 `canImpersonate` / `canLinkSingleton` to override the default entirely.
 
-### If you do wire better-auth's `admin()` plugin
+### Do not wire better-auth's `admin()` plugin
+
+Every capability in the table is pikku's own, gated by the scope next to it and
+implemented against better-auth's internal adapter — `createAuthUser`,
+`setAuthUserPassword`, `setAuthUserBanned`, `deleteAuthUser` and
+`revokeAuthUserSessions`, all exported from `@pikku/better-auth`.
 
-The last five capabilities in the table are implemented by better-auth's own
-`admin()` endpoints, which authorize against `user.role` — a column pikku
-otherwise ignores. Rather than making you maintain two grant systems,
-`syncProjectedAdminRole` keeps that column as a *projection* of the scope set:
-at the session boundary it writes `role = 'admin'` when the user holds any of
-`admin:users:{create,ban,remove,sessions,password}`, and the plugin's
-`defaultRole` otherwise. `projectedAdminRole(scopes, defaultRole)` computes the
-value if you need it yourself.
+`admin()` would add a second gate on a `user.role` column that pikku otherwise
+ignores, which means maintaining two grant systems that have to agree — and the
+column loses, since the scope store is what the rest of the framework reads.
+Pikku used to project scopes onto it for exactly that reason; dropping the
+plugin dropped the projection with it.
 
-The projection is deliberately not "any `admin:*` scope": `impersonate` and
-`users:list` are pikku's own gates, and rolling them in would hand ban and delete
-rights to someone granted only the ability to look. The plugin is auto-detected
-from the live instance, so an app without it never writes to a column that does
-not exist.
+Banning is the one capability with a schema requirement, and it has its own
+small plugin:
+
+```typescript
+import { ban } from '@pikku/better-auth'
+
+betterAuth({ plugins: [ban()] })
+```
+
+`ban()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
+create a session for a banned user, lapsing an expired ban as it goes. It makes
+no authorization decision — who may ban is decided by `admin:users:ban` — so it
+never needs to know about scopes or roles.
 
 ### 2. Production database adapter
 
@@ -273,7 +312,7 @@ export const auth = pikkuBetterAuth(async ({ secrets, variables }) => {
 Functions that require a session use `pikkuFunc` — anonymous callers are rejected automatically. `betterAuthSession` has already bridged better-auth's session into `session`:
 
 ```typescript
-import { pikkuFunc } from '#pikku'
+import { pikkuFunc } from '#pikku/function'
 
 export const me = pikkuFunc({
   expose: true,
@@ -311,11 +350,52 @@ The session cookie is `better-auth.session_token` (dev) / `__Secure-better-auth.
 
 Set `PIKKU_DEV_QUICK_LOGIN=true` and `${basePath}/dev/quick-login` signs in a
 fixed dev admin (`admin@pikku.dev`), creating the user idempotently and granting
-it the bare `admin` scope. It is guarded twice — the env var *and* a localhost
+it the bare `admin` scope. It is guarded twice — the env var _and_ a localhost
 hostname check — because a one-request path to an admin session is exactly the
 thing that must not survive a deploy. An app that has not declared the `admin`
 scope still gets a session, with a warning, since a scopeless dev user is useful.
 
+### Actor sign-in (`actor` plugin)
+
+A different thing from dev quick login, and the one to reach for when "sign in as
+someone" means **a particular kind of user** rather than one fixed admin.
+Register it explicitly — it is not automatic:
+
+```typescript
+import { actor } from '@pikku/better-auth'
+
+plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
+```
+
+`POST ${basePath}/sign-in/actor` `{ email, secret, name? }` → 200 + the normal
+session cookie. `secret` may also be a (possibly async) function, so it can come
+off the secrets service instead of a captured value.
+
+**`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
+persona.** `pikku persona sync` grants declared roles to actor accounts, so an
+`admin` persona is an actor holding real admin — anyone with the secret can take
+a session as one. Keep the endpoint **off outside development and sandbox
+deployments**: leave the secret unset on any stage that should not run scenarios,
+which is the supported switch (`Actor sign-in is not configured`), rather than
+conditionally registering the plugin. Do not treat "actors only" as a licence to
+enable it in production.
+
+Within that boundary, three properties bound the damage:
+
+- **It only ever signs in actors.** The plugin adds a `user.actor` boolean
+  column; an email matching a row without it is refused with `User is not an
+actor`. So the secret cannot take over a **real user's** account — the blast
+  radius is the actor accounts and whatever roles they were granted.
+- **Unknown emails are created**, flagged `actor: true`, so a scenario that
+  declares a new persona needs no seed step. Note the flip side: the secret
+  mints accounts, it does not merely use existing ones.
+- **The comparison is constant-time and length-hiding**, so a wrong secret leaks
+  neither the length nor a prefix of the right one.
+
+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()`.
+
 ---
 
 ## Secret Management