toga-ai 1.0.815 → 1.0.816

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-03
-owners: [apeterson]
+updated: 2026-09-15
+owners: [apeterson, tcox]
 files:
   - toga25-supply/src/fieldsConfig/index.ts
   - toga25-supply/src/fieldsConfig/resolveRole.ts
@@ -196,11 +196,29 @@ modal's chrome from the same per-client JSON, not from the component:
   the Enter-PO modal fields — its nested `valueKey`s are **not** action buttons. `DEFAULT/orderViewFields.json`
   has no `recordActionFields` at all. Any tooling that walks action buttons must scope strictly to the
   `actionOptions` array.
+- **⚠ A client JSON file existing does NOT mean it is wired.** Verified 2026-09-15: the per-client
+  `vendorItemRecordCreateFields.json` files (COMPASS, COMPASSCANADA, NYCHH) are **not imported into
+  `fieldsConfig/index.ts`**, so `FIELDS` resolves `DEFAULT` for every client and edits to those
+  files change nothing. Adding the file is step 1 of five (see *Adding a new client-configurable
+  field*) — if your override has no effect, check the wiring before you debug the JSON.
+- **A missing `header.modalTag` renders a BLANK badge, not no badge.** The modal chrome is fully
+  config-driven, so a client file that omits a block another client has just draws empty chrome.
+  Found on the create modal: COMPASSCANADA's and NYCHH's `itemRecordCreateFields.json` lacked the
+  `header.modalTag` block COMPASS had. **When you add a header/action key to one client's file, add
+  it to every client's file for that modal mode** — there is no per-key fallback to DEFAULT once a
+  client bundle exists.
 - Worked examples: `salesOrdersPageFields` (client × role) and `inventoryGroupings` (client-only +
   hydration; full write-up in `src/pages/Inventory/README.md`); `itemRecordViewFields` /
   `vendorItemRecordViewFields` are record-modal-layout examples living under `src/layout/.../viewModel/FIELDS/`.
 
 ## Change history
+- 2026-09-15 — Added the `header.modalTag` block to COMPASSCANADA's and NYCHH's
+  `itemRecordCreateFields.json` (both rendered a **blank** badge in the create modal because the
+  block was missing, not absent-by-design). Recorded two gotchas found while writing the create-modal
+  Cypress specs: a client JSON file can exist and be **unwired** (the per-client
+  `vendorItemRecordCreateFields.json` files are never imported, so `FIELDS` always uses DEFAULT), and
+  a header key added to one client's file must be added to every client's file for that modal mode.
+  (tcox)
 - 2026-09-03 — Documented the actual `resolveRole` flag → role table (COMPASS/COMPASSCANADA:
   `_isAdmin`/`_isSuperAdmin`/`_isSupervisor`, in that order, else `USER`; QUAD:
   `_isGlobalAdmin`/`_isBuyer`/`_isItShopper`, else `USER`; every other client `DEFAULT`) and the

package/knowledge/2.0/apps/toga25-supply/workflows/amplify-deployment.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-08-31
-owners: [jcardinal, apeterson]
+updated: 2026-09-15
+owners: [jcardinal, apeterson, tcox]
 files:
   - toga25-supply/amplify.yml
   - toga25-supply/src/api/api.ts
@@ -16,6 +16,7 @@ files:
   - toga25-supply/package.json
   - toga25-supply/.env.development
 related:
+  - ./cypress-testing.md
   - ../architecture.md
   - ../../toga-blox/workflows/dynamic-publish-pipeline.md
   - ../features/transfer-orders-page.md
@@ -70,6 +71,23 @@ production.
 - Node: Vite 7 requires Node 20.19+ or 22.12+ (Node 22 recommended). Amplify's default image
   is fine; optionally pin via `.nvmrc`.
 
+### The Cypress test phase (added 2026-09-15, `_sandbox-client`)
+
+`amplify.yml` now runs the full Cypress suite in the build. This is the app's **only** CI — there
+is no GitHub Actions workflow. See [cypress-testing](./cypress-testing.md) for the suite itself.
+
+- **`preTest`** — writes the four `*.togasupply` entries into `/etc/hosts` (the tenant is resolved
+  from the hostname, so without them every spec visits the wrong client), installs Cypress with
+  `CYPRESS_CACHE_FOLDER` set so the binary is cacheable, installs `mochawesome`, and serves the
+  built app with **`pm2` + `vite preview` on 5173**. `vite.config.ts` needs
+  `preview.allowedHosts: ['.togasupply']` or preview rejects the tenant hostnames.
+- **`test`** — one Cypress run **per tenant** (one superdomain per run) plus the component project.
+- **`postTest`** — `mochawesome-merge` combines the per-tenant reports into one.
+- **`USER_DISABLE_TESTS`** gates the phase per branch, so a branch can deploy without the suite.
+- `.gitignore` excludes `cypress/reports` and `.cypress-cache`.
+
+A failing spec fails the deploy — same posture as the `npx tsc -b` step.
+
 ### Why the exact `--mode` matters at runtime
 
 `import.meta.env.MODE` (the `--mode` value) is baked into the bundle and read at **runtime**
@@ -219,6 +237,11 @@ branch does NOT reconnect it**: pushes land in GitHub and Amplify ignores them e
   has ever been developed against a linked local checkout.
 
 ## Change history
+- 2026-09-15 — Documented the **Cypress test phase** added to `amplify.yml` on `_sandbox-client`
+  (`preTest` hosts entries + cached Cypress install + `pm2`/`vite preview` on 5173, one `test` run
+  per tenant plus the component project, `postTest` mochawesome merge, `USER_DISABLE_TESTS` gate),
+  the required `preview.allowedHosts: ['.togasupply']` in `vite.config.ts`, and the new `.gitignore`
+  entries. This build phase is the app's only CI. (tcox)
 - 2026-08-31 — Restored the branch's deploy inputs and recorded three systemic findings.
   (1) **`amplify.yml` was absent from the root of every remote branch** (it lived in a single commit
   `5a276be`), so Amplify had been building from a **console-stored spec** and the fail-loud

package/knowledge/2.0/apps/toga25-supply/workflows/cypress-testing.md

@@ -6,36 +6,30 @@ project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-09-14
-owners: [apeterson]
+updated: 2026-09-15
+owners: [apeterson, tcox]
 files:
   - toga25-supply/cypress.config.ts
   - toga25-supply/cypress/README.md
-  - toga25-supply/cypress/tsconfig.json
   - toga25-supply/cypress/support/e2e.ts
-  - toga25-supply/cypress/support/commands.ts
-  - toga25-supply/cypress/support/component.tsx
   - toga25-supply/cypress/support/tenants.ts
+  - toga25-supply/cypress/support/tenantExpectations.ts
   - toga25-supply/cypress/support/api/stubApi.ts
-  - toga25-supply/cypress/support/api/envelope.ts
-  - toga25-supply/cypress/support/api/users.ts
-  - toga25-supply/cypress/support/api/surfaces.ts
-  - toga25-supply/cypress/support/api/session.ts
   - toga25-supply/cypress/e2e/emptyNavigation.cy.ts
-  - toga25-supply/cypress/component/harness.cy.tsx
-  - toga25-supply/cypress/fixtures/tenants/COMPASS/surfaces/navigation.json
-  - toga25-supply/cypress/fixtures/tenants/COMPASSCANADA/surfaces/navigation.json
-  - toga25-supply/cypress/fixtures/tenants/NYCHH/surfaces/navigation.json
-  - toga25-supply/cypress/fixtures/tenants/QUAD/surfaces/navigation.json
+  - toga25-supply/cypress/e2e/itemModalCreate.cy.ts
+  - toga25-supply/cypress/e2e/vendorItemModalCreate.cy.ts
+  - toga25-supply/cypress/e2e/vendorItemModalEdit.cy.ts
+  - toga25-supply/cypress/fixtures/tenants/COMPASS/expectedUI/itemCreate.ts
+  - toga25-supply/cypress/fixtures/tenants/COMPASS/expectedUI/vendorItemCreate.ts
   - toga25-supply/scripts/cypress.mjs
-  - toga25-supply/tsconfig.node.json
-  - toga25-supply/package.json
 related:
   - ../features/surface-frontend.md
   - ../features/client-configurable-fields.md
+  - ../features/record-modals-and-nested-tables.md
   - ../features/side-navigation-and-default-route.md
   - ../features/sso-redirect-and-session-gating.md
   - ../features/force-logout-on-deployment.md
+  - ./amplify-deployment.md
   - ../architecture.md
   - ../../../2.0/standards/frontend.md
 ---
@@ -47,8 +41,10 @@ a stub layer that answers **every** `/v2` call so no test touches a backend. It
 the thing that actually breaks in this app — **tenant × role × feature** — without needing real
 logins or a seeded database.
 
-Current state (2026-09-03, branch `TRUE-81735`, working tree only): **26 tests green** —
-6 e2e specs × 4 tenants (COMPASS, COMPASSCANADA, NYCHH, QUAD) + 2 component tests.
+Current state (2026-09-15, branch `TRUE-79810`): the base harness (2026-09-03, `TRUE-81735`)
+plus the **record-modal specs** — create + edit for Items and Vendor Items, per tenant. Tenants are
+COMPASS, COMPASSCANADA, NYCHH, QUAD; only COMPASS and COMPASSCANADA have a role that reaches
+`/items` and `/vendor-items`, so NYCHH and QUAD run a single placeholder test per modal spec.
 `cypress/README.md` is the hands-on version of this doc for a developer working without Claude
 (run commands, recipes, traps). Read that to *write* a test; read this to understand *why* it is
 shaped this way.
@@ -121,6 +117,80 @@ Three custom commands: `cy.stubApi()`, `cy.visitAsGuest(path)` (storage cleared
 stable semantic attribute (`input[name]`, `button[type=submit]`, `a[href]`) rather than adding a
 testid for its own sake.
 
+## Record-modal specs (create + edit)
+
+`e2e/itemModalCreate.cy.ts` (16 tests) and `e2e/vendorItemModalCreate.cy.ts` (14 tests) are the
+template for any new create/edit modal spec. They test the Pattern 6 form modal — see
+[record-modals-and-nested-tables](../features/record-modals-and-nested-tables.md).
+
+**Shape — expectations live in a per-tenant fixture, never in the spec.**
+
+- `cypress/fixtures/tenants/<SLUG>/expectedUI/<modal>.ts` holds everything tenant-specific:
+  section and field labels, the option text to pick, and the **names of the records to act on**
+  (`vendorNameWithoutIntegrationMethods`, `vendorNameWithIntegrationMethods`, `itemName`).
+- The shape is typed in `cypress/support/tenantExpectations.ts`
+  (`ItemCreateExpectations`, `VendorItemCreateExpectations`), so a tenant that adds a field fails
+  type-check instead of failing at runtime.
+- **A tenant with no fixture must fail as a failing `it()`, not a module-level `throw`.** A throw at
+  import time kills the whole spec file with no readable reason; a failing test names the missing
+  fixture.
+- Tenants whose role cannot reach the page get **one placeholder test**, so the run count stays
+  honest instead of the spec silently registering zero tests.
+
+**What the create specs cover** (both modals): empty-form state, the header label following the
+picked vendor, the exact POST body (relations sent as `{uuid}`), required-field errors **per
+field**, currency/number formats, `POST` 500 → error toast + modal closes, the unsaved-input guard
+dialog, a clean form after discard, and the table refetch.
+
+Item-create adds: Etilize ID lookup loading images (`GET /vendor-items` join row →
+`GET /items/{uuid}`), option **objects** in the body, an `itemPrices` row for the Default Purchase
+Method, `personaItems` nested as `{persona:{uuid}}`, **no** `itemAssortments` on the body (one
+`POST /assortment-items` per assortment instead), and the *"Unit/Lease price is required when
+Default Price Type is Each/Lease"* rule — which is only reachable on **create**, because on edit
+blox formats the empty price to `0.00` and the rule never fires.
+
+Vendor-item-create adds the PO-integration select, which only unlocks for a vendor that has
+integrations: the spec serves `GET /integrations` **keyed on the vendor uuid in the URL**, because
+the tenant-wide stub returns the same rows for every vendor. Use `stubNoIntegrations()` for the
+"vendor without integrations" cases.
+
+**New stubs (`support/api/stubApi.ts`):** a default `POST /vendor-items` and a `POST /items` that
+echoes the body back under `data.items` with a 201. Both `/assortment-items` and
+`/assortment-items/` are matched — the app posts the trailing-slash form from create hooks and the
+bare form from edit hooks (see *App findings* below).
+
+**Assertion rules learned here — follow them:**
+
+- **Refetch = exactly one more GET than before**, asserted as `before + 1` on `cy.get('@alias.all')`.
+  `> 1` passes on a double-fetch bug.
+- **Never assert "no create happened" without first proving the submit ran.** Untouched-field
+  errors only appear *after* a submit, so assert an error (or `cy.focused()` landing on the first
+  invalid field) and *then* assert no POST. Otherwise the test passes when the button did nothing.
+- **Per-field required errors:** find the smallest ancestor that contains the message and assert it
+  contains **exactly one input** — the field's. Counting message text passes when the wrong field
+  is the one complaining.
+- **Null-safe header assertions:** the vendor header falls back, so assert `number || "Part Number"`.
+
+## Selector rules for blox inputs
+
+The edit spec (`vendorItemModalEdit.cy.ts`) failed **0/5 on both tenants** because it was written
+against selectors that do not exist. These rules are why:
+
+- **Only use a `data-testid` that is actually published in blox.** `getByTestId('Active')`,
+  `'Vendor Sku'`, `'toggleTrack'`, `'virtualRows'` exist in **no** published blox build — not the
+  pinned `1.1.2-production.144`, not the newest `1.1.4-sandbox-client.148`, not the local checkout.
+  Cypress just fails to find them. Check the built package before using a testid.
+- **Target a field by `input#<valueKey>`** — the field's config key is its DOM id, and that is
+  stable across tenants.
+- **Pick select options by their exact text, never by menu row index.** Option order differs per
+  tenant, so an index-based pick tests a different value on COMPASSCANADA than on COMPASS. Put the
+  option text in the tenant's `expectedUI` fixture.
+- **Assert the guard dialog as `dialog[open]`.** `cy.get('cancelDialogGuardrail')` is a bogus
+  selector — it looks for a `<cancelDialogGuardrail>` element.
+- **Re-picking a record's current value is not a change** and fires no dependent request. The
+  Canada edit spec had to switch its "vendor with integrations" case to **COMPASS CANADA**, because
+  re-selecting the record's existing vendor (GRAND & TOY) triggered no `/integrations` fetch.
+
 ## Guardrails built into the suite
 
 ### The fall-through check (the main one)
@@ -163,11 +233,13 @@ detectable instead of silently self-healing.
 `cypress/component/harness.cy.tsx` mounts a blox component and asserts one React + one
 QueryClient. It fails when the component-test Vite config drifts from `vite.config.ts`.
 
-### Not built: CI
+### CI — now an Amplify build phase (not GitHub Actions)
 
-There is **no** CI for this yet. Worth knowing before you plan it: a workflow must add the four
-`*.togasupply` `/etc/hosts` entries as a step (the tenant is resolved from the hostname) and serve
-a build (`vite preview` / `start-server-and-test`).
+The suite runs in the **Amplify build** for `_sandbox-client`: `preTest` writes the four
+`*.togasupply` `/etc/hosts` entries and serves the build, `test` runs one Cypress run per tenant
+plus the component project, `postTest` merges the mochawesome reports, and `USER_DISABLE_TESTS`
+gates it per branch. Full spec and the reasoning live in
+[amplify-deployment](./amplify-deployment.md).
 
 ## How to run it
 
@@ -245,10 +317,51 @@ Every `cy:*` script goes through **`node scripts/cypress.mjs`** — see the firs
   branch.** Otherwise mounted components get a second copy of React / react-query — "Invalid hook
   call", or "No QueryClient set" with the provider plainly visible in the stack.
   `component/harness.cy.tsx` is the canary that fails when it drifts.
+- **⚠ A blox `AdvancedSelect` input collapses to ZERO width once a value is picked** — so clicking
+  the `<input>` to reopen the menu fails ("element has no size"). Click the **control**, i.e. the
+  input's `.parent()`.
+- **⚠ Ignore the ResizeObserver error PER SPEC, never globally.** Chrome throws
+  `ResizeObserver loop completed with undelivered notifications` when the
+  `CancelDialogGuardrail` `<dialog>` opens, because the app's `ButtonPair.tsx` writes button widths
+  **inside** a `ResizeObserver` callback. Swallow that one message with `cy.on('uncaught:exception')`
+  in the spec that opens the dialog. A global handler would hide real app exceptions — the harness
+  is meant to fail loud (CTO call).
+- **⚠ Some lists are fetched TWICE when they open** (once as the unfiltered search source, once for
+  the filtered options), so a `cy.wait('@alias')` can consume the wrong request and assert against
+  the wrong body. Assert on **`cy.get('@alias.all')`** and pick the request you mean.
+- **⚠ After merging a branch off `_feature-cypress`, run `npm install` before anything else.** Those
+  branches import Talos packages (`@assistant-ui/react`, `@assistant-ui/react-markdown`,
+  `@langchain/langgraph-sdk`, `remark-gfm`); with a stale `node_modules` **every page** dies with
+  *"Failed to resolve import"* and every spec fails for a reason that looks nothing like the cause.
+  The lockfile already has them, so plain `npm install` fixes it. **Note:** `npm install` replaces a
+  locally linked blox with the registry copy — relink afterwards if you were testing a local blox.
 - **Scrub captured payloads.** Copying a real body out of Chrome DevTools (Network → filter
   `/v2/` → Response → Copy response) is the fastest way to build a fixture — but those payloads
   carry **real customer data**. Remove emails, names, addresses and tokens before committing.
 
+## App findings surfaced by the suite (open — not fixed)
+
+Writing the create specs turned up five real app defects. They are recorded here because the specs
+are what proves them; fix them in the app, then tighten the spec.
+
+- **`useItemCreateForm`'s success toast says "New Vendor Item Created" for an item.** Copy bug.
+- **`useVendorItemCreateForm`'s follow-up `POST /assortment-items/` can never fire.** It reads
+  `response.data.items.uuid`, but the API returns `data.vendorItems`. It also posts
+  `_unitPrice: { enteredPrice }`.
+- **Trailing-slash split:** create hooks post to `"/assortment-items/"`, edit hooks to
+  `"/assortment-items"`. The stub matches both; api2's real behaviour is **unverified**.
+- **`ButtonPair.tsx` writes button widths inside a `ResizeObserver`** — the source of the Chrome
+  ResizeObserver warning above.
+- **The per-client `vendorItemRecordCreateFields.json` files are not wired** (COMPASS,
+  COMPASSCANADA, NYCHH) — `FIELDS` always resolves DEFAULT. See
+  [client-configurable-fields](../features/client-configurable-fields.md).
+
+## Why e2e per tenant, and not component tests
+
+Decided 2026-09-15 (CTO + reviewer): the record modals are tested as **e2e specs, one run per
+tenant**. There is no component mount harness for these modals, and building one inside a test
+ticket is the bigger risk — the tenant axis is the URL, which only the e2e project models.
+
 ## Rest of the repo's test state (for context)
 
 - **Vitest is the other half.** `npm test` (`vitest run`) currently has **one failing test file**:
@@ -265,6 +378,19 @@ Every `cy:*` script goes through **`node scripts/cypress.mjs`** — see the firs
   `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`; the fixture only simulates the grant.
 
 ## Change history
+- 2026-09-15 — Added the **record-modal create specs** on `TRUE-79810`: `itemModalCreate.cy.ts`
+  (16 tests) and `vendorItemModalCreate.cy.ts` (14 tests), per-tenant `expectedUI` fixtures typed by
+  `support/tenantExpectations.ts`, and `POST /items` / `POST /vendor-items` stubs. **Rewrote the
+  failing `vendorItemModalEdit.cy.ts`** (0/5 on both tenants) — it used `data-testid`s that exist in
+  no published blox build and picked select options by menu row index; now `input#<valueKey>` +
+  exact option text + record names in the fixtures, `dialog[open]` for the guard dialog, and
+  `stubNoIntegrations()` for the no-integrations cases. Recorded three new traps (zero-width
+  `AdvancedSelect` input → click `.parent()`; the `ButtonPair` ResizeObserver error, ignored
+  per-spec only; double-fetched lists → assert on `@alias.all`), the per-field required-error
+  assertion pattern, the refetch-as-`before+1` rule, and the stale-`node_modules` /
+  `npm install` trap after merging from `_feature-cypress`. Logged five open app defects the specs
+  surfaced, and the decision to test these modals e2e-per-tenant rather than build a component
+  mount harness. CI section updated: the suite now runs as an Amplify build phase. (tcox)
 - 2026-09-14 — Re-confirmed the `useTalosSurface.test.ts` / blox `dist/global.css` Vitest load
   failure on a clean tree and refreshed the pass counts (148/148 on the rest). Still unfixed; it
   silently costs one whole suite. No code change. (apeterson)

package/package.json

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