arcodangeandClaude Fable 5
0240c519b1
The checkpoint status/relink-env armed probe calls GET /users/info, which requires Dolibarr right 251 (user->user->lire). WRITE_IDS didn't include it, so a freshly provisioned agent answered 403 on the probe — reported NOT armed — while its key actually authenticates (GET /thirdparties -> 200). Right 251 was granted live in SQL on the sandbox (fk_user=4) today; this persists it in WRITE_IDS so every future provision grants it. Also teach both probes to tell the failure modes apart instead of one opaque message: 401 = key rejected (stale/instance-encrypted -> re-provision), 403 = key OK but right 251 missing (-> grant it / re-provision), 200 = armed. Docs updated accordingly (checkpoint SKILL.md probe outcomes, sandbox-write SKILL.md gotcha, test/README.md rights table synced to WRITE_IDS incl. 262/111). Co-Authored-By: Claude Fable 5 <[email protected]>
78 lines
4.3 KiB
Markdown
78 lines
4.3 KiB
Markdown
---
|
|
name: dolibarr-sandbox-checkpoint
|
|
description: Manage the erp-sandbox iso-prod checkpoint — status, reset (refresh-from-prod), re-provision the write agent, relink the write skill .env. Use after rehearsing writes when you want a clean prod-shaped sandbox again.
|
|
---
|
|
|
|
# dolibarr-sandbox-checkpoint
|
|
|
|
Lifecycle management for the **erp-sandbox** iso-prod checkpoint (ADR-0003). The
|
|
sandbox exists so an agent can rehearse Dolibarr writes on prod-shaped data; this
|
|
skill resets it back to a clean iso-prod baseline and re-arms the write path.
|
|
|
|
All commands are exposed via the CLI:
|
|
|
|
```sh
|
|
arcodange sandbox checkpoint status
|
|
arcodange sandbox checkpoint refresh --yes
|
|
arcodange sandbox checkpoint provision
|
|
arcodange sandbox checkpoint relink-env
|
|
```
|
|
|
|
## The reset cycle
|
|
|
|
```
|
|
refresh --yes provision (auto) relink-env
|
|
───────────────► ──────────────────────► ─────────────────────────►
|
|
wipe + re-seed re-create the write rewrite the write skill
|
|
iso-prod from agent (Playwright; .env from the new key +
|
|
prod (~2-3 min) you log in) + key verify it authenticates
|
|
```
|
|
|
|
1. **`status`** — HTTP liveness + whether the write agent (`ai_agent_sandbox`) is
|
|
*armed*. The armed probe calls `GET /users/info` with the linked key; three
|
|
outcomes: **200** → `ARMED`; **401** → the key itself is rejected (stale, e.g.
|
|
an iso-prod refresh re-encrypted it) → re-run `provision`; **403** → the key
|
|
authenticates but lacks right **251** (`user → lire`, which `/users/info`
|
|
requires) → re-provision (a fresh run grants it via `WRITE_IDS` in
|
|
`test/provisionSandbox.ts`) or grant 251 by hand. Read-only, no cluster access.
|
|
2. **`refresh --yes`** — re-seed the sandbox iso-prod from prod, wrapping
|
|
`ops/sandbox/sandbox-lifecycle.sh` (read-only `pg_dump` of prod → `DROP OWNED` →
|
|
`pg_restore`, then documents/logo sync). **Destructive**: requires `--yes`, and
|
|
it wipes the write agent too (iso-prod overwrites `llx_user` with prod's, which
|
|
has no `ai_agent_sandbox`). `--db-only` skips the documents sync. Needs `kubectl`
|
|
on the lab cluster.
|
|
3. **`provision`** — re-create the write agent by running the Playwright POC
|
|
(`test/provisionSandbox.ts`). It opens a browser; **you complete the admin
|
|
login** — with the **PROD** admin credentials, since the sandbox is iso-prod
|
|
(they come from `test/.env.sandbox`). The POC re-grants the agent's rights
|
|
(including `banque lire` and `user lire` = right 251, which the armed probe
|
|
needs) and writes the key to `test/.ai_agent_sandbox.key`,
|
|
then this command auto-runs `relink-env`. Needs `deno`.
|
|
4. **`relink-env`** — (re)write `dolibarr-sandbox-write/.env` from
|
|
`test/.ai_agent_sandbox.key` (mode 600) and verify it authenticates. Run it
|
|
standalone any time the key changed.
|
|
|
|
## Why a refresh wipes the agent (and the key)
|
|
|
|
A full refresh is **iso-prod**: it replaces the whole `public` schema (incl.
|
|
`llx_user` and `llx_const`) with prod's. So `ai_agent_sandbox` — created *after* the
|
|
seed, absent from prod — disappears, and `DOLI_INSTANCE_UNIQUE_ID` reverts to prod's,
|
|
which invalidates the instance-encrypted API key. That's why re-provisioning (not
|
|
just re-linking) is required after every refresh. This is by design (ADR-0003): the
|
|
sandbox's prod-write isolation is structural, and the agent is cheap to recreate.
|
|
|
|
## Gotchas
|
|
|
|
- **Run from an up-to-date checkout.** The `.env` is written next to the
|
|
`dolibarr-sandbox-write` skill in *this* checkout — invoke `arcodange` from a
|
|
worktree synced to `origin/main` (the trunk may lag), or the skill/`.env` won't be
|
|
where your writes look for them.
|
|
- **PROD admin creds for `provision`.** If the Playwright login fails, fix
|
|
`DOLI_ADMIN_PASSWORD` in `test/.env.sandbox` to prod's admin password.
|
|
- **`refresh` needs `kubectl`** (lab cluster context); **`provision` needs `deno`**.
|
|
- The lifecycle script pauses ArgoCD self-heal for the re-seed and restores it via
|
|
an EXIT trap — an interrupted refresh won't strand the sandbox scaled to 0.
|
|
|
|
See also: `dolibarr-sandbox-write/SKILL.md` (the writes this arms), `ops/sandbox/`
|
|
(the lifecycle script + README), factory `vibe/ADR/0003-sandbox-state-lifecycle.md`.
|