@pikku/skills 0.12.29 → 0.12.32

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.29",
+  "version": "0.12.32",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikkujs/pikku.git",
+    "directory": "packages/skills"
+  },
   "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",
@@ -10,13 +15,13 @@
   "type": "module",
   "scripts": {
     "embed": "node scripts/embed.mjs",
-    "tsc": "yarn embed && tsc",
-    "build": "yarn embed && tsc -b",
+    "tsc": "bun run embed && tsc",
+    "build": "bun run embed && tsc -b",
     "ncu": "npx npm-check-updates",
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "bun run build"
   },
   "exports": {
     ".": "./dist/index.js"
@@ -27,10 +32,9 @@
   ],
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "typescript": "^6.0.3",
     "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/skills/pikku-addon/SKILL.md

@@ -324,6 +324,11 @@ wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
 
 After registration, run `yarn pikku all` to generate types for the addon's functions.
 
+Give each addon its own wiring file. A deployment unit imports a `wireAddon`
+file only while at least one addon that file wires survives the unit's filter,
+so wiring two addons from one file means a unit needing either one registers
+both and bundles both packages' dependencies.
+
 If the addon ships tables, `pikku db generate` then writes one migration per
 addon — named after the package, carrying the addon's own SQL — after Better
 Auth's and the runtime's, so an addon table may reference `user` or a runtime

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

@@ -23,6 +23,85 @@ how a worker deploy fails at runtime instead of at build.
 Always run `plan` before `apply`, and read it. It names what will be created,
 updated and deleted — the deletions are the reason to look.
 
+### How many workers you get
+
+By default a unit holds every function that builds the same set of singleton
+services. One unit per function is available too, but on a large app it means a
+hundred workers whose bundles are mostly the same framework code repeated, and a
+build and an upload for each. `deploy.grouping` in `pikku.config.json` sets the
+shape:
+
+```json
+"deploy": {
+  "grouping": {
+    "strategy": "single",
+    "rules": [
+      { "unit": "console", "addon": "console" },
+      { "unit": "pdf", "tags": ["pdf"] }
+    ]
+  }
+}
+```
+
+`strategy` is the fallback for a function no rule matches:
+
+| strategy | fallback |
+| --- | --- |
+| `services` | one unit per distinct set of singleton services (the default) |
+| `function` | one unit each |
+| `single` | one shared unit |
+
+Rules are ordered, first match wins, and match on `tags`, an `addon` namespace
+or `routes` globs. A rule always beats the strategy, so under `function` a rule
+merges and under `single` or `services` it carves out.
+
+`services` is the default because it is the middle ground: `single` is too
+coarse to reason about and `function` pays a cold start and a deploy step per
+function. Functions are keyed
+on the singleton services their bodies destructure, minus the ones every unit
+builds anyway (`config`, `logger`, `variables`, `schema`, `secrets`, and the
+per-request `rpc`/`mcp`/`channel`/`userSession`). Units are named for that set —
+`svc-todo-store`, `svc-event-hub-todo-store`, `svc-base` for functions needing
+nothing else — and each records it as `servicesKey` in the manifest. On the
+`templates/functions` app it turns 44 units into 10.
+
+The deploy target is part of the key, so a `server` unit is named `-server` and
+can never merge with its serverless twin. That is what keeps `services` from
+tripping the mixed-target refusal below: two functions can carry identical
+services and still run in different places, because a function may name
+`deploy: 'server'` itself without any service crossing it.
+
+Read the shape before trusting it. The partition depends entirely on how varied
+the app's service use is: an app where nearly every function reaches the same
+database collapses to roughly `single` with a few carve-outs. Run `pikku deploy
+plan` and look at the unit list; set `"strategy": "function"` if you want a unit
+per function back.
+
+Changing the strategy renames units, and a unit name is what a queue consumer, a
+scheduled task and a `dependsOn` point at. The manifest rewrites all three, but
+anything holding a unit name outside the manifest does not follow. Units dropped
+from the manifest are not deleted by OSS `deploy()` either (pikkujs/pikku#543) —
+fabric sweeps its dispatch namespace after each deploy, plain pikku leaves the
+old workers in place.
+
+`tags` matches the tags a function inherits from its wirings — `wireHTTP({ ...,
+tags: ['pdf'] })` — as well as any on the function itself, which is where almost
+every project writes them.
+
+Two things that bite:
+
+- **Grouping cannot change a deploy target.** Put a `serverlessIncompatible`
+  function in a group with serverless ones and the build fails naming both
+  sides. Give it its own rule — that refusal is the design, not a bug. To find
+  the culprit, read `deployment-manifest.json`: a unit carries `targetForcedBy`
+  naming the services that crossed it to `server`, and `groupedBy` naming the
+  rule that made it, so you can see which rule to carve the function out of.
+- **Grouping widens secret scope.** Every function in a unit reads every secret
+  that unit is granted, so treat a merge as a security decision too.
+
+Group by something that means something — a domain, a secret scope, a deploy
+cadence. There is deliberately no automatic packing by bundle size.
+
 The frontends build independently (`bun run build` at the root builds every
 workspace). Serve each behind its own hostname, and put the API behind `/api` on
 **all of them**, mirroring the Vite proxy from the multi-app reference: `/api/auth/*` keeps its

package/skills/pikku-knowledge/SKILL.md

@@ -284,6 +284,20 @@ pikku knowledge plan defer <milestone> <item> -r "<why>"
 
 `progress` reconciles the plan against pikku's generated meta — set membership, never anyone's status — and exits non-zero while the first pass is short, or while anything already built contradicts the plan. Unbuilt work in a later pass is reported, not blocked; a function that shipped wide open against a planned permission rule blocks from any pass, because that is a hole rather than a backlog. Writing a plan is its own seat: read `pikku-architect`. Building against one is `pikku-build`.
 
+### A finished milestone is a tombstone
+
+**Once a milestone reaches `built`, its note and its plan are closed. Do not edit either.** Not to correct the wording, not to fold in what the build actually turned out to need, not to add the item everyone agrees should have been there. A finished milestone is the record of what was agreed and what was measured against it, and a record that can be revised afterwards measures nothing.
+
+This is the rule the shape of the thing already implies. `progress` reconciles a plan against generated meta and fails when what shipped contradicts it — a check with no force at all if the losing side of the contradiction may simply be rewritten. `attempts:` brakes a note nothing can satisfy, and refunds that budget when the note's content really changes; a `built` note that keeps changing is that brake removed. Both only work while the plan stays still.
+
+So when a `built` milestone turns out to be wrong or incomplete, **the answer is always a new note, never an edit to the old one**:
+
+- It needed more than it said → a new milestone, which may name the old one.
+- It was built differently than planned → that is what `progress` is for. Reconcile forward, or record a decision saying why the plan was not the right shape.
+- It was simply wrong → a decision note that supersedes it. The wrong milestone stays where it is; a base whose history is edited cannot answer *why* anything is the way it is, which is most of what a base is for.
+
+The exception, and it is narrow: bookkeeping the loop owns. `statusAt:` and `attempts:` are written by whatever moved the note, at any status, and are bookkeeping rather than content. Nothing else about a `built` note moves again.
+
 ## Profiles built on this one
 
 OKF permits frontmatter fields a reader does not know, and the parser ignores them rather than failing. That is the extension point: a tool layered on Pikku can add its own sections and fields on top of everything above without forking the format.

package/skills/pikku-services/SKILL.md

@@ -30,6 +30,16 @@ request-scoped logger or audit buffer is a wire service, and startup work that
 needs the singletons goes in `pikkuServerLifecycle` rather than in a module's
 top level.
 
+## Services the runtime injects
+
+`pikku dev` and `pikku serve` build a set of singletons before your
+`createSingletonServices` runs and hand them in as `existingServices` — among
+them `content`, a `LocalContent` storing files under `.pikku-runtime/content`
+and serving them from `/upload` and `/assets`. **You never construct these in
+`services.ts`, and their absence from that file is not evidence they are off.**
+The optional `content` block in `pikku.config.json` only overrides that
+service's paths and size limit; omitting it does not disable it.
+
 ## Pick the reference
 
 | You are…                                                                     | Read                                                         |

package/skills/pikku-services/references/services.md

@@ -1,6 +1,5 @@
 # Pikku Services (Dependency Injection)
 
-
 ## Before You Start
 
 ```bash
@@ -195,6 +194,13 @@ const createSingletonServices = pikkuServices(async (config) => {
 })
 ```
 
+A deployment split regenerates this manifest **per unit**, so the same
+`services.ts` sees a different manifest in each bundle and each unit builds only
+what its own functions, middleware and permissions reach. A `services.ts` that
+constructs unconditionally gets none of that: every unit pays for every service,
+and the split buys nothing but duplicated bytes. Branching on the manifest is
+what makes the split real.
+
 ### Audit Wire Service
 
 `createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and Fabric notes, read `references/audit-wire-service.md`.

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

@@ -166,49 +166,25 @@ export const deleteTodo = pikkuFunc({
 })
 ```
 
-## MCP Server Setup
+## Reaching the server
 
-`PikkuMCPServer` takes the server config and a logger — not your services. It
-loads the generated `mcp.gen.json`, and the bootstrap import is what registers
-your functions.
+You do not start an MCP server. `pikku dev`, `pikku serve` and a deployed app all
+mount one for you: codegen writes `.pikku/mcp/mcp.gen.json`, the runtime loads it,
+and the server is served at **`/mcp`** — so a tool you export is reachable at
+`https://<your-app-url>/mcp` with nothing else to wire. Set `mcpPath` to move it.
 
-```typescript
-// start.ts
-import { PikkuMCPServer } from '@pikku/modelcontextprotocol'
-import { createConfig, createSingletonServices } from './services.js'
-import mcpJSON from '../.pikku/mcp/mcp.gen.json' with { type: 'json' }
-import '../.pikku/pikku-bootstrap.gen.js'
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-const server = new PikkuMCPServer(
-  {
-    name: 'pikku-mcp-server',
-    version: '1.0.0',
-    mcpJSON,
-    capabilities: { logging: {}, tools: {}, resources: {}, prompts: {} },
-  },
-  singletonServices.logger
-)
-
-await server.init()
-
-// stdio — the transport desktop MCP clients spawn
-await server.connectStdio()
-singletonServices.logger = server.createMCPLogger()
-
-// …or streamable HTTP, for a hosted server
-const { close } = await server.connectHTTP({ port: 3000, host: '127.0.0.1' })
-```
+Two consequences worth stating outright, because both read as breakage:
 
-`capabilities` is a filter, not documentation: a surface you leave out is not
-advertised and its endpoints are never loaded, which is how you ship a tools-only
-server.
+- The mount is **conditional on there being something to serve**. An `mcp.gen.json`
+  with no tools, resources or prompts is not mounted at all, so `/mcp` 404s until
+  the first `mcp: true` function or `pikkuMCP*Func` exists.
+- There is no `wires/mcp` directory and no `mcp` block in `pikku.config.json`.
+  A tool *is* its own registration, so the absence of both is what correct MCP
+  wiring looks like — not evidence that something was missed.
 
-Over stdio the protocol owns stdout, so an ordinary console logger corrupts the
-frames — that is what `createMCPLogger()` is for. Swap the logger before
-anything logs.
+When you add a tool, tell whoever asked for it the URL. An assistant that cannot
+be pointed at an endpoint has not been connected to anything, and `/mcp` is the
+whole answer.
 
 ## Red flags
 
@@ -218,4 +194,4 @@ anything logs.
 | `uri`/`title` rejected on `pikkuMCPResourceFunc` | Those belong on `wireMCPResource`                               |
 | Resource returning `{ uri, blob, mimeType }`     | Resources are text only: `{ uri, text }`                        |
 | Client sees a tool with no description           | `mcp: true` without a `description` — check the codegen warning |
-| stdio client disconnects on the first log line   | Logger still writing to stdout; use `createMCPLogger()`         |
+| `/mcp` 404s                                      | Nothing to serve yet — the mount is skipped until one tool, resource or prompt exists |