toga-ai 1.0.626 → 1.0.627

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

@@ -35,7 +35,7 @@
 | [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, dbchanges2/Team/2026-08-12a - OneUptime Incident Tasks Closed Marker.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, worker2/Worker/Monitor/Aig.php, worker2/Worker/Monitor/Prudential.php, worker2/Worker/Monitor/Nycdoe.php, worker2/Config/production.ini, worker2/Config/beta.ini, worker2/Config/sandbox-dev.ini |
+| [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, worker2/Worker/Monitor/Aig.php, worker2/Worker/Monitor/Prudential.php, worker2/Worker/Monitor/Nycdoe.php, worker2/Worker/Monitor/Staples.php, worker2/Config/production.ini, worker2/Config/beta.ini, worker2/Config/sandbox-dev.ini |
 | [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 |
 | [Service Request → Sales Order → Purchase Order generation (Sync/ServiceRequest)](features/service-request-sales-order-generation.md) | `_Worker_Sync_ServiceRequest` turns a **Service Request into a Sales Order, and then into one Purchase Order per vendor**, for **any** tenant. | worker2/Worker/Sync/ServiceRequest.php, _underscore/Model/Elite/ServiceRequest.php, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.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-worker2-monitoring.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-17
-owners: ["jcardinal", "mhammontree"]
+updated: 2026-08-20
+owners: ["jcardinal", "mhammontree", "bala"]
 files:
   - worker2/Worker/Monitor/Compass.php
   - worker2/Worker/Client/Compass.php
@@ -17,6 +17,7 @@ files:
   - worker2/Worker/Monitor/Aig.php
   - worker2/Worker/Monitor/Prudential.php
   - worker2/Worker/Monitor/Nycdoe.php
+  - worker2/Worker/Monitor/Staples.php
   - worker2/Config/production.ini
   - worker2/Config/beta.ini
   - worker2/Config/sandbox-dev.ini
@@ -26,6 +27,7 @@ related:
   - ./all-client-email-queue-monitor.md
   - ../../_underscore/features/cloud-s3-helpers.md
   - ../../../1.0/apps/worker/features/oneuptime-worker-uptime-monitoring.md
+  - ../../../clients/staples/features/oneuptime-sftp-folder-monitors.md
 ---
 
 ## Summary
@@ -255,6 +257,38 @@ relies on it) — no new Entra consent.
   worker EB tier. The `client_secret` is a credential — it lives in the ini config group,
   never in a doc.
 
+## SFTP monitoring (phpseclib3)
+
+An SFTP monitor logs into an SFTP with **phpseclib3**, `rawlist`s a folder, counts files
+older than an age cutoff, and pushes a decided alarm token — the same reporter model as the
+S3/DB monitors. A login/list failure pushes `status:"error"`, so the monitor doubles as an
+SFTP connectivity check. First instance:
+[Staples SFTP folder monitors](../../../clients/staples/features/oneuptime-sftp-folder-monitors.md).
+
+Two runtime facts about the installed phpseclib3 (v3.0.49) that bite silently — verified at
+runtime against the live SFTP:
+
+- **`SFTP::rawlist($dir)` (non-recursive) returns each entry as an associative ARRAY**, not
+  a stdClass object — keys `'type'`, `'mtime'`, `'filename'`, `'size'`, … Object access
+  (`$entry->mtime`) silently fails. Use array access: `$entry['mtime']`, `$entry['type']`.
+- **The SFTP file-type constants are NOT defined at class-load.** Neither the class const
+  `SFTP::TYPE_DIRECTORY` nor the global `NET_SFTP_TYPE_DIRECTORY` exists when you just
+  load/use the class (phpseclib defines the globals lazily); `defined()` returned false for
+  both. Compare `type` against the SFTP-protocol numeric value via a **self-defined
+  constant**: `1` = regular file, `2` = directory. (`rawlist` returned php-type=array,
+  `type=1` for files, and `mtime` as a unix epoch matching the filename timestamp.)
+
+**Symptom when either is wrong:** reads guarded by `isset()`/`??` silently make the aged-file
+count always **0**, so the monitor never alarms and reads as perfectly healthy. Test the
+count against a folder you know has aged files.
+
+### `_Config::<group>('key')` throws on a missing key — pass a falsy fallback
+
+`_Config::<group>('key')` **throws** when the key is absent, so a `?:` default after it is
+dead code. To get a safe fallback, pass a **falsy second argument**:
+`_Config::sftp_staples('port', false) ?: 22`. Without the second arg the `?:` never runs
+because the throw happens first.
+
 ## Composer / deploy dependency
 
 `worker2/composer.json` added `javanile/php-imap2` (`^0.1.10`) for the IMAP path. The
@@ -293,6 +327,13 @@ check for another client.
   monitors must pass the region (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
 ## Change history
+- 2026-08-20 — Added the **SFTP monitor** shape (phpseclib3 `rawlist` + age-cutoff count +
+  decided token; login/list failure → `status:error` connectivity check) and its two
+  runtime gotchas: `rawlist` returns **arrays** not objects, and the SFTP type constants are
+  **not defined at class-load** (use a self-defined `1`=file/`2`=dir). Also recorded that
+  `_Config::<group>('key')` **throws** on a missing key — pass a falsy 2nd arg for a `?:`
+  fallback. First instance:
+  [Staples SFTP folder monitors](../../../clients/staples/features/oneuptime-sftp-folder-monitors.md). (bala)
 - 2026-08-17 — TRUE-80587: added five monitors and generalized this doc beyond Compass —
   `Monitor/Prudential/{SalesOrderGenerationBacklog,DellPurchaseOrderTransmissionBacklog,
   OrderShippedUpdateBacklog}`, `Monitor/Aig/EntitlementApiHealth`,

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 61 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 53 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 54 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 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) — 7 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/staples/INDEX.md

@@ -2,4 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Staples: OneUptime SFTP folder monitors (Monitor/Staples/*)](features/oneuptime-sftp-folder-monitors.md) | 2.0 | Two worker2 OneUptime push monitors that watch the **Staples SFTP** for stuck files in either direction — a backlog that previously had **no alerting** (the ear | worker2/Worker/Monitor/Staples.php, worker2/Config/beta.ini, worker2/Config/production.ini, dbchanges2/Core/2026-08-20a - Staples SFTP Monitors.sql |
 | [Staples](profile.md) | 1.0 | Staples is a **headless** integration client — no UI, Worker 1.0 only, depending on the `library` (1.0 `App_`) core. | worker/crons/sync/staples/sync_staples_cxml.php, worker/crons/sync/staples/staples_asn_netsuite.php |

package/knowledge/clients/staples/features/oneuptime-sftp-folder-monitors.md

@@ -0,0 +1,113 @@
+---
+title: "Staples: OneUptime SFTP folder monitors (Monitor/Staples/*)"
+framework: "2.0"
+repo: worker2
+project: Worker
+client: staples
+type: client-feature
+status: active
+updated: 2026-08-20
+owners: ["bala"]
+files:
+  - worker2/Worker/Monitor/Staples.php
+  - worker2/Config/beta.ini
+  - worker2/Config/production.ini
+  - dbchanges2/Core/2026-08-20a - Staples SFTP Monitors.sql
+related:
+  - ../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md
+  - ../profile.md
+  - ../../../1.0/apps/worker/features/staples-cxml-order-import.md
+---
+
+## Summary
+
+Two worker2 OneUptime push monitors that watch the **Staples SFTP** for stuck files in
+either direction — a backlog that previously had **no alerting** (the earlier `/out` pickup
+pileup incident went unnoticed). They implement the shared pattern in
+[OneUptime push-metric monitors for 2.0 workers](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md);
+read that first for the payload contract, criteria set, and provisioning runbook.
+
+- `Monitor/Staples/InboundOrderQueue` — watches **`/in`** (cXML orders Staples sent that
+  TOGA has not yet imported).
+- `Monitor/Staples/OutboundPickupQueue` — watches **`/out`** (855 acknowledgements + 856
+  ASNs TOGA wrote, waiting for Staples to download).
+
+Because each monitor logs into SFTP and lists a folder, it **doubles as an SFTP
+connectivity check**: a login/list failure pushes `status:"error"`, so a dead checker or a
+broken SFTP is distinguishable from a real backlog.
+
+## Key files / entry points
+
+- `worker2/Worker/Monitor/Staples.php` — `abstract class _Worker_Monitor_Staples`; two
+  `public static` action methods (`InboundOrderQueue`, `OutboundPickupQueue`), each
+  self-contained (in-method `ALL_CAPS` locals + `$push` closure), following the shared
+  "dumb reporter, smart monitor" model.
+- `dbchanges2/Core/2026-08-20a - Staples SFTP Monitors.sql` — the two `Core.CronJobs` rows
+  (actions `Monitor/Staples/InboundOrderQueue` and `Monitor/Staples/OutboundPickupQueue`,
+  schedule `*/5 * * * *`, `maxExecutionTime` 120), following the sibling monitor
+  cron-registration migration pattern.
+- `[sftp_staples]` config group in `worker2/Config/beta.ini` and
+  `worker2/Config/production.ini` — SFTP host/port/user/password. **The password is a
+  credential; it lives only in the ini group, never in this doc.**
+
+## How it works
+
+Each monitor logs into the Staples SFTP with **phpseclib3**, `rawlist`s the target folder,
+counts files older than an age threshold, decides an alarm token (`HIGH`/`OK`), and POSTs
+the JSON body to a OneUptime incoming-request monitor. The worker makes the threshold
+decision; OneUptime only string-matches the token (it cannot compare numbers — see the
+shared doc). The OneUptime push URLs are in-file constants (push credentials — never logged
+or recorded).
+
+### Staples SFTP folder semantics (background for the thresholds)
+
+The Staples pipeline runs in the **1.0 `worker`** tier, not worker2; worker2 only watches
+the folders. The relevant 1.0 crons and folder meanings (schedules are in
+`worker/schedules/cron.worker.sync.json`, in the server's **Central** timezone):
+
+| 1.0 cron | Schedule | What it does |
+|---|---|---|
+| `worker/crons/sync/staples/sync_staples_cxml.php` | `45 * * * *` (hourly) | imports Staples cXML orders from `/in` into NetSuite, writes an 855 ack to `/out`, archives the processed inbound file to `/archive/archive_in` |
+| `worker/crons/sync/staples/staples_asn_netsuite.php` | `50 * * * *` (hourly) | writes 856 ASN ship notices to `/out` |
+
+- **`/in`** — inbound orders Staples uploads for TOGA to import.
+- **`/out`** — outbound 855/856 files TOGA writes for Staples to download (drained by
+  Staples, moved to `/archive` on pickup).
+
+### Threshold tuning (decided)
+
+- Aged-file cutoff: **120 min for `/in`** (tied to the hourly import) and **240 min for
+  `/out`**.
+- Alarm when **>= 6 aged files** (tunable — can drop to 1 for single-file sensitivity).
+- **5-minute cron cadence** (`*/5 * * * *`), chosen to pair with the OneUptime heartbeat
+  criteria (received-in-8-min + `alarm:OK` recovery; not-received-15-min offline;
+  not-received-10-min degraded), matching the existing Compass monitor convention rather
+  than the source crons' hourly rate. The fast cadence is for a **reliable heartbeat**, not
+  because the folders change that fast — the folder cutoffs above are calibrated against the
+  **hourly 1.0 crons**, per the shared doc's "calibrate against the tier that runs the
+  business logic" rule.
+
+## Gotchas / known issues
+
+- **phpseclib3 `rawlist` returns arrays, and its SFTP type constants are not loaded** — see
+  the shared doc's
+  [SFTP monitoring gotchas](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md#sftp-monitoring-phpseclib3).
+  Getting this wrong silently makes the aged-file count always 0, so the monitor never
+  alarms and looks healthy.
+- The `[sftp_staples]` password and the OneUptime push URLs are credentials — reference
+  their location, never their value.
+
+## Change history
+- 2026-08-20 — Built the two SFTP folder monitors (`Monitor/Staples/InboundOrderQueue` on
+  `/in`, `Monitor/Staples/OutboundPickupQueue` on `/out`), each also acting as an SFTP
+  connectivity check via `status:error`; added the `[sftp_staples]` config group and the
+  `2026-08-20a` cron-registration migration; set the `/in` 120-min / `/out` 240-min aged-file
+  cutoffs and the >=6-file alarm threshold; chose a 5-min cadence for the heartbeat.
+  Motivated by the earlier `/out` pickup pileup incident that had no alerting. (bala)
+
+## Related docs
+- [OneUptime push-metric monitors for 2.0 workers](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md) — the shared pattern, payload contract, and runbook.
+- [Staples profile](../profile.md)
+- [Staples cXML order import (1.0)](../../../1.0/apps/worker/features/staples-cxml-order-import.md) — the inbound pipeline these monitors watch.
+</content>
+</invoke>

package/knowledge/clients/staples/profile.md

@@ -3,17 +3,20 @@ title: Staples
 framework: "1.0"
 apps:
   - worker
+  - worker2
+  - dbchanges2
 project: Worker
 client: staples
 type: profile
 status: active
-updated: 2026-08-13
-owners: [jcardinal]
+updated: 2026-08-20
+owners: [jcardinal, bala]
 files:
   - worker/crons/sync/staples/sync_staples_cxml.php
   - worker/crons/sync/staples/staples_asn_netsuite.php
 related:
   - ../../1.0/apps/worker/features/staples-cxml-order-import.md
+  - ./features/oneuptime-sftp-folder-monitors.md
 ---
 
 ## Summary

package/package.json

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