Merge pull request 'feat(skills,cli): sandbox avoir (credit note) + arcodange sandbox CLI group' (#22) from claude/dolibarr-sandbox-write-cli into main

.claude/skills/dolibarr-sandbox-write/SKILL.md

@@ -104,6 +104,17 @@ payments require an explicit `amount`. `account_id` is the bank account id (the
 read-only `dolibarr-payments-state` skill lists them; `ai_agent_sandbox` does not
 yet have `banque lire`, so pass the id). Emits the new payment id.
 
+### 4 · Credit note (avoir) — `scripts/creditnote-create.sh`
+
+```sh
+echo '{"socid":42,"source_invoice":19,"validate":true,
+       "lines":[{"desc":"Avoir partiel conseil","qty":1,"price_ht":100,"tva":20,"type":"service"}]}' \
+  | scripts/creditnote-create.sh
+```
+A customer invoice of `type=2` referencing `source_invoice` (`fk_facture_source`);
+amounts come out negative (a credit). `validate:true` turns the draft into a
+numbered `AVC…` avoir. Emits `{id, ref, total_ht, total_ttc, fk_facture_source, statut}`.
+
 ## Gotchas
 
 - **Validate before paying.** A draft (`statut=0`, ref `PROV…`) cannot be paid.
@@ -113,5 +124,8 @@ yet have `banque lire`, so pass the id). Emits the new payment id.
 - **Dates** are sent as Unix epochs; pass `date:"YYYY-MM-DD"` or omit for today.
 - **`banque lire`** isn't granted yet → `GET /bankaccounts` returns empty. Add it
   to the provisioner's rights set if account discovery from this skill is needed.
-- **Avoirs (credit notes)** are a planned follow-up (a customer invoice with
+- **Avoirs (credit notes)** → `creditnote-create.sh` (customer invoice `type=2`
-  `type=2` referencing the original).
+  referencing `source_invoice`; amounts negative, ref `AVC…`). Supplier avoirs
+  are a follow-up.
+- **CLI:** all of these are also `arcodange sandbox {thirdparty|invoice|payment|creditnote|write}`
+  (JSON on stdin) — `arcodange sandbox help` for the list.

.claude/skills/dolibarr-sandbox-write/scripts/creditnote-create.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Create a customer credit note (avoir) in the SANDBOX — a customer invoice of
+# type 2 that references the original invoice. Amounts come out negative.
+#
+# Input: a JSON object on stdin (or a file path in $1):
+#   socid          (required) the client (must match the source invoice's client)
+#   source_invoice (required) the original invoice id being credited
+#   date           "YYYY-MM-DD"  (default today)
+#   validate       true|false    (default false = leave draft)
+#   lines: [ { desc, qty, price_ht, tva, type: "product"|"service", product_id? } ]
+#          the lines being credited (positive amounts; Dolibarr nets them as a credit)
+#
+# Emits {id, ref, total_ht, total_ttc, fk_facture_source, statut} on stdout.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+W="${SCRIPT_DIR}/dol-write.sh"
+
+SRC="${1:-}"
+if [[ -n "${SRC}" && "${SRC}" != "-" ]]; then INPUT="$(cat "${SRC}")"; else INPUT="$(cat)"; fi
+
+PYF="$(mktemp -t dolpy.XXXXXX)"; trap 'rm -f "${PYF}"' EXIT
+cat > "${PYF}" <<'PY'
+import json, sys, datetime
+d = json.loads(sys.stdin.read())
+for req in ("socid", "source_invoice"):
+    if not d.get(req):
+        sys.exit("creditnote-create.sh: '%s' is required" % req)
+ds = d.get("date")
+epoch = int((datetime.datetime.strptime(ds, "%Y-%m-%d") if ds
+             else datetime.datetime.now()).timestamp())
+lines = []
+for ln in d.get("lines", []):
+    is_product = ln.get("type", "service").lower() in ("product", "produit")
+    L = {
+        "desc": ln.get("desc", ""),
+        "subprice": str(ln.get("price_ht", ln.get("subprice", 0))),
+        "qty": str(ln.get("qty", 1)),
+        "tva_tx": str(ln.get("tva", ln.get("tva_tx", 20))),
+        "product_type": "0" if is_product else "1",
+    }
+    if ln.get("product_id"):
+        L["fk_product"] = str(ln["product_id"])
+    lines.append(L)
+body = {"socid": d["socid"], "type": 2, "fk_facture_source": d["source_invoice"],
+        "date": epoch, "lines": lines}
+print(json.dumps(body))
+print("1" if d.get("validate") else "0")
+PY
+
+MAPPED="$(printf '%s' "${INPUT}" | python3 "${PYF}")"
+BODY="$(sed -n 1p <<<"${MAPPED}")"
+VALIDATE="$(sed -n 2p <<<"${MAPPED}")"
+
+ID="$("${W}" POST /invoices "${BODY}")"
+if [[ ! "${ID}" =~ ^[0-9]+$ ]]; then
+  echo "creditnote-create.sh: create did not return an id: ${ID}" >&2
+  exit 1
+fi
+if [[ "${VALIDATE}" == "1" ]]; then
+  "${W}" POST "/invoices/${ID}/validate" '{}' >/dev/null
+fi
+"${W}" GET "/invoices/${ID}" | python3 -c "import json,sys
+d=json.load(sys.stdin)
+print(json.dumps({k:d.get(k) for k in ('id','ref','total_ht','total_ttc','fk_facture_source','statut')}))"

bin/arcodange

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# arcodange — read-only operational CLI for the Arcodange Dolibarr ERP.
+# arcodange — operational CLI for the Arcodange Dolibarr ERP. Read-only on prod;
+# host-guarded WRITE ops on the sandbox via `arcodange sandbox ...`.
 #
 # Usage: arcodange <command> [subcommand] [args]
 #
@@ -81,6 +82,13 @@ COMMANDS
     inspect              <messageId> [--folder|--save-pdf|--json]   Parse PDFs + draft Dolibarr entry
     curl                 <path>                    Raw read-only curl through zoho-curl.sh
 
+  sandbox                            WRITE ops on erp-sandbox ONLY (host-guarded; JSON on stdin)
+    thirdparty                                     Create a client/supplier fiche
+    invoice                                        Customer/supplier invoice + product/service lines
+    payment                                        Record a règlement on a validated invoice
+    creditnote                                     Create an avoir (credit note) of a source invoice
+    write                <METHOD> <path> [body]    Raw host-guarded write
+
   whoami                                          GET /users/info — confirm auth
   ping                                            GET /status     — liveness + Dolibarr version
   curl                   <path>                   Raw read-only curl through dol-curl.sh
@@ -99,6 +107,7 @@ EXAMPLES
   arcodange tva summary --year 2026
   arcodange thirdparty audit-all
   arcodange snapshot --out /tmp/erp.json
+  echo '{"name":"OVH","role":"supplier"}' | arcodange sandbox thirdparty
 EOF
 }
 
@@ -265,6 +274,38 @@ EOF
     esac
     ;;
 
+  sandbox)
+    sub="${1:-help}"; shift || true
+    case "${sub}" in
+      thirdparty) exec "${SKILLS}/dolibarr-sandbox-write/scripts/thirdparty-create.sh" "$@" ;;
+      invoice)    exec "${SKILLS}/dolibarr-sandbox-write/scripts/invoice-create.sh"    "$@" ;;
+      payment)    exec "${SKILLS}/dolibarr-sandbox-write/scripts/payment-record.sh"    "$@" ;;
+      creditnote) exec "${SKILLS}/dolibarr-sandbox-write/scripts/creditnote-create.sh" "$@" ;;
+      write)      exec "${SKILLS}/dolibarr-sandbox-write/scripts/dol-write.sh"          "$@" ;;
+      help|-h|--help)
+        cat <<'EOF'
+arcodange sandbox — WRITE operations against erp-sandbox (rehearsal ONLY).
+Every write goes through dol-write.sh, which REFUSES any non-sandbox host.
+Each subcommand reads a JSON object on stdin (or a file path arg).
+
+  thirdparty   client/supplier fiche
+               echo '{"name":"OVH","role":"supplier"}' | arcodange sandbox thirdparty
+  invoice      customer/supplier invoice with product/service lines (+ ref_supplier)
+               echo '{"socid":42,"validate":true,"lines":[{"desc":"X","qty":1,"price_ht":100,"tva":20,"type":"service"}]}' | arcodange sandbox invoice
+  payment      règlement on a validated invoice
+               echo '{"invoice_id":19,"mode":"VIR","account_id":1}' | arcodange sandbox payment
+  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":".."}'
+
+Needs .claude/skills/dolibarr-sandbox-write/.env (DOLIBARR_SANDBOX_URL + _API_KEY).
+See dolibarr-sandbox-write/SKILL.md.
+EOF
+        ;;
+      *) echo "arcodange sandbox: unknown subcommand '${sub}' (try 'arcodange sandbox help')" >&2; exit 2 ;;
+    esac
+    ;;
+
   whoami)
     exec "${DOLC}" /users/info
     ;;