@pikku/skills 0.12.54 → 0.12.55

package/skills/pikku-fabric/references/deploy.md

@@ -1,179 +0,0 @@
-# Deploying a Fabric app
-
-## Contents
-
-- Deploy commands and organization targeting
-- Rebuilding a disposable stage: `--reset`
-- Exit codes, the approval gate, CI splitting, GitHub adoption and the upstream guard (inside Deploy commands)
-- The first user on a deployed stage
-- Opening a private stage
-
-## Deploy commands and organization targeting
-
-```bash
-pikku fabric login              # opens a browser; needs a human, wait for it
-pikku fabric init https://github.com/<owner>/<repo>
-pikku fabric validate           # must pass clean
-pikku fabric deploy apply --production -y
-```
-
-`init` and `link` import into whichever organization your session is in. When
-you belong to several — a personal one and a company one, say — name the target
-with `--organization`, taking a slug, a display name or an id:
-
-```bash
-pikku fabric link --organization vlandor
-```
-
-You have to be a member of the organization you name, and its GitHub account
-has to be connected already: importing a `github.com/<owner>/<repo>` repo needs
-the Fabric GitHub App installed on `<owner>` _and_ linked to that organization,
-or the import refuses by name.
-
-The branch is positional and defaults to the checked-out one, and `-y` is the
-short form of `--auto-approve`, so a one-shot deploy is:
-
-```bash
-pikku fabric deploy apply -y            # the branch you are standing on
-pikku fabric deploy apply my-branch -y  # a named one
-```
-
-`-y` answers the prompts and nothing more. It does **not** approve migrations
-that drop or rewrite data — that stays `--allow-destructive`, typed out on
-purpose.
-
-## Rebuilding a disposable stage: `--reset`
-
-A non-production stage whose migration history or schema has drifted (an app's
-`develop` branch) can be wiped and rebuilt in one deploy:
-
-```bash
-pikku fabric deploy apply develop --reset      # asks first, naming app + stage
-pikku fabric deploy apply develop --reset -y   # prints the warning, skips the prompt
-```
-
-It is the deployed counterpart of `pikku db reset`: **all data on that stage is
-deleted**, every migration is re-applied and `db/<engine>-dev-seed.sql` is
-loaded. It is refused for `--production`, for `main`, and with `--deployment-id`
-(it only applies to a deploy it creates). It needs a fabric server that reports
-the reset back on the deployment; against one that does not, the command fails
-naming the deployment it created without a reset, and wipes nothing. `-y` does
-not imply `--allow-destructive`.
-
-Inferring the branch is safe because the git safety check refuses any branch
-without an upstream or out of sync with it, so it cannot ship an unpushed
-commit; the branch it picked is printed before the build starts. A detached
-HEAD is refused by name rather than travelling on as a branch called `HEAD`.
-
-There is no `deploy plan` subcommand — `apply` runs the same auth, git-safety
-and ref resolution itself, and fabric produces the real plan server-side.
-
-`apply` confirms before deploying, and with no TTY to ask — CI, an agent shell —
-it refuses rather than hangs. `--auto-approve` (`-y`) supplies that confirmation;
-drop it only when a human is at a real terminal.
-
-`apply` waits for a terminal state and exits non-zero unless the deployment went
-live. `--detach` opts out — it queues the deploy, prints the deployment id and
-returns 0, which tells you nothing about whether it worked:
-
-| exit | meaning                                                                 |
-| ---- | ----------------------------------------------------------------------- |
-| 0    | live (or queued, under `--detach`)                                      |
-| 1    | the command could not run — not logged in, unsafe git state, bad flags  |
-| 2    | the deployment failed, errored, timed out server-side, or was cancelled |
-| 3    | the deployment is blocked and nothing the CLI can do will unblock it    |
-| 4    | the wait hit `--timeout` with the deployment still in flight            |
-
-On a failure or timeout, `apply` prints the tail of the builder's own log (and
-carries `buildLog` / `imageBuildLog` on the `--json` result). Read it before
-touching code: `fabric logs` serves the running stage, not the build. When the
-builder recorded nothing, the CLI says so — that is usually fabric-side, so run
-`pikku fabric smoke` before assuming the project is broken.
-
-Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
-Why it parked is the whole story, and it is `statusReason`, not `status`:
-
-- `awaiting_approval` — the plan is fine, a human has to publish it.
-  `-y` does that; without it you get exit 3 and the command to run.
-  One exception: if fabric marked any pending migration **destructive** — a
-  drop, a truncate, a rewrite — `-y` alone declines and exits 3,
-  because a standing yes was given before anyone knew the plan dropped a table.
-  The CLI lists the migrations and fabric's reasons; `--allow-destructive`
-  accepts them for that deploy, and `-y` implies it.
-- `needs_config` — a declared secret or variable has no value covering the
-  stage. The CLI names them. `-y` will **not** force this through;
-  set the values and re-attach — `pikku fabric secrets set <name>` for a
-  declared secret, `pikku fabric variables set <name> --value <v>` for a declared
-  variable. They are separate stores: a secret is sealed to the stage and cannot
-  be read back, a variable is stored plainly and can (`variables get`). `set`
-  reads the value as JSON when it parses, so `--value true` is the boolean on a
-  stage exactly as it is from `.env`, and `--value '"true"'` is the string.
-- `needs_attention` — the plan is red. Nothing to approve.
-
-The wait defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
-it prints the deployment id and the re-attach command rather than lying about
-the outcome.
-
-Splitting kick-off from waiting across two CI jobs is the reason
-`--deployment-id` exists, and what `--detach` is for — the first job here has to
-return the id and exit rather than wait:
-
-```bash
-id=$(pikku fabric deploy apply --production -y --detach --json | jq -r 'select(.event=="result").deploymentId')
-# …later, in another job…
-pikku fabric deploy apply --deployment-id "$id" -y
-```
-
-`--deployment-id` skips the git safety check entirely (the deployment already
-pins a sha, and the checkout is allowed to have moved on) and refuses to be
-combined with a branch or `--production`, which would let the two disagree.
-
-Under `--json`, the wait emits one NDJSON event per line — `created`/`attached`,
-`status` on each transition, `blocked`, `approved` — and the last line is the
-terminal result object, tagged `"event": "result"`.
-
-`init` adopts a **GitHub** repo, and adoption goes through the Pikku Fabric
-GitHub App — the app has to be installed on the account or org that owns the
-repo, and if it is installed with "selected repositories" this one must be in
-the selection. There is no CLI flag that works around a missing installation:
-`init` returns "Connect the GitHub account '<owner>'". Send the user to install
-it, or create the project in the console instead (which provisions a Fabric-hosted
-git repo you push to) and clone it — the remote links the checkout, or put
-the id in `fabric.projectId` in `pikku.config.json`.
-
-Deploy refuses to run unless the target branch equals its upstream — the guard
-compares `main` against `main@{upstream}`. So the remote you pushed to must be
-the one the branch tracks; a stale `origin` left over from scaffolding blocks
-the deploy with "local HEAD … ≠ remote …" even though your code is pushed.
-`git branch --set-upstream-to=<remote>/main main` before deploying.
-
-## The first user on a deployed stage
-
-When sign-up is off, the first account has to come from outside the app.
-`pikku fabric user add <email>` is the CLI form of the console's Add user:
-
-```bash
-pikku fabric user add ada@example.com --name Ada          # prompts; blank generates one
-pikku fabric user add ada@example.com --password '<pw>' -b staging
-```
-
-It mints a short-lived operator token for the stage and calls the stage's own
-`admin:createUser`, so the stage must wire `@pikku/addon-admin` as `admin` —
-a 404 is refused by name and nothing is created. A generated password is printed
-once; one you passed is never echoed. With no TTY, pass `--password` or pipe it.
-
-## Opening a private stage
-
-A non-production stage is private: without a link it answers "This preview is
-private". `pikku fabric stage link` prints the link that opens it:
-
-```bash
-pikku fabric stage link access -b develop --route /login   # use the stage
-pikku fabric stage link changes -b develop                 # use it with the changes panel
-pikku fabric stage visibility public -b develop            # or: private
-```
-
-A stage has one live link of each kind, so asking again returns the same one
-until it expires. A `changes` link turns the panel on first; if that needs a
-deploy, the command says so. `visibility public` opens the stage to anyone with
-its URL — hand out an `access` link instead when that is all you need.

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

@@ -1,123 +0,0 @@
-# Personas and actors
-
-## Contents
-
-- [Declaring personas in TypeScript](#declaring-personas-in-typescript)
-- [Actors that call a third-party API](#actors-that-call-a-third-party-api)
-- [The same actors sign a human in](#the-same-actors-sign-a-human-in)
-
-A **persona** is a person your product is for; an **actor** is one body that signs in as them. Every entry materialises exactly one actor, so `actors.<id>` exists for each declared persona and there is no second way to declare a login.
-
-- 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 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
-
-There may be **one `definePersonas` call in the whole codebase** — one place to
-read the set from, one place to add to it. A second anywhere, including in the
-same file, is a critical. Generated files are exempt and never claim the slot.
-
-> [!WARNING]
-> The declaration is **read from source, never evaluated** — the CLI writes it
-> to JSON that a deployed stage carries without the app. So every value has to
-> be statically knowable, and a value that is not comes out as `undefined`
-> rather than as an error. Only `name` is checked, so a computed `personality`,
-> `jobTitle` or `description` is dropped in silence and the persona runs with a
-> blank temperament.
-
-What that admits and what it does not:
-
-```typescript
-personality: 'Wound up and short with it.' // read
-personality: `Wound up and short with it.
-  Says what she wants in a few blunt words.` // read — no ${} in it
-personality: 'Wound up. ' + 'Short with it.' // dropped, silently
-personality: TEMPERAMENTS.impatient // dropped, silently
-```
-
-A no-substitution template literal is a string literal as far as the reader is
-concerned, so it is the way to write a long personality across several lines —
-not a concatenation, and not a `prettier-ignore`d single line. Its newlines and
-leading indentation are kept verbatim and reach the model that way, which is
-harmless but worth knowing before you align it to the surrounding code.
-
-One more thing worth knowing before writing a rich persona: **`actor.converse`
-builds its prompt from `name`, `jobTitle`, `personality` and the scenario's
-`task` only.** Fields like `disposition`, `goals` and `roles` are read and
-stored, and the console shows them, but they do not reach the conversing
-persona's instructions. Anything that must shape how someone talks belongs in
-`personality` or in the task.
-
-A project that never declares a persona keeps working: a scenario that names no actor needs none.
-
-- `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
-`actor` plugin (see `pikku-auth`, a separate install), which any caller can post to — so the
-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 switcher holds no credential. It lists personas from
-`/auth/sign-in/personas` and signs in by posting only a persona id to
-`/auth/sign-in/persona`; the server resolves the address. One server piece
-serves both, in the auth config:
-
-```ts snippet:personaSignIn
-```
-
-It is always open under `pikku dev`. A deployed stage needs actor
-sign-in opted in **and** its `devSwitcher` feature flag on; production never
-has the opt-in, so it lists nobody and refuses every persona sign-in.
-
-Do not hand-roll the switcher: `useDevActors()` (`pikku-react`, a separate install) is the logic and
-the starter template's `<DevActorSwitcher />` is a ready rendering of it.
-`pikku fabric validate` **requires** any frontend with a login screen to ship
-one — without it a reviewer is locked out of their own sandbox.
-When the switcher is missing, it is one of three things, and none of them
-errors:
-
-- **The list is empty.** On a deployed stage that is the gate
-  doing its job — check the opt-in and the `devSwitcher` flag. Locally, check
-  the personas declare an `email` (via `scenarios.emailDomain`) and are not
-  `runnable: false`.
-- **`personaSignIn` is missing, or the frontend calls another API.** A dev
-  proxy (`VITE_API_PROXY`, default `http://localhost:3000`) that points at
-  another project's API lists that project's personas, or none.
-- **It is not mounted on the page you are looking at.** The template mounts it
-  on the login screen. A public homepage that replaces the `/` → `/app`
-  redirect needs its own `<DevActorSwitcher />` in the public layout.
-
-When the switcher lists personas but a click 404s, that persona has no `email`
-or is `runnable: false`.