toga-ai 1.0.240 → 1.0.241

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

@@ -9,3 +9,4 @@
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
+| [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md

@@ -141,7 +141,22 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   configs must use a `scope` discriminator in the query key or they overwrite each other's cache
   (record modal vs. approval modal: the approval modal omitting item-image fields blanked the
   record modal's images until scoping isolated the entries).
+- **`poNumber` does NOT go through the approval modal.** `SalesOrderView` routes
+  `activeModal === "poNumber"` to a **separate** `EnterPoNumberModal` and explicitly excludes it
+  from `SalesOrderApprovalModalsLayout` (`activeModal !== "poNumber"`). The approval-modal
+  `modalSelected` union still lists `"poNumber"`, but that path is handled by the PO modal, not
+  the approval flow — don't add PO-number handling to the approval layout.
+- **Approval submit payload: workflow vs single decision differ.** A single approve/deny posts a
+  **boolean** `isApproved` (`true`/`false`). The workflow path
+  (`handleFormatApprovalWorkflowPayload`) posts a **string** `"1"`/`"0"`, emits a request **only**
+  for stages whose `note` / `assignedTo` / `decision` actually changed, and chooses verb by
+  `stage.ApprovalDecisions.uuid` — `null` → POST `/approval-decisions`, otherwise PUT
+  `/approval-decisions/{uuid}`.
 
 ## Change history
+- 2026-06-30 — Recorded two behaviors confirmed while building approval-modal tests: `poNumber`
+  is handled by a separate `EnterPoNumberModal` (excluded from the approval layout), and the
+  workflow vs single-decision submit payloads differ (string `"1"`/`"0"` + changed-stages-only +
+  POST/PUT by decision uuid, vs boolean `isApproved`). (apeterson)
 - 2026-06-23 — Documented from CLAUDE.md Modal Patterns 1–5 + the `create-record-modal` skill during
   initial knowledge seed. (apeterson)

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

@@ -0,0 +1,143 @@
+---
+title: Cypress Testing Harness (component + e2e)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: workflow
+status: active
+updated: 2026-06-30
+owners: [apeterson]
+files:
+  - toga25-supply/cypress.config.ts
+  - toga25-supply/cypress/tsconfig.json
+  - toga25-supply/cypress/support/component.tsx
+  - toga25-supply/cypress/support/component-index.html
+  - toga25-supply/cypress/support/e2e.ts
+  - toga25-supply/cypress/support/commands.ts
+  - toga25-supply/cypress/support/fixtures.ts
+  - toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts
+  - toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx
+  - toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx
+  - toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx
+  - toga25-supply/cypress/e2e/salesOrderApproval.cy.ts
+related:
+  - ../features/record-modals-and-nested-tables.md
+  - ../features/action-button-rule-engine.md
+  - ../architecture.md
+---
+
+## What it is
+
+The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch
+(`cypress` was already a dependency but there was no config, no `cypress/` dir, and zero
+tests anywhere in the repo). It defines **both** a `component` project (Vite devServer,
+mounts a single component) and an `e2e` project, plus reusable support code for mounting
+components with the app's providers, mocking a component's data hook without a network or
+tenant config, and sharing fixtures. The first specs cover the Sales Order **approval
+modal flow**. Use this doc when adding any new test to the repo.
+
+## How the harness is wired
+
+### `cypress.config.ts` — two projects
+
+- **`component`** — `devServer: { framework: "react", bundler: "vite" }` with a `viteConfig`
+  that **mirrors the app's `vite.config.ts`**: the `@` → `src` alias, the regex aliases that
+  force a single React copy, `optimizeDeps.exclude: ["@agilant/toga-blox"]` +
+  `optimizeDeps.include: ["dayjs"]`. This is the load-bearing part — toga-blox must resolve
+  the same way it does under `npm run dev`, or mounted components fail to bundle or get a
+  second React copy.
+- **`e2e`** — standard `baseUrl` + `supportFile` setup for full-journey specs.
+
+### `cypress/support/component.tsx` + `commands.ts` — mounting with providers
+
+`cy.mountWithProviders` is a custom command that wraps the mounted component in
+`QueryClientProvider` + `ToasterProvider`. It accepts an **injectable `queryClient`** so a
+spec can `cy.spy()` on `removeQueries` / `invalidateQueries` and assert the cache routine a
+component runs on success. The default QueryClient is configured with `retry: false` for
+determinism. Support also imports `@/index.css` (styling) and `@/api/api` — the latter so
+toga-blox's `apiPost` / `apiPut` have a configured axios instance available during component
+tests.
+
+### Window-backed hook-mock pattern (key technique)
+
+`cypress/support/mocks/useApprovalModalViewModel.ts` lets you unit-test a data-binding
+component **without** a network or tenant config. The component devServer aliases the
+component's **relative** import of its view model to the mock:
+
+```ts
+// in the component viteConfig resolve.alias
+{ find: /^\.\/viewModel\/useApprovalModalViewModel$/, replacement: "<abs>/cypress/support/mocks/useApprovalModalViewModel.ts" }
+```
+
+The mock returns whatever the spec parked on `window.__approvalModalViewModel`. In Cypress
+component testing the spec and the component share the **same `window`**, so a plain
+assignment before `cy.mount` is visible to the hook. Helpers `setApprovalModalViewModel` /
+`resetApprovalModalViewModel` set and clear it. To mock a different component's hook, add a
+parallel regex alias + a parallel `window.__<name>` mock.
+
+### `cypress/support/fixtures.ts` — shared fixtures
+
+Imports the **real shipped** tenant config
+`src/pages/SalesOrders/.../viewModel/FIELDS/QUAD/approvalActionFields.json` as
+`recordActionFields`, so tests track the actual field / label / guardrail config the app
+ships (not a hand-rolled copy that drifts). Adds synthetic order / approval-stages / PO
+fixtures alongside it. (The QUAD file is reused only as a representative real config — this
+harness is generic test infra, not Quad-specific behavior.)
+
+## What the specs cover
+
+- **`SalesOrderApprovalModalsLayout.cy.tsx`** (component) — the sales-order binding:
+  null-guards, `isApproveButtonEnabled` derivation, and the documented `onSuccess` cache
+  routine asserted via the spied QueryClient.
+- **`RecordApprovalModalLayout.cy.tsx`** (component) — the generic approval modal flow: deny
+  requires a reason (approve optional), submit fires the decision API + `onSuccess`/`onClose`,
+  discard-reason guardrail on Cancel/backdrop, workflow approve-enablement, deep workflow
+  stage editing (deny one stage with a required note → submits only that stage; an empty
+  required note blocks submit), and the **decision-failure path** (500 → modal stays open,
+  `onSuccess`/`onClose` not called).
+- **`EnterPoNumberModal.cy.tsx`** (component) — the PO-number action: create requires a PO#,
+  POST `/purchase-orders/`, credit-card flag `0`/`1`, edit → PUT.
+- **`salesOrderApproval.cy.ts`** (e2e) — full journey: seed auth via
+  `localStorage.accessToken`, row-action menu → Deny → submit, stubbing only the write.
+
+## Conventions for writing tests here
+
+- **Component test of a data-binding component** → use the window-backed hook mock so you
+  never need a real network/tenant config; park state on `window.__<hook>` before `cy.mount`.
+- **Asserting a cache side-effect** (invalidate/remove queries on success) → inject a spied
+  `queryClient` into `cy.mountWithProviders`.
+- **Testing an async error path** → use `cy.on("uncaught:exception", ...)` to swallow the
+  rejected `mutateAsync` so the rejection doesn't fail the spec, then assert the modal stayed
+  open and `onSuccess`/`onClose` were not called.
+- **e2e auth** → seed `localStorage.accessToken`; stub only the write request, let reads hit
+  the configured backend (document any backend prerequisites in the spec).
+- **Keep the component devServer config in sync with `vite.config.ts`** — when the app's
+  Vite aliases or `optimizeDeps` change, mirror the change into `cypress.config.ts` or
+  component mounts break.
+
+## package.json scripts
+
+`cy:open`, `cy:run:ct` (component), `cy:run:e2e`, `test:ct`.
+`.gitignore` excludes `cypress/videos|screenshots|downloads`.
+
+## Gotchas
+
+- **Cypress's bundled Electron cannot launch in the sandboxed macOS dev environment** — it
+  fails the pre-run smoke test (`bad option: --no-sandbox / --smoke-test / --ping`), which
+  blocks **all** specs before any run. The specs in this harness were validated by
+  `tsc -p cypress/tsconfig.json` (0 errors) and `eslint cypress` (clean) but **could not be
+  executed in that sandbox** — run them locally with `npm run cy:run:ct`.
+- **`eslint.config.js` is protected by a config-protection hook.** When a spec/support file
+  trips a lint rule (e.g. `no-explicit-any`), **fix the source to satisfy the linter** (use
+  `unknown` / typed shapes) — do **not** weaken the shared eslint config to make tests pass.
+  The override edit to `eslint.config.js` is blocked by the hook by design.
+- **`@agilant/toga-blox` consumes `dist/`** — same as the app, the harness sees built
+  toga-blox, so a toga-blox source change needs a rebuild before tests observe it.
+
+## Change history
+- 2026-06-30 — Bootstrapped the Cypress harness from scratch (dual component + e2e config,
+  `cy.mountWithProviders`, window-backed hook-mock pattern, shared fixtures off the real
+  QUAD `approvalActionFields.json`) and added the first specs for the Sales Order approval
+  modal flow. Documented the sandbox-Electron blocker and the protected-eslint decision.
+  (apeterson)

package/knowledge/INDEX.md

@@ -28,7 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 7 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 7 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 8 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework

package/package.json

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