QS Work Item Insights

Forge app (Jira Cloud, global page, UI Kit) that renders live Work Item Insights for any Jira/JSM space — visible to anyone on the site with a Jira license, without requiring JSM agent seats or space membership. Replaces a Power BI export → Teams workflow.

New here (human or agent)? Read docs/AGENT_BRIEF.md first, then docs/DECISIONS.md.

Quickstart

npm install
forge login                # Atlassian API token
forge register             # assigns an app ID into manifest.yml
forge deploy               # deploys to the development environment
forge install --site <your-site>.atlassian.net --product jira
forge tunnel               # live-reload development loop
npm test                   # pure-function unit tests (node:test)

The page appears under Apps → Work Item Insights in Jira.

Repo map

manifest.yml                    Forge module/scopes definition
src/
  index.js                      resolver entry (thin)
  lib/
    constants.js                tuning knobs (poll/TTL/pager/buckets)
    filters.js                  filter model -> JQL (only JQL assembly point)
    jira-client.js              asApp REST access, defensive pager
    access.js                   blacklist + Browse-permission fallback
    panel-registry.js           BACKEND PARENT: fetch-once, cache, run panels
  panels/
    index.js                    backend panel roster (registerPanel calls)
    aging/
      aggregate.js              pure (issues, ctx) -> data   [reference panel]
      Panel.jsx                 display component            [reference panel]
  frontend/
    index.jsx                   UI Kit entry
    Dashboard.jsx               shell: picker, poll loop, header, grid
    PanelFrame.jsx              FRONTEND PARENT: chrome/loading/error/empty
    panelLayout.jsx             frontend panel roster
test/
  fixtures/issues.json          deterministic issue fixture
  aging.test.js                 aggregate + JQL builder tests
docs/
  AGENT_BRIEF.md                full context transfer / architecture rules
  DECISIONS.md                  settled decisions + open items

Adding a panel (the whole point)

1. src/panels/<name>/aggregate.js — pure function (issues, ctx) => data
2. test/<name>.test.js — fixture test
3. src/panels/<name>/Panel.jsx — display inside <PanelFrame>
4. One line each in src/panels/index.js and src/frontend/panelLayout.jsx
5. forge deploy

If step 6 exists, the architecture is drifting — see AGENT_BRIEF.