Merge pull request 'feat(skills,cli): dolibarr-sandbox-checkpoint — manage the sandbox iso-prod checkpoint' (#30) from claude/sandbox-checkpoint-cli into main

.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`.

.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"

.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 <<EOF
+checkpoint-refresh: this WIPES all erp-sandbox data and re-seeds iso-prod from prod.
+  - the ai_agent_sandbox write user + its key are wiped → you re-provision after
+  - prod is read ONLY (structural guarantee, ADR-0003); only the sandbox is written
+Re-run with --yes to proceed. Then: arcodange sandbox checkpoint provision
+EOF
+  exit 3
+fi
+
+echo ">>> 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"

.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)"

.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

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                <METHOD> <path> [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                 <manifest.json>           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 ;;