toga-ai 1.0.367 → 1.0.368

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

@@ -9,4 +9,5 @@
 | [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/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, 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/SurfaceRowActions.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 |
+| [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [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/workflows/amplify-deployment.md

@@ -0,0 +1,119 @@
+---
+title: AWS Amplify Multi-Environment Deployment
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: workflow
+status: active
+updated: 2026-07-17
+owners: [jcardinal]
+files:
+  - toga25-supply/amplify.yml
+  - toga25-supply/src/api/api.ts
+  - toga25-supply/src/hooks/useAuthenticationFlow.ts
+  - toga25-supply/vite.config.ts
+  - toga25-supply/package.json
+related:
+  - ../architecture.md
+---
+
+## What it is
+
+How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single
+shared `amplify.yml`**. One build spec serves every branch; the correct Vite build mode is
+derived from the Amplify branch name at build time, so there is **zero per-branch console
+configuration**. This supports 21 per-mode environments: `development`, `sandbox-dev`,
+`sandbox-client`, `client-alpha/beta/gamma`, `qa-task/hotfix/alpha/beta/gamma`,
+`qc-task/hotfix/security/performance/alpha/beta/gamma`, `stage`, `demo`, and `production`.
+
+Use this doc when adding a new environment/branch, debugging a deploy that shipped the wrong
+environment identity or wrong API base URL, or touching `amplify.yml`.
+
+## How it works
+
+### Branch → mode convention (load-bearing)
+
+- Branch name convention is **`_<mode>`** — a single leading underscore followed by the mode.
+- `amplify.yml` derives the Vite mode from the built-in `AWS_BRANCH` variable by stripping the
+  one leading underscore: branch `_sandbox-client` → `VITE_MODE=sandbox-client`.
+- `<mode>` matches **both** the `.env.<mode>` file suffix **and** the `package.json` script
+  name literally.
+- Build command is:
+
+  ```
+  npx vite build --mode "$VITE_MODE"
+  ```
+
+  This loads `.env.<mode>` and bakes `import.meta.env.MODE` into the bundle.
+
+- **Not** `npm run build` — that has no `--mode` and defaults to `production` on every branch
+  (this was the original bug: every environment shipped as production).
+- **Not** `npx vite "$VITE_MODE"` / `npm run <mode>` — the per-mode `package.json` scripts are
+  **dev servers** (`vite --mode X --host Y`), not builds.
+
+### Fail-loud guardrails
+
+The spec **fails the build** if the branch has no leading underscore, or if there is no
+matching `.env.<mode>` file. A misconfigured branch therefore can **never** silently ship as
+production.
+
+### Build/cache mechanics
+
+- `preBuild`: `npm ci --cache .npm --prefer-offline`
+- artifacts `baseDirectory`: `dist`
+- cache paths: `.npm/**/*` and `node_modules/.vite/**/*`
+- Node: Vite 7 requires Node 20.19+ or 22.12+ (Node 22 recommended). Amplify's default image
+  is fine; optionally pin via `.nvmrc`.
+
+### Why the exact `--mode` matters at runtime
+
+`import.meta.env.MODE` (the `--mode` value) is baked into the bundle and read at **runtime**
+by the auth flow: `useAuthenticationFlow.ts` sends it as the `environment` value to the
+`/domains` API endpoint. A generic `vite build` (mode `production`) therefore ships the wrong
+**environment identity**, not just the wrong URL. Each deployed environment must be built with
+its exact `--mode` string.
+
+Environments differ only by `VITE_API` base URL (per `.env.<mode>`). Per-**client** behavior
+is separate and resolves at **runtime by hostname** (`useHostnameStore` / `clientSlug`), not
+at build time — this is a multi-client shared build, so there are no client-specific branches.
+
+### API base-URL resolution (`api.ts`)
+
+axios `baseURL` resolves as:
+
+```
+import.meta.env["VITE_API_" + hostname.split(".")[0].toUpperCase()] || import.meta.env.VITE_API
+```
+
+i.e. an optional per-subdomain override, falling back to `VITE_API`. The `.env.<mode>` files
+are committed and git-tracked; they contain **only public `VITE_API` base URLs, no secrets**,
+and are the single source of truth for environment API endpoints.
+
+## Adding a new environment
+
+1. Create `.env.<mode>` with the public `VITE_API` base URL.
+2. Create an Amplify branch named `_<mode>` (matching the `.env` suffix exactly).
+3. Do **not** add any `VITE_*` environment variable in the Amplify console (see gotcha).
+4. Deploy — `amplify.yml` handles the rest.
+
+## Gotchas
+
+- **NEVER set `VITE_API` (or any `VITE_*` URL) as an Amplify console environment variable.**
+  Vite does not let `.env` files overwrite variables that already exist in the build shell.
+  Amplify injects every "App settings > Environment variables" into the build shell as an OS
+  env var, so a console `VITE_API` silently **overrides every `.env.<mode>` file on every
+  branch**. Confirmed live: a console `VITE_API="sandbox-client"` produced a bundle whose
+  axios `baseURL` was the literal relative string `sandbox-client`, so API calls hit
+  `https://<site-origin>/sandbox-client/auth/...` (404) instead of
+  `https://api.client.sandbox.togahub.com/v2`. **Fix:** remove the console variable **and
+  redeploy** — removing the var does not retroactively fix an already-built bundle; a fresh
+  build is required. The `.env.<mode>` files are the single source of truth.
+- **`npm run build` ships production everywhere** — always build with an explicit
+  `--mode "$VITE_MODE"`; the per-mode `package.json` scripts are dev servers, not builds.
+
+## Change history
+- 2026-07-17 — Documented the single shared `amplify.yml` multi-environment deploy: `_<mode>`
+  branch → `--mode` derivation, fail-loud guardrails, runtime `import.meta.env.MODE` identity,
+  and the critical never-set-`VITE_API`-in-the-Amplify-console gotcha (console vars override
+  all `.env` files; requires removal **and** redeploy). (jcardinal)

package/knowledge/2.0/standards/frontend-deploy.md

@@ -0,0 +1,36 @@
+---
+title: 2.0 Frontend Deployment (Vite + AWS Amplify)
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-07-17
+owners: [jcardinal]
+related:
+  - ../apps/toga25-supply/workflows/amplify-deployment.md
+---
+
+## Scope
+Applies to all 2.0 Vite + React/TS frontends deployed on AWS Amplify.
+
+## Branch → build mode
+- Amplify branches are named `_<mode>` (single leading underscore + mode).
+- The shared `amplify.yml` derives the Vite mode from `AWS_BRANCH` by stripping the
+  leading underscore and builds with `npx vite build --mode "$VITE_MODE"`.
+- `<mode>` must match the `.env.<mode>` file suffix exactly.
+- Never deploy with `npm run build` (no `--mode` → defaults to production on every branch).
+- The build spec must fail loudly when a branch lacks the leading underscore or a matching
+  `.env.<mode>` file, so a misconfigured branch can never silently ship as production.
+
+## Environment variables
+- **Never** set `VITE_*` URL variables (e.g. `VITE_API`) in the Amplify console. Vite will
+  not let `.env` files override variables already present in the build shell, so a console
+  var silently overrides every `.env.<mode>` file on every branch.
+- Removing such a console var requires a **redeploy** — it does not fix an already-built
+  bundle.
+- Public base URLs live in committed, git-tracked `.env.<mode>` files (no secrets); these
+  are the single source of truth.
+
+## Node
+- Vite 7 requires Node 20.19+ or 22.12+ (Node 22 recommended). Pin via `.nvmrc` if needed.

package/knowledge/INDEX.md

@@ -29,7 +29,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) — 7 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 9 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/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)
+- **toga25-supply** (TOGa 2.5 Supply) — 9 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)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 

package/package.json

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