@pikku/skills 0.12.59 → 0.12.60

package/package.json

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

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

@@ -5,6 +5,7 @@
 - Package Structure
 - pikku.config.json
 - package.json (key fields)
+- Platform service contributors (`pikku.contributors`)
 - 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.
@@ -98,6 +99,58 @@ 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`)
+
+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`:
+
+```json
+{
+  "exports": {
+    "./contributors": {
+      "types": "./dist/src/contributors.d.ts",
+      "import": "./dist/src/contributors.js"
+    }
+  },
+  "pikku": {
+    "contributors": [
+      { "module": "@my-org/addon-logs/contributors", "export": "logSources" }
+    ]
+  }
+}
+```
+
+`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',
+  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) }`,
+  ],
+}
+```
+
+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.
+
 ## tsconfig.json (key fields)
 
 ```json

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

@@ -179,8 +179,12 @@ in the repo, green or red on every future run.
 }
 ```
 
-The module exports a `PlatformServiceContributor` (`{ name, imports?, emit }`, the
-type `@pikku/deploy` takes). `pikku all` writes `.pikku/pikku-dev-platform-services.gen.ts`
+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
 `createSingletonServices` runs, so a contributed `emailService` beats
 `LocalEmailService` (and the test-mode spy). Nothing is written without

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

@@ -25,6 +25,13 @@ 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.
+
 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/SKILL.md

@@ -124,6 +124,13 @@ Config lives in `pikku.config.json`:
 }
 ```
 
+A config can `extends` another (`"extends": "./pikku.config.json"`) and state only
+what differs. The child merges into the parent: objects merge key by key,
+`srcDirectories` is the parent's list plus the child's new entries, every other
+array and value the child sets replaces the parent's, and `null` removes a
+parent value. Each file's paths are relative to that file, and `rootDir` is
+inherited unless the child sets its own.
+
 ## Project Structure Convention
 
 ```text