toga-ai 1.0.115 → 1.0.117

package/knowledge/2.0/apps/toga2-supply/INDEX.md

@@ -4,4 +4,4 @@
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
 | [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
-| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys to **AWS Amplify** for non-prod environments (qc-security, qc-performance, alpha, beta, gamma, …). | toga2-supply/amplify.yml, toga2-supply/package.json, toga2-supply/.env.qc-security |
+| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys to **AWS Amplify** for non-prod environments (Stage, QC Security, QC Performance, …). | toga2-supply/amplify.yml, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |

package/knowledge/2.0/apps/toga2-supply/workflows/amplify-build-and-deploy.md

@@ -10,7 +10,7 @@ updated: 2026-06-17
 owners: ["jcardinal"]
 files:
   - toga2-supply/amplify.yml
-  - toga2-supply/package.json
+  - toga2-supply/.github/workflows/sync-stage-environments.yml
   - toga2-supply/.env.qc-security
 related:
   - ../architecture.md
@@ -19,34 +19,54 @@ related:
 ## Summary
 
 How `toga2-supply` (React + Vite) builds and deploys to **AWS Amplify** for non-prod
-environments (qc-security, qc-performance, alpha, beta, gamma, …). Note that the
-**alpha/beta/gamma/production** environments historically deploy via **GitHub Actions**
-(`.github/workflows/*.yml`) into the `agilantsolutions/toga2-supply-build` repo — Amplify
-is the newer path used when standing up additional non-prod environments. The first Amplify
-build of this app failed with a JavaScript heap OOM; this doc records the fix and the
-scalable per-environment build setup.
+environments (Stage, QC Security, QC Performance, …). The **alpha/beta/gamma/production**
+environments historically deploy via **GitHub Actions** (`.github/workflows/*.yml`) into the
+`agilantsolutions/toga2-supply-build` repo — Amplify is the path used for the newer non-prod
+environments. The first Amplify build failed with a JavaScript heap OOM; this doc records the
+fix and the chosen **branch-per-environment** deployment model.
+
+## Deployment model — branch per environment, mirrored from `_stage`
+
+The unit of an environment in Amplify is a **branch** (idiomatic Amplify: branch = environment).
+A single branch cannot fan out to multiple environments, and a branch can only be connected once
+per Amplify app. So:
+
+- **`_stage` is the integration branch** — where work lands and is reviewed. It is **not deployed
+  directly**.
+- Each environment is its **own deployment branch** that mirrors `_stage` exactly:
+  `stage`, `qc-security`, `qc-performance`, …
+- **Branch name == Vite mode == `.env.<branch>` filename.** `amplify.yml` builds with
+  `--mode "$AWS_BRANCH"` (Amplify injects `$AWS_BRANCH`), so branch `qc-security` builds
+  `--mode qc-security` and loads `.env.qc-security`. No per-branch env var needed.
+- A GitHub Action (`sync-stage-environments.yml`) **fast-forwards every environment branch to
+  `_stage` on each push**, triggering each branch's Amplify build with its own mode.
+
+```
+_stage (integration, not deployed)
+   │  push → sync-stage-environments.yml fast-forwards ↓
+   ├──▶ stage           ──▶ Amplify ──▶ build --mode stage
+   ├──▶ qc-security     ──▶ Amplify ──▶ build --mode qc-security
+   └──▶ qc-performance  ──▶ Amplify ──▶ build --mode qc-performance
+```
 
 ## Steps
 
-1. **`amplify.yml` at the repo root drives the build.** When present, it **overrides the
-   Amplify console build settings entirely, for every branch of the app** — you cannot split
-   "memory in the file, build command in the console." Whichever owns the build phase owns all
-   of it. Our `amplify.yml`:
-   - Sets `NODE_OPTIONS=--max-old-space-size=4096` in both `preBuild` and `build` (the OOM fix).
-   - Runs `npx tsc && npx vite build --mode "$VITE_BUILD_MODE"` — the build mode is **not**
-     hardcoded.
-   - Publishes `dist/` as the artifact baseDirectory.
-2. **Per environment, set one Amplify env var on that branch:** `VITE_BUILD_MODE` =
-   `qc-security` | `qc-performance` | `alpha` | `beta` | `gamma`. No new npm script per env.
-3. **Each mode needs a matching `.env.<mode>` file** committed in the repo (Vite loads
-   `.env.<mode>` for `--mode <mode>`). e.g. `.env.qc-security` provides `VITE_API`. A new
-   environment requires creating its `.env.<mode>` file.
-4. Commit `amplify.yml` + the env file, push the branch; Amplify rebuilds.
+1. **`amplify.yml` (repo root) drives the build.** When present it **overrides the Amplify
+   console build settings entirely** — you cannot split "memory in the file, build command in the
+   console." It sets `NODE_OPTIONS=--max-old-space-size=4096` (the OOM fix) and runs
+   `npx tsc && npx vite build --mode "$AWS_BRANCH"`, publishing `dist/`.
+2. **In the Amplify app, connect one branch per environment** (`stage`, `qc-security`,
+   `qc-performance`, …). Each branch is its own environment with its own hosting domain.
+3. **Each environment needs a committed `.env.<branch>` file** (Vite loads `.env.<mode>`).
+   e.g. `.env.qc-security` provides `VITE_API`.
+4. **Add the branch to the sync matrix.** Edit `sync-stage-environments.yml` → `matrix.branch`.
+5. Push to `_stage`; the Action mirrors the env branches; Amplify rebuilds each.
 
 ## Systems involved
 
-- AWS Amplify (build + hosting), per-branch environment variables.
-- Vite 4 build (`vite build --mode <mode>`), TypeScript `tsc` precompile.
+- AWS Amplify (build + hosting) — one branch per environment, branch name selects the mode.
+- GitHub Actions — `sync-stage-environments.yml` mirrors `_stage` → env branches on push.
+- Vite 4 build (`vite build --mode <branch>`), TypeScript `tsc` precompile.
 - Sentry source-map upload via `@sentry/vite-plugin` (source maps are **on** —
   `build.sourcemap: true` in `vite.config.ts`).
 
@@ -59,18 +79,26 @@ scalable per-environment build setup.
   has ≥4 GB. Amplify **Standard** compute is 4 GB (tight with source maps on). If it OOMs
   again, switch to the **Large build instance** (Amplify → App settings → Build settings)
   and raise to `6144`/`7168`. Setting the heap above physical RAM makes it worse, not better.
-- **Mode/filename mismatch:** `--mode qc-security` loads `.env.qc-security` exactly — a file
-  named `.env.qc-security.beta` is silently ignored (build succeeds but ships with no
-  `VITE_API`). Name the env file to match the mode.
-- **Secret hygiene:** `.env.<mode>` files have historically carried a live
-  `SENTRY_AUTH_TOKEN`. Prefer rotating it and moving it to an Amplify env var rather than
-  committing it.
+- **"Can't pick `_stage` again" in the UI:** within one Amplify app a branch connects only once.
+  This is why environments are separate *branches*, not multiple connections to `_stage`. (An
+  alternative — multiple Amplify *apps* all pointed at `_stage` — works but is a non-idiomatic
+  workaround: N apps to manage, no single dashboard. Branch-per-env is preferred.)
+- **Env branches are disposable deployment pointers — never commit to them directly.** The sync
+  Action force-updates them (`--force-with-lease`) to match `_stage`; any direct commit is lost.
+- **Branch name must match the mode/`.env` filename.** `--mode qc-security` loads
+  `.env.qc-security` exactly — a mismatch (e.g. a stray `.env.qc-security.beta`) is silently
+  ignored: the build succeeds but ships with no `VITE_API`.
+- **Secret hygiene:** `.env.<mode>` files have historically carried a live `SENTRY_AUTH_TOKEN`.
+  Prefer rotating it and moving it to an Amplify env var rather than committing it.
 
 ## Change history
 
+- 2026-06-17 — Switched to branch-per-environment: `amplify.yml` now builds `--mode "$AWS_BRANCH"`
+  and added `sync-stage-environments.yml` to mirror `_stage` → env branches. (Superseded the
+  earlier `VITE_BUILD_MODE` per-branch-env-var idea — unworkable because multiple environments
+  must deploy from the single `_stage` branch.) (jcardinal)
 - 2026-06-17 — Created on first Amplify setup of a new QC environment: added root `amplify.yml`
-  with raised Node heap + parameterized `VITE_BUILD_MODE`; renamed `.env.qc-security.beta` →
-  `.env.qc-security` (jcardinal)
+  with raised Node heap (OOM fix); renamed `.env.qc-security.beta` → `.env.qc-security`. (jcardinal)
 
 ## Related docs
 

package/knowledge/2.0/apps/worker2/features/netsuite-salesorder-open-orders-sync.md

@@ -80,6 +80,14 @@ None — uniform (platform-wide Forecast2 sync).
 - **REST shape ≠ SOAP shape.** The cron reads the SOAP-shim shape; this handler reads the REST record
   (`status->refName`, line `quantityBilled`, `class->refName`, `entity->id`, `salesRep->id`,
   `shippingCost`). Verified against live orders via `test/@dave/probe_salesorder_rest_shape.php`.
+- **REST OMITS `rate` for a $0 line — treat missing/non-numeric rate as `0`, don't skip the line.**
+  A $0-priced line comes through SOAP as `rate = 0` (numeric); the cron computes `revenue = 0`,
+  `profit = −qtyOpen × unitCost`, and — since profit ≠ 0 — **inserts** the row (tracking open *cost* at
+  zero revenue). REST instead **leaves `rate` out entirely**, so an early `if (!is_numeric($rate)) continue;`
+  silently drops the whole class of rows. **Prod has 575 such rows** (`revenue = 0`, profit ≠ 0), so this
+  was real data loss. Fix (2026-06-17): `$unitPrice = is_numeric($line->rate ?? null) ? (float)$line->rate : 0.0;`
+  — the genuine filter is the both-zero check (`revenue == 0 && profit == 0`), not rate presence. Caught
+  live by editing a $0 test SO (7163257 → revenue 0, profit −105).
 - **Three deliberate departures from the legacy cron (all intentional):**
   1. **No date-window gate.** The cron flips `isOrderOpen=false` for tranDate outside −365d/+90d
      (`common_import_…:1753`) to bound its windowed scan. Irrelevant to a single-id webhook — dropped.
@@ -99,6 +107,18 @@ None — uniform (platform-wide Forecast2 sync).
   before *every* action — keeping it would couple the REST import to SOAP config. The push methods
   (`Create`/`Update`/`Sync`) self-construct `NetSuiteService`, so push is unaffected and the Forecast
   DB is registered globally in `_.php`.
+- **Local testing — the webhook path hides errors; run the action directly to see them.** A real NS
+  edit reaches the local worker via the legacy `{action,parameters}` envelope, and `_Worker_NetSuite::Webhook`
+  dispatches the per-record action through `_Worker::runTask()`, whose **debug-mode self-POST swallows the
+  sub-action result** (you get `Successfully Executed: ok` from the *router* even when the import threw).
+  To see the truth, POST the sub-action straight to the worker and read the response:
+  `curl -X POST http://worker2/ -d '{"action":"Netsuite/SalesOrder/PUT","parameters":{"internalId":<id>}}'`.
+- **Local `Forecast.Items` is a partial/stale copy → the "unknown item" guard throws.** The importer
+  (correctly) throws `Forecast.Items has no row for NetSuite item <id>` when a line's item isn't local;
+  prod keeps Items current (hourly import) so it won't, but local testing of an arbitrary SO often hits
+  this. Pre-seed the missing item locally (copy the row from the prod reader) or test that SO against prod.
+- **Local worker2 writes to the DB its config points at — not prod.** With `[database] hostname = localhost`,
+  rows land in **local** `Forecast.OpenOrderItems`; verify there, not on the prod reader.
 
 ## Related work
 
@@ -111,6 +131,11 @@ and are a candidate to extract into a shared `_Component_Forecast_Db` before the
 
 ## Change history
 
+- 2026-06-17 — **Fixed dropped zero-revenue/open-cost lines.** REST omits `rate` for $0 lines, and the
+  `if (!is_numeric($rate)) continue;` guard was skipping them — but the cron inserts these (profit =
+  −qtyOpen × unitCost; 575 such rows in prod). Now defaults missing/non-numeric rate to 0 so the both-zero
+  filter alone decides. Verified e2e from a real NS edit: 7162297 → $3,698, 7163257 → revenue 0/profit −105.
+  Added local-testing gotchas (webhook debug-swallow; stale local Items guard; local-DB write target). (dfranks)
 - 2026-06-17 — Initial open-orders importer merged into `_Worker_Netsuite_SalesOrder` (TRUE-79142):
   REST-only, no date-window gate, no shipping line, cascade bug fixed. (dfranks)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.115",
+  "version": "1.0.117",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",