toga-ai 1.0.106 → 1.0.108

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

@@ -4,3 +4,4 @@
 |-----|---------|-------|
 | [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/ |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |
+| [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, _underscore/Route.php |

package/knowledge/2.0/apps/api2/workflows/environment-configuration-and-provisioning.md

@@ -0,0 +1,92 @@
+---
+title: New Environment Configuration & Provisioning (api2)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: workflow
+status: active
+updated: 2026-06-16
+owners: ["jcardinal"]
+files:
+  - api2/Config/<environment>.ini
+  - api2/Controller/Index.php
+  - dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql
+  - _underscore/Route.php
+related: []
+---
+
+## Summary
+What it takes for a 2.0 API environment (e.g. `qc-security`, `qa-task`, `stage`) to actually
+serve requests. Three independent things must all be correct, or `/v2/...` calls fail — often
+with a **misleading** error. This documents the config conventions, the `Core.DatabaseHosts`
+data the framework needs, and the database seeding step, plus the diagnostic gotcha that masks
+the real cause.
+
+## Steps (to stand up a new environment)
+
+1. **Create `api2/Config/<environment>.ini`.** Copy an existing all-in-one env file
+   (e.g. `qc-security.ini`) and change **only**:
+   - `[database]` and `[database1]` → `hostname` = the env's DB cluster endpoint.
+   - `[api]` → `_` and `worker` = the env's API/worker base URLs.
+   Leave everything else (cloud keys, fedex, netsuite, ups, calcom, etc.) as-is. Match the
+   file's existing **CRLF** line endings — a whole-file LF flip buries the real diff.
+
+2. **Use the correct host naming convention** (load-bearing — see Gotchas):
+   - **DB host:** `<specific>.<family>.database.togahub.com` — e.g. `security.qc...`,
+     `task.qa...`. The specific name comes **first**, the family (`qa`/`qc`) second.
+     `stage`/`demo` are single-label: `stage.database.togahub.com`.
+   - **API/worker base:** `https://api.<dbprefix>.togahub.com/v2` and
+     `https://worker.<dbprefix>.togahub.com`, where `<dbprefix>` is the DB host minus
+     `.database` (e.g. DB `security.qc.database...` → `api.security.qc.togahub.com`).
+
+3. **Register `Core.DatabaseHosts` rows** for the environment (via a `dbchanges2/Core`
+   migration). Non-prod environments are **all-in-one**: a single cluster holds `Core` +
+   every `Client_`/`Logs_`/`Archive_` DB. So insert **one row per database**, `regionId = NULL`,
+   with `hostCluster = hostWriter = hostReader` = the single endpoint. Resolve `environmentId`
+   by `Environments.slug` and `databaseId` from the Core's own `Databases` table so the migration
+   is portable across every Core; guard with `NOT EXISTS` for idempotency. (Production differs:
+   per-family clusters and per-region reader rows.)
+
+4. **Seed the cluster.** A brand-new RDS cluster has only system schemas. `Core` and the client
+   DBs must be provisioned and the `dbchanges2` migrations applied before the app can connect.
+   Until then, every request throws on the first Core query.
+
+## Systems involved
+- **api2** — `Config/<env>.ini` (DB + API hosts); `Controller/Index.php::api()` registers `Core`
+  from `[database]` then dispatches by hostname.
+- **_underscore** — boot/routing; reads `Core.Environments` + `Core.DatabaseHosts` to resolve
+  region-aware connections.
+- **dbchanges2/Core** — the migration that populates `Core.DatabaseHosts` per environment.
+- **Core DB** — `Environments`, `Databases`, `DatabaseHosts`, `Regions` drive resolution.
+
+## Edge cases & escalation — diagnosing a broken environment
+
+**Symptom:** a fatal like
+`Uncaught Exception: Failed to determine how to render view for route '/v2/auth/api' ... Route.php:525`.
+
+**This message is misleading — it is almost never about views.** `_Controller_Index::api()`
+threw an `Exception` (e.g. the `Core` DB connection/query failed), and `_underscore/Route.php`'s
+dispatch **catches `Exception`, silently rolls back, leaves the controller response unset**, then
+falls through to its view-render path and throws the generic "Failed to determine how to render
+view" error. The real exception is swallowed. When the same codebase works in `production` but
+fails in a new environment, suspect **environment config / Core DB**, not the view layer.
+
+Diagnostic order:
+1. Compare the env's `[database] hostname` against the `<specific>.<family>.database.togahub.com`
+   convention — a reversed host (e.g. `qc.security...` instead of `security.qc...`) won't resolve.
+   Verify with `nslookup` / PHP `mysqli_connect`.
+2. Connect to the resolved host and `SHOW DATABASES` — confirm `Core` actually exists (a fresh
+   cluster has only `information_schema/mysql/performance_schema/sys` → not seeded yet).
+3. Confirm `Core.DatabaseHosts` has rows for this `environmentId` (Core Logs DB id is `11`).
+
+## Change history
+- 2026-06-16 — Documented after fixing `qc-security`: `[database] hostname` was reversed
+  (`qc.security...`), which threw on Core connect and surfaced as the Route.php:525 view fatal.
+  Added the `2026-06-16a` Core migration registering `DatabaseHosts` for the stage/demo/qa-*/qc-*
+  all-in-one environments, and created the matching `Config/*.ini` files. (jcardinal)
+
+## Related docs
+- `2.0/apps/api2/architecture.md` — host dispatch, transaction/logging boundary.
+- `2.0/apps/_underscore/architecture.md` — environment→host table, DB resolution, boot sequence.
+- `2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md` — deploy pipeline.

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

@@ -7,4 +7,5 @@
 | [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, 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

@@ -0,0 +1,140 @@
+---
+title: NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: ["dfranks"]
+files:
+  - 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
+  - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
+related:
+  - ../architecture.md
+---
+
+## Summary
+
+Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls
+(opportunities first; sales/items/etc. to follow). Replaces the legacy
+`worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php` *pull* cron with a
+**NetSuite-side push**: a SuiteScript enqueues each create/edit/delete into a NetSuite custom
+record ("API Message Queue"), a scheduled SuiteScript drains it to
+`webhook.togahub.com/netsuite`, and worker2 routes it to a per-recordType handler that upserts
+into the `Forecast` DB. The legacy NetSuite→ClickUp opportunity-task creation is preserved as a
+second, independently-gated concern in the same handler.
+
+## Key files / entry points
+
+**NetSuite side** (SuiteScript 2.1, kept in the `test` repo at
+`test/@dave/NetSuite/api-message-queue/` — upload all four `.js` to one File Cabinet folder):
+- `lib_amq_queue.js` — shared module: record-type/field ids, `transmit()`, `findSendableIds()`.
+- `ue_api_msg_queue_enqueue.js` — User Event on the synced source records (Opportunity, …):
+  writes one queue row per create/edit/delete.
+- `ue_amq_drain.js` — User Event on the **API Message Queue** record: async trigger — kicks the
+  scheduled drainer via `N/task` (no inline HTTP, so it never blocks the source save).
+- `ss_amq_drain.js` — Scheduled Script: catch-up drainer (retries + anything the UE missed).
+- The custom record itself: **"API Message Queue"**, internal id **1185**.
+
+**worker2 side:**
+- `Worker/Netsuite.php` — `_Worker_Netsuite::Webhook($payload,$headers)` router (TRUE-79184):
+  derives `Netsuite/<RecordType>/<verb>` and `_Worker::runTask()`s it.
+- `Worker/Netsuite/Opportunity.php` — `_Worker_Netsuite_Opportunity::{POST,PUT,DELETE}`:
+  Forecast DB upsert + ClickUp-task parity.
+
+## How it works
+
+1. **Enqueue (NetSuite):** on create/edit/delete of a synced record, `ue_api_msg_queue_enqueue`
+   writes a queue row — `status='Created'`, `method=POST`, `endpoint`, `payload`
+   (`{recordType, internalId, eventType, action}`), `headers`. It maps `record.Type`
+   (lowercase) → the camelCase `recordType` worker2 expects (explicit map; e.g.
+   `salesorder`→`salesOrder`), and `context.type` → CRUD verb (`create`→POST, `edit`/`xedit`→PUT,
+   `delete`→DELETE).
+2. **Trigger + drain (NetSuite):** the queue record's `ue_amq_drain` UE fires the scheduled
+   `ss_amq_drain` via `N/task` (async); `ss_amq_drain` also runs on its own schedule.
+   `transmit()` claims a row (`Created`→`Sending`) before the HTTP call, POSTs to the row's
+   endpoint, then **deletes on 2xx** / sets `Retry` (+exponential backoff) / `Failed`
+   (terminal — never auto-deleted; Jeff's data-loss rule).
+3. **Ingest (prod):** `webhook.togahub.com/netsuite` → WebhookIngestion **Python Lambda** →
+   INSERT `Core.WorkerJobs` + SQS → returns 200 immediately. Fully async; outcome lives in
+   `WorkerJobs.isSuccess`/`failureReason`.
+4. **Route (worker2):** the PHP worker runs `_Worker_Netsuite::Webhook`, which
+   `_Worker::runTask('Netsuite/Opportunity/<verb>', {internalId})`.
+5. **Handle (worker2):** `_Worker_Netsuite_Opportunity` fetches the record from NetSuite by id
+   and upserts it into `Forecast.Opportunities` (+ `OpportunityItems`), and — only when a
+   Presales Lead is set — creates the ClickUp opportunity task.
+
+## Data model
+
+Writes `Forecast.Opportunities` (header) + `Forecast.OpportunityItems` (children), faithful to
+the legacy cron's OPPORTUNITIES section:
+- Upsert header by `netsuiteOpportunityInternalId`; items insert/update/delete by `line`; no
+  header delete; children deleted before the header on DELETE.
+- Lookups: `customerId`/`salesRepEmployeeId` → null on miss; `forecastCategoryId`/`salesStageId`/
+  `percentToCloseStatusId` → **create-on-miss** (+name update); unknown line item → **throws**
+  (Retries until the item import runs).
+- `netsuiteStatus` (NOT-NULL enum `'In Progress'|'Closed - Won'|'Closed - Lost'`) comes from
+  **SuiteQL `transaction.status`** letter mapped `A→In Progress, C→Closed - Won, D→Closed - Lost`
+  (same as `App_Api_Netsuite_Rest::listOpportunities`) — **not** `entityStatus` (that's the
+  sales-stage percent → `percentToCloseStatusId`). The REST record GET doesn't return that
+  letter, so the handler runs a one-row SuiteQL query for it.
+- Writes use raw `_Query` against `_underscore::DB_FORECAST` and **must**
+  `_Database::transactionCommit(DB_FORECAST)` (lazy-transaction gotcha).
+
+## Client variations
+
+None — platform-wide Forecast sync.
+
+## Gotchas / known issues
+
+- **worker2 routes EVERY request to `_Controller_Index::worker()`** — `worker2/_.php` sets
+  `DEFAULT_CONTROLLER_METHOD = ['_Controller_Index','worker']`, which short-circuits `_Route`'s
+  URI matching. There is no per-URL routing, and `.htaccess` denies direct `.php` files, so you
+  can't add a real `/netsuite` route or a standalone script — everything enters through `worker()`.
+- **`_Worker::runTask()` debug mode swallows the sub-request result.** In debug it self-POSTs
+  `_Config::api('worker')` and does **not** check the response (`_underscore/Worker.php:12`). So a
+  failing sub-action (e.g. `Netsuite/Opportunity/PUT` throwing) is invisible: the outer webhook
+  still returns 200, the queue row clears, and the DB write never happened. In prod the same
+  failure surfaces in `WorkerJobs.isSuccess=0`/`failureReason`. To debug locally, POST the
+  `{action,parameters}` envelope straight to the worker and read the response, or check logs —
+  don't trust the 200.
+- **Local dev needs `[api] worker` in the worker2 config** — debug-mode `runTask` requires
+  `_Config::api('worker')`. Set `worker = "http://worker2/"` (the local Apache vhost) plus the
+  standard `[api] endpoint`/`uuid_*`. Without `[api]` you get
+  `Configuration group [api] has not been defined`.
+- **No WebhookIngestion Lambda locally.** Dev points the enqueuer at an ngrok tunnel to local
+  worker2 via the `DEV_OVERRIDE` block, which also wraps the body in worker2's legacy
+  `{action,parameters}` envelope (since there's no Lambda to convert `/netsuite` → an action).
+  Set `DEV_OVERRIDE.enabled=false` for prod.
+- **NetSuite doubled-prefix ids.** The queue record and its fields were created with the full
+  custom prefix typed into the ID box, so the real ids are doubled:
+  type `customrecordcustomrecord_api_msg_queue`, fields `custrecordcustrecord_amq_*`. The
+  single-prefix forms do not exist — use the doubled ids everywhere (SuiteScript, SuiteQL, REST).
+- **REST opportunity line `itemType` is an object** (`{id,refName}`), not a string — casting it to
+  string throws `Object of class stdClass could not be converted to string`. Normalize before
+  matching.
+- **Drain dedup** uses a `Sending` claim status: `transmit()` flips `Created`→`Sending` before the
+  HTTP call so a concurrent pass skips it; the immediate UE trigger only fires for `Created`/
+  `Pending`, so the drainer's own `Sending`/`Retry`/`Failed` writes don't re-trigger it (a
+  `skip (status not triggerable)` debug line on those is expected). `findSendableIds` must list
+  every sendable status (`Created`,`Pending`,`Retry`,`Sending`) — omitting `Created` silently
+  matches nothing (`candidates:0`).
+
+## Change history
+- 2026-06-16 — Built the queue enqueuer/drainer SuiteScripts, the worker2 `/netsuite` router, and
+  the `_Worker_Netsuite_Opportunity` Forecast importer (header + items + status), with ClickUp
+  parity. Verified opportunity 5483750 imports end-to-end in dev via ngrok. (dfranks)
+
+## Related docs
+- `2.0/apps/worker2/architecture.md` — the WorkerJobs/SQS/Lambda model and always-HTTP-200 worker.
+- `2.0/apps/_underscore/architecture.md` — the `_Database::register()` lazy-transaction gotcha.

package/knowledge/INDEX.md

@@ -15,8 +15,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 7 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 6 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)
+- **worker2** (Worker) — 7 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)
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/package.json

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