toga-ai 1.0.134 → 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/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-17
+updated: 2026-06-18
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite.php
@@ -90,7 +90,15 @@ second, independently-gated concern in the same handler.
 
 1. `findClickupTaskByOpportunityNumber($tranId)` — GET the list filtered by the `Opportunity #`
    custom field (`include_closed=true&include_archived=true&custom_fields=[{field_id,operator:'=',value}]`).
-2. **Match → `updateTask()`**: **diffs first, writes only what changed** (change-detection backstop,
+2. **Match → `updateTask()` — but ONLY when `UPDATE_CLICKUP === true`.** `const UPDATE_CLICKUP = false`
+   ([Opportunity.php](worker2/Worker/Netsuite/Opportunity.php)) is a **deliberate one-way guard, NOT a
+   temporary backstop to flip**: once a ClickUp opportunity task exists, ClickUp is the source of truth
+   for it, and a NetSuite edit must **not** clobber edits made on the ClickUp side. With the flag false
+   (its production value), a match returns `skipped update (update disabled)` and ClickUp is left
+   untouched — so the *designed, correct* behavior of a NetSuite edit to an opportunity that already has
+   a task is: **Forecast upserts, ClickUp unchanged.** Do not "enable updates" by flipping it. The
+   change-detection logic below only runs in the (currently-off) update path. When enabled, it:
+   **diffs first, writes only what changed** (change-detection backstop,
    since 2026-06-17). PUT name/description **only if** one differs; POST **only** the custom fields
    that differ (each to `/task/{id}/field/{fieldId}` — ClickUp has no bulk custom-field set). When
    nothing differs it writes nothing and returns `task unchanged`. This kills the no-op-write echo: a
@@ -204,6 +212,13 @@ None — platform-wide Forecast sync.
   (`https://webhook.togahub.com/netsuite`) with `debugWrap` off. Also flip the enqueuer deployment
   `Testing → Released` (Testing fires only for the deploying user). Full checklist in
   `DEPLOY_RUNBOOK.md` §6.
+- **ClickUp's `=` custom-field filter is substring/prefix, NOT strict equality.** `findClickupTaskByOpportunityNumber($tranId)`
+  filters the `Opportunity #` field with `operator:'='`, but for a short-text custom field ClickUp matches
+  loosely: a lookup for `74266` still returns a task whose value is `74266--` (confirmed live 2026-06-18).
+  So **appending** to the dedup value does NOT defeat the match — to force a dedup *miss* (e.g. to exercise
+  the create branch) you must change the **leading** content or clear the field entirely. Verified both ways
+  on opp 74266/internalId 7161054: `74266--` → matched (update branch, skipped); field removed → missed
+  (create branch, new task `868k2rfj8`).
 - **ClickUp dedup keys on the `Opportunity #` field, not a DB column.** We deliberately did NOT add
   a `clickupTaskId` column — the dedup lookup queries ClickUp itself by `Opportunity #` (= tranId).
   Consequences to know:
@@ -262,6 +277,16 @@ same **skip-if-unchanged** compare on the extracted values, and **actor-identity
 trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
 
 ## Change history
+- 2026-06-18 — **Verified live in production** (no code change): real NetSuite SuiteScript webhooks
+  (`user-agent: NetSuite/2026.1`) arrive at `webhook.togahub.com/netsuite` and process successfully
+  (e.g. opp 6926224 PUT). Clarified that **`UPDATE_CLICKUP = false` is an intentional one-way guard**
+  (NS edits must not overwrite ClickUp-side edits), not a flag to flip — so "NS edit → Forecast upserts,
+  existing ClickUp task untouched" is the *designed* behavior. Documented that ClickUp's `=` custom-field
+  filter is **substring/prefix**, not exact (a `74266` lookup matched `74266--`); confirmed both dedup
+  branches on opp 74266/internalId 7161054. Testing note: the webhook needs the **internalId**, not the
+  opportunity number — resolve it via `Forecast.Opportunities.netsuiteOpportunityInternalId` for a given
+  `opportunityNumber` (tranId). Fire a manual test with
+  `curl -X POST https://webhook.togahub.com/netsuite -d '{"recordType":"opportunity","eventType":"edit","internalId":<id>}'`. (dfranks)
 - 2026-06-17 — ClickUp **change-detection backstop** added to `updateTask()`: diff before write, skip
   no-op syncs (`task unchanged`), PUT name/description only when changed, POST only changed custom
   fields. `findClickupTaskByOpportunityNumber()` now returns the full task object; added

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.134",
+  "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",