@pikku/skills 0.12.4 → 0.12.6

package/skills/pikku-deploy-cloudflare/SKILL.md

@@ -26,57 +26,99 @@ yarn add @pikku/cloudflare
 
 ## Worker Entry
 
+`@pikku/cloudflare` ships the handler factories the deploy codegen emits — use
+them rather than hand-rolling an `ExportedHandler`. Each returns a
+`WorkerEntrypoint` class that sets services up on every invocation (cached after
+the first) and adds an RPC-callable `runRpc(name, args)`:
+
 ```typescript
-import { runFetch, runScheduled } from '@pikku/cloudflare'
-import { setupServices } from './setup-services.js'
+import { createCloudflareHandler } from '@pikku/cloudflare'
+import { createConfig, createSingletonServices } from './services.js'
 import './.pikku/pikku-bootstrap.gen.js'
 
-export default {
-  async scheduled(controller, env) {
-    await setupServices(env)
-    await runScheduled(controller)
-  },
-
-  async fetch(request, env): Promise<Response> {
-    await setupServices(env)
-    return await runFetch(request as unknown as Request)
-  },
-} satisfies ExportedHandler<Record<string, string>>
+export default createCloudflareHandler(
+  { createConfig, createSingletonServices },
+  ['fetch', 'scheduled']
+)
 ```
 
+| Factory | For |
+| --- | --- |
+| `createCloudflareHandler(factories, handlerTypes)` | combined `fetch`/`queue`/`scheduled` |
+| `createCloudflareWorkerHandler(factories)` | HTTP / agent / RPC / workflow-orchestrator units |
+| `createCloudflareCronHandler(factories)` | cron units |
+| `createCloudflareQueueHandler(factories)` | queue-consumer and workflow-step units |
+| `createCloudflareMCPHandler(factories)` | MCP units (same HTTP transport) |
+| `createCloudflareWebSocketHandler(factories)` | channel units, delegating to the DO |
+
+`factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
+
 ## Service Setup
 
-Cloudflare passes env variables per-request — wrap them with Pikku services:
+Cloudflare passes env bindings per-request, so services are built from `env`
+rather than at module load. `setupServices(env, factories)` is exported from
+`@pikku/cloudflare` and is what the factories call:
 
 ```typescript
-// setup-services.ts
-import { LocalVariablesService, LocalSecretService } from '@pikku/core/services'
-import { createConfig, createSingletonServices } from './services.js'
+import { setupServices } from '@pikku/cloudflare'
 
-export const setupServices = async (
-  env: Record<string, string | undefined>
-) => {
-  const localVariables = new LocalVariablesService(env)
-  const config = await createConfig(localVariables)
-  const localSecrets = new LocalSecretService(localVariables)
-  return await createSingletonServices(config, {
-    variables: localVariables,
-    secrets: localSecrets,
-  })
-}
+const services = await setupServices(env, {
+  createConfig,
+  createSingletonServices,
+})
 ```
 
+**Do not hand-roll this.** Beyond building `LocalVariablesService` /
+`LocalSecretService` and caching the result, it calls `setSingletonServices()` —
+and the core runners (`fetchData`, `runQueueJob`, `runScheduled`) resolve
+services through that global slot, *not* through the value you were returned. A
+setup function that only returns the services leaves every request throwing
+"Singleton services not initialized" as a CF `1101`. It also stashes the env via
+`setCloudflareEnv`, which `getCloudflareEnv()` reads for bindings.
+
+## HTTP
+
+`runFetch(request, websocketHibernationServer?, options?)`:
+
+- A `GET` with `Upgrade: websocket` is routed to the hibernation server. Without
+  one passed in it answers **426**, so a channel worker that forgets the second
+  argument fails every upgrade while plain HTTP keeps working.
+- `CF-Ray` becomes the traceId when present, so a Cloudflare trace and a Pikku
+  trace line up without extra wiring.
+- `options.exposeErrors` defaults to **`false`** — error detail is withheld from
+  responses unless you opt in.
+
+## Scheduled Tasks
+
+`runScheduled(controller)` matches registered tasks against
+`controller.cron` and **returns after the first match**. Two tasks sharing one
+cron expression means only one of them ever runs — give each its own expression,
+or invoke `runScheduledTask({ name })` per task yourself.
+
 ## WebSocket (Durable Objects)
 
+The ready-made DO class is exported; re-export it under the binding name and
+point the worker at it:
+
 ```typescript
-import { CloudflareWebSocketHibernationServer } from '@pikku/cloudflare'
-
-export class WebSocketHibernationServer extends CloudflareWebSocketHibernationServer {
-  protected async getParams() {
-    const singletonServices = await setupServices(this.env)
-    return { singletonServices }
-  }
-}
+export { PikkuWebSocketHibernationServer as WebSocketHibernationServer } from '@pikku/cloudflare'
+export default createCloudflareWebSocketHandler({
+  createConfig,
+  createSingletonServices,
+})
 ```
 
-Register the Durable Object in `wrangler.toml` and export from the worker entry.
+Subclass `CloudflareWebSocketHibernationServer` only when you need something
+`getParams()` cannot express — it is abstract with one method returning
+`{ singletonServices, createWireServices? }`. The channel store
+(`CloudflareWebsocketStore` over the DO's own storage), the event hub and the
+channel handler factory are all built by the base class; do not supply them.
+
+The router looks up the DO through the **`WEBSOCKET_HIBERNATION_SERVER`**
+binding and answers `503` naming it if the binding is missing, so declare it in
+`wrangler.toml` under exactly that name.
+
+A throw during `onConnect` closes the socket with `1008` and answers `403
+Forbidden` with a deliberately generic body — an auth denial and a genuine fault
+look identical to the client. The real reason is on the logger, so read the
+worker logs rather than the status code.

package/skills/pikku-deploy-express/SKILL.md

@@ -55,15 +55,37 @@ await appServer.start()
 
 **Methods:**
 
-- `init(httpOptions?): Promise<void>` — Register middleware and routes
+- `init(httpOptions?: RunHTTPWiringOptions): Promise<void>` — installs the body parsers, the cookie parser and the Pikku middleware
 - `start(): Promise<void>` — Start listening
-- `stop(): Promise<void>` — Graceful shutdown
-- `enableExitOnSigInt(): Promise<void>` — SIGINT handler
+- `stop(): Promise<void>` — Graceful shutdown; throws if the server was never started
+- `enableExitOnSigInt(): Promise<void>` — SIGINT handler: stops the singleton services, then the server, then exits 0
 - `enableCors(options): void` — Enable CORS
-- `enableStaticAssets(): void` — Serve static files (requires `content` config)
+- `enableStaticAssets(): void` — serve `content.localFileUploadPath` under `content.assetUrlPrefix`
+- `enableReaper(): void` — a `PUT /reaper/*path` upload sink for local development, path-traversal checked and bounded by `content.sizeLimit` (default `1mb`)
+- `getHttpServer(): Server` — the underlying `http.Server`, e.g. to attach a WebSocket server; throws before `start()`
+
+`enableStaticAssets` and `enableReaper` both throw when `content` is unset.
 
 **Property:** `app: Express` — Direct access to Express instance for custom middleware.
 
+### Ordering, and what `init` installs for you
+
+The health check is registered in the **constructor**, so it answers before any
+middleware you add and cannot be wrapped in auth. It defaults to
+`/health-check`; override with `healthCheckPath`.
+
+Everything else is installed by `init()`: `express.json`, `express.text` (for
+`text/xml`), `express.urlencoded`, `cookie-parser`, then the Pikku middleware.
+Call `enableCors` **before** `init` if you want CORS applied to Pikku's routes.
+
+Express buffers the body before Pikku sees it, so the parser limit is the only
+place an oversized request can actually be stopped. `httpOptions.maxBodySize`
+therefore feeds those parser limits, with an explicit `config.limits` entry
+(`json` / `xml` / `urlencoded`) still winning. Everything defaults to `1mb`.
+
+`init` passes `logRoutes: true` and `loadSchemas: true` by default; your
+`httpOptions` spread over them, so you can turn either off.
+
 ## Middleware (existing Express app)
 
 ```bash
@@ -76,11 +98,25 @@ import { pikkuExpressMiddleware } from '@pikku/express-middleware'
 import './.pikku/pikku-bootstrap.gen.js'
 
 const app = express()
+app.use(express.json())
+app.use(cookieParser())
 app.use(
   pikkuExpressMiddleware({
     logger: singletonServices.logger,
     logRoutes: true,
     loadSchemas: true,
+    // plus any RunHTTPWiringOptions: maxBodySize, respondWith404, coerceDataFromSchema
   })
 )
 ```
+
+Options beyond `logger` are all optional: `logRoutes` logs the wiring table once
+at startup, `loadSchemas` compiles every schema up front, and the rest are
+`RunHTTPWiringOptions` passed through per request.
+
+On your own app **you** own the parser stack — the middleware reads
+`req.body`, so a body parser and `cookie-parser` must be registered before it,
+and `maxBodySize` alone will not stop an oversized request that your parser
+already accepted. Unmatched requests fall through to `next()` (unless
+`respondWith404` is set), so Pikku's routes coexist with your existing ones;
+a streaming response is the exception and does not call `next()`.

package/skills/pikku-deploy-fastify/SKILL.md

@@ -47,10 +47,19 @@ await appServer.start()
 
 **Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
 
-**Methods:** `init(httpOptions?)`, `start()`, `stop()`, `enableExitOnSigInt()`
+**Methods:** `init(httpOptions?: RunHTTPWiringOptions)`, `start()`, `stop()`, `enableExitOnSigInt()`
 
 **Property:** `app: FastifyInstance` — Direct access to Fastify instance.
 
+`enableCors` exists on the class but **throws `Method not implemented.`** — unlike
+the Express server. Register `@fastify/cors` on `app` yourself before `init()`.
+
+Unlike the Express server, the health check is registered by `init()`, not the
+constructor, so nothing answers before `init` runs. `init` also passes
+`logRoutes: true` and `loadSchemas: true`, which your `httpOptions` can override.
+The Fastify instance is constructed with no options; reach for the plugin package
+if you need `Fastify({ … })` of your own.
+
 ## Plugin (existing Fastify app)
 
 ```bash
@@ -68,6 +77,18 @@ app.register(pikkuFastifyPlugin, {
     logger: singletonServices.logger,
     logRoutes: true,
     loadSchemas: true,
+    // plus any RunHTTPWiringOptions: maxBodySize, respondWith404, …
   },
 })
 ```
+
+Every option other than `logger` is optional, and the rest of the `pikku` object
+is `RunHTTPWiringOptions` passed straight through.
+
+The plugin registers a catch-all `fastify.all('/*')`, so mount it on a
+[Fastify prefix](https://fastify.dev/docs/latest/Reference/Plugins/) if the app
+has routes of its own to keep.
+
+Fastify buffers the body itself, so its `bodyLimit` is where an oversized request
+is stopped. `maxBodySize` sets it — and left unset, Fastify's stricter 1MB default
+stands rather than being loosened to Pikku's 10MB fallback.

package/skills/pikku-deploy-lambda/SKILL.md

@@ -44,30 +44,75 @@ export const coldStart = async () => {
 }
 ```
 
+If the deploy codegen generated your handlers, this caching is already done for
+you by the factories in `@pikku/lambda` — `createLambdaHandler(factories,
+handlerTypes)`, `createLambdaWorkerHandler(factories)` and
+`createLambdaWebSocketHandler(factories)`. They build `variables`/`secrets` from
+`process.env`, cache the singleton services in module scope, and return the
+named exports (`handler`, `queue`, `scheduled`, or `connect`/`disconnect`/
+`default`) that `serverless.yml` references. Hand-written handlers are for cases
+the codegen does not cover.
+
 ## HTTP Handler
 
+Pick the entry point that matches the API Gateway payload version — they take
+different event types and are not interchangeable:
+
 ```typescript
-import type { APIGatewayProxyEvent } from 'aws-lambda'
-import { runFetch } from '@pikku/lambda/http'
+import type { APIGatewayEvent } from 'aws-lambda'
+import { runFetch } from '@pikku/lambda/http' // REST API / payload v1
 
-export const httpRoute = async (event: APIGatewayProxyEvent) => {
+export const httpRoute = async (event: APIGatewayEvent) => {
   await coldStart()
   return await runFetch(event)
 }
 ```
 
+```typescript
+import type { APIGatewayProxyEventV2 } from 'aws-lambda'
+import { runFetchV2 } from '@pikku/lambda/http' // HTTP API / payload v2
+
+export const httpRoute = async (event: APIGatewayProxyEventV2) => {
+  await coldStart()
+  return await runFetchV2(event)
+}
+```
+
+Both answer `OPTIONS` themselves before Pikku's wirings run, so a preflight
+never reaches your middleware. Only `runFetchV2` echoes the request `Origin`
+into `Access-Control-Allow-Origin`; `runFetch` sets allowed headers and methods
+but **no origin header at all**, so v1 preflights fail in the browser unless
+API Gateway or a CloudFront layer adds one.
+
+They also differ on failure: `runFetchV2` logs and returns a JSON `500`, while
+`runFetch` swallows the error and returns whatever status the response already
+carried.
+
+Neither takes `RunHTTPWiringOptions` — there is no `maxBodySize` or
+`respondWith404` knob here; API Gateway's own payload limit is the bound.
+
 ## Scheduled Tasks
 
 ```typescript
 import type { ScheduledHandler } from 'aws-lambda'
-import { runScheduledTask } from '@pikku/core/scheduler'
+import { runLambdaScheduled } from '@pikku/lambda/scheduled'
 
-export const myScheduledTask: ScheduledHandler = async () => {
+export const scheduled: ScheduledHandler = async (event) => {
   await coldStart()
-  await runScheduledTask({ name: 'myScheduledTask' })
+  await runLambdaScheduled(event)
 }
 ```
 
+`runLambdaScheduled` runs **every** scheduled task registered in the bundle,
+each with its own `cron-<uuid>` traceId, and logs rather than rethrows a task
+failure — so one bad task cannot fail the invocation or stop the others. The
+event itself is ignored; which tasks run is decided by what the unit bundled,
+not by which EventBridge rule fired.
+
+Reach for `runScheduledTask({ name })` from `@pikku/core/scheduler` directly
+only when one Lambda genuinely bundles several tasks that must fire on separate
+schedules.
+
 ## SQS Queue Worker
 
 ```typescript
@@ -80,6 +125,25 @@ export const mySQSWorker: SQSHandler = async (event) => {
 }
 ```
 
+The worker returns an `SQSBatchResponse` listing the failed messages in
+`batchItemFailures`, which SQS only honours when the event source mapping has
+**`ReportBatchItemFailures`** enabled. Without it the whole batch is retried
+when any one message fails, so successfully processed jobs run twice.
+
+Records are processed in parallel, and the queue name is taken from the last
+segment of `eventSourceARN` — it must match the name the worker was wired under.
+A `QueueJobDiscardedError` counts as success (no retry); anything else is
+reported as a failed item.
+
+`waitForCompletion` throws on an SQS job: the transport is fire-and-forget.
+
+On the producer side, `SQSQueueService` resolves each queue URL from the
+constructor's `queueUrlMap` first, then from
+`SQS_QUEUE_URL_<SCREAMING_SNAKE_NAME>`, and throws naming the missing variable
+if neither has it. `supportsResults` is `false` and `getJob()` always throws —
+use BullMQ or PgBoss if you need results. `delay` is milliseconds, rounded up to
+whole seconds and capped at SQS's 900s ceiling.
+
 ## WebSocket (API Gateway v2)
 
 ```typescript
@@ -90,21 +154,37 @@ import {
   LambdaEventHubService,
 } from '@pikku/lambda/websocket'
 
-export const connectHandler = async (event) => {
-  const params = await getParams(event)
-  await connectWebsocket(event, params)
-  return { statusCode: 200, body: '' }
+const params = async (event) => {
+  const { channelStore } = await coldStart()
+  return { channelStore }
 }
 
-export const disconnectHandler = async (event) => {
-  const params = await getParams(event)
-  return await disconnectWebsocket(event, params)
-}
+export const connectHandler = async (event) =>
+  await connectWebsocket(event, await params(event))
 
-export const defaultHandler = async (event) => {
-  const params = await getParams(event)
-  return await processWebsocketMessage(event, params)
-}
+export const disconnectHandler = async (event) =>
+  await disconnectWebsocket(event, await params(event))
+
+export const defaultHandler = async (event) =>
+  await processWebsocketMessage(event, await params(event))
 ```
 
-WebSocket requires a `ChannelStore` (e.g., `PgChannelStore`) and `LambdaEventHubService` for cross-connection messaging.
+All three take the same `{ channelStore }` and **return a complete
+`APIGatewayProxyResult`** — return it. Discarding `connectWebsocket`'s result
+and answering a hardcoded `200` accepts every connection, including the ones
+your channel's auth rejected.
+
+`channelStore` (e.g. `PgChannelStore`) must be a real shared store: each route
+is a separate invocation, so nothing survives in memory between `$connect` and
+`$default`.
+
+`LambdaEventHubService` handles cross-connection messaging and takes
+`(logger, event, channelStore, eventHubStore)` — the `event` is needed to derive
+the API Gateway Management endpoint, so it is constructed per invocation, not
+once at cold start. It also needs an `EventHubStore` alongside the channel
+store.
+
+Two behaviours to design around: **binary payloads throw** (`Binary data is not
+supported on serverless lambdas`), and any `PostToConnection` failure removes
+the connection from the channel store — a transient error drops a live client,
+not just a stale one.

package/skills/pikku-deploy-nextjs/SKILL.md

@@ -38,6 +38,17 @@ export const PATCH = pikkuAPIRequest
 export const DELETE = pikkuAPIRequest
 ```
 
+`pikkuAPIRequest` strips a leading `/api` from the pathname before routing, so
+wirings are declared as `/todos`, not `/api/todos`, even though the route file
+lives under `app/api`. Turn that off with `removeAPIPrefix(false)` from the same
+generated file if your wirings really do carry the prefix.
+
+It takes `(req, context)` to match Next's handler signature but ignores the
+context — Pikku routes from the URL, so the catch-all segment name is yours to
+choose. It also passes no `RunHTTPWiringOptions`: to set `maxBodySize` or
+`respondWith404` you need your own handler over `new PikkuNextJS(...)` calling
+`apiRequest(req, options)`.
+
 ## Server-Side Data Fetching
 
 Use the generated `pikku()` helper in Server Components or Server Actions:
@@ -45,7 +56,7 @@ Use the generated `pikku()` helper in Server Components or Server Actions:
 ```typescript
 import { pikku } from '@/pikku-nextjs.gen.js'
 
-const { get, post, del, rpc, staticGet, staticPost, staticRPC } = pikku()
+const { get, post, patch, del, rpc, staticGet, staticPost, staticRPC } = pikku()
 
 // Dynamic (reads headers/cookies — requires request context)
 const todos = await get('/todos')
@@ -60,8 +71,19 @@ const result = await rpc('calculateTax', { amount: 100, region: 'US' })
 
 **Dynamic vs Static:**
 
-- `get`, `post`, `del`, `rpc` — access headers/cookies, use in dynamic Server Components
-- `staticGet`, `staticPost`, `staticRPC` — no request context, safe for precompile/ISR
+- `get`, `post`, `patch`, `del`, `rpc` — read `next/headers` cookies and headers,
+  so they force the component dynamic
+- `staticGet`, `staticPost`, `staticRPC` — no request context, safe for
+  precompile/ISR
+
+The static variants pass `skipUserSession: true`, so a wiring that expects a
+session sees none. That is the real difference — not just where they can run.
+There is no `staticPatch` or `staticDel`; a mutation at build time is not a
+thing the generated client offers.
+
+Both paths run with `bubbleErrors: true`, so a failing wiring **throws** in your
+Server Component rather than resolving to an error status. Wrap the call, or let
+the Next.js error boundary take it.
 
 ## How It Works
 
@@ -73,6 +95,28 @@ import { PikkuNextJS } from '@pikku/next'
 const pikku = new PikkuNextJS(createConfig, createSingletonServices)
 ```
 
-**Constructor:** `new PikkuNextJS(createConfig?, createSingletonServices)`
+**Constructor:** `new PikkuNextJS(createConfig | undefined, createSingletonServices)`
+
+Both arguments are positional and `createConfig` is only optional in the sense
+that passing `undefined` substitutes an empty config —
+`createSingletonServices` is required.
+
+Initialization is memoized on a promise, so concurrent first requests share one
+setup; a failed setup clears the promise, so the next request retries rather
+than caching the failure forever.
+
+The generated `pikku-nextjs.gen.ts` wraps this with full type safety from your
+route definitions.
+
+## Related exports
 
-The generated `pikku-nextjs.gen.ts` wraps this with full type safety from your route definitions.
+- **`PikkuNextJSWorkerRPC({ fetcher })`** — same surface as `PikkuNextJS`, but
+  every call is dispatched through a `Fetcher` (a Cloudflare service binding, a
+  local HTTP client, a fabric dispatcher) instead of loading function code
+  in-process. Use it to keep functions out of the SSR bundle. A non-2xx
+  response throws with the status and body text.
+- **`toNextJsAuthHandler(auth)`** — wraps a better-auth instance or handler
+  function for an auth route. The three-argument form
+  `(pikkuAuthFactory, createConfig, createSingletonServices)` resolves a Pikku
+  better-auth factory lazily; it throws if you pass `createConfig` without
+  `createSingletonServices`. `nextCookies` is re-exported alongside it.

package/skills/pikku-deploy-uws/SKILL.md

@@ -47,10 +47,52 @@ await appServer.start()
 
 **Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
 
-**Methods:** `init(httpOptions?)`, `start()`, `stop()`, `enableExitOnSigInt()`
+**Methods:** `init(httpOptions?: RunHTTPWiringOptions)`, `start()`, `stop()`, `enableExitOnSigInt()`
 
 **Property:** `app: uWS.App` — Direct access to uWebSockets app instance.
 
+### What the server does and does not give you
+
+`init()` registers three things in order: the health check (`healthCheckPath`,
+default `/health-check`), a catch-all `app.any('/*')` HTTP handler, and a
+catch-all `app.ws('/*')` websocket handler. Nothing is registered by the
+constructor, so nothing answers before `init` runs.
+
+**There is no `enableCors`, no static assets and no `content` support** — unlike
+the Express server. The class is explicitly a prototyping convenience; for
+anything that needs extra handlers, use `@pikku/uws-handler` directly and treat
+`pikku-uws-server.ts` as the template (that is what its own JSDoc says).
+
+`httpOptions` reaches the HTTP handler only. The websocket handler is
+constructed with a fixed `{ logger, logRoutes: true }`, so per-request options
+do not apply to the upgrade path. `loadSchemas` is also never passed by the
+server, so schemas compile lazily on first use rather than at startup — pass
+`loadSchemas: true` in `httpOptions` if you want the startup cost paid up front.
+
+`stop()` closes the listen socket and then waits a fixed 2 seconds for
+connections to drain. Called before `start()`, it throws a bare **string**, not
+an `Error`, so `catch (e) { e.message }` reads `undefined`.
+
+### Body limits
+
+uWS hands over raw chunks with no limit of its own, so the handler counts the
+bytes itself. A request over `maxBodySize` (default `DEFAULT_MAX_BODY_SIZE`) is
+answered `413` with a `PayloadTooLargeError` body, and the chunks are dropped
+rather than concatenated — an oversized request never accumulates in memory. A
+`content-length` header that already exceeds the limit short-circuits before any
+data arrives.
+
+### Handlers directly (own uWS app)
+
+```typescript
+import { pikkuHTTPHandler, pikkuWebsocketHandler } from '@pikku/uws-handler'
+
+app.any('/*', pikkuHTTPHandler({ logger, logRoutes: true, loadSchemas: true }))
+app.ws('/*', pikkuWebsocketHandler({ logger, logRoutes: true }))
+```
+
+Both take `{ logger, logRoutes?, loadSchemas? } & RunHTTPWiringOptions`.
+
 ## WebSocket Standalone (ws library)
 
 For WebSocket-only servers using the `ws` library:
@@ -86,3 +128,14 @@ process.on('SIGINT', async () => {
   process.exit(0)
 })
 ```
+
+`pikkuWebsocketHandler` takes `{ server, wss, logger, logRoutes?, loadSchemas? }`
+plus `RunHTTPWiringOptions`, and there is no server class in `@pikku/ws` — the
+handler attaches to a `Server` you own.
+
+`noServer: true` is required, not stylistic: the handler listens for the HTTP
+server's own `upgrade` event, opens the channel (running middleware and auth
+first), and only then calls `wss.handleUpgrade`. A `WebSocketServer` bound to
+the server would take the socket before any of that ran. An upgrade the channel
+rejects gets the socket destroyed, and an auth failure is written as a real HTTP
+response on the raw socket rather than a silent drop.

package/skills/pikku-deps/SKILL.md

@@ -36,19 +36,29 @@ installGroups: [core]
 
 - `pikku audit` — reports **security advisories** only.
 - `pikku audit --outdated` — also reports **available dependency updates**.
-- Package-manager detection is by **lockfile** (walks up: `bun.lock`/`bun.lockb`,
-  then `yarn.lock`). Only **bun** runs a real audit (`bun audit --json` +
+- Package-manager detection is by **lockfile**, walking up to 12 levels to the
+  workspace root, checking in this order: `bun.lock`/`bun.lockb`,
+  `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`. A project with several
+  lockfiles resolves as bun. Only **bun** runs a real audit (`bun audit --json` +
   `bun outdated`, normalised into one `SecurityAuditReport` with per-severity /
   per-update-level counts). Other PMs are detected but **stubbed** with a `note`
   field until their shapes are normalised — issues/updates come back empty.
-- `bun audit` exits non-zero when it *finds* advisories but still writes a valid
-  report — treat any non-zero exit as data, not failure.
+- `bun audit` exits non-zero when it *finds* advisories but still writes the
+  payload to stdout, so a non-zero exit **with output** is data. A non-zero exit
+  with **no** output — or a launch failure, timeout, or a blown 32MB buffer —
+  throws, precisely so a failed run can't masquerade as "0 advisories".
 
 ## Console integration (@pikku/addon-console)
 
 Three RPCs, all reading/writing the same artifact via the meta service. Shared
 spawn/read helpers live in `lib/audit-exec.ts` (`readAuditReport`,
-`runPikkuAudit`, `spawnProcess`, `findBin`) — reuse them, don't re-implement.
+`runPikkuAudit`, `spawnProcess`, `findBin`), alongside `lib/find-project-root.ts`
+and `lib/resolve-package-manager.ts` (`resolvePackageManager`, `installArgs`,
+`execPrefix`) — reuse them, don't re-implement. `resolvePackageManager` reads
+package.json's corepack `packageManager` field first and only falls back to
+lockfiles, because that field states intent before a lockfile exists and a
+project can carry a stale one from another tool. Guessing wrong is not a soft
+failure: the spawn dies with `Executable not found in $PATH`.
 Like every console RPC these require an **authenticated session** (the console
 is admin-only), so the host must have Better Auth wired — see `pikku-better-auth`.
 
@@ -84,15 +94,26 @@ is admin-only), so the host must have Better Auth wired — see `pikku-better-au
 
 ```ts
 {
+  schemaVersion: number
   tool: string                 // e.g. 'bun'
+  generatedAt: string          // ISO timestamp
   note?: string                // set when the audit could NOT run (unsupported PM);
                                // render ONLY the note — never a reassuring "no vulnerabilities"
-  summary: { critical, high, moderate, low, info: number }
-  issues: SecurityAuditIssue[] // package, severity, title, advisoryId, cwe[], cvssScore?,
-                               // url?, vulnerableVersions, recommendedVersion?
+  summary: {
+    totalIssues, critical, high, moderate, low: number   // no `info` bucket
+    totalUpdates, major, minor, patch: number
+  }
+  issues: SecurityAuditIssue[] // package, severity, title, advisoryId, url,
+                               // vulnerableVersions, cwe[], cvssScore, recommendedVersion
   updates: SecurityAuditUpdate[] // package, current, latest, level (major|minor|patch|unknown)
 }
 ```
 
+`severity` is one of `critical | high | moderate | low | info`, but `summary`
+has no `info` count — an informational advisory raises `totalIssues` without
+landing in a severity bucket, so don't sum the four to get the total. On an
+issue, `url`, `cvssScore` and `recommendedVersion` are always present and
+**nullable** rather than optional: check for `null`, not `undefined`.
+
 When `note` is present the audit did not run — show only the note (an "Audit not
 run" state), never the "no known vulnerabilities / up to date" copy.