toga-ai 1.0.51 → 1.0.52

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

@@ -3,4 +3,3 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
-| [Nested Field Foreign-Key Resolution (getChildOptionRecords)](bug/nested-field-foreign-key-resolution.md) | When a request supplies a `fields` option, the V2 JSON engine does NOT use the depth-bounded `getFullModelData()` serializer. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ItemCategoryFeature.php, _underscore/Model/Client/ItemFeature.php, _underscore/Model/Client/ItemCategoryFeatureGroup.php |

package/knowledge/INDEX.md

@@ -11,10 +11,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 4 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 5 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 2 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 1 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-commerce** (TOGa Commerce) — 2 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 
 ## Clients
 

package/knowledge/registry.json

@@ -5,6 +5,5 @@
   { "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": "toga2-commerce", "project": "TOGa Commerce", "framework": "2.0", "role": "app", "dependsOn": ["api2"] }
+  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] }
 ]

package/package.json

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

package/knowledge/2.0/apps/api2/bug/nested-field-foreign-key-resolution.md

@@ -1,108 +0,0 @@
----
-title: Nested Field Foreign-Key Resolution (getChildOptionRecords)
-framework: "2.0"
-repo: api2
-project: API
-client: shared
-type: feature
-status: active
-updated: 2026-06-11
-owners: [bala]
-files:
-  - api2/Component/Api/V2/V2.php
-  - _underscore/Model/Client/ItemCategoryFeature.php
-  - _underscore/Model/Client/ItemFeature.php
-  - _underscore/Model/Client/ItemCategoryFeatureGroup.php
-related:
-  - 2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md
----
-
-## Summary
-
-When a request supplies a `fields` option, the V2 JSON engine does NOT use the
-depth-bounded `getFullModelData()` serializer. It uses a fields-driven serializer
-(`V2.php` ~line 3383) that splits each nested field path into:
-
-- **foreign-key sub-objects** (belongsTo) → resolved by `getChildOptionRecords()`
-- **inherent children** (one-to-many) → resolved by recursive `processRoutePairs()`
-
-There was a bug in `getChildOptionRecords()`: a foreign-key sub-object that sits on an
-**inherent child which is itself reached underneath another foreign-key parent** was
-fetched but never attached to the output, so it silently disappeared from the JSON.
-
-This surfaced as the `toga2-commerce` item-view "Specifications" headings showing
-`undefined` when an item was opened **through a bundle** (but not through a category).
-
-## Key files / entry points
-
-- `api2/Component/Api/V2/V2.php`
-  - `execute()` / `processRoutePairs()` — request lifecycle, depth setup (`DEFAULT_DEPTH = 3`).
-  - fields-driven serialization branch at ~line 3383 (`if (empty($selectFields))` else).
-  - `getChildOptionRecords()` (~line 5279) — resolves FK sub-objects and nested inherent children.
-
-## How it works
-
-For a request like `GET /items/{uuid}` with
-`...itemFeatures.itemCategoryFeatures.itemCategoryFeatureGroup.name`:
-
-- The item is the **top-level record**, so `itemFeatures` and `itemCategoryFeatures` are
-  handled as inherent children via the main `processRoutePairs` recursion, and
-  `itemCategoryFeatureGroup` (an FK on `ItemCategoryFeature`) resolves correctly. WORKS.
-
-For `GET /bundles/{uuid}` with
-`bundleItems.item.itemFeatures.itemCategoryFeatures.itemCategoryFeatureGroup.name`:
-
-- The top record is the bundle; `item` is an **FK** on `bundleItem`. Stepping through that FK
-  routes the whole `item` subtree into `getChildOptionRecords()`.
-- Inside it: `feature` is an FK → handled correctly (so `feature.measure.name` came back).
-  But `itemCategoryFeatures` is an **inherent child**, so it fell into the branch at
-  ~line 5779 ("requesting all available data for an inherent child"). That branch fetched
-  each row's FK (`itemCategoryFeatureGroup`) into `$res` (~line 5840) and **discarded it** —
-  only scalar columns (`uuid`, `limitDirection`) were attached. The group fell out.
-
-## The fix
-
-Attach the resolved FK result to the inherent child row (after the `getChildOptionRecords`
-call at ~line 5850):
-
-```php
-$outDataThisInherentChild[$inherentChildField] = $res;
-```
-
-## Data model
-
-Relationship chain (all `_Model_Client_*`, DB_CLIENT):
-
-- `ItemFeature` (`itemId`, `featureId`) — inherent child of `Item`.
-- `ItemCategoryFeature` (`itemFeatureId`, `itemCategoryFeatureGroupId`, `limitDirection`) —
-  inherent child of `ItemFeature`.
-- `ItemCategoryFeatureGroup` (`itemCategoryId`, `name`) — FK target that holds the heading.
-- `Feature` (`measureId`) -> `Measure` — the FK chain that always worked (different code arm).
-
-## Client variations
-
-None — this is a core engine fix affecting every client and every endpoint whose `fields`
-request has the shape "FK -> inherent child -> FK". The common top-level case
-(`/items`, `/sales-orders`, etc.) uses the other code path and is unaffected.
-
-## Gotchas / known issues
-
-- It is NOT a depth, ACL, or data problem. Verified against prod `Client_Compass`:
-  the group data exists (0 null `itemCategoryFeatureGroupId`), the
-  `item-category-feature-groups` record (126) has READ with `indirectRecordId = NULL`
-  (readable on any path), and no `minDepth` interceptor applies — both calls run at
-  `DEFAULT_DEPTH = 3`. `feature.measure.name` and `itemCategoryFeatureGroup.name` are at
-  identical nesting depth, so depth could never explain why one survived and the other did
-  not — the real cause is FK-vs-inherent-child handling.
-- Tell-tale sign of the buggy branch: it ignores the requested sub-fields and dumps all
-  permitted scalar columns, so the response contained a `uuid` that was never requested.
-- This branch still ignores `$varOptions` (over-returns columns) — the fix only makes FK
-  sub-objects consistent with the scalars. Acceptable and ACL-bounded, but slightly more
-  payload.
-- Leftover dead code: a second `getChildOptionRecords()` call at ~line 5887 also computes
-  `$res` and discards it (and references `$newPreviousIdentifiers`, only defined when an FK
-  field was seen). Left untouched to keep the fix minimal; worth removing separately.
-
-## Related docs
-
-- 2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md

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

@@ -1,6 +0,0 @@
-# toga2-commerce (TOGa Commerce) — 2.0 knowledge
-
-| Doc | Summary | Files |
-|-----|---------|-------|
-| [TOGa Commerce (toga2-commerce) Architecture](architecture.md) | TOGa Commerce (npm package `commerce2-react`) is the multi-tenant 2.0 storefront. | toga2-commerce/src/App.tsx, toga2-commerce/src/routes.tsx, toga2-commerce/src/api/axiosInstance.ts, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/themeConfig/ThemeContext.tsx, toga2-commerce/src/stores/index.ts |
-| [Item-View Bundle vs Direct Fetch](bug/item-view-bundle-vs-direct-fetch.md) | The item-view page (`/item-view`) fetches a single item two different ways depending on how the user reached it and what access they have: - **Direct** — `GET / | toga2-commerce/src/pages/ItemsView/api/ItemsApi.ts, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |

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

@@ -1,68 +0,0 @@
----
-title: TOGa Commerce (toga2-commerce) Architecture
-framework: "2.0"
-repo: toga2-commerce
-project: TOGa Commerce
-client: shared
-type: architecture
-status: active
-updated: 2026-06-11
-owners: [bala]
-files:
-  - toga2-commerce/src/App.tsx
-  - toga2-commerce/src/routes.tsx
-  - toga2-commerce/src/api/axiosInstance.ts
-  - toga2-commerce/src/contexts/AuthContext.tsx
-  - toga2-commerce/src/themeConfig/ThemeContext.tsx
-  - toga2-commerce/src/stores/index.ts
-related: []
----
-
-## Summary
-
-TOGa Commerce (npm package `commerce2-react`) is the multi-tenant 2.0 storefront. React 18 +
-Vite + TypeScript + Tailwind. Its backend is api2 (2.0 REST); shared UI comes from the
-`@agilant/toga-blox` component library. Multi-tenant by hostname — dev hosts include
-`compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce`, `togacommerce`
-(see the `npm run` scripts in `package.json`).
-
-## Routing & shell
-
-- `src/routes.tsx` — `createBrowserRouter` (react-router-dom v7). `PrivateRoute` gates all
-  authed pages behind `useAuthenticationFlow`; authed pages are wrapped in `AuthLayout`.
-  Pages: Home, Filter, ItemsView (`/item-view`), BundleView, Cart, OrderDetails, Account,
-  GetSupport, Login, ResetPassword, Privacy/Terms.
-- `src/App.tsx` — provider stack: `PersistQueryClientProvider` (TanStack Query persisted to
-  `localStorage`, key `commerce`, 24h staleTime) -> `AuthProvider` -> `ThemeProvider` ->
-  `ToasterProvider` -> `RouterProvider`.
-
-## State management
-
-- **Server state:** TanStack Query, persisted to localStorage. Query defs in `src/queries/`.
-- **Client state:** Zustand stores in `src/stores/` — cart (`useCartStoreZu`), edit-order mode
-  (`useEditOrderZu`), bundle builder, user, fields, view-as impersonation, etc.
-- **Cart <-> API sync:** `src/api/` holds `syncSalesOrderFromApiToLocalStorage`,
-  `syncSalesOrderItemsFromLocalStorageCartToApi`, `syncSalesOrdersDataFromLocalStorageCartToApi`.
-  The cart lives in localStorage and syncs to api2 sales orders; "Edit Order" mode lets users
-  edit an existing sales order (App.tsx tracks a `synced` flag).
-
-## Cross-cutting
-
-- **Auth:** `src/contexts/AuthContext.tsx`, token-based, plus a "View As" user-impersonation
-  flow (`useReturnOriginalUserFromViewAsStore`).
-- **Theming:** `src/themeConfig/ThemeContext.tsx` + `themes.json`, per tenant.
-- **Dynamic fields:** `src/fieldsConfig/` and per-page `FIELDS/<CLIENT>/<LANG>/<ROLE>/*.json`
-  drive client-specific form/field sets.
-- **HTTP:** axios instance in `src/api/axiosInstance.ts`; Sentry for error reporting;
-  react-hook-form for forms.
-
-## Key decisions / gotchas
-
-- `dependsOn: ["api2"]` — runtime dependency on the api2 REST surface (not a PHP class
-  dependency). Field requests use the api2 `fields` option; deep nested field paths are
-  subject to api2's serializer behavior (see related api2 doc on FK resolution).
-
-## Related docs
-
-- 2.0/apps/api2/bug/nested-field-foreign-key-resolution.md
-- 2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md

package/knowledge/2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md

@@ -1,69 +0,0 @@
----
-title: Item-View Bundle vs Direct Fetch
-framework: "2.0"
-repo: toga2-commerce
-project: TOGa Commerce
-client: shared
-type: feature
-status: active
-updated: 2026-06-11
-owners: [bala]
-files:
-  - toga2-commerce/src/pages/ItemsView/api/ItemsApi.ts
-  - toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts
-related:
-  - 2.0/apps/api2/bug/nested-field-foreign-key-resolution.md
----
-
-## Summary
-
-The item-view page (`/item-view`) fetches a single item two different ways depending on how
-the user reached it and what access they have:
-
-- **Direct** — `GET /items/{uuid}` via `fetchItemDetails()`. Used for users with direct item
-  access. Fields come from the client/role `ITEMVIEWPAGEFIELDS.json` config.
-- **Via bundle** — `GET /bundles/{uuid}` via `fetchItemDetailsViaBundle()`, then the bundle's
-  `bundleItems` are filtered client-side to the requested item uuid. Used for **indirect-access**
-  users (they can read the item through the bundle ACL but not the item endpoint directly).
-  Triggered when the URL has `type=bundleItem` and a `bundleUuid` query param.
-
-## Key files / entry points
-
-- `src/pages/ItemsView/api/ItemsApi.ts`
-  - `fetchItemDetails()` — direct `/items/{uuid}` fetch (fields from config, optional persona where).
-  - `fetchItemDetailsViaBundle()` — `/bundles/{uuid}` fetch with `bundleItems.item.*` fields,
-    then client-side filter to the matching item (API does not support nested-uuid where clauses).
-- `src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts`
-  - Chooses the fetch by `viewTypeParam === "bundleItem" && bundleUuid`.
-  - Groups features for the Specifications section by
-    `itemCategoryFeatures[0].itemCategoryFeatureGroup?.name`. If that group object is missing,
-    the heading key becomes the string `undefined`.
-
-## How it works
-
-1. Read `uuid`, `type`, `bundleUuid` from the URL query string.
-2. If `type=bundleItem` and `bundleUuid` present → `fetchItemDetailsViaBundle`; else
-   `fetchItemDetails`.
-3. Normalize the response to `{ data: { items } }` and group `itemFeatures` by their
-   category-feature group name for display.
-
-## Client variations
-
-Multi-tenant by host (compass / compasscanada / quad / togacommerce). Field sets are
-per-client/per-language/per-role under
-`src/pages/ItemsView/viewModel/FIELDS/<CLIENT>/<LANG>/<ROLE>/ITEMVIEWPAGEFIELDS.json`.
-
-## Gotchas / known issues
-
-- The two fetch paths request the same leaf fields but at different nesting depths
-  (`bundle -> bundleItems -> item -> ...` adds two levels). This exposed an api2 serializer
-  bug where the `itemCategoryFeatureGroup` foreign key was dropped only on the bundle path,
-  making Specifications headings render as `undefined`. Root cause and fix are documented in
-  the api2 feature doc below — the frontend grouping logic itself is correct and identical
-  on both paths.
-- `fetchItemDetailsViaBundle` exists specifically for indirect-access users, so you cannot
-  simply switch it to `/items/{uuid}` — those users would hit an ACL denial.
-
-## Related docs
-
-- 2.0/apps/api2/bug/nested-field-foreign-key-resolution.md