@pikku/skills 0.12.37 → 0.12.38

package/skills/pikku-scenario/SKILL.md

@@ -35,13 +35,13 @@ Use this skill as an execution checklist, not reference material.
 This skill covers writing and running scenarios end to end. Four topics are one level down, and
 each says when to open it:
 
-| Read                        | For                                                                       |
-| --------------------------- | ------------------------------------------------------------------------- |
-| `references/steps.md`       | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given |
-| `references/browser.md`     | Browser bindings, and locating by message key in a translated app         |
-| `references/personas.md`    | Personas vs actors, `definePersonas`, and the human "Sign in as …" switcher |
-| `references/coverage.md`    | Live coverage, filling it, and unit tests for pure logic                  |
-| `references/persona-run.md` | Running a persona as a model-driven virtual user against a stage          |
+| Read                        | For                                                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `references/steps.md`       | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given                                    |
+| `references/browser.md`     | Browser bindings, and locating by message key in a translated app                                            |
+| `references/personas.md`    | Personas vs actors, `definePersonas`, upstream credentials for actors, and the human "Sign in as …" switcher |
+| `references/coverage.md`    | Live coverage, filling it, and unit tests for pure logic                                                     |
+| `references/persona-run.md` | Running a persona as a model-driven virtual user against a stage                                             |
 
 ## What a scenario is
 
@@ -245,7 +245,7 @@ suite survives its first redesign:
   through the actor.
 - **Steps describe intent, not actions** — `buys the £5 strawberry milkshake`, never
   `clicks [data-testid=add]`. The clicking lives in plain utilities the step composes.
-- **`then` bindings are witnesses, not alternatives** — a `then` runs *every* binding it declares
+- **`then` bindings are witnesses, not alternatives** — a `then` runs _every_ binding it declares
   and fails when they disagree, because "database right, user still watching a spinner" is the bug
   nobody catches.
 - **What language the prose is in** — identifiers are English in every project; `description`,
@@ -265,6 +265,7 @@ whole project — codegen builds the `PersonaId` union from it, materialises one
 scenario actor per person, and seeds a user row each:
 
 ```ts snippet:definePersonas
+
 ```
 
 `pikku.config.json` carries the settings around them — nothing about a person:

package/skills/pikku-scenario/references/personas.md

@@ -5,7 +5,7 @@ A **persona** is a person your product is for; an **actor** is one body that sig
 - Two people of the same kind are two entries, not one persona with two logins — "you see yours, not theirs" is only testable with two customers.
 - Never write an email address: each is derived from the persona id and `scenarios.emailDomain`, and a hand-written one signs in as somebody who was never created.
 - `roles` is typechecked against `defineSystemRole`; an undeclared role is a build error.
-- A person who is only ever acted *upon* — the account an admin bans — sets `runnable: false`: declared and seeded, never signed in, because a run as them would race the scenario that acts on them.
+- A person who is only ever acted _upon_ — the account an admin bans — sets `runnable: false`: declared and seeded, never signed in, because a run as them would race the scenario that acts on them.
 - A persona holds only what is true of that kind of person for the app's whole lifetime (`name`, `jobTitle`, `description`, `personality`, `roles`, `goals`, `disposition`). What someone is trying to get done, and the circumstances they are doing it in, belong to the **scenario**, not to them.
 
 ## Declaring personas in TypeScript
@@ -50,6 +50,32 @@ A project that never declares a persona keeps working: a scenario that names no
 - `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`.
 - **`SCENARIO_ACTOR_SECRET` is an environment variable and never goes in `pikku.config.json`.** It signs actors in. `pikku scenario run` throws without it; a server auto-building actors warns and runs without them.
 
+## Actors that call a third-party API
+
+An addon generated from an upstream API (Dolibarr, a CRM, a calendar) calls it
+with the signed-in user's own credential. An actor has none until one is stored
+for it, so every step that reaches the addon fails with `No <X> session`. Give
+the `actor` plugin a `credentials` option, and each actor carries its upstream
+credential into every session:
+
+- `names: ['dolibarr']` — the credentials to carry
+- `store: (name, value, userId) => credentialService.set(name, value, userId)`
+- `remove: (name, userId) => credentialService.delete(name, userId)`
+
+At each actor sign-in the plugin reads `ACTOR_CREDENTIAL_<PERSONA>_<NAME>` —
+`dan` + `dolibarr` is `ACTOR_CREDENTIAL_DAN_DOLIBARR` — and stores it with
+`credentialService.set` for that actor. A bare value is stored as `{ token }`
+(what a delegated or bearer credential holds); a JSON object is stored as-is,
+e.g. `{"apiKey":"…"}` for an API-key credential. Unset means the actor has no
+upstream credential: `remove` drops one stored at an earlier sign-in.
+
+- **Values live in `.env` (or CI secrets), never in `personas.ts` or code.**
+  Use a dedicated upstream test account per persona, not a real person's.
+- `read` defaults to `process.env`; a Worker passes `(key) => variables.get(key)`.
+- A malformed JSON value refuses the sign-in with a 500 that names the variable.
+- A delegated token expires upstream like any other; re-signing the actor
+  in re-stores whatever the variable holds now.
+
 ## The same actors sign a human in
 
 Declared actors are not only for automated runs. `signInPath` is Better Auth's
@@ -57,8 +83,8 @@ Declared actors are not only for automated runs. `signInPath` is Better Auth's
 frontend gets a one-click "Sign in as …" switcher over the **same** list, and an
 app can be reviewed as each kind of user without anyone knowing a seed password.
 
-The sandbox dev server bakes both halves into the frontend from the declared
-personas: `VITE_DEV_ACTORS` (the JSON actor list) and `VITE_DEV_ACTOR_SECRETS`
+The dev server bakes both halves into the frontend from the declared
+personas — the sandbox's, or the template's `bun run dev`, never `pikku dev`: `VITE_DEV_ACTORS` (the JSON actor list) and `VITE_DEV_ACTOR_SECRETS`
 (`{ email: credential }`, one per persona — `SCENARIO_ACTOR_SECRET` itself never
 goes in a bundle; see **pikku-auth**). Neither var is set in a production
 build, so the control renders nothing there — but gate the reads on your
@@ -85,3 +111,39 @@ When the switcher is there but signing in fails with `401 Invalid actor
 secret`, check which server answered before checking the secret: a frontend
 whose dev proxy (`VITE_API_PROXY`, default `http://localhost:3000`) points at
 another project's API sends the sign-in there.
+
+**A runner of your own that starts vite has to bake them itself**, from the
+generated persona meta (`<outDir>/workflow/personas.gen.json`, which already
+carries the derived `email`):
+
+```js
+const personas = Object.values(JSON.parse(readFileSync(personasPath, 'utf8')))
+
+env.VITE_DEV_ACTORS = JSON.stringify(
+  personas.map(({ id, email, name, jobTitle }) => ({
+    key: id,
+    email,
+    name,
+    jobTitle: jobTitle ?? '',
+  }))
+)
+env.VITE_DEV_ACTOR_SECRETS = JSON.stringify(
+  Object.fromEntries(
+    await Promise.all(
+      personas.map(async ({ email }) => [
+        email,
+        await deriveActorSecret(env.SCENARIO_ACTOR_SECRET, email),
+      ])
+    )
+  )
+)
+```
+
+**Set `SCENARIO_ACTOR_SECRET` yourself**, at least 32 characters, in the
+environment both processes read. Left unset, `pikku dev` mints an ephemeral root
+for its own run that a separately spawned vite cannot see, so the two derive
+from different roots: the switcher renders every persona and each click is
+refused, which reads as a broken login rather than missing configuration. On a
+brand-new project the persona file does not exist until the first `pikku dev`
+codegen, after vite has baked an empty list — watch it and restart the frontend
+when it changes.