@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-workspace/docs/status-mon.md

@@ -0,0 +1,168 @@
+# status-mon
+
+Background poller + state file + workspace banner for Statuspage.io-backed service status monitoring.
+
+## What it does
+
+Every 60 seconds, polls a configurable list of Statuspage.io `/api/v2/summary.json` endpoints and writes a normalised state file. The workspace server exposes that file at `/__api/status-mon`; every workspace page loads `/banner.js`, which reads the endpoint and renders a slim, severity-tinted banner as the first element in the viewport. Default sources ship as Anthropic + GitHub; any Statuspage.io-hosted status site works.
+
+The banner is the only visible surface. Active incidents render as amber (minor), red (major/critical), or blue (maintenance) and are non-dismissable. A "recovered" row is green and dismissable per-incident via `localStorage`. When no source has anything to report, the banner is empty.
+
+## Architecture
+
+```
+┌────────────────────────┐       ┌──────────────────────────┐       ┌──────────────────┐
+│ Poller                 │ writes│ State file               │ reads │ Banner API       │
+│ core/tools/status-mon/ ├──────▶│ .state/status-mon.json   │◀──────┤ /__api/status-mon│
+│ 60s, server-side       │       │ (gitignored, per-host)   │       │                  │
+└────────────────────────┘       └──────────────────────────┘       └─────────┬────────┘
+                                                                              │ 30s client poll
+                                                                              ▼
+                                                                    ┌──────────────────┐
+                                                                    │ Banner client    │
+                                                                    │ /banner.js + CSS │
+                                                                    │ inlined on pages │
+                                                                    └──────────────────┘
+```
+
+The workspace server imports `startPoller({ repoRoot })` on boot. The returned handle exposes `stop()` for graceful shutdown. The poller writes the shared state file every 60s. A standalone `run.mjs` CLI is also provided for one-shot / scheduled use, but the server-side integration is the default because the workspace is launchd-supervised.
+
+### Why server-side integration (not a separate scheduled task)
+
+- The workspace server is supervised by launchd (`com.dave.workspace`) — always on.
+- A separate cron/launchd job would duplicate supervision, add localhost→localhost file-coordination risk, and widen the failure surface for no operational benefit.
+- The module loads `poll.mjs` directly so the CLI (`run.mjs`) and the server share the exact same normalisation logic.
+
+If an operator prefers a scheduled-task layout, `run.mjs` is a complete, supervision-ready CLI. See "Scheduled mode" below.
+
+## Files
+
+| File | Role |
+|---|---|
+| `poll.mjs` | Pure normalisation + poll logic. No I/O at import. |
+| `poller.mjs` | Server-side lifecycle: interval loop, state-file IO, preferences resolution. |
+| `run.mjs` | One-shot CLI wrapper. Writes `.state/status-mon.json`. |
+| `poll.test.mjs` | Node tests for parsing + merging. |
+| `poller.test.mjs` | Node tests for the poller lifecycle. |
+
+## State file
+
+Default location: `$DAVE_ROOT/.state/status-mon.json` (gitignored).
+
+```jsonc
+{
+  "polledAt": "2026-04-20T12:00:00.000Z",
+  "lastSuccessfulPollAt": "2026-04-20T12:00:00.000Z",
+  "sources": [
+    {
+      "id": "anthropic",
+      "name": "Anthropic",
+      "sourceUrl": "https://status.anthropic.com/api/v2/summary.json",
+      "overall": { "indicator": "minor", "description": "Partial service disruption" },
+      "incidents": [
+        {
+          "id": "abc123",
+          "name": "Elevated error rates on Messages API",
+          "status": "monitoring",
+          "impact": "minor",
+          "startedAt": "2026-04-20T11:00:00Z",
+          "updatedAt": "2026-04-20T11:45:00Z",
+          "url": "https://stspg.io/abc123"
+        }
+      ],
+      "recentlyResolved": []
+    },
+    {
+      "id": "github",
+      "name": "GitHub",
+      "sourceUrl": "https://www.githubstatus.com/api/v2/summary.json",
+      "overall": { "indicator": "none", "description": "All Systems Operational" },
+      "incidents": [],
+      "recentlyResolved": [
+        {
+          "id": "xyz789",
+          "name": "Actions queue delays",
+          "resolvedAt": "2026-04-20T07:15:00Z",
+          "url": "https://www.githubstatus.com/incidents/xyz789"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Graceful degradation
+
+When a source fetch fails but the previous poll's slice for that source succeeded, the poller retains the prior slice, adds `"fetchError": "<reason>"` and `"stale": true`, and carries forward `lastSuccessfulPollAt` at the top level. Consumers can read this to decide whether to show a warning; the banner currently treats stale data exactly like live data since "the last thing we knew" is more useful than "status unknown".
+
+If a source has *never* fetched successfully, its slice shows `indicator: 'none'` with the `fetchError` field — the banner silently omits it rather than rendering a spurious red row.
+
+## Configuration
+
+Override sources via `operator/config/preferences.json`:
+
+```json
+{
+  "statusMonSources": [
+    { "id": "anthropic", "name": "Anthropic", "url": "https://status.anthropic.com/api/v2/summary.json" },
+    { "id": "openai", "name": "OpenAI", "url": "https://status.openai.com/api/v2/summary.json" }
+  ]
+}
+```
+
+Each entry must be a Statuspage.io `/api/v2/summary.json` endpoint. Non-Statuspage sources are out of scope for v1; the config shape is forward-compatible (a future `adapter` field could opt into alternative shapes).
+
+If `statusMonSources` is absent or invalid, the tool falls back to the built-in defaults (Anthropic + GitHub).
+
+## Server-side integration (default)
+
+The workspace server imports and starts the poller on boot:
+
+```javascript
+// server.mjs (excerpt)
+import { startPoller } from '../status-mon/poller.mjs';
+const statusMonHandle = startPoller({ repoRoot: REPO_ROOT });
+// shutdown hook calls statusMonHandle.stop()
+```
+
+Startup writes `.state/status-mon.json` out-of-band (non-blocking). Subsequent writes happen every 60s. The API endpoint `/__api/status-mon` reads the file verbatim — it never triggers a fetch, so page loads don't stall on upstream latency.
+
+## Scheduled mode (alternative)
+
+For deployments that prefer cron/launchd to the server-side loop, invoke the CLI:
+
+```bash
+node core/tools/status-mon/run.mjs            # production run
+node core/tools/status-mon/run.mjs --dry-run  # prints state to stdout
+node core/tools/status-mon/run.mjs --out /tmp/x.json  # redirect output
+```
+
+Example cron: `* * * * * cd $DAVE_ROOT && node core/tools/status-mon/run.mjs`
+
+When both modes run simultaneously they're safe (last write wins; the file is tiny), but the practical recommendation is: server-side on a launchd-supervised workspace, CLI-scheduled on unsupervised hosts.
+
+Exit codes: `0` ok, `1` usage error, `2` all sources failed and no cached state, `3` write failure.
+
+## Banner client
+
+`core/tools/workspace/app/banner.js` — included on every workspace HTML page via `<script src="/banner.js" defer></script>` and renders into a `<div id="global-banner"></div>` placed as the first child of `<body>`.
+
+- Fetches `/__api/status-mon` on load.
+- Polls every 30s while `document.visibilityState === 'visible'`; pauses when hidden.
+- Severity ordering: `critical` > `major` > `minor` > `maintenance` > `recovered` > `none`. One row per source, rendered in source order.
+- `localStorage.getItem('dave.statusmon.dismissed')` holds a JSON array of dismissed `recentlyResolved` IDs. Dismissals are GC'd on load — IDs no longer in the current state are dropped.
+- Active-disruption rows link out to the incident's status page in a new tab. Green rows carry an × dismiss button.
+- CSS is inlined by the script — no separate stylesheet request.
+
+## Tests
+
+- `node --test packages/workspace/test/status-mon/*.test.mjs` — pure logic + lifecycle (no network).
+- `packages/workspace/e2e/specs/banner.spec.mjs` — Playwright coverage for the render matrix against fixture state files.
+
+Node tests run in the `test` job; the e2e suite runs in the `workspace-e2e` job — both in `.github/workflows/ci.yml`.
+
+## Extending
+
+Add a non-Statuspage source type: extend `poll.mjs` with an `adapter` switch that dispatches on a per-source `adapter` field (default `'statuspage'`). Keep the normalised output shape identical so the banner and state file schema stay untouched.
+
+Add a non-banner surface (e.g. desktop notification, slack webhook): write a consumer against `.state/status-mon.json`. The state file is the contract; the banner is one consumer.

package/dist/engineering-pa-workspace/index.mjs

@@ -0,0 +1,12 @@
+// @stravica-ai/engineering-pa-workspace — workspace server + viewer.
+//
+// Public surface exposes the server entry, nav loader, install-daemon helper,
+// and the status-mon poller. Most consumers want to spawn the bin shim (or
+// `pa workspace`); this surface is for in-process embedding.
+
+export const name = './';
+export const version = '0.1.1';
+
+export { loadNav } from './src/nav.mjs';
+export { startPoller as startStatusMonPoller } from './src/status-mon/poller.mjs';
+export { handleApi } from './src/api.mjs';

package/dist/engineering-pa-workspace/nav.json.example

@@ -0,0 +1,8 @@
+[
+  {
+    "id": "mypage",
+    "label": "My Page",
+    "href": "/mypage.html",
+    "section": "Extensions"
+  }
+]

package/dist/engineering-pa-workspace/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@stravica-ai/engineering-pa-workspace",
+  "version": "0.1.6",
+  "description": "Workspace server + viewer — operator-facing local web UI for the PA platform.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "dependencies": {
+    "@stravica-ai/engineering-pa-cli": "workspace:*",
+    "@stravica-ai/engineering-pa-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1"
+  },
+  "private": true,
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test --test-isolation=none 'test/**/*.test.mjs'",
+    "e2e": "playwright test --config e2e/playwright.config.mjs"
+  },
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie."
+}