@pikku/skills 0.12.42 → 0.12.43

package/package.json

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

package/skills/pikku-changes/SKILL.md

@@ -1,172 +1,124 @@
 ---
 name: pikku-changes
-description: 'Work a project''s changes queue — the todo list someone filed by walking a deployed stage. Covers `pikku fabric changes list|claim|show|ask|shot|done`, when to ask a question instead of guessing, and how to offer options as images. TRIGGER when: the user says "work the changes", "pick up the changes queue", names a change by its #number, or you are otherwise idle in a repo that has a pikkufabric.config.json. DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
+description: 'Work a Fabric project''s changes queue — the todo list someone filed by circling things on a deployed stage. Covers `pikku fabric changes next|claim|show|ask|shot|done`: waiting for work without polling, asking instead of guessing, offering options as images, one commit per item. TRIGGER when: the user says "run the pikkufabric changes", "run the changes against <stage>", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a repo that has a pikkufabric.config.json. DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
 installGroups: [fabric]
 ---
 
 # Working a changes queue
 
-Someone walked the deployed app and circled twenty things. Each one is a row with their
-words, a picture of what they were looking at, and the elements the circle enclosed. You
-have the repo and the app running locally. Your job is to empty the queue without making
-them regret filing.
+Someone walked the deployed app and circled things. Each item is their words, a
+screenshot of what they saw, and the elements the circle enclosed. You have the repo.
+Empty the queue without making them regret filing.
 
-## The loop
-
-Every argument is a flag; nothing is positional. `--json` works on any of them. The
-project comes from the local `pikkufabric.config.json`, so `--project-id` is only needed
-when you are not in the checkout.
+Run every command from the checkout: the project comes from `pikkufabric.config.json`.
+`--json` works on all of them. Items are addressed as `2`, `#2` or their uuid.
 
-```bash
-pikku fabric changes list --pickup-only --json
-pikku fabric changes claim --change-ids <id>,<id> --title "Checkout pass" --claimed-by claude-code
-pikku fabric changes show --change-id <id>
-pikku fabric changes ask --change-id <id> --question "…" --option "…" --option "…" --author-name claude-code
-pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
-pikku fabric changes done --change-id <id> --note "What you did"
-```
+## Which stage
 
-`list --pickup-only` is the one a harness wants: it skips items still inside the grace
-window, so a batch someone is mid-way through typing is picked up together rather than item
-by item as it lands.
+The queue is per project. "Against develop" or a pasted stage URL narrows it:
+`--stage` takes a branch, the stage URL (as filed, path optional) or a stage id. With
+no stage named, work the whole project. An unknown name prints the stages there are.
 
-Deciding what belongs together is yours: `claim` with `--change-ids` and no `--group-id`
-forms the group. Claim an existing one with `--group-id`.
+## The loop
 
-Claim before working. The lease expires (30 minutes by default, `--lease-minutes` to
-change it), so an abandoned claim returns to the queue rather than parking the work
-forever — but a second harness picking up something you are halfway through is the failure
-this prevents.
+**Never poll.** No `sleep` loops, no repeated `list`, no re-running `show` to see if
+something changed. `next` does the waiting and exits only when there is work.
 
-## Reading an item
+1. Start `next` as a **background** command, and stop there until it exits:
 
-`show` gives you four things, in descending order of trustworthiness:
+   ```bash
+   pikku fabric changes next --stage develop --claim --claimed-by claude-code
+   ```
 
-1. **Their words.** The title and body are the requirement. Everything else is evidence.
-2. **The screenshot.** What they actually saw, at their width, with their data. When the
-   other addresses disagree with the picture, the picture is right.
-3. **The circled elements** — a testid, a source anchor, a CSS path. The testid greps
-   straight to a component because it is the i18n message key.
-4. **The source anchor**, printed as `src/routes/app.orders.tsx:42 as of a91c4e2`. That line
-   number is where the JSX was **at that commit**. Read it as a starting point and find
-   today's equivalent; never edit line 42 of today's file because the anchor said 42.
+   It waits out the grace window (a just-filed item is held about a minute so a batch
+   being typed arrives together), claims what is ready as one group, prints it, and
+   exits. It also wakes when someone answers a question you asked under that
+   `--claimed-by`.
 
-Resolution is a guess and the panel says so. If the circle and the anchor point at
-different things, believe the circle.
+2. When it exits, read the exit code:
 
-## When to ask
+   | code | meaning | do |
+   | --- | --- | --- |
+   | 0 | work printed (claimed, and/or `Answered`) | work it, then step 3 |
+   | 2 | `--timeout`/`--once` found nothing | stop, or restart `next` |
+   | 3 | session refused | tell the user to run `pikku fabric login`; stop |
+   | 1 | anything else (bad `--stage`, fabric down for minutes) | report the message; stop |
 
-Ask when the item admits more than one reasonable implementation and you would be **picking
-for them**. Do not ask to confirm something the item already says.
+3. For each item: `show` → fix → commit → `done`, or `ask` and move on. Then start
+   `next` again, in the background.
 
-Ask:
-- "Make the total stand out" — bigger, bolder, coloured, or moved above the fold?
-- "This should be faster" — is it the spinner, the request, or the number of steps?
-- Anything that changes what data is stored, what an existing user sees, or what something costs.
+Without `--claim` it only reports what is claimable; claim it yourself:
 
-Do not ask:
-- "Should I use flexbox or grid?" — that is yours.
-- "Do you want me to fix the typo?" — they filed it; fix it.
-- "Can you confirm you want the button blue?" — they said blue.
+```bash
+pikku fabric changes claim --change-ids 3,4 --title "Checkout pass" --claimed-by claude-code
+```
 
-A question costs them a context switch, not typing. That is the budget you are spending.
+A `claim` refused with a 409 says per item why (held, claimed by someone else, done).
+For held items, run `next --claim` rather than retrying. The lease is 30 minutes
+(`--lease-minutes`); an abandoned claim returns to the queue by itself.
 
-## What a good question looks like
+## Reading an item
 
-One decision. Their vocabulary, not the codebase's. And the choices in `--option`, not in
-the sentence.
+`pikku fabric changes show 3` gives, most trustworthy first:
 
-> **Bad:** "How would you like me to handle the ambiguity in the checkout total component's
-> emphasis requirement?"
->
-> **Good:** `--question "Make the total stand out — which way?"`
-> `--option "Bigger" --option "Move it above the delivery line"`
+1. **Their words.** The title and body are the requirement. Everything else is evidence.
+2. **The screenshot.** What they saw, at their width, with their data. When the other
+   addresses disagree with the picture, the picture is right.
+3. **The circled elements**: a testid (greps straight to a component, it is the i18n
+   key), a source anchor, a CSS path.
+4. **The source anchor**, `src/routes/app.orders.tsx:42 as of a91c4e2`, is where the JSX
+   was at *that* commit. Find today's equivalent; never edit line 42 because it said 42.
 
-**A choice written into the prose is not a choice.** Every `--option` becomes a button in
-the panel and the console, and clicking one records the answer; a question that says
-"(a) build it, (b) leave existing bookings, (c) hold" makes them re-type in free text what
-they should have been able to click, and leaves you parsing prose to find out which one
-they meant. If you can enumerate them in the sentence, you can pass them as flags.
+## When to ask
 
-Pass them even when there are only two, and even when one is "hold until I check" — that
-last one is a real option and it is the one most often left off. The filer can always
-choose "say something else", so the list constrains nothing.
+Ask when the item admits more than one reasonable implementation and you would be
+picking for them — "make the total stand out" (bigger? bolder? moved?), anything that
+changes stored data, what an existing user sees, or what something costs. Do not ask
+what the item already says, or implementation choices that are yours.
 
-Batch per group. Three questions about one checkout flow go out together; three separate
-asks about the same screen is three interruptions for one context switch.
+One decision, in their vocabulary, with the choices as `--option` flags — each becomes
+a button. Include "hold until I check" when it is real. Batch questions per group.
 
-Then **park it**. `ask` flips the item to `needs_answer` and you move to the next item. Do
-not sit waiting — pick answers up on your next `show`, and bound your polling so an
-unanswered item does not spin forever.
+```bash
+pikku fabric changes ask --change-id 3 --question "Make the total stand out — which way?" \
+  --option "Bigger" --option "Move it above the delivery line" --author-name claude-code
+```
 
-## When to show instead of ask
+Then **park it** and move on. The answer wakes `next` (same `--claimed-by`); it prints
+under `Answered`, and `show` has the reply.
 
-If the answer is visual and you can build it, build all of them and attach images:
+If the answer is visual and you can build it, build each variant, screenshot all of
+them in one pass at one width (baseline included), and attach them — the panel turns
+`--kind option` shots into a pick-one:
 
 ```bash
-pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
-pikku fabric changes shot --change-id <id> --label "Above the line" --kind option --image b.png
+pikku fabric changes shot --change-id 3 --label "Bigger" --kind option --image a.png
 ```
 
-The panel turns a set of `option` attachments into a pick-one they open full-screen, and
-picking one writes the choice into the thread. Capture every variant in **one pass at one
-width**, including the baseline — variants shot at different sizes are not comparable, and
-comparing is the whole point.
-
-`--kind evidence` is the other use: a picture that proves something, rendered inline rather
-than as a choice.
+`--kind evidence` is a picture that proves something, shown inline.
 
 ## Committing
 
-One item, one commit. `done` records a single `head_commit`, and that sha is what a human
-reverts when they change their mind — so an item folded in with three others cannot be
-undone without taking the other three with it. Land unrelated work separately.
-
-The subject carries the short id the way a GitHub issue number does, and the uuid goes in a
-trailer so `git log --grep` has an exact handle:
+One item, one commit — `done` records one sha, and that is what a human reverts. The
+subject carries the short id; the uuid goes in a trailer:
 
 ```
-feat(login): #4 make the sign-in heading brown
+fix(booking): #7 stop the date picker closing on the first click
 
 Change-Id: 0f3c8a12-9b44-4d2e-8f01-27c6a1d9e5b3
 ```
 
-Both ids come from `show`. The type and scope are the usual conventional-commit ones —
-`feat`, `fix`, `style`, `refactor` — with the scope naming the screen or area they were
-looking at, not the file you edited.
-
-More:
-
-```
-fix(booking): #7 stop the date picker closing on the first click
-style(nav): #12 tighten the spacing around the logo
-```
-
-Reverting one later is then:
-
-```bash
-git revert $(git log --grep="Change-Id: <uuid>" --format=%H -1)
-```
+Scope names the screen they were looking at, not the file you edited.
 
 ## Finishing
 
-`done` records the branch and commit that closed it, which is what strikes the item through
-on the page it was filed on and tells them where the fix landed. Both default to the
-checkout you are standing in, so run it from there and let it read git:
-
 ```bash
-pikku fabric changes done --change-id <id> \
-  --note "What you did, for whoever reads the thread later"
+pikku fabric changes done --change-id 7 --note "What you did, for whoever reads the thread"
 ```
 
-`--branch` and `--head-commit` override them, for the case where the fix landed somewhere
-other than where you are. Never type a sha by hand — one that does not exist points the
-filer at nothing.
-
-An item you decided not to do is not `done`. Say why in the thread and leave it for a human
-to dismiss.
-
-## Scope
+Branch and commit default to the checkout you are in — run it there, never type a sha.
+An item you decided not to do is not `done`: say why in the thread and leave it for a
+human to dismiss.
 
-Writes need the `changes:project:write` scope on your bearer. `list` and `show` are reads.
-The project comes from the local `pikkufabric.config.json`, so run these from the checkout.
+Writes need the `changes:project:write` scope; `list`, `show` and `next` without
+`--claim` are reads.

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

@@ -105,6 +105,9 @@ subscribe to its events as `<source>:<event>`:
 ```
 
 - The route is `POST /webhooks/<name>` unless `method`/`route` say otherwise.
+  `method` may be a list, e.g. `['get', 'post']` for a provider that verifies
+  the URL with a GET and delivers events with a POST, or `['head', 'post']`
+  for one that checks the URL with a HEAD.
   It needs no session.
 - `events` maps each event name to a schema. An event that fails its schema is
   logged and dropped; so is one no `wireTrigger` listens for. Both still get a
@@ -126,9 +129,12 @@ id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
   even on queues that ignore job ids, and records each attempt and its last
   error. Its `webhookReceipt` table comes from `pikku db generate`; `pikku dev`
   and `pikku serve` use it when a Kysely database is configured.
-- `receive` sees singleton services without `secrets`: read the signing secret
-  in a service method, and declare it with `defineSecret`. Name it in `secret`
-  so deploy knows where `setup` should store it.
+- `receive` sees singleton services without `secrets`. Declare the signing
+  secret with `defineCredential({ type: 'singleton', ... })` and hold it as
+  `WebhookSigningSecret.fromCredential(provider, credentialService, name)`
+  from `@pikku/core/hmac`; `receive` calls `await signingSecret.load()` and
+  checks against what it returns. A handshake that hands over the secret
+  (Asana) stores it with `credentialService.set`.
 
 `check`, `setup` and `teardown` register the route with the provider. Each gets
 `{ url, label, events, previous? }`, where `events` are only the ones some
@@ -142,10 +148,9 @@ pikku webhooks teardown --url https://api.example.com --labelPrefix shop:prod --
 
 Each prints one JSON line per source (`ok`, `missing`, `drifted`, `created`,
 `updated`, `unchanged`, `manual`, `deleted`, `absent`, `skipped`, `failed`). `setup` only
-runs where `check` does not report `ok`, and a `setup` that returns a new signing
-secret prints it with the `secret` name to store it under. In CI pass
-`--secretsOut <file>`: secrets are written there (mode 600) as
-`{ secretName: secret }` and left out of stdout. Any step can be
+runs where `check` does not report `ok`. A `setup` that gets a signing secret
+from the provider stores it with `credentialService.set`, and `teardown`
+deletes it, so a new secret needs no deploy and never reaches stdout. Any step can be
 `ref('<addon>:<fn>')` to use an addon's implementation.
 
 ## Usage Patterns