toga-ai 1.0.135 → 1.0.136

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

@@ -3,3 +3,4 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
+| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |

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

@@ -0,0 +1,99 @@
+---
+title: AWS Amplify Build & Deploy (non-prod environments)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: workflow
+status: active
+updated: 2026-06-18
+owners: ["jcardinal"]
+files:
+  - toga2-commerce/amplify.yml
+  - toga2-commerce/.gitattributes
+  - toga2-commerce/package.json
+  - toga2-commerce/.github/workflows/sync-stage-environments.yml
+related:
+  - ../../toga2-supply/workflows/amplify-build-and-deploy.md
+---
+
+## Summary
+
+How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**.
+Same branch-per-environment model as `toga2-supply` (see related doc), with one important
+difference: commerce's build scripts **install a per-environment `@agilant/toga-blox` channel**
+before building, so the Amplify build must run the npm scripts (not a raw `vite build`), and the
+matching blox dist-tag must exist on npm first.
+
+## Deployment model — one branch per environment (mirrors toga2-supply)
+
+- Branches are **underscore-prefixed** (`_production`, `_beta`, `_gamma`, `_qc-security`); the
+  Vite mode is the same name **without** the underscore.
+- Repo-root `amplify.yml` drives every branch's build. It sets
+  `NODE_OPTIONS=--max-old-space-size=8192`, strips the leading `_` from `$AWS_BRANCH` to get the
+  mode, **fails loudly if `.env.<mode>` is missing**, then maps the mode → the matching npm build
+  script via a `case` (production→`npm run build`, alpha→`buildAlpha`, beta→`buildBeta`,
+  gamma→`buildGamma`, qc-security→`buildQcSecurity`; unmapped → `exit 1`). Single-line command, LF
+  only (`.gitattributes` pins `*.yml` to `eol=lf`).
+- `sync-stage-environments.yml` fans `_stage` → `_qc-security` on push.
+
+## blox per-environment channel + the publish chain
+
+Unlike supply (which pins blox via a normal dependency), each commerce build script installs a
+**blox dist-tag** matching the environment:
+`"buildQcSecurity": "npm install @agilant/toga-blox@qc-security --legacy-peer-deps && tsc && vite build --mode qc-security"`.
+
+Those dist-tags are produced by the **`agilantsolutions/toga-blox-npm`** repo's
+`.github/workflows/publish.yml`, which auto-publishes on push to specific branches and maps
+**branch → dist-tag** (one-to-one, underscore stripped): `_production`→`latest`, `_beta`→`beta`,
+`_gamma`→`gamma`, and (added 2026-06-18) `_qc-security`→`qc-security`. So enabling a new channel
+is a two-part change: (1) add the branch + its `elif` case to `publish.yml`, push it onto that
+branch, and let it publish; (2) reference `@agilant/toga-blox@<channel>` in the app's build script.
+
+## Steps (to stand up a new environment, e.g. QC Security)
+
+1. In `toga-blox-npm`: add the branch to `on.push.branches` and an `elif` case (version suffix +
+   `DIST_TAG`) in `publish.yml`; create the publish branch **from** a branch that has the updated
+   workflow (e.g. `_qc-security` from `_production`); push → it publishes `@agilant/toga-blox@qc-security`.
+   Verify: `npm dist-tag ls @agilant/toga-blox`.
+2. In `toga2-commerce`: add a `build<Env>` script (blox `@<channel>` install + `--legacy-peer-deps`
+   + `tsc` + `vite build --mode <mode>`); add the `case` arm in `amplify.yml`; commit `.env.<mode>`.
+3. Connect the Amplify branch; push; watch for the `Branch '...' -> Vite mode '...'` echo.
+
+## Systems involved
+
+- AWS Amplify (build + hosting); GitHub Actions (`sync-stage-environments.yml` + the blox
+  `publish.yml`); npm registry (`@agilant/toga-blox` dist-tags); Vite 5 + `tsc`.
+
+## Edge cases & escalation
+
+- **All the toga2-supply gotchas apply** (console build spec overriding repo `amplify.yml`;
+  CRLF breaking block-scalar parsing; Vite silently falling back to `.env`/beta when a mode's env
+  file is missing). See the related doc.
+- **blox dist-tag must exist before the app builds.** `npm install @agilant/toga-blox@qc-security`
+  fails `ETARGET No matching version` until `publish.yml` has published that tag. `publish.yml`
+  only triggers on branches listed in `on.push.branches` and only tags branches with an explicit
+  `elif` case — creating the branch alone does nothing; the workflow file must be present on that
+  branch (GitHub Actions runs the workflow version on the pushed branch).
+- **`--legacy-peer-deps` is required** because blox declares `react-router-dom@^6` as a peer while
+  commerce uses `react-router-dom@7` (npm 7+ `ERESOLVE` otherwise). All non-prod build scripts use it.
+- **`--legacy-peer-deps` disables npm's peer auto-install**, so any blox peer that is NOT in
+  commerce's own `dependencies` and NOT in blox's `dependencies` must be added explicitly, or Vite/
+  Rollup fails with `failed to resolve import "<pkg>"`. Concretely, commerce had to add the table
+  peers: `@tanstack/react-table@^8`, `react-table@^7.8.0`, `react-table-sticky@^1.1.3`. Check
+  `npm view @agilant/toga-blox@<tag> peerDependencies` against commerce deps when a resolve error
+  appears.
+- **Secret hygiene:** commerce's committed `.npmrc` has historically held live FontAwesome + npm
+  publish tokens. Rotate and untrack — keep tokens in env vars (`${NODE_AUTH_TOKEN}` /
+  `${FONTAWESOME_NPM_TOKEN}`) as the blox `publish.yml` does.
+
+## Change history
+
+- 2026-06-18 — Initial Amplify setup: added `amplify.yml` (8192 heap, underscore-strip, fail-loud,
+  case→npm script), `.gitattributes` (LF), `sync-stage-environments.yml`; added `buildQcSecurity`
+  with `@qc-security` blox channel + `--legacy-peer-deps` (and same flag on alpha/beta/gamma);
+  added blox table peer deps; added `_qc-security` branch+case to toga-blox-npm `publish.yml`. (jcardinal)
+
+## Related docs
+
+- [toga2-supply Amplify Build & Deploy](../../toga2-supply/workflows/amplify-build-and-deploy.md) — the base pattern and shared gotchas.

package/knowledge/INDEX.md

@@ -25,7 +25,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **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) — 1 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 2 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 
 ## standalone framework
 

package/package.json

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