From 79286650d71c9ddbbe55a044a81735a3bc3ea074 Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Mon, 29 Jun 2026 21:04:49 +0200 Subject: [PATCH] feat(skills,cli): sandbox avoir (credit note) + arcodange sandbox CLI group MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dolibarr-sandbox-write/scripts/creditnote-create.sh: create a customer avoir (credit note) — a customer invoice type=2 referencing source_invoice (fk_facture_source); amounts negative, validates to an AVC… ref. Proven live. - bin/arcodange: new `sandbox` command group wiring the write scripts — `arcodange sandbox {thirdparty|invoice|payment|creditnote|write}` (JSON on stdin). Header + usage updated to note the CLI now does host-guarded sandbox writes (still read-only on prod). - SKILL.md: avoir workflow + CLI notes. Verified end-to-end through the CLI: thirdparty -> invoice (FAC…) -> avoir (AVC…, total_ttc -240, fk_facture_source set); host-guard intact via the CLI. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../skills/dolibarr-sandbox-write/SKILL.md | 18 +++++- .../scripts/creditnote-create.sh | 64 +++++++++++++++++++ bin/arcodange | 43 ++++++++++++- 3 files changed, 122 insertions(+), 3 deletions(-) create mode 100755 .claude/skills/dolibarr-sandbox-write/scripts/creditnote-create.sh diff --git a/.claude/skills/dolibarr-sandbox-write/SKILL.md b/.claude/skills/dolibarr-sandbox-write/SKILL.md index 6785224..178d3ba 100644 --- a/.claude/skills/dolibarr-sandbox-write/SKILL.md +++ b/.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 - `type=2` referencing the original). +- **Avoirs (credit notes)** → `creditnote-create.sh` (customer invoice `type=2` + 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. diff --git a/.claude/skills/dolibarr-sandbox-write/scripts/creditnote-create.sh b/.claude/skills/dolibarr-sandbox-write/scripts/creditnote-create.sh new file mode 100755 index 0000000..8c8444f --- /dev/null +++ b/.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')}))" diff --git a/bin/arcodange b/bin/arcodange index 57901e2..98ff820 100755 --- a/bin/arcodange +++ b/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 [subcommand] [args] # @@ -81,6 +82,13 @@ COMMANDS inspect [--folder|--save-pdf|--json] Parse PDFs + draft Dolibarr entry curl 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 [body] Raw host-guarded write + whoami GET /users/info — confirm auth ping GET /status — liveness + Dolibarr version curl 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 ;;