toga-ai 1.0.296 → 1.0.297

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

@@ -21,3 +21,4 @@
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |
+| [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. | _underscore/Environment.php, _underscore/Config.php, _underscore/Database.php, _underscore/Route.php, api2/Component/Api/V2/V2.php, api2/index.php, api2/.htaccess |

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
-owners: ["dfranks", "jcardinal"]
+updated: 2026-07-09
+owners: ["dfranks", "jcardinal", "mhammontree"]
 files:
   - _underscore/Database.php
   - _underscore/ApiRequest.php
@@ -93,6 +93,7 @@ registration is region-aware in `api2/Controller/Index.php`; the alias const is
 
 ## Change history
 
+- 2026-07-09 — Linked the new [Running a 2.0 app locally](../workflows/running-a-2.0-app-locally.md) runbook, which frames these three connections as one requirement of a full local browser run. (mhammontree)
 - 2026-07-07 — Noted the new shared **Cache** cluster (`Databases` id 145, alias `DB_CACHE`,
   region-aware) added for the api2 cross-client retrieval engine. (jcardinal)
 - 2026-06-18 — Documented after the `Logs_Growrk`/`Logs_Aig` local 500s while testing the
@@ -101,4 +102,5 @@ registration is region-aware in `api2/Controller/Index.php`; the alias const is
 ## Related docs
 
 - [_underscore architecture](../architecture.md)
+- [Running a 2.0 app locally (browser end-to-end)](../workflows/running-a-2.0-app-locally.md) — the full local-stack runbook these three connections are one requirement of.
 - [NetSuite → TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md) — the work that surfaced this.

package/knowledge/2.0/apps/_underscore/workflows/running-a-2.0-app-locally.md

@@ -0,0 +1,124 @@
+---
+title: Running a 2.0 App Locally (browser, end-to-end via api2)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: workflow
+status: active
+updated: 2026-07-09
+owners: ["mhammontree"]
+files:
+  - _underscore/Environment.php
+  - _underscore/Config.php
+  - _underscore/Database.php
+  - _underscore/Route.php
+  - api2/Component/Api/V2/V2.php
+  - api2/index.php
+  - api2/.htaccess
+related:
+  - ../features/per-client-database-connections.md
+  - ../../dbchanges2/workflows/client-onboarding.md
+  - ../../dbchanges2/architecture.md
+---
+
+## Summary
+
+The full dependency chain required to run a 2.0 client app **through the browser**,
+end-to-end, against a **local `api2`** (e.g. pointing the `toga2-view` frontend at a laptop
+`api2` instead of beta/prod). This is separate from CLI/script backend testing — it exercises
+the web SAPI, the Apache-supplied environment, Core-driven client-DB registration, and the
+`/v2/auth/login` browser auth gate, none of which the CLI path touches. It cost hours to
+reverse-engineer; the notes below are platform-general (any 2.0 client app), with Rate used
+only as the running example.
+
+**Bottom line:** most local failures here are a **provisioning gap in the local stack**
+(missing/stale DB, unregistered origin, unseeded Core), *not* an app bug. The confusing
+`Route.php:525` "failed to determine how to render view" and stale-Core "missing model file"
+fatals below both mean "the local stack isn't fully stood up."
+
+> Cost/benefit note from the originating session: because standing the full local backend up
+> is this involved, the team's chosen shortcut for front-end work was to **deploy api2 to beta
+> and point the local frontend at beta** rather than rebuild the entire local backend stack.
+
+## Steps / requirements
+
+### 1. ENVIRONMENT comes from Apache for the web app (not the CLI)
+
+- `_Environment::initialize()` reads `getenv('ENVIRONMENT')` (`_underscore/Environment.php:11`)
+  and **throws if unset**. `_Config` then loads `Config/<ENVIRONMENT>.ini` (`Config.php:38`).
+- The **web app** gets `ENVIRONMENT` from **Apache** — a `SetEnv ENVIRONMENT <name>` in the
+  api2 vhost — *not* from your shell/CLI environment. Dev convention:
+  `ENVIRONMENT=dev-<name>-laptop` → loads `Config/dev-<name>-laptop.ini`.
+- To see what the **web** app actually resolves (the frontend URL/console won't show it — api2
+  is a separate host), temporarily add to the top of `api2/index.php`:
+  `if (isset($_GET['__env'])) die(getenv('ENVIRONMENT'));` and hit `http://api2/?__env=1`.
+  Remove it afterward.
+
+### 2. api2 collapses the environment name to a slug
+
+- `V2.php:146`: `$this->environment = (substr($name,0,4)=='dev-') ? 'dev' : $name`. So **any**
+  `dev-*` INI resolves to the slug **`dev`** for downstream lookups (notably Core DB host
+  selection, below).
+
+### 3. Client DB connections are Core-driven, not from the INI
+
+- `_Database::registerClientDatabases($environment, $clientId)` (`_underscore/Database.php:56`)
+  SELECTs from **Core**, joining `Clients → Databases → DatabaseHosts → Environments(slug=<env>)`
+  to resolve the client's **client, log, AND archive** databases (all three INNER-JOINed — a
+  missing row for any one drops the whole registration).
+- For local, Core must have an `Environments.slug='dev'` row plus `DatabaseHosts` rows pointing
+  all three DBs at `localhost`. A prod Core backup **already carries a `dev`→localhost row by
+  design** — do not assume it's missing.
+- There are **two** log connections: `DB_LOGS` (base framework `Logs`) and `DB_CLIENT_LOGS`
+  (per-tenant `Logs_<tenant>`). See
+  [per-client database connections](../features/per-client-database-connections.md) for the
+  three-alias mechanism and the logs-DB write trap.
+
+### 4. Browser login `POST /v2/auth/login` — requirements in the order code checks them
+
+Checked in `V2.php` (~lines 485–800):
+
+1. **POST with an `Origin` header.** A browser address-bar **GET** has neither → silent
+   fallthrough (no auth, no useful error). Requests must come from the frontend (fetch/XHR),
+   not a typed URL.
+2. **`Core.Domains` row for the port-stripped origin.** `V2.php:98-103` strips the port, so
+   `http://rate.togaview:5173` matches a `Core.Domains` row for `http://rate.togaview`. That
+   row's `clientId`/`appId` must resolve to the local client/app.
+3. **Active login user** must exist in `Client_<tenant>.Users`.
+4. **All four databases must exist WITH SCHEMAS:** `Client_<tenant>`, `Logs_<tenant>`,
+   `Archive_<tenant>`, and base `Logs`. An **empty** database is not enough — every request
+   writes a transaction log via `$log->save()` at `execute()` finalization (`V2.php:2138`) into
+   `Logs_<tenant>.Api` / `Logs.Api`. Structure-only imports of the log/archive DBs are fine.
+5. **`Core.Apis` must be seeded** — API auth uses `Apis.uuid`/`Apis.secret`. `Apis` is
+   deliberately **excluded from blanks/backups**, so a freshly restored Core often has it empty.
+
+## Gotchas / known issues
+
+- **The silent `Route.php:525` error** — `"Failed to determine how to render view for route
+  '/v2/...'"` (thrown at `_underscore/Route.php:525`) means the API handler returned **no**
+  response, so `_Route` fell through to view rendering. It is thrown during bootstrap
+  **outside** api2's JSON error handler, so the browser shows raw HTML and often **nothing** is
+  written to the PHP error log. The real cause is almost always a **local DB/registration gap**
+  (missing DB or schema, unresolved client-DB registration, or the auth gate being skipped per
+  step 4.1) — treat it as "the local stack isn't fully provisioned," not a request/app defect.
+
+- **A STALE local Core silently 500s every api2 request.** api2's V2 loops **every**
+  `Core.Records` model at request time (`$thisModelName::TABLE`, `V2.php:3442-3446`). If local
+  Core is missing recent migrations it still references removed models and **fatals on a missing
+  model file** — a confusing error that looks unrelated to the DB and breaks *all* requests.
+  Concrete example: `dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql` is **non-idempotent**
+  (fixed record ids 317–322, RecordFields 2171–2200 — cannot be re-run) and its Section 9
+  **DELETES** Core `Records` row 41 (`ItemFulfillmentPackages`, model
+  `\_Model_Client_ItemFulfillmentPackage`), consolidating it into
+  `ItemFulfillments_TrackingNumbers` (record 317). A local Core missing this migration still has
+  record 41, so V2 fatals on the removed `_Model_Client_ItemFulfillmentPackage` file.
+  **Fix:** bring local Core current — apply the missing Core migrations in date order, or refresh
+  Core wholesale. Do not re-run a single non-idempotent migration in isolation.
+
+## Change history
+
+- 2026-07-09 — Documented the full local browser-run dependency chain (Apache `ENVIRONMENT`,
+  `dev-*`→`dev` slug collapse, Core-driven client-DB registration, `/v2/auth/login` browser gate,
+  the `Route.php:525` silent-fallthrough gotcha, and the stale-Core "missing model file" fatal),
+  discovered while trying to run `toga2-view` against a local `api2`. (mhammontree)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 26 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 27 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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