toga-ai 1.0.104 → 1.0.106

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
-| [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/Component/Library/Carriers/Ups/Ups.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 |
+| [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/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/Carriers/Ups/Ups.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 |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
 | [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 |

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -6,10 +6,11 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-10
+updated: 2026-06-16
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Client/ItemFulfillments/TrackingNumber.php
   - _underscore/Component/Library/Carriers/Ups/Ups.php
   - _underscore/Trait/Netsuite/ItemFulfillment.php
   - _underscore/Trait/Netsuite/SalesOrder.php
@@ -39,7 +40,10 @@ decision** (dev lead Jeff, June 2026) that supersedes what the code currently do
   the DB storage field, return `{ trackingNumber, pdfLabel, fileInternalId }` or
   `{ error, trackingNumber }`. UPS path now checks `$shipmentResponse->success` and
   fast-fails on an empty service code (it previously swallowed UPS errors and surfaced
-  a misleading "Failed to save PDF to NetSuite").
+  a misleading "Failed to save PDF to NetSuite"). These methods (plus `fulfill` and
+  `createNetsuiteItemFulfillment`'s package-detail query) resolve the tracking record by
+  joining **`ItemFulfillments_TrackingNumbers`** (the bridge); they previously joined the
+  dropped `ItemFulfillmentPackages` table — see Gotchas.
 - `_Component_Library_Carriers_Ups::submitShipmentRequest`
   (`Component/Library/Carriers/Ups/Ups.php`): returns `{ success, errorMessage,
   trackingNumber, encodedLabel }`.
@@ -104,8 +108,20 @@ attempted.
   recommended: always scope `getInventoryNumberFromSerialNumber` by location.
 - `createNetsuiteItemFulfillment` doesn't set carrier/method on the NS IF — it defaults
   (can show FedEx for a UPS shipment). Open item.
+- **Carrier-label queries joined the *dropped* `ItemFulfillmentPackages` table** (a
+  tracking-number-bridge migration write-back gap). `upsShipmentApi`, `fedexShipmentApi`,
+  `fulfill`, and `createNetsuiteItemFulfillment`'s package-detail query resolved the tracking
+  number by joining `ItemFulfillmentPackages` — retired by the bridge migration. Post-migration
+  that matched the **wrong/null** `TrackingNumbers` record, so the label + `number` saved to the
+  wrong row (the bridge-linked record's `labelPdfFile`/`number` stayed null → **reprint had no
+  label**) and the NS IF was built **without its tracking number**. **Fixed 2026-06-16** by
+  repointing all four joins to `ItemFulfillments_TrackingNumbers`. Diagnostic tell: the
+  bridge-linked `TrackingNumbers` row shows `number = NULL` after a "successful" ship. Backend
+  change — only effective once deployed to beta. Worth grepping `ItemFulfillmentPackage::TABLE`
+  across `_underscore`/`api2`/`library` for the same staleness elsewhere.
 
 ## Change history
+- 2026-06-16 — Repointed the carrier-label/NS-IF tracking-number queries (`upsShipmentApi`, `fedexShipmentApi`, `fulfill`, `createNetsuiteItemFulfillment`) from the dropped `ItemFulfillmentPackages` table to the `ItemFulfillments_TrackingNumbers` bridge — they had been saving the label/`number` to the wrong/null record (reprint `labelPdfFile` null; NS IF missing tracking). Confirmed working on beta. (mhammontree)
 - 2026-06-10 — Documented carrier shipping label mechanics (UPS/FedEx) + the authoritative GIF label-storage decision and NetSuite IF attachment. (mhammontree)
 
 ## Related docs

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -135,6 +135,7 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   **not** join `Records`. This gap belongs back in the migration (Core §7 + Client §6b + blank-client template).
 
 ## Change history
+- 2026-06-16 — Caught a migration code-update miss: four queries in `Model/Client/ItemFulfillment.php` (`upsShipmentApi`, `fedexShipmentApi`, `fulfill`, `createNetsuiteItemFulfillment`) still joined the dropped `ItemFulfillmentPackages` table to resolve tracking — repointed to `ItemFulfillments_TrackingNumbers`. See the carrier-shipping-labels doc. (mhammontree)
 - 2026-06-16 — Found + documented the bridge ACL gap: the migration creates bridge `AclRecordPermissions` (317–322) but not their `AclLogicGroups`/`AclLogicGroupExpressions`/`AclRecordExpressions` chain → 403 "No ACL Logic Groups defined" for non-Super-User reads (confirmed prod + all clients). Recorded the `slug='all'`/`sqlExpression='1'` fix for Core + per-client, plus the Client-DB `Records`-table caveat. (mhammontree)
 - 2026-06-10 — Documented the tracking-number bridge migration: scalar FK columns → `*_TrackingNumbers` bridge tables across ASN/IF/IR, ASN unit table rename, packages-table consolidation. (jcardinal)
 

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

@@ -3,3 +3,4 @@
 | 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/ |
+| [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |

package/knowledge/2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md

@@ -0,0 +1,88 @@
+---
+title: AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: workflow
+status: active
+updated: 2026-06-16
+owners: ["jcardinal"]
+files: []
+related: []
+---
+
+## Summary
+2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. The Source stage
+pulls from GitHub via a **CodeConnections** connection (the modern replacement for
+CodeStar Connections), backed by the **"AWS Connector for GitHub" GitHub App** installed on
+the `agilantsolutions` org. A single pipeline can have multiple Source actions sharing one
+connection (e.g. `agilantsolutions/api2` and `agilantsolutions/_underscore` on the same
+connection ARN). Deployment target is Elastic Beanstalk.
+
+## Steps
+1. A push to the watched branch (e.g. `_stage`) triggers the pipeline.
+2. The Source stage uses `CodeStarSourceConnection` actions, each referencing:
+   - `ConnectionArn` — the CodeConnections connection
+   - `FullRepositoryId` — `owner/repo` (e.g. `agilantsolutions/api2`)
+   - `BranchName`
+3. The CodePipeline service role must allow `codeconnections:UseConnection` **and**
+   `codestar-connections:UseConnection` on that connection ARN.
+4. Source artifacts flow downstream to build/deploy stages → Elastic Beanstalk.
+
+## Systems involved
+- AWS CodePipeline + CodeConnections (per-AWS-account; each account has its own connection
+  and its own GitHub App installation).
+- GitHub org `agilantsolutions` + the "AWS Connector for GitHub" App.
+- Elastic Beanstalk (deploy target); see `api2/.ebextensions/`.
+
+## Edge cases & escalation
+
+### Gotcha: "[GitHub] GitHub returned an Internal Error exception" at the Source step
+This generic error is a **catch-all** CodePipeline shows for several distinct Source-stage
+failures — it is usually **not** an actual GitHub outage. When it fails **immediately and
+consistently** (not intermittently), and GitHub status is green, work through these in order:
+
+1. **Pending GitHub App access request (most common, and the root cause seen 2026-06-16).**
+   Even with the GitHub App set to **"All repositories"** and the connection showing
+   `AVAILABLE`, GitHub may have a **pending "review access request"** notification on the
+   AWS Connector App that an org owner must **approve**. Until approved, every Source action
+   fails with this exact error. Fix: GitHub → Org → Settings → GitHub Apps / installed apps
+   → AWS Connector for GitHub → approve the pending access request. No AWS-side change needed;
+   the pipeline works on the next run.
+2. **GitHub App not granted to the repo.** If the App is "Only select repositories," confirm
+   the repo(s) are in the list.
+3. **IAM.** The service role needs `codeconnections:UseConnection` + `codestar-connections:UseConnection`
+   on the **exact** connection ARN. A policy scoped to a different connection ARN denies the
+   pipeline and surfaces as the same generic GitHub error.
+4. **SAML SSO.** If the org enforces SSO, the App authorization may need re-authorizing.
+
+**Key diagnostic insight:** `ConnectionStatus: AVAILABLE` only proves the initial OAuth
+handshake completed once — it does **not** re-verify ongoing repo access or installation
+health. A connection stays `AVAILABLE` while every source action fails. Also: if **all** repos
+on one connection fail identically, the problem is the **connection / App installation**, not
+anything repo-specific. The AWS CLI cannot introspect the GitHub App installation for
+`ProviderType: GitHub` — that check must be done in the GitHub UI.
+
+**Cross-account comparison is a fast triage:** the same repo working in a *different* AWS
+account proves it is not a GitHub/repo/branch problem — connections and App installations are
+per-account, so the fault is local to the failing account's connection.
+
+### CloudShell triage commands (read-only)
+```bash
+PIPELINE="<pipeline-name>"; REGION="us-east-1"
+EXEC_ID=$(aws codepipeline list-pipeline-executions --pipeline-name "$PIPELINE" --region "$REGION" \
+  --max-results 1 --query 'pipelineExecutionSummaries[0].pipelineExecutionId' --output text)
+aws codepipeline list-action-executions --pipeline-name "$PIPELINE" --region "$REGION" \
+  --filter pipelineExecutionId="$EXEC_ID" \
+  --query 'actionExecutionDetails[?stageName==`Source`].{action:actionName,status:status,summary:output.executionResult.externalExecutionSummary}'
+aws codepipeline get-pipeline --name "$PIPELINE" --region "$REGION" \
+  --query 'pipeline.stages[?name==`Source`].actions[].{name:name,config:configuration}'
+aws codeconnections get-connection --connection-arn "<CONN_ARN>" --region "$REGION"
+```
+
+## Change history
+- 2026-06-16 — Documented after a pipeline (API-QC-Security, account 975050298201) failed every
+  run at Source with "[GitHub] GitHub returned an Internal Error"; connection was AVAILABLE and
+  IAM was correct — root cause was a pending GitHub App access-request approval in the
+  `agilantsolutions` org. (jcardinal)

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_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) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 2 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.104",
+  "version": "1.0.106",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",