`README.md`

37 lines
# dw-vendor-registry-sync (DTD Option C — 2026-06-30)

Sanctioned, parameterized write-back of `vendor_registry` **metadata** from the
local Mac2 `dw_unified` mirror to the **canonical Kamatera** `dw_unified`.

## Why
Mac2 can edit `vendor_registry` but had no sanctioned write-back to canonical
Kamatera → every local edit was a latent split-brain (a Kamatera→Mac2 sync would
silently revert it). Raw `ssh my-server psql` is hard-blocked by the auto-mode
classifier (psql can shell out via `\!` / `COPY TO PROGRAM`). This tool removes
that vector: no shell-out, only **parameterized UPDATEs**, restricted to a hard
**column whitelist** (purchasing/pricing metadata), never INSERT/DDL/DELETE.

## Use
```bash
npm install
cp .env.example .env        # set REMOTE_DATABASE_URL (confirm reachable path)

# DRY RUN (local read only, no remote connection):
node sync.js --vendors DWCQ-,DWXL-,DWAL-,DWOI-

# APPLY to canonical Kamatera (writes only whitelisted columns):
node sync.js --vendors DWCQ-,DWXL-,DWAL-,DWOI- --apply
```
Default columns: `buy_from, buy_from_confirmed, buy_from_notes`. Override with
`--columns a,b,c` (each must be in the whitelist in `sync.js`).

## Guardrails
- Hard `ALLOWED_COLUMNS` whitelist — any other column is refused before any DB call.
- `--apply` runs inside a transaction; any failure rolls back (no partial writes).
- Matches existing rows by `vendor_code`; never creates a vendor.
- Re-reads + prints remote state after apply to verify.

The agent may build + dry-run this locally; **applying to canonical Kamatera is
Steve-gated** — run `--apply` yourself (or add a narrow `Bash(node sync.js:*)`
allow-rule scoped to this tool).