@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-workspace/src/status-mon/poll.mjs

@@ -0,0 +1,220 @@
+/**
+ * poll.mjs — Pure polling logic for Statuspage.io-backed service-status sources.
+ *
+ * No filesystem side effects at import time. All I/O (fetch, read, write)
+ * happens inside explicit functions so tests can drive the module with
+ * injected fetchers and temp paths.
+ *
+ * Source shape assumed: Atlassian Statuspage `/api/v2/summary.json`. The
+ * adapter only reads fields that are documented + stable across all major
+ * Statuspage.io deployments (Anthropic, GitHub, OpenAI, Stripe, etc.).
+ *
+ * See README.md for the state-file schema and configuration contract.
+ */
+
+/** Default polling sources. Override via operator/config/preferences.json. */
+export const DEFAULT_SOURCES = [
+  { id: 'anthropic', name: 'Anthropic', url: 'https://status.anthropic.com/api/v2/summary.json' },
+  { id: 'github',    name: 'GitHub',    url: 'https://www.githubstatus.com/api/v2/summary.json' },
+];
+
+/**
+ * Overall status indicators emitted by Statuspage.io in `status.indicator`.
+ * Ordering matters for severity (higher index = more severe). `maintenance`
+ * is rendered distinctly on the banner; it's not strictly "more severe"
+ * than `minor` in text, but colour-wise it's neutral.
+ */
+export const INDICATORS = ['none', 'maintenance', 'minor', 'major', 'critical'];
+
+/** Incident statuses that mean "still open". Anything else is considered closed. */
+const OPEN_STATUSES = new Set(['investigating', 'identified', 'monitoring']);
+
+/** Default window for "recently resolved" highlighting. */
+const DEFAULT_RESOLVED_WINDOW_MS = 6 * 60 * 60 * 1000; // 6h
+
+/**
+ * Normalise a raw summary.json payload into the canonical per-source slice
+ * used by the state file. Validates required fields loosely — Statuspage.io
+ * occasionally ships optional fields absent, so we prefer lenient coercion
+ * over schema rejection. Returns null on unusable payload so the caller can
+ * skip one bad source without failing the whole poll.
+ *
+ * @param {object} source  { id, name, url }
+ * @param {object} payload Raw Statuspage.io summary JSON.
+ * @param {number} nowMs   Epoch millis at poll time (injected for tests).
+ * @param {number} [resolvedWindowMs]  Override the recently-resolved window.
+ * @returns {object|null}
+ */
+export function normaliseSummary(source, payload, nowMs, resolvedWindowMs) {
+  if (!payload || typeof payload !== 'object') return null;
+  const status = payload.status || {};
+  const indicator = typeof status.indicator === 'string' ? status.indicator : 'none';
+  const description = typeof status.description === 'string' ? status.description : '';
+
+  const window = typeof resolvedWindowMs === 'number' ? resolvedWindowMs : DEFAULT_RESOLVED_WINDOW_MS;
+  const rawIncidents = Array.isArray(payload.incidents) ? payload.incidents : [];
+
+  const incidents = [];
+  const recentlyResolved = [];
+  for (const inc of rawIncidents) {
+    if (!inc || typeof inc.id !== 'string') continue;
+    const normal = {
+      id: inc.id,
+      name: typeof inc.name === 'string' ? inc.name : 'Unknown incident',
+      status: typeof inc.status === 'string' ? inc.status : 'unknown',
+      impact: typeof inc.impact === 'string' ? inc.impact : 'none',
+      startedAt: typeof inc.started_at === 'string' ? inc.started_at : null,
+      updatedAt: typeof inc.updated_at === 'string' ? inc.updated_at : null,
+      resolvedAt: typeof inc.resolved_at === 'string' ? inc.resolved_at : null,
+      url: typeof inc.shortlink === 'string' && inc.shortlink
+        ? inc.shortlink
+        : (typeof inc.url === 'string' ? inc.url : null),
+    };
+    if (OPEN_STATUSES.has(normal.status)) {
+      incidents.push({
+        id: normal.id,
+        name: normal.name,
+        status: normal.status,
+        impact: normal.impact,
+        startedAt: normal.startedAt,
+        updatedAt: normal.updatedAt,
+        url: normal.url,
+      });
+    } else if (normal.status === 'resolved' && normal.resolvedAt) {
+      const resolvedMs = Date.parse(normal.resolvedAt);
+      if (!Number.isNaN(resolvedMs) && (nowMs - resolvedMs) <= window) {
+        recentlyResolved.push({
+          id: normal.id,
+          name: normal.name,
+          resolvedAt: normal.resolvedAt,
+          url: normal.url,
+        });
+      }
+    }
+  }
+
+  return {
+    id: source.id,
+    name: source.name,
+    sourceUrl: source.url,
+    overall: { indicator, description },
+    incidents,
+    recentlyResolved,
+  };
+}
+
+/**
+ * Poll all configured sources and build a state payload. Uses the injected
+ * fetcher so production code passes `globalThis.fetch` and tests pass a
+ * deterministic stub. Never throws — per-source failure is captured in the
+ * source slice as `fetchError` and the overall indicator defaults to 'none'
+ * so the banner degrades gracefully.
+ *
+ * @param {object} options
+ * @param {Array<{id:string,name:string,url:string}>} options.sources
+ * @param {(url:string)=>Promise<Response>} options.fetcher
+ * @param {number} options.nowMs
+ * @param {number} [options.timeoutMs]  Abort fetches after this many ms.
+ * @returns {Promise<object>}
+ */
+export async function poll({ sources, fetcher, nowMs, timeoutMs }) {
+  const effectiveTimeout = typeof timeoutMs === 'number' ? timeoutMs : 10_000;
+  const list = Array.isArray(sources) && sources.length > 0 ? sources : DEFAULT_SOURCES;
+  const results = await Promise.all(list.map(async (source) => {
+    const slice = {
+      id: source.id,
+      name: source.name,
+      sourceUrl: source.url,
+      overall: { indicator: 'none', description: '' },
+      incidents: [],
+      recentlyResolved: [],
+    };
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), effectiveTimeout);
+      let res;
+      try {
+        res = await fetcher(source.url, { signal: controller.signal });
+      } finally {
+        clearTimeout(timer);
+      }
+      if (!res || !res.ok) {
+        slice.fetchError = res ? `HTTP ${res.status}` : 'no response';
+        return slice;
+      }
+      const payload = await res.json();
+      const normalised = normaliseSummary(source, payload, nowMs);
+      if (!normalised) {
+        slice.fetchError = 'unusable payload';
+        return slice;
+      }
+      return normalised;
+    } catch (err) {
+      slice.fetchError = err && err.message ? err.message : String(err);
+      return slice;
+    }
+  }));
+
+  const polledAt = new Date(nowMs).toISOString();
+  const anyOk = results.some((r) => !r.fetchError);
+  const state = {
+    polledAt,
+    sources: results,
+  };
+  if (anyOk) state.lastSuccessfulPollAt = polledAt;
+  return state;
+}
+
+/**
+ * Merge a fresh poll result with the previously-persisted state. The goal is
+ * graceful degradation: when a source fetch fails this pass but succeeded
+ * last pass, keep showing the last-known-good slice (with its age carried in
+ * `lastSuccessfulPollAt` at top level) rather than flipping the banner to
+ * 'unknown'. Per-source `fetchError` is preserved on the latest attempt so
+ * consumers can distinguish stale-but-known from never-fetched.
+ *
+ * @param {object|null} previous  Previous state file contents, or null.
+ * @param {object} fresh          Result of poll().
+ * @returns {object}
+ */
+export function mergeWithPrevious(previous, fresh) {
+  if (!previous || !Array.isArray(previous.sources)) return fresh;
+  const merged = { ...fresh, sources: [] };
+  for (const freshSlice of fresh.sources) {
+    if (freshSlice.fetchError) {
+      const prev = previous.sources.find((s) => s.id === freshSlice.id);
+      if (prev && !prev.fetchError) {
+        merged.sources.push({
+          ...prev,
+          sourceUrl: freshSlice.sourceUrl,
+          fetchError: freshSlice.fetchError,
+          stale: true,
+        });
+        continue;
+      }
+    }
+    merged.sources.push(freshSlice);
+  }
+  // Carry forward lastSuccessfulPollAt when the fresh poll had no successes.
+  if (!merged.lastSuccessfulPollAt && previous.lastSuccessfulPollAt) {
+    merged.lastSuccessfulPollAt = previous.lastSuccessfulPollAt;
+  }
+  return merged;
+}
+
+/**
+ * Load sources from a preferences.json object. Falls back to defaults when
+ * the key is missing or malformed. Validates each entry has { id, name, url }.
+ *
+ * @param {object|null} prefs  Parsed preferences.json, or null.
+ * @returns {Array<{id:string,name:string,url:string}>}
+ */
+export function resolveSources(prefs) {
+  if (!prefs || typeof prefs !== 'object') return DEFAULT_SOURCES;
+  const configured = prefs.statusMonSources;
+  if (!Array.isArray(configured) || configured.length === 0) return DEFAULT_SOURCES;
+  const valid = configured.filter((s) =>
+    s && typeof s.id === 'string' && typeof s.name === 'string' && typeof s.url === 'string',
+  );
+  return valid.length > 0 ? valid : DEFAULT_SOURCES;
+}

package/dist/engineering-pa-workspace/src/status-mon/poller.mjs

@@ -0,0 +1,113 @@
+/**
+ * poller.mjs — Server-side poller lifecycle for the workspace.
+ *
+ * The workspace server imports `startPoller({ repoRoot })` on boot. The
+ * returned handle exposes `stop()` for graceful shutdown. The poller writes
+ * the shared state file every `intervalMs` (default 60s); the banner client
+ * reads it via the /__api/status-mon endpoint.
+ *
+ * This module lives alongside poll.mjs so the (A) server-side integration
+ * and the (B) CLI path share the exact same polling + normalisation logic.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { poll, resolveSources, mergeWithPrevious } from './poll.mjs';
+
+const DEFAULT_INTERVAL_MS = 60_000;
+
+function readPreferences(repoRoot) {
+  try {
+    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (!existsSync(prefsPath)) return null;
+    return JSON.parse(readFileSync(prefsPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function readState(statePath) {
+  try {
+    if (!existsSync(statePath)) return null;
+    return JSON.parse(readFileSync(statePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(statePath, state) {
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Start the poller loop.
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot        Absolute path to project root.
+ * @param {number} [options.intervalMs]    Poll cadence (default 60s).
+ * @param {string} [options.statePath]     Override state file location.
+ * @param {Function} [options.fetcher]     Injected fetcher (default globalThis.fetch).
+ * @param {Function} [options.onError]     Called on unexpected poll errors.
+ * @param {boolean} [options.runImmediately] If true, runs the first poll now (default true).
+ * @returns {{ stop: () => void, triggerNow: () => Promise<object> }}
+ */
+export function startPoller(options) {
+  const repoRoot = options.repoRoot;
+  if (!repoRoot) throw new Error('startPoller: repoRoot is required');
+  const intervalMs = options.intervalMs || DEFAULT_INTERVAL_MS;
+  const statePath = options.statePath || join(repoRoot, '.state', 'status-mon.json');
+  const fetcher = options.fetcher || globalThis.fetch;
+  const onError = options.onError || function () {};
+  const runImmediately = options.runImmediately !== false;
+
+  let stopped = false;
+  let timer = null;
+  let inflight = null;
+
+  async function runOnce() {
+    if (stopped) return null;
+    try {
+      const prefs = readPreferences(repoRoot);
+      const sources = resolveSources(prefs);
+      const previous = readState(statePath);
+      const fresh = await poll({ sources, fetcher, nowMs: Date.now() });
+      const state = mergeWithPrevious(previous, fresh);
+      writeState(statePath, state);
+      return state;
+    } catch (err) {
+      try { onError(err); } catch { /* user hook must not crash the loop */ }
+      return null;
+    }
+  }
+
+  function schedule() {
+    if (stopped) return;
+    timer = setTimeout(async function tick() {
+      inflight = runOnce();
+      try { await inflight; } finally { inflight = null; schedule(); }
+    }, intervalMs);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  }
+
+  function triggerNow() {
+    inflight = runOnce();
+    return inflight;
+  }
+
+  if (runImmediately) {
+    // Kick off a first poll out-of-band so the banner has data before the
+    // first interval elapses. We don't await — boot shouldn't block on
+    // network. The result lands in the state file when it's ready.
+    triggerNow();
+  }
+  schedule();
+
+  return {
+    stop() {
+      stopped = true;
+      if (timer) { clearTimeout(timer); timer = null; }
+    },
+    triggerNow,
+  };
+}

package/dist/engineering-pa-workspace/src/status-mon/run.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * run.mjs — One-shot CLI wrapper for the status-mon poller.
+ *
+ * Writes the state file to $DAVE_ROOT/.state/status-mon.json by default.
+ * Intended to be invoked either:
+ *   - directly on a schedule (schedules/status-mon.json) via the OS scheduler
+ *   - by tests (via `--out <path>` to redirect the write target)
+ *
+ * The workspace server's server-side integration (see server.mjs / poller.mjs)
+ * imports poll.mjs directly rather than spawning this script, because it
+ * already has the repo root resolved and the in-memory state is cheaper than
+ * a subprocess round-trip.
+ *
+ *   run.mjs              Run a live poll against configured sources.
+ *   run.mjs --dry-run    Fetch, write to stdout as JSON, don't touch fs.
+ *   run.mjs --out PATH   Write state to PATH (overrides default).
+ *   run.mjs --help       Show this help.
+ *
+ * Environment:
+ *   DAVE_ROOT   Override the project root (default: derived by walking up to .git).
+ *
+ * Exit codes: 0 ok | 1 usage | 2 fetch failure (all sources) | 3 write failure
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { poll, resolveSources, mergeWithPrevious } from './poll.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function printHelp() {
+  const help = [
+    'Usage: run.mjs [--dry-run] [--out PATH] [--help]',
+    '',
+    'Polls configured Statuspage.io sources and writes a state file.',
+    '',
+    'Default output path: $DAVE_ROOT/.state/status-mon.json',
+    'Override sources via operator/config/preferences.json (statusMonSources).',
+  ].join('\n');
+  process.stdout.write(help + '\n');
+}
+
+function parseArgs(argv) {
+  const out = { dryRun: false, help: false, outPath: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') out.help = true;
+    else if (arg === '--dry-run') out.dryRun = true;
+    else if (arg === '--out') { out.outPath = argv[++i]; }
+    else {
+      process.stderr.write(`unknown argument: ${arg}\n`);
+      return null;
+    }
+  }
+  return out;
+}
+
+function findRepoRoot() {
+  if (process.env.DAVE_ROOT) return process.env.DAVE_ROOT;
+  let dir = __dirname;
+  while (dir !== '/' && dir !== '.') {
+    if (existsSync(join(dir, '.git'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(__dirname, '..', '..', '..');
+}
+
+function readPreviousState(statePath) {
+  try {
+    if (!existsSync(statePath)) return null;
+    const raw = readFileSync(statePath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function readPreferences(repoRoot) {
+  try {
+    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (!existsSync(prefsPath)) return null;
+    return JSON.parse(readFileSync(prefsPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed) { printHelp(); process.exit(1); }
+  if (parsed.help) { printHelp(); process.exit(0); }
+
+  const repoRoot = findRepoRoot();
+  const prefs = readPreferences(repoRoot);
+  const sources = resolveSources(prefs);
+  const outPath = parsed.outPath || join(repoRoot, '.state', 'status-mon.json');
+
+  const previous = parsed.dryRun ? null : readPreviousState(outPath);
+  const fresh = await poll({
+    sources,
+    fetcher: globalThis.fetch,
+    nowMs: Date.now(),
+  });
+  const state = mergeWithPrevious(previous, fresh);
+
+  const allFailed = state.sources.every((s) => s.fetchError);
+
+  if (parsed.dryRun) {
+    process.stdout.write(JSON.stringify(state, null, 2) + '\n');
+    process.exit(allFailed && !state.lastSuccessfulPollAt ? 2 : 0);
+  }
+
+  try {
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+  } catch (err) {
+    process.stderr.write(`write failed: ${err.message}\n`);
+    process.exit(3);
+  }
+
+  process.exit(allFailed && !state.lastSuccessfulPollAt ? 2 : 0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`unexpected: ${err && err.stack ? err.stack : err}\n`);
+  process.exit(1);
+});