toga-ai 1.0.122 → 1.0.124

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

@@ -0,0 +1,5 @@
+# toga2-commerce (TOGa Commerce) — 2.0 knowledge
+
+| 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 |

package/knowledge/2.0/apps/toga2-commerce/features/cart-notification-emails.md

@@ -0,0 +1,79 @@
+---
+title: Cart Notification Emails — duplicate prevention
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["bala"]
+files:
+  - 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
+related: []
+---
+
+## Summary
+On the cart "Notifications" section a user can add CC email addresses to an order. Adding the
+same address twice (often with different casing) used to slip through to the API and blow up on
+submit with a MySQL 1062 duplicate-key error on the `SalesOrderEmailAddresses.salesOrderId_emailAddress`
+unique index (whose collation `utf8mb4_0900_ai_ci` is case-insensitive). This feature blocks
+duplicates case-insensitively in the frontend and shows a sapphire info message instead of letting
+the error reach the user.
+
+## Key files / entry points
+- `CartPage.tsx` — `handleAddEmail`: validates the email regex, then on success calls
+  `addEmailOption` (UI options list) and `addEmail` (the cart sales-quote store that builds the
+  `salesOrderEmailAddresses` payload). Normalizes the input once with `.trim()`.
+- `CartForm.tsx` — owns the duplicate UX. `handleAddEmailWithDuplicateCheck` wraps the passed-in
+  `handleAddEmail`: it case-insensitively checks the existing `emails` list and, on a match, shows
+  the message instead of adding. The **Add Email** button calls this wrapper.
+- `useEmailOptionsStore.ts` — `addEmailOption` de-dupes the checkbox list.
+- `useCartSalesQuoteZu.ts` — `addEmail` de-dupes the actual `salesOrderEmailAddresses` payload.
+
+## How it works
+1. **Before (manual add):** clicking Add Email runs `handleAddEmailWithDuplicateCheck` in
+   `CartForm`. It compares `(e.email ?? "").trim().toLowerCase()` against the normalized input. On a
+   match it sets `duplicateEmailMessage` and returns (does not add).
+2. **After (auto-add on user select):** when the order user is chosen, their email (and manager's)
+   is auto-added via `addEmailOption`. Both stores de-dupe case-insensitively, so a case-variant of
+   an already-present address is silently dropped rather than duplicated.
+3. **Display:** the message renders via the shared `InfoBanner` component (the same one used for the
+   "view as" / "edit order" banners), styled `text-sapphire-700 text-xs`, no icon. It is NOT a
+   toaster and NOT a red `setError` validation — it is a sapphire info message.
+4. The message text comes from the `notifications.duplicateEmailAddressError.label` field config,
+   present in every `CARTPAGE.ts` (all client/role/language variants, English + French).
+5. A `useEffect` clears the message when the input, selected user (`orderForUser?.uuid`), or email
+   list (`emails.length`) changes.
+
+## Data model
+Frontend only. The payload list maps to the `SalesOrderEmailAddresses` table (api2/backend), which
+has a case-insensitive unique index on `(salesOrderId, emailAddress)`.
+
+## Client variations
+The de-dupe mechanism is uniform across clients. Only the message label text differs per client
+config: English `"This email has already been added"`; French (Compass Canada)
+`"Cette adresse e-mail a déjà été ajoutée"`. The label must exist in every `CARTPAGE.ts` variant or
+the message resolves to `undefined` and renders blank.
+
+## Gotchas / known issues
+- The real source of the 1062 was `useCartSalesQuoteZu.addEmail` comparing with `===`
+  (case-sensitive). Both stores must compare case-insensitively; fixing only the UI list is not
+  enough because `addEmail` builds the payload.
+- Normalize with `(x ?? "").trim().toLowerCase()`, not `x?.trim().toLowerCase()` — both are
+  nullish-safe (optional chaining short-circuits the whole chain, it does not throw), but `(x ?? "")`
+  guarantees a string and avoids an `undefined === undefined` match edge.
+- Adding the label to only some `CARTPAGE.ts` files leaves other client/role/language users with a
+  blank message.
+- Do not use a toaster or `setError` (red) for this — product wants the sapphire info style.
+
+## Change history
+- 2026-06-18 — Initial: case-insensitive de-dupe in both cart stores, sapphire `InfoBanner` message in
+  CartForm, `duplicateEmailAddressError` label added to all CARTPAGE.ts variants (bala)
+
+## Related docs
+None yet.

package/knowledge/INDEX.md

@@ -25,10 +25,12 @@ _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)
 
 ## standalone framework
 
 - **togatech** (TOGA Technology Website) — 1 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
+- **forward** (Forwarder) — 2 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
 
 ## Clients
 

package/knowledge/clients/compass-canada/profile.md

@@ -5,14 +5,15 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga2-commerce
   - worker
   - dbchanges2
 project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-18
+owners: [jcardinal, bala]
 files: []
 related:
   - ../compass-usa/profile.md

package/knowledge/clients/compass-usa/profile.md

@@ -5,14 +5,15 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga2-commerce
   - worker
   - dbchanges2
 project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-18
+owners: [jcardinal, bala]
 files: []
 related:
   - features/asn-to-item-fulfillment.md

package/knowledge/registry.json

@@ -1,21 +1,163 @@
 [
-  { "repo": "_underscore", "project": "_Underscore", "framework": "2.0", "role": "core", "dependsOn": [] },
-  { "repo": "worker2",     "project": "Worker",      "framework": "2.0", "role": "app",  "dependsOn": [] },
-  { "repo": "api2",        "project": "API",         "framework": "2.0", "role": "app",  "dependsOn": [] },
-  { "repo": "dbchanges2",  "project": "Database Changes", "framework": "2.0", "role": "core", "dependsOn": [] },
-  { "repo": "library",     "project": "Library",     "framework": "1.0", "role": "core", "dependsOn": [] },
-  { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "saml",        "project": "SAML SSO Gateway", "framework": "2.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-view",  "project": "TOGa View Frontend", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "togadesk",    "project": "TOGa Desk",   "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "togaview",    "project": "TOGa View",   "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-hub",   "project": "TOGa Hub",    "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "togatech",    "project": "TOGA Technology Website", "framework": "standalone", "role": "app", "dependsOn": [] },
-  { "repo": "webhook",     "project": "Webhook",     "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
-  { "repo": "walmarttechservices", "project": "Walmart Tech Services", "framework": "1.0", "role": "app", "dependsOn": ["library"] },
-  { "repo": "talos",       "project": "TOGa IQ",      "framework": "2.0", "role": "app", "dependsOn": [], "language": "python" },
-  { "repo": "test",        "project": "Test",        "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
-  { "repo": "voice-to-voice", "project": "TOGa Voice", "framework": "2.0", "role": "app", "dependsOn": [], "language": "python" },
-  { "repo": "ai-bdr",      "project": "AI-BDR",      "framework": "2.0", "role": "app", "dependsOn": [] }
+  {
+    "repo": "_underscore",
+    "project": "_Underscore",
+    "framework": "2.0",
+    "role": "core",
+    "dependsOn": []
+  },
+  {
+    "repo": "worker2",
+    "project": "Worker",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "api2",
+    "project": "API",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "dbchanges2",
+    "project": "Database Changes",
+    "framework": "2.0",
+    "role": "core",
+    "dependsOn": []
+  },
+  {
+    "repo": "library",
+    "project": "Library",
+    "framework": "1.0",
+    "role": "core",
+    "dependsOn": []
+  },
+  {
+    "repo": "worker",
+    "project": "Worker",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "toga2-supply",
+    "project": "TOGa Supply",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [
+      "api2"
+    ]
+  },
+  {
+    "repo": "saml",
+    "project": "SAML SSO Gateway",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "toga2-view",
+    "project": "TOGa View Frontend",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [
+      "api2"
+    ]
+  },
+  {
+    "repo": "togadesk",
+    "project": "TOGa Desk",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "togaview",
+    "project": "TOGa View",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "toga2-hub",
+    "project": "TOGa Hub",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [
+      "api2"
+    ]
+  },
+  {
+    "repo": "togatech",
+    "project": "TOGA Technology Website",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "webhook",
+    "project": "Webhook",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
+  {
+    "repo": "walmarttechservices",
+    "project": "Walmart Tech Services",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
+  {
+    "repo": "talos",
+    "project": "TOGa IQ",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [],
+    "language": "python"
+  },
+  {
+    "repo": "test",
+    "project": "Test",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
+  {
+    "repo": "voice-to-voice",
+    "project": "TOGa Voice",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [],
+    "language": "python"
+  },
+  {
+    "repo": "ai-bdr",
+    "project": "AI-BDR",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "forward",
+    "project": "Forwarder",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "toga2-commerce",
+    "project": "TOGa Commerce",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": ["api2"]
+  }
 ]

package/knowledge/standalone/apps/forward/INDEX.md

@@ -0,0 +1,6 @@
+# forward (Forwarder) — standalone knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [Forwarder Architecture](architecture.md) | Forwarder is a tiny **standalone PHP application** that powers TOGA's short, branded redirect domains. | forward/forward.ini, forward/index.php, forward/.htaccess, forward/.platform/httpd/conf.d/rewritemap.conf, forward/.ebextensions/rewritemap.config, forward/composer.json |
+| [Encrypted-Link Handler](features/encrypted-link-handler.md) | A `index.php` feature in [Forwarder](../architecture.md) for redirect domains whose URL path carries an **encrypted token** that must be decoded before redirect | forward/index.php |

package/knowledge/standalone/apps/forward/architecture.md

@@ -0,0 +1,121 @@
+---
+title: Forwarder Architecture
+framework: "standalone"
+repo: forward
+project: Forwarder
+client: shared
+type: architecture
+status: active
+updated: 2026-06-18
+owners: [jcardinal]
+files:
+  - forward/forward.ini
+  - forward/index.php
+  - forward/.htaccess
+  - forward/.platform/httpd/conf.d/rewritemap.conf
+  - forward/.ebextensions/rewritemap.config
+  - forward/composer.json
+related: []
+---
+
+# Forwarder Architecture
+
+Forwarder is a tiny **standalone PHP application** that powers TOGA's short, branded
+redirect domains. The pattern: point a short **CNAME** (e.g. `powerbi.togatech.com`,
+`feedback.agilantsolutions.com`) at the Forwarder app running on **AWS Elastic Beanstalk**
+(Amazon Linux 2023 / Apache), and Forwarder issues an HTTP redirect to the real
+destination. It does **not** use either PHP framework (1.0 `App_` or 2.0 `_underscore`),
+which is why it lives under the `standalone/` knowledge partition.
+
+Local path on dev machines is tracked in Claude memory (`repo-path-forward`), not here.
+
+## Two layers: zero-compute map vs. light PHP compute
+
+Forwarder has two distinct redirect mechanisms. The vast majority of traffic never
+touches PHP at all.
+
+### 1. Zero-compute redirects (the common case) — Apache `RewriteMap` + `forward.ini`
+
+The `.htaccess` at the repo root drives a plain-text lookup table:
+
+- `forward.ini` is an Apache **`txt` RewriteMap** of `source destination` lines:
+  - `source` = full host or `host/path` (no scheme, no trailing slash)
+  - `destination` = full target URL (query strings allowed)
+  - Blank lines and `#` comments are ignored.
+- The `RewriteMap forwardmap txt:/var/www/html/forward.ini` directive **cannot** live in
+  `.htaccess` (must be server/VirtualHost scope), so it is deployed separately (see
+  Deployment below).
+- **Match precedence in `.htaccess`:**
+  1. Exact `HTTP_HOST + REQUEST_URI` match → `302` (flags `NE,QSA`).
+  2. Else `HTTP_HOST`-only match → `302`, appending the original path + query to the
+     destination.
+  3. Else, if the request is not a real file/dir, fall through to `index.php`.
+- **Operational win:** editing `forward.ini` takes effect **immediately** — Apache
+  re-reads the txt map on the next request after a graceful reload (`sudo systemctl
+  reload httpd`); no redeploy or restart needed. Most "add a redirect" requests are a
+  one-line edit to `forward.ini`.
+- **Authoring rule:** put the most **specific** `host/path` lines **before** the general
+  `host`-only line, or the general line matches first and the path line is never reached
+  (documented in the `forward.ini` header).
+- **Health check:** `.htaccess` short-circuits to `200 OK` for `ELB-HealthChecker`
+  user-agents and localhost / private-IP hosts (`127.*`, `10.*`, `172.*`, `192.168.*`),
+  so AWS ELB health checks pass without a map entry.
+
+### 2. Light compute (the exception) — `index.php`
+
+`index.php` is reached only when no map entry matched. It handles three cases:
+
+- **Encrypted-link handler** — for a hardcoded `$encryptedDomains` allowlist (PCMatic /
+  Newegg / `forward.*` agent-download domains), it extracts the encrypted path segment
+  (by a per-domain `offset`: `0` = first segment, `1` = second), runs `decrypt()`, then
+  `302`s to the domain's configured base URL with the decrypted value `urlencode`d
+  appended. Invalid/empty/tampered input returns a styled `400`. See the
+  [encrypted-link-handler](features/encrypted-link-handler.md) feature doc.
+- **Local directory handler** — if the first host label matches a directory in the repo
+  (e.g. `sos.*` → `/sos/`), it redirects to `/<subdomain>/` and serves that dir's
+  `index.html`. Used for the bundled `sos/` Splashtop SOS download page.
+- **404** — otherwise returns a styled `404` echoing the unmatched `host + uri`.
+
+## Deployment (Elastic Beanstalk / Apache)
+
+- Runs on **Elastic Beanstalk**, Amazon Linux 2023, Apache `httpd`.
+- The `RewriteMap` definition is deployed to `/etc/httpd/conf.d/rewritemap.conf` two ways
+  for cross-platform safety:
+  - `.platform/httpd/conf.d/rewritemap.conf` — the **Amazon Linux 2+/2023** mechanism
+    (current).
+  - `.ebextensions/rewritemap.config` — legacy **Amazon Linux 1** `files:` fallback.
+    Both can coexist; AL2+ ignores the `.ebextensions` file path managed by `.platform`,
+    and AL1 ignores `.platform` entirely.
+- `forward.ini` deploys to `/var/www/html/forward.ini` (the path the map points at).
+- `composer.json` declares a `Togatech\Forward\` PSR-4 autoload over `src/` but has **no
+  dependencies** and no `src/` is shipped today — the app is effectively a single
+  `index.php` plus the Apache config.
+
+## The `decrypt()` scheme
+
+`decrypt()` in `index.php` is a **home-rolled** symmetric scheme, used only to obfuscate
+agent-download tokens in URLs — **not** real encryption and not for protecting secrets:
+
+1. URL-safe base64 normalize (`-_` → `+/`); the **last char** is a stored integrity hash.
+2. base64-decode the remainder; the **first byte** is the key-start seed.
+3. Regenerate a keystream from the seed (`i += i` per step, `chr(i % 255)`) and XOR it
+   against the payload to recover the plaintext.
+4. Verify by recomputing the first char of `base64(hmac_sha256(payload, key))` and
+   comparing to the stored hash; mismatch → empty string (treated as failure → `400`).
+
+Treat this as obfuscation only. Anything genuinely sensitive must not rely on it.
+
+## Notes / gotchas
+
+- **No restart needed for new redirects** — edit `forward.ini`, reload httpd. This is the
+  single most useful operational fact about this app.
+- Specific-path map lines must precede host-only lines (see `forward.ini` header).
+- New **encrypted** domains require a code change (`$encryptedDomains` in `index.php`),
+  not just a `forward.ini` edit.
+- `index.php` only runs on a map miss, so a bad/over-broad `forward.ini` host-only line
+  can shadow paths you expected PHP to handle.
+
+## Change history
+
+- 2026-06-18 (jcardinal) — Initial architecture documentation; registered `forward`
+  (Forwarder, standalone) in the knowledge base.

package/knowledge/standalone/apps/forward/features/encrypted-link-handler.md

@@ -0,0 +1,70 @@
+---
+title: Encrypted-Link Handler
+framework: "standalone"
+repo: forward
+project: Forwarder
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: [jcardinal]
+files:
+  - forward/index.php
+related:
+  - standalone/apps/forward/architecture.md
+---
+
+# Encrypted-Link Handler
+
+A `index.php` feature in [Forwarder](../architecture.md) for redirect domains whose URL
+path carries an **encrypted token** that must be decoded before redirecting — used for
+remote-support / agent-download links (PCMatic, Newegg, generic `forward.*` agent
+downloads) where the trailing value (e.g. a user identifier) is obfuscated in the path.
+
+## When it runs
+
+Only when the Apache `RewriteMap` (`forward.ini`) produced **no match** and the request
+falls through to `index.php`, and the lowercased `HTTP_HOST` is a key in the hardcoded
+`$encryptedDomains` allowlist near the top of `index.php`.
+
+## Configuration
+
+`$encryptedDomains` maps a host to `['url' => <base>, 'offset' => <int>]`:
+
+- `url` — the destination base URL; the decrypted value is `urlencode`d and appended.
+- `offset` — which **0-based path segment** holds the encrypted token:
+  - `0` → `host.com/ENCRYPTED`
+  - `1` → `host.com/prefix/ENCRYPTED`
+
+Adding a new encrypted domain is a **code change** (edit `$encryptedDomains`), not a
+`forward.ini` edit.
+
+## Flow
+
+1. Split the request path on `/`; take the segment at `offset` as the token.
+2. Empty token → styled **`400` Invalid Link**.
+3. `decrypt($token)` (see below); failure (empty return) → styled **`400` Decryption
+   Failed**.
+4. Success → `header('Location: ' . $base . urlencode($decrypted), 302)`.
+
+## The `decrypt()` algorithm
+
+Custom symmetric scheme — **obfuscation, not real encryption**:
+
+1. Restore URL-safe base64 (`-_` → `+/`). The **final character** is a stored 1-char
+   integrity hash; strip and keep it.
+2. base64-decode the rest. The **first byte** is the key-start seed; the remainder is the
+   payload.
+3. Regenerate a keystream from the seed — `for (i = seed, j = 0; j < len; i += i, j++)
+   key .= chr(i % 255)` — and XOR it byte-for-byte against the payload to recover the
+   plaintext.
+4. Integrity check: recompute `substr(base64_encode(hash_hmac('SHA256', payload, key,
+   true)), 0, 1)` and compare to the stored hash char. Mismatch → return `''` (→ `400`).
+
+Because it is home-rolled and uses only a single hash character for integrity, treat it
+strictly as link obfuscation. Do not use it to protect anything sensitive.
+
+## Change history
+
+- 2026-06-18 (jcardinal) — Initial documentation of the encrypted-link handler during
+  Forwarder onboarding into the knowledge base.

package/package.json

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