toga-ai 1.0.471 → 1.0.472

package/knowledge/1.0/apps/tools/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
+| [ClickUp Sprint Dashboard (tools /clickup/react)](features/clickup-sprint-dashboard.md) | A native **ClickUp sprint dashboard** in the 1.0 `tools` app at route `/clickup/react`, built for a wall-mounted **TV display** ("TOGa IQ" internal sprint metri | tools/_/app/clickup/sprint.php, tools/v2/sprints/tile/index.php, tools/v2/sprints/current/index.php, tools/v2/sprints/status-breakdown/index.php, tools/v2/sprints/worktype-breakdown/index.php, tools/v2/sprints/points-by-dev/index.php, tools/v2/sprints/burndown/index.php, tools/assets/clickup/sprint-dashboard.html, tools/mvc/clickup/react/get.php, tools/mvc/login/get.php, tools/_/app/nav.php |
 | [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |

package/knowledge/1.0/apps/tools/features/clickup-sprint-dashboard.md

@@ -0,0 +1,142 @@
+---
+title: ClickUp Sprint Dashboard (tools /clickup/react)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-07-29
+owners: [kyalamarthi]
+files:
+  - tools/_/app/clickup/sprint.php
+  - tools/v2/sprints/tile/index.php
+  - tools/v2/sprints/current/index.php
+  - tools/v2/sprints/status-breakdown/index.php
+  - tools/v2/sprints/worktype-breakdown/index.php
+  - tools/v2/sprints/points-by-dev/index.php
+  - tools/v2/sprints/burndown/index.php
+  - tools/assets/clickup/sprint-dashboard.html
+  - tools/mvc/clickup/react/get.php
+  - tools/mvc/login/get.php
+  - tools/_/app/nav.php
+related:
+  - ./persona-gated-navigation.md
+  - ./saml-sso-auth.md
+  - ./mvc-data-access-patterns.md
+  - ../architecture.md
+  - ../../../2.0/apps/worker2/features/team-sprint-management.md
+---
+
+## Summary
+
+A native **ClickUp sprint dashboard** in the 1.0 `tools` app at route `/clickup/react`,
+built for a wall-mounted **TV display** ("TOGa IQ" internal sprint metrics). It replaces a
+standalone Node/Express prototype from a prior session, folding the dashboard into `tools`
+so it runs on the existing App\_ framework + SSO with no separate service.
+
+It reads the **same Team DB** and reproduces the **same Power BI-parity metric definitions**
+already documented for worker2 — see
+[team-sprint-management](../../../2.0/apps/worker2/features/team-sprint-management.md). This
+doc does **not** duplicate those DAX→SQL definitions; it documents the tools-side delivery
+(data engine, routes, UI, embed, nav, TV decisions).
+
+## How it works
+
+### Data engine — `App_Clickup_Sprint` (`_/app/clickup/sprint.php`)
+
+Static methods, one per metric: `tile`, `status-breakdown`, `worktype-breakdown`,
+`points-by-dev`, `burndown`, `current`. Each queries the **Team DB** via the `db_team`
+connection (registry string `'db_team'`, from the `[database_team]` config section) using
+`App_Database::query($sql, 'db_team')`. Responses are wrapped in the **api2 `/v2` envelope**
+(`{success, data, errors}`) so the tool is a faithful stand-in for api2.
+
+**Auth is done by hand as JSON**, not the HTML auth card: `App_Auth::isLoggedIn()` +
+`App_Nav::personasForRoute('/clickup/react')` + `hasAnyPersona`; on failure it returns a
+JSON **401/403** so the fetch-based UI gets a clean error instead of an HTML login page.
+
+Two 1.0-framework gotchas this engine had to work around (both reusable beyond this
+feature — see [Gotchas](#gotchas)):
+
+1. **Query-logging preflight on a `Defaults`-less DB.** Call
+   `App_Registry::set('queryLogging', false)` before the first query on `db_team`, or
+   `App_Query`'s one-time preflight (`SELECT ... FROM Defaults WHERE setting='QUERY_LOGGING'`)
+   throws `#1146 Table 'Team.Defaults' doesn't exist` and every metric 500s.
+2. **`App_Database::buildArrayOfRows()` takes its result by reference.** Assign the query
+   result to a variable first; passing `App_Database::query(...)` inline is fatal under the
+   E_ALL handler.
+
+### Routes — `v2/sprints/{metric}/index.php`
+
+Thin route handlers mapping `/v2/sprints/*` to `App_Clickup_Sprint::serve($metric)`. One
+`index.php` per metric (`tile`, `current`, `status-breakdown`, `worktype-breakdown`,
+`points-by-dev`, `burndown`).
+
+### UI — `assets/clickup/sprint-dashboard.html`
+
+**React via CDN in a single HTML file** — React 18.3.1 + ReactDOM (production UMD) +
+Babel-standalone from CDN, JSX inside a `<script type="text/babel">`. **No build step, no
+npm, no bundler.** It fetches `/v2/sprints/*` **same-origin**, so the SSO session cookie
+authenticates the calls automatically. Do not mistake this for a bundled React app.
+
+### Embed page — `mvc/clickup/react/get.php`
+
+A PHP MVC view that `requireAuth`s, then embeds `sprint-dashboard.html` in an
+`<iframe allowfullscreen>` (cache-busted by `filemtime`). Heading "Clickup Dashboard",
+subtitle notes the data is "…refreshed every 5 min."
+
+### Nav — `_/app/nav.php`
+
+Registered under the **"Dashboard"** nav folder as
+`['label'=>'Clickup','route'=>'/clickup/react']`, persona-gated like every folder (see
+[persona-gated-navigation](./persona-gated-navigation.md)). The old Power BI embed nav entry
+(`/clickup/dashboard`) was **removed** — the page file stays on disk, just unlinked — because
+the React dashboard supersedes it.
+
+## TV display decisions
+
+- **Soft 5-min auto-refresh.** The `useApi` hook re-fetches in place every 5 min via
+  `setInterval`; it does **not** `location.reload()`. On a full-screen TV a soft refresh
+  keeps the page full-screen and flash-free, whereas a full reload exits full screen every
+  cycle. (JS timers only throttle in hidden/background tabs; a foreground full-screen TV tab
+  is not throttled.)
+- **16:9 stage.** The iframe stage uses `aspect-ratio:16/9` with
+  `max-height: calc(100vh - 170px)` so it stays TV-shaped without forcing page scroll. Full
+  width comes from lifting the shell content cap for this page only —
+  `.app-content:has(.cur-dash){max-width:none}` (same pattern the design tool uses in
+  `assets/css/design.css`); the dashboard `.page` has no max-width so it fills the stage.
+
+## Local development
+
+- **Dev auth bypass.** `mvc/login/get.php` has a block that, when
+  `!empty($internal['dev_mode']) && !empty($internal['dev_autologin'])`, calls
+  `App_Auth::establishSession([...synthetic 'Local Dev' user...], ['Development Team','TOGa Technology'])`
+  and `App_MVC::routeTo('/clickup/dashboard')`, skipping the SSO form. The `dev_autologin`
+  flag lives **only** in the git-ignored `config.dev-local.ini` (next to `dev_mode`); prod
+  has `dev_mode=0` and no such flag, so the bypass is inert in every deployed env. The config
+  filename is chosen by `getenv('ENVIRONMENT')` → `config.<env>.ini`
+  (`App_Framework::initialize` / `App_Config::getConfigFilename`).
+- **Run on Windows** (the repo's `docs/LOCAL_DEV.md` is macOS-worded):
+  `cd tools && ENVIRONMENT=dev-local php -d "include_path=.;C:/www/library" -S localhost:8000 router.php`.
+  The `App_` framework + `_.php` bootstrap load from the separate `library` repo via
+  `include_path`; `router.php` reproduces the `.htaccess` rewrite for PHP's built-in server.
+
+> Credentials note: DB creds and the `dev_mode` / `dev_autologin` flags live in the
+> git-ignored `config.dev-local.ini` — never commit values.
+
+## Gotchas
+
+- **`queryLogging` preflight fails on any non-core DB without a `Defaults` table.** `App_Query`
+  (`library/app/query.php`) runs a one-time-per-request check on the **first** query of the
+  request against the active connection: `SELECT value FROM Defaults WHERE setting='QUERY_LOGGING'`.
+  If that first query runs on `db_team` (the Team schema has no `Defaults` table) it throws
+  `#1146 Table 'Team.Defaults' doesn't exist`. Set `App_Registry::set('queryLogging', false)`
+  before any query on a `Defaults`-less connection. General to any 1.0 App\_ code hitting the
+  Team DB or any other non-core schema.
+- **`App_Database::buildArrayOfRows()` result is by-reference.**
+  `buildArrayOfRows(App_Database::query($sql,$db), false)` raises "Only variables should be
+  passed by reference", which the E_ALL error handler promotes to a fatal 500. Assign first:
+  `$res = App_Database::query(...); buildArrayOfRows($res, false);`.
+
+## Change history
+- 2026-07-29 — Built `/clickup/react` as a native tools feature (data engine, `/v2/sprints/*` routes, CDN-React TV UI, iframe embed, "Dashboard/Clickup" nav); removed the old `/clickup/dashboard` Power BI nav entry; documented two reusable 1.0 gotchas (queryLogging preflight on Defaults-less DBs, buildArrayOfRows by-ref). (kyalamarthi)

package/knowledge/INDEX.md

@@ -13,7 +13,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 13 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 10 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 11 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/package.json

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