@polderlabs/bizar 10.7.2 → 10.11.0

package/bizar-dash/src/server/otel.mjs

@@ -1,260 +0,0 @@
-/**
- * src/server/otel.mjs
- *
- * v5.1.0 — Expanded OpenTelemetry tracing surface for the Bizar dashboard.
- *
- * Initialises the NodeSDK with an OTLP HTTP trace exporter and exposes:
- *   - `tracer`                        — the shared tracer instance
- *   - `initOtel()` / `shutdownOtel()` — SDK lifecycle (off by default)
- *   - `withSpan(name, fn, attrs)`     — ergonomic wrapper that records
- *                                       OK on success, ERROR+exception
- *                                       on throw, and ends the span in
- *                                       every code path
- *   - `setCommonAttributes(span, …)`  — fast-path for the recurring
- *                                       user/workspace/ip/ua attributes
- *                                       that 95% of route spans set
- *
- * Auto-instrumentation is intentionally NOT enabled. The dashboard
- * already has structured logger + Prometheus for the "what" metrics, so
- * distributed tracing is only interesting for the multi-step flows
- * where request correlation matters (chat SSE pump, cline session
- * creation, plugin install, workspace invites, etc).
- *
- * Off by default. Enable with one of:
- *   BIZAR_OTEL=1
- *   OTEL_ENABLED=1
- *   OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318/v1/traces   (also opts in)
- *
- * `shutdownOtel()` flushes any pending spans and tears down the SDK.
- * It is idempotent and safe to call multiple times — subsequent calls
- * are a no-op once the SDK has been shut down.
- *
- * The NodeSDK constructor is wrapped in try/catch so that a malformed
- * OTLP endpoint or missing optional binding (e.g. test runs that
- * import this module but never call `initOtel`) does not crash the
- * dashboard.
- */
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { Resource } from '@opentelemetry/resources';
-import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
-import { SpanStatusCode, trace } from '@opentelemetry/api';
-import os from 'node:os';
-import { info as logInfo, warn as logWarn } from './logger.mjs';
-
-const DEFAULT_OTLP_ENDPOINT = 'http://localhost:4318/v1/traces';
-const SERVICE_NAME = 'bizar-dash';
-const SERVICE_NAMESPACE = 'bizar';
-const TRACER_NAME = 'bizar-dash';
-const TRACER_VERSION = '0.1.0';
-
-let sdk = null;
-let shuttingDown = false;
-
-/**
- * The shared tracer used by route handlers. Bound to the global
- * tracer provider — when OTEL is not enabled this resolves to a
- * no-op tracer (a `startActiveSpan` call still returns a valid span
- * object whose methods are all no-ops), so route handlers do not
- * need a feature flag of their own.
- */
-export const tracer = trace.getTracer(TRACER_NAME, TRACER_VERSION);
-
-/**
- * Build the OTel resource attributes for this dashboard process.
- *
- * Used both at SDK init time (so a collector sees deployment
- * context) and exposed via `getResourceAttributes()` for any
- * consumer that needs the same metadata on a per-span basis.
- *
- * @returns {Record<string, string|number>}
- */
-export function getResourceAttributes() {
-  return {
-    [SemanticResourceAttributes.SERVICE_NAME]: SERVICE_NAME,
-    [SemanticResourceAttributes.SERVICE_VERSION]:
-      process.env.npm_package_version || '0.0.0',
-    [SemanticResourceAttributes.SERVICE_NAMESPACE]: SERVICE_NAMESPACE,
-    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]:
-      process.env.NODE_ENV || 'development',
-    [SemanticResourceAttributes.PROCESS_PID]: process.pid,
-    [SemanticResourceAttributes.HOST_NAME]: os.hostname(),
-    [SemanticResourceAttributes.OS_VERSION]: `${os.platform()} ${os.release()}`,
-  };
-}
-
-/**
- * Initialise the NodeSDK with an OTLP HTTP trace exporter. Safe to
- * call multiple times — the second call returns the cached SDK.
- *
- * `npm_package_version` is set by `npm run` contexts; in any other
- * context we fall back to '0.0.0'. The version is informational
- * (the OTLP collector shows it in the resource panel), so failing to
- * read it is never a startup blocker.
- *
- * @param {object} [opts]
- * @param {string} [opts.serviceName]  Override SERVICE_NAME (default 'bizar-dash')
- * @param {string} [opts.endpoint]     OTLP HTTP traces endpoint
- * @returns {object|null}              The NodeSDK instance, or null on failure
- */
-export function initOtel({
-  serviceName = SERVICE_NAME,
-  endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_OTLP_ENDPOINT,
-} = {}) {
-  if (sdk) return sdk;
-  if (shuttingDown) return null;
-  try {
-    const attrs = getResourceAttributes();
-    if (serviceName !== SERVICE_NAME) attrs[SemanticResourceAttributes.SERVICE_NAME] = serviceName;
-    sdk = new NodeSDK({
-      resource: new Resource(attrs),
-      traceExporter: new OTLPTraceExporter({ url: endpoint }),
-    });
-    sdk.start();
-    logInfo('OpenTelemetry initialised', {
-      module: 'otel',
-      serviceName,
-      endpoint,
-      namespace: SERVICE_NAMESPACE,
-      deployment: process.env.NODE_ENV || 'development',
-    });
-    return sdk;
-  } catch (err) {
-    logWarn('OpenTelemetry init failed; continuing without tracing', {
-      module: 'otel',
-      err: err?.message || String(err),
-    });
-    sdk = null;
-    return null;
-  }
-}
-
-/**
- * Flush pending spans and shut down the SDK. Idempotent.
- *
- * Designed to be wired into the dashboard's SIGTERM/SIGINT handler
- * so spans in flight at shutdown are not silently dropped. Tests
- * call this between scenarios to keep registry state clean.
- *
- * @returns {Promise<void>}
- */
-export async function shutdownOtel() {
-  if (!sdk) return;
-  if (shuttingDown) return;
-  shuttingDown = true;
-  try {
-    await sdk.shutdown();
-  } catch (err) {
-    logWarn('OpenTelemetry shutdown failed', {
-      module: 'otel',
-      err: err?.message || String(err),
-    });
-  } finally {
-    sdk = null;
-    shuttingDown = false;
-  }
-}
-
-/**
- * Test-only: return whether the SDK is currently initialised. Lets
- * tests assert that initOtel really did instantiate the SDK without
- * having to introspect private state from outside.
- *
- * @returns {boolean}
- */
-export function isOtelEnabled() {
-  return sdk !== null;
-}
-
-/**
- * Run `fn` inside an active span on the shared tracer.
- *
- * The helper:
- *   - opens a span with the given name and pre-bound attributes;
- *   - awaits the user callback (which receives the span as its
- *     last argument, after `(req, res)` in route handlers, or as
- *     the only argument in free-standing helpers);
- *   - sets the span status to OK on success;
- *   - on throw: records the exception and sets ERROR status before
- *     rethrowing so the original error propagates to `wrap()` /
- *     `next(err)` exactly as if the helper were not used;
- *   - ends the span in a finally block so a thrown error from the
- *     callback cannot leak the span.
- *
- * `withSpan` works under both the live SDK and the no-op tracer
- * shipped when OTEL is disabled — every span method is a no-op then
- * and the callback's return value is what callers see.
- *
- * @template T
- * @param {string} name
- * @param {(span: import('@opentelemetry/api').Span, ...args: any[]) => Promise<T>|T} fn
- * @param {Record<string, string|number|boolean>} [attributes]
- * @returns {(...args: any[]) => Promise<T>}
- */
-export function withSpan(name, fn, attributes = {}) {
-  return (...args) => tracer.startActiveSpan(name, { attributes }, async (span) => {
-    try {
-      const result = await fn(span, ...args);
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (err) {
-      try {
-        span.recordException(err);
-      } catch {
-        /* no-op tracer swallows everything */
-      }
-      try {
-        span.setStatus({
-          code: SpanStatusCode.ERROR,
-          message: err?.message || String(err),
-        });
-      } catch {
-        /* ignore */
-      }
-      throw err;
-    } finally {
-      try {
-        span.end();
-      } catch {
-        /* never re-throw inside OTel helpers */
-      }
-    }
-  });
-}
-
-/**
- * Apply the common request-scoped attributes most route spans want:
- * user/workspace identity, plus the OTel HTTP semantic conventions
- * for the client IP and user-agent string.
- *
- * Each attribute is set independently and only if a value was
- * provided; passing `undefined`/`null`/empty string skips the
- * attribute so spans for public endpoints don't get an empty
- * `bizar.user.id = ""` cluttering the trace UI.
- *
- * Attribute naming rationale:
- *   - `bizar.user.id`       — namespaced custom key (avoids colliding
- *                             with any future OTel `enduser.id`)
- *   - `bizar.workspace.id`  — namespaced custom key
- *   - `http.client_ip`      — OTel HTTP semantic convention
- *   - `http.user_agent`     — OTel HTTP semantic convention (the
- *                             spec later renamed this to
- *                             `user_agent.original`; the dashboard
- *                             keeps `http.user_agent` because the
- *                             v4.x dashboards in production still
- *                             search by that key)
- *
- * @param {import('@opentelemetry/api').Span} span
- * @param {object} opts
- * @param {string} [opts.userId]
- * @param {string} [opts.workspaceId]
- * @param {string} [opts.ip]
- * @param {string} [opts.userAgent]
- */
-export function setCommonAttributes(span, { userId, workspaceId, ip, userAgent } = {}) {
-  if (!span) return;
-  if (userId) span.setAttribute('bizar.user.id', userId);
-  if (workspaceId) span.setAttribute('bizar.workspace.id', workspaceId);
-  if (ip) span.setAttribute('http.client_ip', ip);
-  if (userAgent) span.setAttribute('http.user_agent', userAgent);
-}

package/bizar-dash/src/server/pair-store.mjs

@@ -1,138 +0,0 @@
-/**
- * src/server/pair-store.mjs
- *
- * v3.5.2 — Pairing token store for the Bizar Companion mobile app.
- *
- * Generates short-lived bearer tokens that the dashboard issues when a user
- * taps "Pair Device" in the Settings view (or runs the TUI / pair CLI).
- * The companion app scans a QR code containing:
- *
- *   bizar://pair?url=<publicUrl>&token=<token>
- *
- * …then calls `GET /api/pair/verify` with the token. On success the
- * companion stores the URL + token in expo-secure-store and uses it as a
- * Bearer header for all subsequent API + WebSocket calls.
- *
- * Tokens are stored in memory only — a server restart invalidates all
- * outstanding tokens. The TTL is 5 minutes, which is enough for the user
- * to open the app, scan, and verify.
- */
-import { randomBytes } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-
-/** @typedef {{ token: string, expiresAt: number, publicUrl: string }} PairToken */
-
-/** @type {Map<string, PairToken>} */
-const tokens = new Map();
-
-const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
-
-function gc() {
-  const now = Date.now();
-  for (const [tok, entry] of tokens) {
-    if (entry.expiresAt <= now) tokens.delete(tok);
-  }
-}
-
-/**
- * Mint a fresh pairing token bound to a public URL.
- * @param {string} publicUrl - URL the companion app should hit (https://... or http://localhost:...)
- * @param {number} [ttlMs] - milliseconds until expiry
- * @returns {PairToken & { qrPayload: string }}
- */
-export function mint(publicUrl, ttlMs = DEFAULT_TTL_MS) {
-  gc();
-  const token = `pair_${randomBytes(24).toString('base64url')}`;
-  const expiresAt = Date.now() + ttlMs;
-  const entry = { token, expiresAt, publicUrl };
-  tokens.set(token, entry);
-  return {
-    ...entry,
-    qrPayload: `bizar://pair?url=${encodeURIComponent(publicUrl)}&token=${encodeURIComponent(token)}`,
-  };
-}
-
-/**
- * Verify a Bearer token. Returns the entry on success, null on failure.
- * @param {string | null | undefined} token
- * @returns {PairToken | null}
- */
-export function verify(token) {
-  if (!token || typeof token !== 'string') return null;
-  const entry = tokens.get(token);
-  if (!entry) return null;
-  if (entry.expiresAt <= Date.now()) {
-    tokens.delete(token);
-    return null;
-  }
-  return entry;
-}
-
-/**
- * Express middleware: if the request carries a valid Bearer pair token,
- * set `req.pairToken` and `req.pairEntry`. Does NOT block unauthenticated
- * requests — the dashboard itself doesn't require auth; this middleware
- * just enriches the request so other handlers can recognize paired clients.
- */
-export function pairTokenMiddleware(req, _res, next) {
-  const auth = req.headers.authorization;
-  if (!auth || !auth.startsWith('Bearer ')) {
-    req.pairToken = null;
-    req.pairEntry = null;
-    return next();
-  }
-  const token = auth.slice(7).trim();
-  const entry = verify(token);
-  req.pairToken = entry ? token : null;
-  req.pairEntry = entry;
-  next();
-}
-
-/**
- * Detect the URL the companion app should hit. Preference order:
- *   1. Tailscale MagicDNS hostname from `tailscale.json` (if enabled)
- *   2. The Host header from the current request (so localhost works in dev)
- *   3. localhost on the configured port
- *
- * @param {import('express').Request} req
- * @param {number} port
- * @returns {string}
- */
-export function detectPublicUrl(req, port) {
-  // 1. Tailscale config (best for phone-over-WiFi)
-  try {
-    const cfgPath = join(homedir(), '.config', 'bizar', 'tailscale.json');
-    if (existsSync(cfgPath)) {
-      const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
-      if (cfg?.enabled && cfg?.hostname) {
-        const proto = cfg.https === false ? 'http' : 'https';
-        return `${proto}://${cfg.hostname}`;
-      }
-    }
-  } catch {
-    /* fall through */
-  }
-
-  // 2. Host header from the current request
-  const host = (req?.headers?.host || '').toString().trim();
-  if (host && /^[A-Za-z0-9.:[\]-]+$/.test(host) && !host.startsWith('127.0.0.1') && !host.startsWith('localhost')) {
-    const rawProto = (req?.headers?.['x-forwarded-proto'] || req?.protocol || 'http').toString().split(',')[0].trim().toLowerCase();
-    const proto = rawProto === 'https' ? 'https' : 'http';
-    return `${proto}://${host}`;
-  }
-
-  // 3. localhost fallback
-  return `http://localhost:${port}`;
-}
-
-export const pairStore = {
-  mint,
-  verify,
-  detectPublicUrl,
-  middleware: pairTokenMiddleware,
-  /** For tests / introspection only. */
-  _size: () => tokens.size,
-  _clear: () => tokens.clear(),
-};

package/bizar-dash/src/server/progress-parser.test.mjs

@@ -1,129 +0,0 @@
-/**
- * src/server/progress-parser.test.mjs
- *
- * Sprint S10 — Unit tests for progress-parser.mjs.
- * Uses node:test (matches the existing `cli/__tests__/*.test.mjs` pattern
- * shipped across the harness — no vitest/jsdom dependency).
- */
-
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import { parseProgress, serializeProgress } from './progress-parser.mjs';
-
-test('empty input → empty goals + empty preamble', () => {
-  const r = parseProgress('');
-  assert.equal(r.goals.length, 0);
-  assert.equal(r.preamble, '');
-  assert.equal(r.postamble, '');
-});
-
-test('parses single F-NNN header with status + progress + owner', () => {
-  const text = `# Title\n\nIntro line.\n\n## F-052 — Ship dashboard\nOwner: sam\nDue: Q3 2026\n\nGoal is **at-risk**. About 42% done.\n\nKey results:\n- [x] First KR\n- [ ] Second KR (@alex)\n`;
-  const r = parseProgress(text);
-  assert.equal(r.goals.length, 1);
-  const g = r.goals[0];
-  assert.equal(g.id, 'F-052');
-  assert.equal(g.title, 'Ship dashboard');
-  assert.equal(g.status, 'at-risk');
-  assert.equal(g.owner, 'sam');
-  assert.equal(g.due, 'Q3 2026');
-  assert.equal(g.keyResults.length, 2);
-  assert.equal(g.keyResults[0].done, true);
-  assert.equal(g.keyResults[1].done, false);
-  assert.equal(g.keyResults[1].assignee, 'alex');
-  assert.equal(g.progress, 0.5);
-});
-
-test('parses bare title (no F-NNN id)', () => {
-  const r = parseProgress('## Cut S9 polish in half\nGoal is **on-track**.\n');
-  assert.equal(r.goals.length, 1);
-  assert.equal(r.goals[0].id, 'cut-s9-polish-in-half');
-  assert.equal(r.goals[0].title, 'Cut S9 polish in half');
-});
-
-test('multi-goal preserves preamble and orders', () => {
-  const text = `# Header\nPreamble line.\n\n## F-001 — One\nGoal is **done**.\n\n## F-002 — Two\nGoal is **active**. 25%.\n\n## F-003 — Three\nGoal is **blocked**.\n`;
-  const r = parseProgress(text);
-  assert.equal(r.goals.length, 3);
-  assert.equal(r.goals[0].id, 'F-001');
-  assert.equal(r.goals[0].status, 'done');
-  assert.equal(r.goals[1].status, 'active');
-  assert.equal(r.goals[2].status, 'blocked');
-  assert.ok(r.preamble.includes('Preamble line.'));
-});
-
-test('progress derives from KRs when no % present', () => {
-  const text = '## F-A — Title\n- [x] a\n- [x] b\n- [ ] c\n- [ ] d\n';
-  const r = parseProgress(text);
-  assert.equal(r.goals[0].progress, 0.5);
-});
-
-test('unknown status defaults to on-track', () => {
-  const r = parseProgress('## F-X — Title\nNo status marker here.\n');
-  assert.equal(r.goals[0].status, 'on-track');
-});
-
-test('serialise round-trips goal + KR structure', () => {
-  const parsed = {
-    preamble: '# Header\n',
-    postamble: '',
-    goals: [
-      {
-        id: 'F-052',
-        title: 'Ship dashboard',
-        status: 'at-risk',
-        description: 'Description body.',
-        progress: 0.5,
-        keyResults: [
-          { id: 'kr-1', title: 'First KR', done: true },
-          { id: 'kr-2', title: 'Second KR', done: false, assignee: 'alex' },
-        ],
-        owner: 'sam',
-        due: 'Q3 2026',
-        section: 'in-progress',
-      },
-    ],
-  };
-  const out = serializeProgress(parsed);
-  assert.ok(out.includes('## F-052 — Ship dashboard'));
-  assert.ok(out.includes('Owner: sam'));
-  assert.ok(out.includes('Goal is **at-risk**.'));
-  assert.ok(out.includes('- [x] First KR'));
-  assert.ok(out.includes('- [ ] Second KR (@alex)'));
-});
-
-test('serialise preserves preamble verbatim', () => {
-  const parsed = {
-    preamble: '# Title\n\nIntro stays here.\n\n',
-    postamble: '\n## Footnotes\nThis stays too.\n',
-    goals: [],
-  };
-  const out = serializeProgress(parsed);
-  assert.ok(out.startsWith('# Title'));
-  assert.ok(out.includes('Intro stays here.'));
-  assert.ok(out.includes('## Footnotes'));
-});
-
-// v10-S3 — bug: parse → mutate status → serialise → re-parse must preserve
-// the new status. Previously, the original `Goal is **<old>**` line was
-// captured into goal.description during parse and serialised back
-// underneath the freshly-emitted status line, so the second match won on
-// re-parse and the status mutation silently no-op'd.
-test('v10-S3 — parse → mutate status → serialise → re-parse preserves new status', () => {
-  const text = `## G-003 — Write integration E2E (Sprint S3 Next Steps)
-
-Goal is **blocked**
-
-Final open: cross-boundary agent ↔ restart roundtrip.
-`;
-  const parsed = parseProgress(text);
-  assert.equal(parsed.goals[0].status, 'blocked');
-  parsed.goals[0].status = 'on-track';
-  const out = serializeProgress(parsed);
-  const reread = parseProgress(out);
-  assert.equal(reread.goals[0].status, 'on-track',
-    `expected on-track after round-trip, got ${reread.goals[0].status}; out was:\n${out}`);
-  // And the file must contain exactly one status line per goal.
-  const statusLines = out.split('\n').filter((l) => /Goal is \*\*[a-z-]+\*\*/i.test(l));
-  assert.equal(statusLines.length, 1, `expected 1 status line, got ${statusLines.length}`);
-});