toga-ai 1.0.113 → 1.0.115

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

@@ -4,3 +4,4 @@
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
 | [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
+| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys to **AWS Amplify** for non-prod environments (qc-security, qc-performance, alpha, beta, gamma, …). | toga2-supply/amplify.yml, toga2-supply/package.json, toga2-supply/.env.qc-security |

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

@@ -0,0 +1,77 @@
+---
+title: AWS Amplify Build & Deploy (non-prod environments)
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: shared
+type: workflow
+status: active
+updated: 2026-06-17
+owners: ["jcardinal"]
+files:
+  - toga2-supply/amplify.yml
+  - toga2-supply/package.json
+  - toga2-supply/.env.qc-security
+related:
+  - ../architecture.md
+---
+
+## Summary
+
+How `toga2-supply` (React + Vite) builds and deploys to **AWS Amplify** for non-prod
+environments (qc-security, qc-performance, alpha, beta, gamma, …). Note that the
+**alpha/beta/gamma/production** environments historically deploy via **GitHub Actions**
+(`.github/workflows/*.yml`) into the `agilantsolutions/toga2-supply-build` repo — Amplify
+is the newer path used when standing up additional non-prod environments. The first Amplify
+build of this app failed with a JavaScript heap OOM; this doc records the fix and the
+scalable per-environment build setup.
+
+## Steps
+
+1. **`amplify.yml` at the repo root drives the build.** When present, it **overrides the
+   Amplify console build settings entirely, for every branch of the app** — you cannot split
+   "memory in the file, build command in the console." Whichever owns the build phase owns all
+   of it. Our `amplify.yml`:
+   - Sets `NODE_OPTIONS=--max-old-space-size=4096` in both `preBuild` and `build` (the OOM fix).
+   - Runs `npx tsc && npx vite build --mode "$VITE_BUILD_MODE"` — the build mode is **not**
+     hardcoded.
+   - Publishes `dist/` as the artifact baseDirectory.
+2. **Per environment, set one Amplify env var on that branch:** `VITE_BUILD_MODE` =
+   `qc-security` | `qc-performance` | `alpha` | `beta` | `gamma`. No new npm script per env.
+3. **Each mode needs a matching `.env.<mode>` file** committed in the repo (Vite loads
+   `.env.<mode>` for `--mode <mode>`). e.g. `.env.qc-security` provides `VITE_API`. A new
+   environment requires creating its `.env.<mode>` file.
+4. Commit `amplify.yml` + the env file, push the branch; Amplify rebuilds.
+
+## Systems involved
+
+- AWS Amplify (build + hosting), per-branch environment variables.
+- Vite 4 build (`vite build --mode <mode>`), TypeScript `tsc` precompile.
+- Sentry source-map upload via `@sentry/vite-plugin` (source maps are **on** —
+  `build.sourcemap: true` in `vite.config.ts`).
+
+## Edge cases & escalation
+
+- **OOM root cause:** Amplify gives Node the default ~2 GB old-space heap. This app
+  (1793 modules + source maps on) exceeds it during Rollup's `rendering chunks` phase →
+  `FATAL ERROR: Ineffective mark-compacts near heap limit`. Fix = raise `NODE_OPTIONS`.
+- **Heap vs. instance RAM:** `--max-old-space-size=4096` only helps if the build container
+  has ≥4 GB. Amplify **Standard** compute is 4 GB (tight with source maps on). If it OOMs
+  again, switch to the **Large build instance** (Amplify → App settings → Build settings)
+  and raise to `6144`/`7168`. Setting the heap above physical RAM makes it worse, not better.
+- **Mode/filename mismatch:** `--mode qc-security` loads `.env.qc-security` exactly — a file
+  named `.env.qc-security.beta` is silently ignored (build succeeds but ships with no
+  `VITE_API`). Name the env file to match the mode.
+- **Secret hygiene:** `.env.<mode>` files have historically carried a live
+  `SENTRY_AUTH_TOKEN`. Prefer rotating it and moving it to an Amplify env var rather than
+  committing it.
+
+## Change history
+
+- 2026-06-17 — Created on first Amplify setup of a new QC environment: added root `amplify.yml`
+  with raised Node heap + parameterized `VITE_BUILD_MODE`; renamed `.env.qc-security.beta` →
+  `.env.qc-security` (jcardinal)
+
+## Related docs
+
+- [TOGa Supply architecture](../architecture.md)

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -7,6 +7,6 @@
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
-| [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini |

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-16
+updated: 2026-06-17
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite.php
@@ -20,6 +20,7 @@ files:
   - test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md
   - test/@dave/clickup/backfill_opportunity_numbers.php
   - test/@dave/clickup/probe_opportunity_fields.php
+  - test/@dave/probe_clickup_desc_match.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
   - ./netsuite-salesorder-open-orders-sync.md
@@ -89,8 +90,16 @@ 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()`**: PUT name/description, then POST each custom field individually to
-   `/task/{id}/field/{fieldId}` (ClickUp has no bulk custom-field set on an existing task).
+2. **Match → `updateTask()`**: **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
+   blind rewrite fires a `taskUpdated` webhook on every sync. Comparison is **block-to-block** —
+   `buildDescription()` is regenerated from current NS data and compared to the stored block (no field
+   extraction needed), and `findClickupTaskByOpportunityNumber()` returns the **full task object** so
+   the diff has the existing name/description/custom-field values. Helpers: `clickupFieldMatches()`
+   (text = string compare; Presales Lead users field = add-only, matches when already assigned) and
+   `normalizeDescription()`.
 3. **No match → `createTask()`**: POST to list `901111987449`, `custom_item_id` = `1009`.
 
 Shared helpers: `buildCustomFields()` (the field array, used by both create and update),
@@ -118,7 +127,10 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
   JS `Date.toString()` style in **America/Los_Angeles**, e.g. `GMT-0800 (PST)`, auto PST/PDT by date);
   Stage = `entityStatus.refName` (the percent string like "10%", NOT `probability`); Details = `memo`
   (which carries NetSuite's "Missing Required Details…" fallback verbatim for pre-mandatory records).
-  The blank separator lines are a single space. Rendered verbatim — no trailing-period normalization.
+  The blank separator lines are emitted as a single space, but **ClickUp stores them as truly empty
+  lines** (our `\n \n` comes back `\n\n`). Change-detection's `normalizeDescription()` rtrims each line
+  so that whitespace delta doesn't read as a change (otherwise every sync would re-write the
+  description). Confirmed against task 868jh6x08 / opp 73142 via `test/@dave/probe_clickup_desc_match.php`.
 - **Custom-field value mapping** (the non-obvious part — these were swapped before 2026-06-16):
   `Opportunity #` (`a5529cdc-…`) ← `tranId`; `Customer #` (`170dc118-…`) ← `entity->refName`
   (the customer **name**, deliberately — not the NetSuite customer number). Plus `Sales Rep`,
@@ -227,7 +239,37 @@ None — platform-wide Forecast sync.
   window to the load→claim gap. `findSendableIds` must list every sendable status
   (`Created`,`Pending`,`Retry`,`Sending`) — omitting `Created` silently matches nothing (`candidates:0`).
 
+## CU→NS direction (future — not yet built): reverse mapping
+
+The current sync is **NS→CU only**. When the ClickUp→NetSuite direction is built, it cannot reuse the
+block-to-block compare, because the source of the edit is the ClickUp **composite** but the destination
+is **discrete NetSuite fields**. It must **reverse-map** — extract the real NS values out of the wrapper
+before comparing-to / writing-to NetSuite:
+
+- **Title → NS `title`:** the task name is `{opp#} — {customer} — {title}`. Do **not** naively split on
+  ` — ` (a title can contain a dash). Strip the **known** `{Opportunity#} — {Customer#} — ` prefix using
+  the values already on the `Opportunity #` / `Customer #` custom fields as anchors; the remainder is
+  the NS title.
+- **Description → NS `memo`:** take only the lines between the `Details:` marker and the trailing
+  `NetSuite Internal ID:` line. Company / Amount / Expected Close / Stage are NS-derived display, not
+  ClickUp-authored — parse them out and ignore.
+- **Custom fields** are already discrete — no extraction.
+
+Pair this with: a **field-ownership gate** (only write fields ClickUp is authoritative for — Amount/
+Stage/Expected Close are NS-owned, and HubSpot also writes these records, so don't push them back), the
+same **skip-if-unchanged** compare on the extracted values, and **actor-identity suppression** (drop
+`taskUpdated` events authored solely by the ClickUp bot/integration user) so our own NS→CU writes don't
+trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
+
 ## Change history
+- 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
+  `clickupFieldMatches()` (add-only users field) + `normalizeDescription()` (per-line rtrim — ClickUp
+  trims our single-space separator lines to empty, which previously read as a permanent change).
+  Verified opp 73142 (changed in NS → correctly flagged) and same-data (→ `unchanged`). Also recorded
+  the future **CU→NS reverse-mapping** design (extract title/memo, field-ownership gate, actor-identity).
+  (dfranks)
 - 2026-06-16 — ClickUp task description switched to a structured block (`buildDescription()` +
   `formatAmount()`/`formatExpectedClose()`): Company/Opportunity/Amount/Expected Close/Stage/Details/
   Internal ID. Field sources confirmed via `probe_opportunity_fields.php`; Expected Close rendered

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 3 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
-- **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
+- **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 0 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)

package/package.json

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