@pikku/skills 0.12.62 → 0.12.64

package/package.json

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

package/skills/pikku-addon/SKILL.md

@@ -52,7 +52,7 @@ wireAddon({
   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
+  ui?: boolean,                    // Mount the screens the addon declares with definePlugin
   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
@@ -377,14 +377,14 @@ At runtime an unmapped alias, or the wired name called directly, throws
 
 ### Studio screens
 
-An addon declares the screens it adds to Pikku Studio with `pikkuStudio`, in
+An addon declares the screens it adds to Pikku Studio with `definePlugin`, 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'
+import { definePlugin } from '@pikku/core/addon'
 
-export default pikkuStudio({
+export default definePlugin({
   title: 'invoices__title', // message key: the addon's name in Studio
   screens: [
     {

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

@@ -5,7 +5,7 @@
 - Package Structure
 - pikku.config.json
 - package.json (key fields)
-- Platform service contributors (`pikku.contributors`)
+- Platform service contributors (`defineContributors`)
 - 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.
@@ -105,57 +105,72 @@ 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`)
+## Platform service contributors (`defineContributors`)
 
-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`:
+An addon can ship code that builds services for the **host's** target — a log
+source over the host's database, a client built from a host secret. The addon
+registers them in code with `defineContributors`; nothing goes in `package.json`
+and `wireAddon` of the addon itself has no field for it. A host that wants one
+opts in by name with `wireAddon({ contributors: ['log-sources'] })`, and gets
+nothing it did not list.
 
-```json
-{
-  "exports": {
-    "./contributors": {
-      "types": "./dist/src/contributors.d.ts",
-      "import": "./dist/src/contributors.js"
-    }
-  },
-  "pikku": {
-    "contributors": [
-      { "module": "@my-org/addon-logs/contributors", "export": "logSources" }
-    ]
-  }
-}
+```ts
+// src/contributors.ts
+import { defineContributors } from '@pikku/core/contributors'
+import { logSourcesDev } from './log-sources-dev.js'
+import { logSourcesDeploy } from './log-sources-deploy.js'
+
+export const contributors = defineContributors({
+  'log-sources': { dev: logSourcesDev, deploy: logSourcesDeploy },
+})
 ```
 
-`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',
+// src/log-sources-deploy.ts — each variant in its OWN module
+import type { Contributor } from '@pikku/core/contributors'
+import { kyselyLogSource } from './log-source.js'
+
+export const logSourcesDeploy: Contributor = {
   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) }`,
-  ],
+  run: (services, _env, runtime) => {
+    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.
+Rules the inspector and the build enforce:
+
+- `defineContributors` takes an object literal keyed by contributor name; each
+  `dev` / `deploy` value must be a reference to an `export const`. Anything else
+  is PKU360; a name defined twice is PKU361.
+- **Each variant lives in its own module.** The build imports the module that
+  exports the selected variant, so a `dev` and a `deploy` variant sharing a file
+  both reach every bundle, production included.
+- A contributor with no variant for a target is simply not part of it.
+- Run `pikku all` in the addon: it writes
+  `.pikku/contributors/pikku-contributors-meta.gen.json`, which a host reads to
+  opt in (an unknown name is PKU363). Ship `.pikku` in `files`.
+- `pikku.contributors` in `package.json` is removed and is now an error
+  (PKU364), not silently ignored.
+- Contributors run after every contributor providing one of their `needs`; a
+  dotted need (`logSources.stage`) is met by a provider of the key or its
+  prefix. `run` reads services the target built before it 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.
+- Two contributors providing the same key (after `when` / `requires` filtering)
+  is a build error naming both, except that a target's baseline services may be
+  replaced. A decorator declares `provides: []`. A contributor providing what it
+  needs is a cycle. An unmet `needs` is a build error.
+- `requires: ['cloudflare']` on a contributor a host opted in to, for a target
+  that cannot supply it, is a build error; use `when` to say "not here".
+- `onServerStart` / `onServerStop` run only where the server lifecycle runs
+  (dev, serve, standalone, generic server entry, Cloudflare container). On a
+  Worker `onServerStart` is a build error and `onServerStop` a warning.
+- Fail closed: a contributor whose bindings are missing at startup throws.
+
+Full reference: `docs/contributors.md` in the pikku repo.
 
 ## tsconfig.json (key fields)
 

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

@@ -10,6 +10,18 @@ Read this when a screen needs data no function returns yet, or returns in a diff
 
 The app loads its mocks with `registerPikkuMocks()` from the generated `mocks.gen.ts` beside `api.gen.ts`, called when `import.meta.env.DEV || import.meta.env.VITE_MOCK`. It covers the app's `.mocks/` and every wired addon's, so never glob `.mocks` or `node_modules` by hand.
 
+## Adding a mock
+
+`pikku mocks add <rpc>` does the whole job. It checks the RPC is a real function, writes `.mocks/<rpc with : as .>/<state>.json` and `<state>.meta.json`, keeps exactly one default (the first mock is the default, `--default` moves it) and prints the stub hook to use. The response comes from `--body '<json>'` or `--from <file>`; an error mock and an empty mock of a list have a default body.
+
+```
+pikku mocks add classes:month --body '[{"id":"c1","name":"Yoga"}]' --flag classMonth
+pikku mocks add classes:month --state empty
+pikku mocks add classes:month --state error --status 500
+```
+
+`--flag <name>` declares the flag in the project's `defineFeatureFlags({ ... })` file when it is not there yet, or prints the entry to add by hand. Nothing is overwritten without `--force`. A body that differs from the function's output is written anyway and reported, because a stub may stand in for data the function does not return yet.
+
 ## Addon mocks
 
 An addon ships default mocks in its own package as `.mocks/<function>/<scenario>.json`, named without a namespace, and lists `.mocks` in `files`. An app that wires the addon as `studio` gets them as `studio:<function>`. The app's `.mocks/studio.<function>/` adds scenarios; one with the same name replaces the addon's, and a `default: true` in the app wins over the addon's default. Put mocks for an addon's functions in the addon, and only the app's own variations in the app.

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

@@ -166,29 +166,31 @@ it is worth writing as a browser step on §7's scenario and running
 `pikku scenario run local --spawn --run browser`: same clicks, same assertions,
 in the repo, green or red on every future run.
 
-**A host can inject platform services into `pikku dev`** the way a deploy does, with
-`dev.contributors` in `pikku.config.json`:
-
-```json
-{
-  "dev": {
-    "contributors": [
-      { "module": "./dev/email-contributor.ts", "export": "email" }
-    ]
-  }
-}
+**A project can take platform services from an addon's contributors.** The addon
+registers them with `defineContributors` (an object keyed by name, each with an
+optional `dev` and `deploy` variant that is a plain `Contributor`), and the
+project opts in by name:
+
+```ts
+wireAddon({
+  name: 'inbox',
+  package: '@my-org/addon-inbox',
+  contributors: ['inbox'],
+})
 ```
 
-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
+Nothing is injected without that list. `pikku all` resolves the `dev` variants
+(dropping what `when` or `requires` rules out, ordering by `needs`/`provides`)
+and writes `.pikku/contributors/pikku-dev-contributors.gen.ts`; `pikku dev` and
+`pikku serve` merge what it builds over the local services before
 `createSingletonServices` runs, so a contributed `emailService` beats
-`LocalEmailService` (and the test-mode spy). Nothing is written without
-contributors, `pikku serve` never loads it, and `NODE_ENV=production` ignores it. An import a contributor names by `file://` URL or absolute path is written as the package export that points at it, or as a path relative to `.pikku/`, so the file typechecks under the project's tsconfig as long as the lines a contributor emits are typed.
+`LocalEmailService` (and the test-mode spy). Both skip the file under
+`NODE_ENV=production`. A contributor's `onServerStart` runs before the app's
+`beforeStart`; its `onServerStop` after the app's `afterStop`. An unmet need, a
+key provided twice or a cycle fails `pikku all`, and so does a declared database
+(`createConfig` or `db/<dialect>`) with no `db` in the pikku config. A host that
+injects an addon (CI, Studio) writes a gitignored wiring file containing
+`wireAddon({ name, package, contributors })`. Reference: `docs/contributors.md`.
 
 ## 6a. Close the changeset against its plan, not against your memory
 

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

@@ -25,12 +25,16 @@ 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.
+Platform services an addon builds for the bundle come from contributors the
+project opted in to with `wireAddon({ contributors: [...] })`; the addon
+registers them with `defineContributors`. `plan` and `apply` select the `deploy`
+variant of each, drop what `when` rules out, order them by `needs`/`provides`
+and, on standalone, run them after the database is open, with `runtime.logger`
+and `runtime.kysely` in reach. Standalone, the generic server entry and the
+Cloudflare adapter support contributors; a provider without `contributorSupport`
+fails the build when a project opts in to one with a deploy variant. On a
+Cloudflare Worker a contributor with `onServerStart` is a build error. See
+`docs/contributors.md`.
 
 Always run `plan` before `apply`, and read it. It names what will be created,
 updated and deleted — the deletions are the reason to look.

package/skills/pikku-concepts/references/concept-mapping.md

@@ -197,7 +197,7 @@ function authMiddleware(req, res, next) {
 **Pikku:**
 
 ```typescript
-import { authBearer } from '@pikku/core/middleware'
+import { authBearer } from '#pikku/middleware'
 
 // One line - handles token extraction, JWT verification, session population
 addHTTPMiddleware('*', [authBearer({})])

package/skills/pikku-meta/references/versioning.md

@@ -137,11 +137,11 @@ the manifest alone. Fix the contract or bump the version, then run it again.
 `check` is a within-repo gate — "you changed a contract without bumping
 `version:`". `release` is a release question — "what does this build owe the
 clients of the last release, and how do we ship it?". The baseline is
-`surface.pikku.json`, the snapshot committed by the previous release.
+`pikku.surface.json`, the snapshot committed by the previous release.
 
 ```bash
 npx pikku release init                                   # first run: snapshot + CHANGELOG.md
-npx pikku release diff                                   # vs surface.pikku.json
+npx pikku release diff                                   # vs pikku.surface.json
 npx pikku release diff --against https://api.acme.com/surface.json  # vs any baseline
 npx pikku release diff --fail-on major                   # PR gate
 npx pikku release snapshot --out surface.json            # write a snapshot
@@ -162,7 +162,7 @@ writes it; it never commits, tags or pushes. Who does that is your call — you
 with plain git, or a platform with its own credentials.
 
 `prepare` runs on a checkout of `origin/staging` after `pikku all`. It diffs the
-surface against `surface.pikku.json`, reads the commits production does not have
+surface against `pikku.surface.json`, reads the commits production does not have
 yet, bumps `package.json`, prepends a `CHANGELOG.md` section and rewrites the
 snapshot. No commits since the last release means nothing to release. It
 refuses when `main` has commits `staging` lacks (merge `main` into `staging`
@@ -174,7 +174,7 @@ Shipping is then one commit on top of that trunk sha:
 
 ```bash
 npx pikku release prepare
-git add package.json CHANGELOG.md surface.pikku.json
+git add package.json CHANGELOG.md pikku.surface.json
 git commit -m "release: v0.4.0"
 git tag v0.4.0
 git push --atomic origin HEAD:staging HEAD:main v0.4.0

package/skills/pikku-middleware/SKILL.md

@@ -82,7 +82,7 @@ wireHTTP({
 Runs before everything else, across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns (e.g. telemetry) that must wrap every invocation regardless of transport.
 
 ```typescript
-import { addGlobalMiddleware } from '@pikku/core/middleware'
+import { addGlobalMiddleware } from '#pikku/middleware'
 import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
 
 addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })]) // wraps the full call
@@ -95,7 +95,7 @@ addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })]) // closes
 
 ```typescript
 import { addHTTPMiddleware } from '@pikku/core/http'
-import { cors, authBearer } from '@pikku/core/middleware'
+import { cors, authBearer } from '#pikku/middleware'
 
 // All routes
 addHTTPMiddleware('*', [

package/skills/pikku-react/references/client.md

@@ -239,11 +239,29 @@ pikku.fetch.setHeader('x-tenant', tenantId)
 `authHeaders.jwt` becomes `Authorization: Bearer …` and `authHeaders.apiKey`
 becomes `X-API-KEY`; setting a JWT takes precedence over an API key.
 
+## Generated client files
+
+Name any of these under `clientFiles` in `pikku.config.json` and `pikku all` writes them, with
+import paths computed from the config:
+
+- `typesFile` — `RPCInput<'name'>`, `RPCOutput<'name'>`, `FlattenedRPCMap` (and `AnalyticsEvent`
+  when `scaffold.analytics` is on). Use these instead of reaching into the functions package.
+- `envFile` — `apiUrl()`, `basePath()`, `appHref(path)`.
+- `rpcFile` — `rpc()`, a client for code outside React such as a route `beforeLoad`. It forwards
+  the request cookie during SSR (TanStack Start). Needs `envFile`.
+- `authClientFile` — the Better Auth client glue from `@pikku/better-auth/client`. Needs
+  `rpcFile`, `envFile` and a `getSession` function; `clientAuth` sets the login and home paths.
+
+In `vite.config.ts`, `pikkuVite()` from `@pikku/vite` adds `testIds()` and, with Better Auth, the
+dev cross-site session plugin. `pikku dev` runs every frontend that sets `dev.command`
+(`--frontend a,b`, `--no-frontends`) and creates `BETTER_AUTH_SECRET` in `.env` on first run.
+
 ## What NOT to do
 
 - Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`
   goes once at the app root, the instance flows through Context.
 - Don't call `usePikkuRPC()` outside a `<PikkuProvider>` — it throws.
+- Don't copy a `rpc.ts` or `env.ts` between apps — generate them with `rpcFile` and `envFile`.
 - Don't write a custom RPC client. The generated one already covers every
   exposed function with full types.
 - Don't hardcode user-facing strings. Every display string goes through an

package/skills/pikku-theme/SKILL.md

@@ -90,8 +90,9 @@ pikku ui theme apply --preset quorum --structure monopro
 | `--structure <id>`                     | swap in another preset's structure (depth) under this brand                                                              |
 | `--primary`, `--secondary`, `--accent` | brand colours, hex                                                                                                       |
 | `--font-heading`, `--font-body`        | Google Fonts families                                                                                                    |
-| `--page`                               | light-mode page colour (`structure.page`) — paper, linen, bone instead of white                                          |
-| `--ink`                                | light-mode text colour (`structure.ink`)                                                                                 |
+| `--mode light\|dark`                   | `light` (default). `dark` makes `--page`/`--ink` the dark ground and its text (see Dark designs)                         |
+| `--page`                               | page colour (`structure.page`) — paper, linen, bone instead of white; with `--mode dark`, the dark ground                |
+| `--ink`                                | text colour (`structure.ink`); with `--mode dark`, the text on the dark ground                                           |
 
 Flags are flat scalars, one value each; there is no nested `--colors` object. One call writes the
 theme, makes it active, regenerates `themes/index.ts` (so the running app reloads) and re-brands
@@ -102,6 +103,27 @@ Fine-grained structure tweaks the flags do not cover (a shadow scale, the radius
 the active `themes/<id>.json` `structure`, followed by `pikku ui theme apply` to regenerate
 `theme.css`; keep them in the theme, not in components.
 
+## Dark designs
+
+`--page`/`--ink` are light-mode colours unless you pass `--mode dark`. For a design that is dark
+(a dark reference, a dark ground in the brief) always pass `--mode dark` with its ground and text:
+
+```bash
+pikku ui theme apply --preset linear --mode dark \
+  --primary '#c6ff3d' --secondary '#22262d' --page '#14161a' --ink '#eef1f4'
+```
+
+Every other token is derived for that ground: card and popover a step lighter, muted a further
+step, muted text a mid tone of the ink at 4.5:1 or better, border and input visibly above the card,
+and each `-foreground` black or white by contrast against its actual fill (so a lime primary gets a
+dark label). The same values are written to `:root` and `.dark` (with `color-scheme: dark`), so a
+stored scheme or `class="dark"` never switches to the preset's unrelated greys. Without
+`--mode dark`, a dark `--page` is derived as a light ground and comes out wrong.
+
+After every apply the command prints a contrast report (text/page, muted-text/page,
+primary-foreground/primary, border/page, input/page) and warns on any pair under its target; fix
+the colours and re-run, the exit code stays 0.
+
 ## Colour rule
 
 Every colour in app code comes from the theme: a semantic utility (`bg-primary`, `text-foreground`,

package/skills/pikku-theme/references/from-a-reference.md

@@ -20,6 +20,9 @@ has no extractor: you read the design off the source and pass it to `pikku ui th
    pikku ui theme apply --preset breeze --primary '#0B6E99' --font-heading 'Manrope' --font-body 'Manrope' --page '#F7F5F0' --ink '#1C2A33'
    ```
 
+   If the reference is dark, add `--mode dark` (then `--page`/`--ink` are the dark ground and its
+   text); without it a dark page is derived as a light one.
+
    You are the art director: what you read is signal, not a finished theme. Check page and ink
    against each other and against the primary for 4.5:1 before applying.
 

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

@@ -44,7 +44,7 @@ permissions were removed in #972. Authorization lives on the function's own
 ### `pikkuChannelMiddleware(fn)`
 
 ```typescript
-import { pikkuChannelMiddleware } from '@pikku/core/middleware'
+import { pikkuChannelMiddleware } from '#pikku/middleware'
 
 const middleware = pikkuChannelMiddleware(async (services, event, next) => {
   // Transform or filter events before/after

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

@@ -98,7 +98,7 @@ Authorization is not a wiring concern — declare it on the function via `permis
 ### Middleware
 
 ```typescript
-import { cors, authBearer } from '@pikku/core/middleware'
+import { cors, authBearer } from '#pikku/middleware'
 
 // Global middleware
 addHTTPMiddleware('*', [
@@ -206,7 +206,7 @@ export const getBook = pikkuFunc({
 
 // wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
 import { addHTTPMiddleware } from '#pikku/middleware'
-import { cors, authBearer } from '@pikku/core/middleware'
+import { cors, authBearer } from '#pikku/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])
 ```