mega-plant/docs/plant-site-import.md

Plant site history from Buildsite Fuel Logs

Fuel Logs provide dated evidence of where an existing Plant vehicle was recorded. The importer updates its current site and shows the previous distinct recorded site. It does not import fuel measurements, create vehicles, infer trips, or change a vehicle's QR identity.

Initial setup

Run from the Plant checkout after installing its dependencies and configuring its existing .env.local database settings:

cd /Volumes/EXT/DEVELOPMENT/PLANT_TEST
node scripts/setup-plant-site-history.mjs

The setup script adds the site-history schema idempotently. The importer loads Plant's own environment file; credentials must not be passed on the command line, copied into reports, or added to this runbook.

Source and matching rules

Use the download skill's complete fuel-logs-all-sites.csv, not a site-specific extract. Preserve the CSV beside its manifest.json and source-records.json. Before importing, verify that the manifest reports a complete source period, matching source/server counts and litres, and pagination ending with at_end: true. Report any unresolved labels or source warnings. The downloader reconstructs these files from authenticated Buildsite records; they are not a native Summary export.

• A Buildsite vehicle QR must match an existing Plant vehicle exactly. A source submission ID identifies an observation; it is not a vehicle QR. Unmatched upstream vehicles are reported and intentionally ignored. Names, registrations and similar-looking codes are not fallback identity matches.
• The latest recorded observation date determines the current site. The logged date describes the observation; download order and CSV row order do not decide where a vehicle is now.
• The previous site is the latest earlier different site. Repeated records at the current site do not replace that previous distinct site. No previous evidence means an unknown previous site, not a guessed move.
• Repeated or overlapping monthly downloads are expected. Existing source observations are deduplicated rather than added again; importing older evidence may enrich history without moving a vehicle backwards.
• Conflicting latest observations that cannot be ordered safely hold that vehicle for review. Other vehicles with clear evidence can still be updated. A held vehicle must remain visible in the result; do not silently select one of its sites.
• Manual site changes append dated manual observations. Older fuel evidence does not undo a later manual move. A manual selection takes precedence over an untimed fuel observation on the same day.
• Confirmed site-name aliases live in lib/plant-site-policy.json. An identity conflict needs a human decision; do not alter a QR or add a speculative alias to make an import pass.
• A real site name can be recorded without coordinates. It remains awaiting a map pin until a person supplies one in the map sidebar. Never substitute headquarters or invent latitude/longitude.

Source files and upstream records remain unchanged. History records are location evidence, not new fuel transactions. The latest recorded site is not a live GPS location. Refresh the Plant screen after importing to see the updated site and history.

Review and apply one file

Use fresh result paths and an absolute CSV path. Preview reads the proposed work without applying it:

cd /Volumes/EXT/DEVELOPMENT/PLANT_TEST
node --import tsx scripts/import-plant-sites.ts \
  --file /absolute/snapshot/fuel-logs-all-sites.csv \
  --preview --result /absolute/new-run/preview.json

Read changes, issues, unknownQrs, and newSites. The preview reports each matched vehicle's current and previous sites, observation dates, status, and whether it needs coordinates. canApply: true means there is safe work to apply; it does not mean every vehicle is unambiguous.

Apply the unchanged source using the exact fileHash from that preview:

node --import tsx scripts/import-plant-sites.ts \
  --file /absolute/snapshot/fuel-logs-all-sites.csv \
  --apply --expected-hash PREVIEW_FILE_HASH \
  --result /absolute/new-run/apply.json

Keep the apply result, including appliedVehicles, insertedObservations, unchangedVehicles and heldVehicles. Preview the same file again into a new verify.json. Safe work must be exhausted (canApply: false); held issues may remain and must be reported separately. If verification fails, preserve all evidence and investigate before reporting completion. A failed command may have made partial progress; a retry uses the same preserved source and a new evidence directory.

Scheduled download bridge

The Buildsite checkout contains scripts/sync-plant-sites-from-buildsite.mjs. After the scheduled downloader has validated and preserved the complete previous-month and current-month snapshots, run:

cd /Volumes/EXT/DEVELOPMENT/MEGAIFRASTRUCTURE
node scripts/sync-plant-sites-from-buildsite.mjs \
  --file /absolute/previous-month/fuel-logs-all-sites.csv \
  --file /absolute/current-month/fuel-logs-all-sites.csv \
  --out /absolute/new-scheduled-run/plant-sites

Use oldest first. --file is repeatable; --out must be a new directory. The default Plant checkout is sibling PLANT_TEST; --plant-root /absolute/plant-checkout overrides it. The bridge is a consumer of already downloaded files and does not log into Buildsite or install a schedule.

For each source, the bridge runs Plant's CLI in the Plant checkout, previews, applies with the preview hash only if safe work exists, then previews again. Each child has a 120-second timeout. Numbered evidence folders contain preview.json, optional apply.json, verify.json, and child stdout/stderr logs. summary.json records sources, hashes, outcomes and review issues. No previous evidence directory is overwritten.

Exit codes:

Code	Meaning	Scheduled report
0	All safe work verified	Report updated or unchanged counts and ignored upstream QRs.
1	Importer, connectivity, schema, source or verification failure	Report failure and evidence path; do not claim completion. Later sources are not applied.
2	Safe work verified, vehicles held for review	Report the safe updates and list each held QR/reason separately.

If the Plant checkout or dependencies are missing, fix that deployment before retrying. If the database is unreachable or the schema is absent, report the failure instead of skipping Plant synchronization. Preserve the original download and use a new output directory on every retry.

Offline bridge tests (no database reads or writes):

node --test /Volumes/EXT/DEVELOPMENT/MEGAIFRASTRUCTURE/scripts/sync-plant-sites-from-buildsite.test.mjs