@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

package/dist/skill/references/users/use-test-account.md

@@ -0,0 +1,79 @@
+# Use a tenant's test account
+
+**When to use:** you want to walk a school's actual admission process as an
+applicant — on local, staging or prod — without registering a new address first.
+
+## Prerequisites
+
+- The account exists already in every tenant with an applicant portal:
+  `config:bootstrap` provisions it on every deploy, `config apply` on every
+  tenant onboarding, and the local development seed. Nothing to create.
+- Identity: **`test@example.com`** ("Test Bewerber", stable key `fixture_test`
+  on `user_tenant_access.configKey`), a member of the tenant's applicant group.
+- Staging/prod: a platform admin (`_platform.users.manage`) to set its password
+  once per deployment.
+
+## Steps
+
+### 1. Check the account in the target tenant
+
+```bash
+plexus-cli --env <local|staging|prod> users show test@example.com
+```
+
+Expect one access row per tenant with an applicant portal, each in the
+`applicant` group.
+
+### 2. Set a password (staging / prod, once per deployment)
+
+A deploy provisions the account with a random password nobody holds. Set one:
+
+```bash
+plexus-cli --env <staging|prod> --tenant <slug> users set-password test@example.com
+```
+
+The identity is global, so this one password opens the account in **every**
+tenant of that deployment. The plaintext is printed once — password manager,
+not a ticket.
+
+**Local** needs no password: the account carries the dev-login marker, so
+`/login?as=test@example.com&redirect=/<slug>/e` signs in as it.
+
+### 3. Apply
+
+Open `https://<host>/<slug>/e`, start the offer, fill the form — the same
+surfaces a parent uses.
+
+## Verify
+
+```bash
+# It is the test row of "Wer ist der Antragsteller?" (needs testActions.run).
+plexus-cli --env <env> call admission:testApplicantParties client=<slug>
+```
+
+## Gotchas
+
+- **Every application of it is a test application.** Started by the
+  account itself through the portal (any Testmodus checkbox is irrelevant) or
+  by staff from the internal „+ Bewerbung" dialog (its amber first row, for
+  anyone with `bewerbungsmanagement.testActions.run`; refused without it), the
+  server derives test mode from the key. Discard it like any test application.
+- **Mail.** Never sent, in any mode (staging `redirect` included):
+  `example.com` is a reserved test address, so the delivery is rendered and
+  recorded and settles `skipped` / `reserved_address` — sign in with the
+  password, not a magic link.
+- **A deploy never rotates the password.** An existing credential is preserved,
+  so a password you distributed survives every `config:bootstrap`.
+- **Identity is the key, not the name.** Renaming "Test Bewerber" moves the row;
+  it never creates a second account.
+- **A real account on `test@example.com` fails the deploy** (`config:bootstrap`
+  throws "not the test fixture"). Move that account to another address first.
+- **Not in `config export`.** The account is platform-provisioned, so it is
+  never emitted as a config user.
+- Skipped (and named in the bootstrap result under `fixtures.skipped`): tenants
+  without a `defaultApplicantGroupKey`, and the reserved `_platform` tenant.
+
+## Related
+
+- [Drive a test application through test mode](../test-actions/drive-a-test-application.md)
+- [Set (rotate) a user's password](./set-password.md)

package/dist/skill/references/worker-ops/debug-worker-jobs.md

@@ -0,0 +1,90 @@
+# Debug a stuck / failed import or worker job
+
+**When to use:** an import shows "running" but looks stuck, the Worker console
+shows no active worker, a job failed and you need to know why, or you must clean
+up a stranded import run. This is the **canonical agent debugging setup** for the
+worker/job system: `plexus-cli` for the LIVE job/worker/import state +
+`glitchtip-cli` for the captured stack traces.
+
+## Prerequisites
+- `--env local|staging|prod`; the new worker/job commands need **platform-admin**
+  (the configured token already is, on staging/prod).
+- For the stack traces: access to the platform's GlitchTip (the error tracker the
+  worker reports to), e.g. through `glitchtip-cli` (`glitchtip-cli info` shows the
+  server + auth). That is platform-operator access; without it, ask the operator.
+
+## Steps
+
+```bash
+# 1. Live fleet: is any worker alive, and what is it running right now?
+plexus-cli --env prod platform workers --json        # lifecycle live|stale|dead, currentJob
+
+# 2. The jobs themselves (generic queue). Filter to what's stuck/broken.
+plexus-cli --env prod jobs list --status running     # genuinely in flight
+plexus-cli --env prod jobs list --status failed --kind import
+plexus-cli --env prod jobs show <jobId>              # lease, attempts, phase, error, run timeline
+plexus-cli --env prod jobs logs <jobId>             # captured worker stdout/stderr
+
+# 3. Import-domain view (imports stuck "still running" live here, NOT in jobs).
+plexus-cli --env prod imports status --tenant <slug>
+
+# 4. Captured exceptions for the failure (stack trace + tags).
+glitchtip-cli issues list
+#   GlitchTip event tags the worker attaches: errorSource=backend:worker,
+#   jobKind, jobId, importRunId, configKey. Filter by them via GlitchTip's API
+#   (the CLI `issues list` has no tag filter).
+
+# 5. Is the reaper (the only authority that frees stuck leases) actually firing?
+plexus-cli --env prod workers reaper-status --json   # ranAt should be < ~1 min old
+```
+
+### The decision rule (why did the worker die?)
+
+A job reaper-failed / vanished, **and**:
+- **GlitchTip HAS an event** → it was a JS throw. Read the stack in the issue.
+- **GlitchTip has NO event** → uncatchable **OOM/SIGKILL**. The only trace is the
+  reaper-failed job; its error message names the last phase + idle time (e.g.
+  *"vanished during phase 'importing' after N min"*). Confirming it needs a
+  platform operator with host access: the worker container's **exit code 137**
+  (or the kernel's OOM-killer log).
+
+## Recovery
+
+```bash
+# Force a reaper pass now instead of waiting for the 1-min cron.
+plexus-cli --env prod workers reap --allow-prod --json
+
+# Clear import runs stuck 'running' with no active job (the orphan class).
+# DRY-RUN first (no --confirm), then confirm. Marks failed, never deletes.
+plexus-cli --env prod imports cleanup-orphaned --tenant <slug>
+plexus-cli --env prod imports cleanup-orphaned --allow-prod --tenant <slug> --confirm
+plexus-cli --env prod imports cleanup-orphaned --all-tenants            # dry-run sweep
+
+# Cancel a job that should not be running.
+plexus-cli --env prod jobs cancel --allow-prod <jobId>
+```
+
+## Verify
+
+```bash
+plexus-cli --env prod imports status --tenant <slug>   # the stuck run now 'failed'
+plexus-cli --env prod jobs list --status running       # nothing unexpectedly in flight
+```
+
+## Idempotency / gotchas
+- `cleanup-orphaned` and `jobs cancel` flip rows to **failed/canceled**, never
+  delete — history is preserved. `cleanup-orphaned` is dry-run unless `--confirm`.
+- Since the terminal-state fix (the job registry's `onTerminal` hook), a job
+  that terminally fails now propagates to its `import_runs` row automatically —
+  **new** orphans shouldn't appear; `cleanup-orphaned` is for pre-fix strays and
+  as a backstop.
+- The **reaper** only touches the generic `jobs` table (frees leases / fails
+  stalled jobs); it does **not** scan `import_runs`. A "running" import with all
+  workers idle = an orphaned domain row → use `cleanup-orphaned`.
+- `jobs list --kind` filters client-side after paging; raise `--limit` if you page
+  past the row you want.
+
+## Related
+- [Verify that a deploy's migrations ran](./verify-migrations.md)
+- Command reference: `plexus-cli jobs list --help`, `plexus-cli workers reap --help`,
+  `plexus-cli imports cleanup-orphaned --help`.

package/dist/skill/references/worker-ops/verify-migrations.md

@@ -0,0 +1,51 @@
+# Verify that a deploy's migrations ran
+
+**When to use:** after a staging or production deploy whose release lists
+pending migrations (the release's `PENDING_MIGRATIONS` list), when you need the
+state from the deployment itself rather than from the deploy log. The deploy job
+already prints, by name, the dry run of the next migration, every migration that
+ran (with its document count) and a final check that every pending entry is
+`success` — it goes red if any is not; that log is the platform operator's.
+
+## Prerequisites
+- `--env staging|prod` (or `local` for a local development backend).
+- The CLI token's user holds `_platform.config.read` (every full platform
+  admin does). Anyone else gets `FORBIDDEN`.
+
+## Steps
+
+```bash
+plexus-cli --env staging migrations status            # pending migrations, exit 1 while one is not success
+plexus-cli --env staging migrations status --recent   # + the 20 most recently started of any name
+plexus-cli --env staging migrations status --json     # raw answer + `unfinished`
+```
+
+A release script gates on the exit code instead of grepping the output:
+`plexus-cli --env prod migrations status || exit 1`.
+
+Underneath it reads `migrations:getStatus`, which returns two lists of `{ name, state, isDone, processed, error, latestStart, latestEnd }`:
+- **`pending`**: every entry of `PENDING_MIGRATIONS`, in run order. After a good
+  deploy each one reads `state: "success"`, `isDone: true`. A name that reads
+  `unknown` never started on this deployment.
+- **`recent`**: the 20 most recently started migrations of any name, newest
+  first. Use it to see what the last deploy actually touched.
+
+## Verify
+- Every `pending` entry is `success`, and `latestEnd` is after the deploy's
+  workflow run started.
+- `pending` is empty when the release carries no migration. Then there is
+  nothing to verify, and the migration step only pushed functions.
+
+## Gotchas
+- `failed` or `canceled` with an `error`: `runPending` threw and the deploy
+  stopped before the config bootstrap. Read the error here; the host-side output
+  is in the deploy log (platform operator).
+- `inProgress` long after the deploy means the migration is stuck. Hand it to a
+  platform operator; do not try to restart it from the CLI.
+- A local development backend lists every pending migration as `unknown` (exit 1): the seed
+  builds data in the new shape and never runs migrations. Only staging/prod answer the question.
+- „Could not find public function migrations:getStatus“: the CLI points at a deployment
+  without this release (often a local development backend that never received the
+  functions). Check `--env` (`plexus-cli config show`).
+- The query shows names, state, progress and errors only; it never returns a
+  cursor or document data.