# test — Dolibarr UI automation (Deno + Playwright)

A small Deno + Playwright POC that drives the Dolibarr admin UI in the `fr-FR`
locale. Playwright fills the same forms a human admin would, so the automation
works even where the REST API can't (e.g. generating an API key, which is
encrypted with the instance's own `DOLI_INSTANCE_UNIQUE_ID`).

## Layout

- `main.ts` — original entrypoint (first install, company/display/module setup).
- `provisionSandbox.ts` — entrypoint that provisions the `erp-sandbox` instance
  for the AI agent (enable REST API, create a write-scoped user, generate its
  API key).
- `scripts/login.ts` — admin login / logout / whoami helpers.
- `scripts/forms.ts` — `fillForm`, `toggleOnOff`, CKEditor/ACE helpers.
- `scripts/admin/moduleSetup.ts` — `configureModule`, `enableApiModule`.
- `scripts/admin/userSetup.ts` — `createUser`, `assignRights`, `generateApiKey`.

## Configure

Copy `.env.example` to `.env` and fill it in. `.env`, `*.key`, and
`.ai_agent_sandbox.key` are gitignored — never commit secrets.

```sh
cp .env.example .env
```

## Lock the installer (after a fresh install via `main.ts`)

Dolibarr keeps its web installer reachable until an `install.lock` file exists.
After a fresh install (the `main.ts` flow), create it in the target pod — for the
sandbox:

```sh
kubectl -n erp-sandbox exec \
  "$(kubectl get pod -n erp-sandbox -l app.kubernetes.io/instance=erp-sandbox -o name)" -- \
  /bin/sh -c 'touch /var/www/documents/install.lock && chown www-data:www-data /var/www/documents/install.lock'
```

The path is the Dolibarr **data root** (`/var/www/documents`, a PVC) — that's where
Dolibarr checks, and being on the PVC the lock persists across pod restarts. For
prod, swap to `-n erp -l app.kubernetes.io/instance=erp`. A sandbox **seeded** from
prod still needs this: the seed (see `../ops/sandbox/`) copies the DB +
`documents/mycompany`, not `install.lock`.

## Provision the sandbox

Provisions `erp-sandbox.arcodange.lab`: enables the REST API module, creates the
write-scoped `ai_agent_sandbox` user, grants it its write rights, and has
Dolibarr generate the user's API key. The key is written to
`test/.ai_agent_sandbox.key` (gitignored) — it is never printed.

```sh
cd test
deno run --allow-all provisionSandbox.ts
```

Populate `.env` from the `erp-sandbox` namespace secrets first. `secretkv`
carries the app env (including `DOLI_ADMIN_PASSWORD`); `vso-db-credentials`
carries the database password:

```sh
# Admin password (key DOLI_ADMIN_PASSWORD inside the secretkv secret)
kubectl get secret secretkv -n erp-sandbox \
  -o jsonpath='{.data.DOLI_ADMIN_PASSWORD}' | base64 -d

# Database password (key `password` inside vso-db-credentials)
kubectl get secret vso-db-credentials -n erp-sandbox \
  -o jsonpath='{.data.password}' | base64 -d
```

Set in `.env`:

```sh
DOLIBARR_ADDRESS=https://erp-sandbox.arcodange.lab
DOLI_ADMIN_LOGIN=admin
DOLI_ADMIN_PASSWORD="<from secretkv above>"
DOLI_DB_PASSWORD="<from vso-db-credentials above>"
# Optional — otherwise a random password is generated and only the API key emitted:
# AI_AGENT_SANDBOX_PASSWORD="<choose one>"
```

### After it runs

The generated API key lands in `test/.ai_agent_sandbox.key`. Next step (not
automated by this POC): load it into the `dolibarr` skill's sandbox config /
Vault at `kvv2/erp-sandbox/ai_agent`.

> [!IMPORTANT]
> The sandbox Dolibarr is not installed/provisioned yet (empty DB, fresh install
> wizard). Until the install wizard has been completed against the sandbox,
> `provisionSandbox.ts` will not have a UI to drive, and the selectors in
> `moduleSetup.ts` / `userSetup.ts` are best-effort (Dolibarr 22 conventions,
> not verified live). Confirm them on the first real run.

### Write rights granted

The `ai_agent_sandbox` user is created non-admin and granted read + create on:

| Module           | rights ids                         |
| ---------------- | ---------------------------------- |
| facture          | lire=11, creer=12                  |
| societe          | lire=121, creer=122                |
| societe contact  | lire=281, creer=282                |
| fournisseur      | lire=1181, facture lire=1231, facture creer=1232 |
| produit          | lire=31, creer=32                  |