toga-ai 1.0.545 → 1.0.547

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

@@ -13,7 +13,7 @@
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Running 2.0 code from a bare CLI script (bootstrap + transactions)](features/cli-script-bootstrap.md) | A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real 2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the | _underscore/Database.php, _underscore/Environment.php, api2/Initialize.php |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
-| [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, api2/Component/Api/Netsuite/Netsuite.php, _underscore/Component/Api/Paypal/Paypal.php |
+| [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Api/Oneuptime/Oneuptime.php, api2/Component/Api/Netsuite/Netsuite.php, _underscore/Component/Api/Paypal/Paypal.php |
 | [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('<property>')` reads a value out of the active `Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.** | _underscore/Config.php, _underscore/Component/Api/Paypal/Paypal.php |
 | [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the | _underscore/Database.php, _underscore/Query.php, api2/Component/Api/V2/V2.php, api2/Component/Api/CrossClient/CrossClient.php |
 | [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. | _underscore/Email.php, _underscore/String.php, worker2/Worker/Infrastructure/Email/Send.php |

package/knowledge/2.0/apps/_underscore/features/component-model-namespace-registration.md

@@ -6,14 +6,15 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: [dfranks, mhammontree]
+updated: 2026-08-10
+owners: [dfranks, mhammontree, jcardinal]
 files:
   - _underscore/Loader.php
   - worker2/_.php
   - api2/_.php
   - worker2/Component/Forecast/Db/Db.php
   - worker2/Component/Forecast/SaleImport/SaleImport.php
+  - worker2/Component/Api/Oneuptime/Oneuptime.php
   - api2/Component/Api/Netsuite/Netsuite.php
   - _underscore/Component/Api/Paypal/Paypal.php
 related:
@@ -113,8 +114,19 @@ project-local `_Component_*`/`_Model_*` must still declare the project namespace
   runtime-only failure.
 - A global-namespace `_Component_*`/`_Model_*` fails **loudly** (the throw above). An
   unqualified `catch (Exception $e)` fails **silently** — the more insidious of the two.
+- **The namespace rule is APP-repo-only.** `_Component_*` classes that live in the
+  `_underscore` **core** repo (e.g. `_Component_Api_Togaiq`, `_Component_Api_Clickup`) are
+  declared in the **global** namespace and do **not** `extend \_Component`. Do not copy a core
+  `_Component_*` as the template for a new worker2/api2 one — copy a *project-local* precedent
+  (e.g. `worker2/Component/Forecast/Db/Db.php`, `api2/Component/Api/Netsuite/Netsuite.php`).
 
 ## Change history
+- 2026-08-10 — Confirmed again in worker2 building `_Component_Api_Oneuptime`
+  (`Component/Api/Oneuptime/Oneuptime.php`): the component threw the Loader
+  "namespace … has not been defined" fatal until `namespace worker;` + `extends \_Component`
+  + `\`-prefixed framework refs (`\_ApiRequest`, `\_Config`, `\_Query`, `\Exception`, …) were
+  applied. Added the app-repo-only clarification — core-repo `_Component_*` (Togaiq, Clickup)
+  are global-namespace and don't extend `\_Component`, so they're the wrong template. (jcardinal)
 - 2026-08-04 — TRUE-80282: documented the **file-layout** half of `_Component_*` loading, which
   precedes the namespace rule — `_Loader::autoloader()` (`Loader.php:60-67`) pops the trailing
   `_`-segment and appends it as **both a directory and the filename**, so

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

@@ -30,6 +30,7 @@
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [NYCHH Asset-Tag Backfill (worker2)](features/nychh-asset-tag-backfill.md) | Keeps NYC Health & Hospitals (`Client_Nychh`) unit asset tags and MAC addresses synced from NetSuite. | worker2/Worker/Client/Nychh.php, worker2/Worker/Client/Nychh/AssetTagBackfill.php, worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php, worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php |
+| [OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)](features/oneuptime-incident-clickup-sync.md) | An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for **currently-open** incidents and ensures a ClickUp task exists for eac | worker2/Component/Api/Oneuptime/Oneuptime.php, worker2/Worker/Monitor/Oneuptime.php, worker2/Config/production.ini, dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql, dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql |
 | [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php, worker2/Worker/Monitor/Operations.php |
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |

package/knowledge/2.0/apps/worker2/features/oneuptime-incident-clickup-sync.md

@@ -0,0 +1,122 @@
+---
+title: OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-08-10
+owners: ["jcardinal"]
+files:
+  - worker2/Component/Api/Oneuptime/Oneuptime.php
+  - worker2/Worker/Monitor/Oneuptime.php
+  - worker2/Config/production.ini
+  - dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql
+  - dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql
+related:
+  - ./oneuptime-worker2-monitoring.md
+  - ./error-escalation-cron.md
+  - ./creating-worker-actions.md
+  - ./team-sprint-management.md
+  - ../../_underscore/features/component-model-namespace-registration.md
+---
+
+## Summary
+
+An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for
+**currently-open** incidents and ensures a ClickUp task exists for each, so operational
+incidents become actionable tickets automatically without duplicates. This is the **first
+*reader* of the OneUptime API** in worker2 — until now OneUptime was **push-only** (workers
+POST metrics/heartbeats to Incoming-Request monitors; see
+[OneUptime push-metric monitors](./oneuptime-worker2-monitoring.md)). The model was "dumb
+reporter, smart monitor"; this feature adds the reader half.
+
+## Key files / entry points
+
+- `worker2/Component/Api/Oneuptime/Oneuptime.php` — `_Component_Api_Oneuptime`, the OneUptime
+  API read client, modeled on `_Component_Api_Togaiq`. Reads a new `[oneuptime]` config group
+  (endpoint, api_key, project_id) via `_Config`; `isConfigured()` guard; `send()` wraps
+  `_ApiRequest` with `APIKey` + `ProjectID` headers; `getActiveIncidents()` returns normalized
+  open incidents (filters out resolved **in PHP**).
+- `worker2/Worker/Monitor/Oneuptime.php` — `_Worker_Monitor_Oneuptime::SyncIncidents(): string`,
+  the cron action. Returns a structured summary string on every path
+  (`incidentsPolled` / `created` / `skipped` / `failed`).
+
+## How it works
+
+Canonical worker2 scheduled-3rd-party-API-job shape (see
+[Creating Worker Actions](./creating-worker-actions.md)): a `Core.CronJobs` row (cron expr,
+Central tz) → CronScheduler Lambda enqueues → `Controller/Index::worker()` dispatches the
+`action` `Monitor/Oneuptime/SyncIncidents` to `_Worker_Monitor_Oneuptime::SyncIncidents`.
+HTTP goes through `_ApiRequest`; secrets come from `_Config::oneuptime()` reading
+`Config/<env>.ini`; ClickUp uses `_Component_Api_Clickup::send()`.
+
+### Open-only
+
+Only currently-open incidents are synced. The list route returns all incidents and resolved
+ones are filtered out in PHP inside `getActiveIncidents()`.
+
+### Claim-first (unique-key) dedup
+
+For each open incident, INSERT a ledger row into `OneUptimeIncidentTasks` keyed on the
+OneUptime incident id **before** calling ClickUp. A unique-key violation means a task already
+exists → skip. On success, create the ClickUp task via
+`_Component_Api_Clickup::send('POST','/list/{listId}/task', …)` and attach the returned id to
+the ledger row; on failure, **delete the claim and re-throw**. This is the established
+worker2 way to prevent duplicate ClickUp tasks under overlapping cron runs — pattern copied
+from `_Worker_Infrastructure_Errors::createClickupTask`. `INSERT … WHERE NOT EXISTS` is
+**insufficient** under REPEATABLE READ; the UNIQUE key is the concurrency arbiter.
+
+### Target list = current sprint list
+
+The ClickUp task lands in the **current sprint** list, resolved by `GET /folder/{id}` and
+matching the list whose `start_date`/`due_date` window contains now (mirrors
+`_Worker_Team_Sprint::SprintLock` — see [Team Sprint Management](./team-sprint-management.md)
+and the sprint-promotion note in [Error Escalation Cron](./error-escalation-cron.md)). Folder
+id is read from `[clickup] sprint_folder_id` with a constant fallback (`90020432579`).
+
+## Data model
+
+`OneUptimeIncidentTasks` (CREATE on the **Team** cluster — chosen over Logs;
+`dbchanges2/Team/2026-08-10a`): `id`, `uuid char(36)`, `dtCreated`,
+`oneuptimeIncidentId varchar(64)`, `clickupIdentifier varchar(64) NULL`. The **UNIQUE KEY on
+`oneuptimeIncidentId`** is the dedup contract, same rationale as `IssueClickupTasks`.
+
+## Provisioning / deploy
+
+- `dbchanges2/Core/2026-08-10b` inserts the `Core.CronJobs` row: action
+  `Monitor/Oneuptime/SyncIncidents`, schedule `*/15 * * * *`, `maxExecutionTime` 120, seeded
+  **`isActive = 0`**. Flip to 1 only after (a) the ledger table exists, (b) the `[oneuptime]`
+  config group is populated, and (c) the incident-list route is confirmed.
+- `[oneuptime]` config group (endpoint, api_key, project_id) added to
+  `worker2/Config/production.ini` with placeholders — **values are filled by the developer,
+  not committed**. Credentials live only in the ini files.
+
+## Configuration / credentials
+
+- `[oneuptime]` — `endpoint`, `api_key`, `project_id`. The hosted OneUptime SaaS base is
+  `https://oneuptime.com` (confirmed from `worker/.ebextensions/045_oneuptime_agent.config`);
+  the REST API path is appended to that base.
+- `[clickup]` — `sprint_folder_id` (fallback constant `90020432579`) plus the ClickUp token.
+  ClickUp/OneUptime token **values** live in `worker2/Config/<env>.ini` — location only,
+  never the value.
+
+## Gotchas / known issues
+
+- **Incident-list route/fields are PLACEHOLDER** (`/api/incident/get-list`) pending
+  confirmation against the live OneUptime instance. Do not enable the cron (`isActive = 1`)
+  until the route and returned fields are verified.
+- **OneUptime cannot filter open-only server-side here** — resolution filtering happens in
+  PHP, so the returned field set must actually carry the resolved/open state.
+- Ship the worker2 code deploy and both dbchanges2 migrations **together**; the cron row is
+  inert until the action is deployed and the ledger table exists.
+
+## Change history
+- 2026-08-10 — Built: first OneUptime API *reader* (`_Component_Api_Oneuptime`) + the
+  `Monitor/Oneuptime/SyncIncidents` cron that claim-first-dedups an open incident into a
+  ClickUp task in the current sprint list; new `OneUptimeIncidentTasks` ledger (Team cluster,
+  UNIQUE on incident id) and a seeded-inactive `*/15 * * * *` cron row. Incident-list route
+  left PLACEHOLDER pending confirmation. (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/worker2/features/oneuptime-worker2-monitoring.md

@@ -15,6 +15,7 @@ files:
   - _underscore/Cloud.php
   - worker2/Worker/Monitor/Operations.php
 related:
+  - ./oneuptime-incident-clickup-sync.md
   - ./monitoring-framework.md
   - ./all-client-email-queue-monitor.md
   - ../../_underscore/features/cloud-s3-helpers.md
@@ -211,6 +212,10 @@ check for another client.
   monitors must pass the region (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
 ## Change history
+- 2026-08-10 — Noted that worker2 gained its **first OneUptime API *reader*** (this doc covers
+  the push-only half; OneUptime was previously push-only, "dumb reporter, smart monitor"). The
+  reader polls open incidents and files ClickUp tasks — see
+  [OneUptime Incident → ClickUp Task Sync](./oneuptime-incident-clickup-sync.md). (jcardinal)
 - 2026-08-10 — Documented OneUptime incident/alert `{{requestBody.*}}` templating (missing
   paths → empty string; `Not Recieved In Minutes` heartbeat spelling), discovered while
   wiring the second all-client `_Worker_Monitor_Operations` monitor —

package/knowledge/INDEX.md

@@ -18,8 +18,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 48 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 43 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 49 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 44 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 22 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 5 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

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