@pikku/skills 0.12.34 → 0.12.37

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

@@ -186,6 +186,63 @@ 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.
 
+## Authentication
+
+An MCP endpoint is not gated as a whole. Pikku already knows, tool by tool, which
+calls need a session, and the endpoint answers accordingly:
+
+| Declaration                              | Anonymous call      |
+| ---------------------------------------- | ------------------- |
+| `pikkuSessionlessFunc` with `mcp: true`  | runs                |
+| the same, plus `auth: true`              | `401` + a challenge |
+| `pikkuFunc` with `mcp: true`             | `401` + a challenge |
+
+```typescript
+// public: anyone connecting to /mcp can call this
+export const searchCatalog = pikkuSessionlessFunc<Query, Results>({
+  mcp: true,
+  func: async (services, data) => services.catalog.search(data),
+})
+
+// private: an anonymous caller is challenged, never dispatched
+export const myOrders = pikkuFunc<void, Order[]>({
+  mcp: true,
+  func: async (services, _data, session) =>
+    services.orders.forUser(session.userId),
+})
+```
+
+The `401` carries a `WWW-Authenticate` header naming the endpoint's RFC 9728
+Protected Resource Metadata document, which the server also serves — `/mcp` is
+described at `/.well-known/oauth-protected-resource/mcp`. That pair is what an
+MCP client needs to discover an authorization server and start an OAuth flow;
+a refusal delivered as a JSON-RPC result instead reads to a client as a tool that
+failed, and no discovery happens.
+
+`tools/list` is never gated, so a client can still see what exists before it has
+a token.
+
+Nothing needs configuring: the metadata document defaults to advertising the
+origin the request arrived on, which is right whenever the app is its own
+authorization server. To point elsewhere, pass `mcpAuth` to the runtime:
+
+```typescript
+new PikkuNodeHTTPServer(config, logger, {
+  mcpJson,
+  mcpAuth: {
+    authorizationServers: ['https://auth.example.com'],
+    scopesSupported: ['mcp'],
+    resourceName: 'Example API',
+  },
+})
+```
+
+The transport never verifies a token itself — session resolution stays with the
+app's own middleware, exactly as it works over HTTP. One consequence: only a
+request carrying *no* credentials is challenged. A token that is present but
+expired is dispatched, and the runner's refusal reaches the client as a tool
+error.
+
 ## Red flags
 
 | Symptom                                          | Cause                                                           |
@@ -195,3 +252,5 @@ whole answer.
 | 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 |
 | `/mcp` 404s                                      | Nothing to serve yet — the mount is skipped until one tool, resource or prompt exists |
+| A tool an assistant should be able to call returns `401` | It is a `pikkuFunc`, or declares `auth: true` — make it a `pikkuSessionlessFunc` if it is genuinely public |
+| A private tool returns a result rather than a challenge | The request carried a credential, so it was dispatched; only a call with none is refused at the door |

package/skills/pikku-workflow/SKILL.md

@@ -16,12 +16,12 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Capture baseline. Run `pikku-verify` (or `pikku all`) BEFORE writing code; note existing errors — only NEW errors are yours to fix.
-2. Discover before editing. Prefer `pikku-meta` / `pikku info functions --verbose` and `pikku info tags --verbose` to see functions usable as steps and project organization; inspect only the focused output you need.
+1. Capture baseline. Run `pikku all` BEFORE writing code; note existing errors — only NEW errors are yours to fix.
+2. Discover before editing. Prefer `pikku meta` / `pikku info functions --verbose` and `pikku info tags --verbose` to see functions usable as steps and project organization; inspect only the focused output you need.
 3. Identify the source files that own the behavior. Do not start from generated output, `.pikku`, `node_modules`, vendored packages, or build artifacts.
 4. Make the smallest source change. Keep generated files generated — never hand-edit SDKs, schema output, or typegen to paper over errors; fix the source cause.
-5. Validate with the narrowest relevant command, then re-run `pikku-verify`. If only files you did not touch still error, those are pre-existing — leave them unless asked.
-6. Call `pikku-workflow-view` only when `pikku-verify` fully passes (codegen AND type check both green) — never after a partial pass.
+5. Validate with the narrowest relevant command, then re-run `pikku all`. If only files you did not touch still error, those are pre-existing — leave them unless asked.
+6. Only claim success when `pikku all` and `tsc` both pass (codegen AND type check green) — never after a partial pass.
 
 See `pikku-concepts` for the core mental model.
 
@@ -33,7 +33,7 @@ The deciding question is: **does any part of this cross an external boundary tha
 
 - **Checkout WITH payment → workflow.** Get cart → compute total → **(atomic: create order + order items, deduct stock, clear cart)** → **charge payment through the provider** → send confirmation email. It's a workflow because the payment leg (and the email) are external and must be **retried, not lost, and not charged twice** across a restart — and the user benefits from seeing where the run is.
 - **Checkout with NO external payment** — e.g. it just records the order and decrements stock in one transaction, nothing leaves the process — is a **single-shot algorithm**: a plain `pikkuFunc` wrapping one `kysely.transaction`. Not a workflow. A workflow here would add durability machinery for a thing that already commits atomically in one shot.
-- **One durable step is NOT a workflow — it's a queue worker.** A lone side-effect that must be retried / not lost (send one email, fire one webhook, one external charge) → a **queue worker** (`pikku-queue`), enqueued fire-and-forget. A workflow adds a step graph for a thing that has no steps to orchestrate. (A single non-durable step is just a direct RPC call.)
+- **One durable step is NOT a workflow — it's a queue worker.** A lone side-effect that must be retried / not lost (send one email, fire one webhook, one external charge) → a **queue worker** (see `pikku-wiring`'s queue reference), enqueued fire-and-forget. A workflow adds a step graph for a thing that has no steps to orchestrate. (A single non-durable step is just a direct RPC call.)
 - Also workflows: onboarding sequences, settlements/payouts, digests and batch sends, anything that waits (`sleep`/`suspend`) or fans out with retries — the common thread is **multiple** steps or a durable wait, never a single step.
 
 **HARD RULE — never a single-RPC (one-step) workflow.** A workflow whose body is one `workflow.do('x', 'someRpc', …)` is a mislabeled durable function, not orchestration. Route by durability, NOT into a workflow:
@@ -310,12 +310,11 @@ export const userOnboarding = pikkuWorkflowGraph({
 
 ## Step dispatch & HTTP wiring
 
-For per-step inline-vs-queue dispatch (`workflowQueued: true` and the `dispatchStep` rules), the manual `workflowStart`/`workflow`/`workflowStatus` HTTP wirings, and a suspend/resume example, read `references/workflow-reference.md`.
+For per-step inline-vs-queue dispatch (`workflowQueued: true` and the `dispatchStep` rules) and a suspend/resume example, read `references/workflow-reference.md`.
 
 ## After writing
 
-1. `pikku-verify` (codegen + tsc).
+1. `pikku all`, then `tsc --noEmit` (codegen + type check).
 2. PKU641 → a `const`/`let` is inside a block; hoist it to the top of the function body.
 3. Import errors → use `#pikku/workflow/pikku-workflow-types.gen.js`, not `#pikku`.
 4. Type errors only in files you did not touch → pre-existing template errors; safe to ignore.
-5. Both green → call `pikku-workflow-view` with the workflow name.