From 275a59b47869494bf8d19512e81d7689f231342f Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Tue, 30 Jun 2026 07:19:59 +0200 Subject: [PATCH] =?UTF-8?q?feat(skills,cli):=20dolibarr-sandbox-checkpoint?= =?UTF-8?q?=20=E2=80=94=20manage=20the=20sandbox=20iso-prod=20checkpoint?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A skill + CLI group to drive the ADR-0003 sandbox lifecycle, instead of the manual kubectl/deno/.env dance: arcodange sandbox checkpoint status # liveness + is the write agent armed? arcodange sandbox checkpoint refresh --yes # re-seed iso-prod (DESTRUCTIVE, gated) arcodange sandbox checkpoint provision # re-create ai_agent_sandbox (Playwright) + relink arcodange sandbox checkpoint relink-env # rewrite write skill .env from the key + verify - refresh wraps ops/sandbox/sandbox-lifecycle.sh; requires --yes (it wipes the agent too, since iso-prod overwrites llx_user). --db-only skips the documents sync. - provision runs test/provisionSandbox.ts (you do the admin login — PROD creds, iso-prod) then auto-relinks; relink-env writes .env mode 600 and verifies via GET /users/info. - scripts resolve the repo root from ARCO_ROOT (set by bin/arcodange) or their own path, so they work via the CLI or standalone. Tested: status reports armed/not-armed correctly; refresh refuses without --yes (exit 3); relink-env errors with no key (exit 1); help/usage wired. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../dolibarr-sandbox-checkpoint/SKILL.md | 71 +++++++++++++++++++ .../scripts/checkpoint-provision.sh | 23 ++++++ .../scripts/checkpoint-refresh.sh | 40 +++++++++++ .../scripts/checkpoint-relink-env.sh | 30 ++++++++ .../scripts/checkpoint-status.sh | 32 +++++++++ bin/arcodange | 29 +++++++- 6 files changed, 224 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/dolibarr-sandbox-checkpoint/SKILL.md create mode 100755 .claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-provision.sh create mode 100755 .claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-refresh.sh create mode 100755 .claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-relink-env.sh create mode 100755 .claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-status.sh diff --git a/.claude/skills/dolibarr-sandbox-checkpoint/SKILL.md b/.claude/skills/dolibarr-sandbox-checkpoint/SKILL.md new file mode 100644 index 0000000..efb1a7a --- /dev/null +++ b/.claude/skills/dolibarr-sandbox-checkpoint/SKILL.md @@ -0,0 +1,71 @@ +--- +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* (its key authenticates `GET /users/info`). 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 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`. diff --git a/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-provision.sh b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-provision.sh new file mode 100755 index 0000000..7d2ad97 --- /dev/null +++ b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-provision.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +# Re-provision the ai_agent_sandbox write user after a refresh, then relink the +# write skill .env. Runs the Playwright POC (test/provisionSandbox.ts): it opens a +# browser — YOU complete the admin login. +# +# IMPORTANT: the sandbox is iso-prod, so log in with the PROD admin credentials. +# Those come from test/.env.sandbox (DOLI_ADMIN_LOGIN / DOLI_ADMIN_PASSWORD) — make +# sure they are prod's. The POC re-grants the agent's rights (incl. banque lire) and +# writes the new key to test/.ai_agent_sandbox.key. +set -euo pipefail +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="${ARCO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}" +POC="${ROOT}/test/provisionSandbox.ts" + +command -v deno >/dev/null || { echo "checkpoint-provision: deno not found (https://deno.land)" >&2; exit 1; } +[[ -f "${POC}" ]] || { echo "checkpoint-provision: missing ${POC}" >&2; exit 1; } +[[ -f "${ROOT}/test/.env.sandbox" ]] || echo "checkpoint-provision: WARN no test/.env.sandbox (admin creds) — login may fail" >&2 + +echo ">>> launching provisionSandbox.ts — complete the admin login in the browser (use PROD admin creds)" +( cd "${ROOT}/test" && deno run --allow-all provisionSandbox.ts ) + +echo ">>> provisioning finished; relinking the write skill .env" +exec "${SCRIPT_DIR}/checkpoint-relink-env.sh" diff --git a/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-refresh.sh b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-refresh.sh new file mode 100755 index 0000000..4bd57ee --- /dev/null +++ b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-refresh.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# Re-seed erp-sandbox to a clean iso-prod checkpoint (ADR-0003). Wraps +# ops/sandbox/sandbox-lifecycle.sh. +# +# DESTRUCTIVE: wipes ALL sandbox data — including the ai_agent_sandbox write user +# and its API key (iso-prod overwrites llx_user with prod's). After it completes +# you MUST re-provision: arcodange sandbox checkpoint provision +# +# checkpoint-refresh.sh --yes # db re-seed + documents (logo) sync +# checkpoint-refresh.sh --yes --db-only # db re-seed only (skip documents) +set -euo pipefail +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="${ARCO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}" +LIFECYCLE="${ROOT}/ops/sandbox/sandbox-lifecycle.sh" +[[ -f "${LIFECYCLE}" ]] || { echo "checkpoint-refresh: missing ${LIFECYCLE}" >&2; exit 1; } + +MODE="refresh"; YES=0 +while [[ $# -gt 0 ]]; do + case "$1" in + --yes) YES=1; shift ;; + --db-only) MODE="refresh-from-prod"; shift ;; + *) echo "checkpoint-refresh: unknown arg '$1'" >&2; exit 2 ;; + esac +done + +if [[ "${YES}" != "1" ]]; then + cat >&2 <>> re-seeding erp-sandbox (${MODE}) — ~2-3 min (scale-down, pg_dump prod, restore, scale-up)" +bash "${LIFECYCLE}" "${MODE}" +echo +echo ">>> iso-prod checkpoint restored. The write agent was wiped — bring it back with:" +echo " arcodange sandbox checkpoint provision" diff --git a/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-relink-env.sh b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-relink-env.sh new file mode 100755 index 0000000..73bf73e --- /dev/null +++ b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-relink-env.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# (Re)write the dolibarr-sandbox-write skill .env from the provisioned key file, +# then verify it authenticates. Run this after 'provision' (or any time the key +# changed). The key is instance-encrypted per Dolibarr instance, so a refresh +# invalidates it — re-provision first if this fails to authenticate. +set -euo pipefail +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="${ARCO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}" +SB_URL="${DOLIBARR_SANDBOX_URL:-https://erp-sandbox.arcodange.lab}" +KEY="${ROOT}/test/.ai_agent_sandbox.key" +ENV="${ROOT}/.claude/skills/dolibarr-sandbox-write/.env" +DOLW="${ROOT}/.claude/skills/dolibarr-sandbox-write/scripts/dol-write.sh" + +[[ -s "${KEY}" ]] || { echo "checkpoint-relink-env: no key at ${KEY}" >&2 + echo " run 'arcodange sandbox checkpoint provision' first." >&2; exit 1; } + +umask 077 +{ echo "DOLIBARR_SANDBOX_URL=${SB_URL}" + printf 'DOLIBARR_SANDBOX_API_KEY=%s\n' "$(tr -d '\r\n' < "${KEY}")"; } > "${ENV}" +chmod 600 "${ENV}" +echo "✓ wrote ${ENV} (mode 600)" + +printf 'verify: ' +"${DOLW}" GET /users/info | python3 -c "import json,sys +d = json.load(sys.stdin) +if isinstance(d, dict) and d.get('login'): + print('OK — armed as %s (id %s)' % (d['login'], d.get('id'))) +else: + msg = d.get('error', {}).get('message', '?') if isinstance(d, dict) else str(d) + print('FAILED — %s' % msg); sys.exit(1)" diff --git a/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-status.sh b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-status.sh new file mode 100755 index 0000000..1e9e7c0 --- /dev/null +++ b/.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-status.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# Report the erp-sandbox checkpoint state: HTTP liveness + whether the write agent +# (ai_agent_sandbox) is armed (its key authenticates). Read-only, no cluster access. +set -uo pipefail +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="${ARCO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}" +SB_URL="${DOLIBARR_SANDBOX_URL:-https://erp-sandbox.arcodange.lab}" +WRITE_ENV="${ROOT}/.claude/skills/dolibarr-sandbox-write/.env" +DOLW="${ROOT}/.claude/skills/dolibarr-sandbox-write/scripts/dol-write.sh" +KEY="${ROOT}/test/.ai_agent_sandbox.key" + +echo "erp-sandbox checkpoint status" +code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 "${SB_URL}/" 2>/dev/null || echo "---") +echo " HTTP : ${code} (${SB_URL})" +echo " agent key file : $([ -s "${KEY}" ] && echo "present" || echo "absent (provision needed)")" +if [[ -f "${WRITE_ENV}" ]]; then + echo " write .env : present" + printf ' write agent : ' + "${DOLW}" GET /users/info 2>/dev/null | python3 -c "import json,sys +try: + d = json.load(sys.stdin) +except Exception: + print('NOT armed — no/invalid response'); sys.exit(0) +if isinstance(d, dict) and d.get('login'): + print('ARMED — login=%s id=%s' % (d['login'], d.get('id'))) +else: + msg = d.get('error', {}).get('message', '?') if isinstance(d, dict) else 'unexpected' + print('NOT armed — %s' % msg[:80])" +else + echo " write .env : ABSENT" + echo " write agent : not linked — run 'arcodange sandbox checkpoint relink-env' after provisioning" +fi diff --git a/bin/arcodange b/bin/arcodange index 2ad2324..4cb4e8a 100755 --- a/bin/arcodange +++ b/bin/arcodange @@ -89,6 +89,7 @@ COMMANDS creditnote Create an avoir — customer or supplier (kind) accounts List bank accounts (id/label) to pick account_id write [body] Raw host-guarded write + checkpoint status|refresh|provision|relink-env Manage the iso-prod checkpoint promote Replay a reviewed change-set sandbox -> prod (ADR-0003) plan Human-readable review of the change-set @@ -288,6 +289,30 @@ EOF creditnote) exec "${SKILLS}/dolibarr-sandbox-write/scripts/creditnote-create.sh" "$@" ;; accounts) exec "${SKILLS}/dolibarr-sandbox-write/scripts/bank-accounts.sh" "$@" ;; write) exec "${SKILLS}/dolibarr-sandbox-write/scripts/dol-write.sh" "$@" ;; + checkpoint) + export ARCO_ROOT="${SROOT}" + csub="${1:-status}"; shift || true + case "${csub}" in + status) exec "${SKILLS}/dolibarr-sandbox-checkpoint/scripts/checkpoint-status.sh" "$@" ;; + refresh) exec "${SKILLS}/dolibarr-sandbox-checkpoint/scripts/checkpoint-refresh.sh" "$@" ;; + provision) exec "${SKILLS}/dolibarr-sandbox-checkpoint/scripts/checkpoint-provision.sh" "$@" ;; + relink-env) exec "${SKILLS}/dolibarr-sandbox-checkpoint/scripts/checkpoint-relink-env.sh" "$@" ;; + help|-h|--help) + cat <<'EOF' +arcodange sandbox checkpoint — manage the erp-sandbox iso-prod checkpoint (ADR-0003). + + status Liveness + whether the write agent is armed (key authenticates) + refresh --yes [--db-only] Re-seed iso-prod from prod (DESTRUCTIVE; wipes the agent too) + provision Re-create ai_agent_sandbox (Playwright; you log in) + relink .env + relink-env Rewrite the write skill .env from test/.ai_agent_sandbox.key + verify + +Typical reset: arcodange sandbox checkpoint refresh --yes then ... provision +(provision opens a browser for the admin login — use the PROD admin creds, iso-prod — and auto-relinks the .env) +EOF + ;; + *) echo "arcodange sandbox checkpoint: unknown '${csub}' (try 'arcodange sandbox checkpoint help')" >&2; exit 2 ;; + esac + ;; help|-h|--help) cat <<'EOF' arcodange sandbox — WRITE operations against erp-sandbox (rehearsal ONLY). @@ -303,9 +328,11 @@ Each subcommand reads a JSON object on stdin (or a file path arg). creditnote avoir (credit note) referencing a source invoice echo '{"socid":42,"source_invoice":19,"validate":true,"lines":[...]}' | arcodange sandbox creditnote write raw host-guarded write arcodange sandbox write POST /thirdparties '{"name":".."}' + checkpoint manage the iso-prod checkpoint (status|refresh|provision|relink-env) + arcodange sandbox checkpoint status Needs .claude/skills/dolibarr-sandbox-write/.env (DOLIBARR_SANDBOX_URL + _API_KEY). -See dolibarr-sandbox-write/SKILL.md. +See dolibarr-sandbox-write/SKILL.md and dolibarr-sandbox-checkpoint/SKILL.md. EOF ;; *) echo "arcodange sandbox: unknown subcommand '${sub}' (try 'arcodange sandbox help')" >&2; exit 2 ;; -- 2.49.1