@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/otel.mjs

@@ -0,0 +1,260 @@
+/**
+ * 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/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/pair-store.mjs

@@ -0,0 +1,138 @@
+/**
+ * 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/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/progress-parser.mjs

@@ -0,0 +1,221 @@
+/**
+ * src/server/progress-parser.mjs
+ *
+ * Sprint S10 — Parse `.bizar/PROGRESS.md` into a structured goal list
+ * for the v8 dashboard.
+ *
+ * Goals are the `## F-NNN — Title` (or `## Some — Title`) headings.
+ * Each goal's status is parsed from the first paragraph:
+ *   "Goal is **on-track**" / "**at-risk**" / "**done**" / "**blocked**"
+ * Key results are `- [ ] text` / `- [x] text` lines inside the goal block.
+ * `Owner:` / `Due:` lines are extracted from the goal header lines.
+ *
+ * Pure: no I/O. Callers pass the raw text in. Deterministic.
+ *
+ * Reuses none — there is no existing goal state in the dashboard.
+ */
+
+const STATUS_VALUES = new Set([
+  'on-track',
+  'at-risk',
+  'off-track',
+  'done',
+  'blocked',
+  'active',
+]);
+
+/**
+ * Parse raw PROGRESS.md content into a structured goal list.
+ *
+ * @param {string} text  raw file content
+ * @returns {{
+ *   goals: Array<{
+ *     id: string,
+ *     title: string,
+ *     status: string,
+ *     description: string,
+ *     progress: number,
+ *     keyResults: Array<{ id: string, title: string, done: boolean, assignee?: string }>,
+ *     due?: string,
+ *     owner?: string,
+ *     section: 'in-progress' | 'next' | 'recent' | 'backlog' | 'unknown'
+ *   }>,
+ *   preamble: string,
+ *   postamble: string
+ * }}
+ */
+export function parseProgress(text) {
+  if (typeof text !== 'string' || !text) {
+    return { goals: [], preamble: '', postamble: '' };
+  }
+  const lines = text.split(/\r?\n/);
+  /** @type {ReturnType<typeof parseProgress>['goals']} */
+  const goals = [];
+  let preamble = '';
+  let current = null;
+  let currentSection = 'unknown';
+  let postambleStart = -1;
+
+  function pushCurrent() {
+    if (current) {
+      // finalise: derive progress from KRs
+      const done = current.keyResults.filter((kr) => kr.done).length;
+      current.progress = current.keyResults.length > 0
+        ? done / current.keyResults.length
+        : current.progress || 0;
+      current.section = currentSection;
+      goals.push(current);
+      current = null;
+    }
+  }
+
+  let i = 0;
+  // preamble — everything before the first `## ` heading.
+  while (i < lines.length && !lines[i].startsWith('## ')) {
+    preamble += lines[i] + '\n';
+    i += 1;
+  }
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.startsWith('## ')) {
+      pushCurrent();
+      const headerText = line.slice(3).trim();
+      const { id, title } = parseHeader(headerText);
+      current = {
+        id,
+        title,
+        status: 'on-track',
+        description: '',
+        progress: 0,
+        keyResults: [],
+        section: currentSection,
+      };
+      currentSection = inferSection(text, i, headerText);
+      i += 1;
+      continue;
+    }
+    if (!current) {
+      // Lines between sections — accumulate into preamble/postamble.
+      if (goals.length === 0) preamble += line + '\n';
+      else { postambleStart = postambleStart === -1 ? i : postambleStart; }
+      i += 1;
+      continue;
+    }
+    // Body lines under the current goal.
+    const kr = parseKeyResultLine(line);
+    if (kr) {
+      current.keyResults.push({ id: `kr-${current.id}-${current.keyResults.length + 1}`, ...kr });
+      i += 1;
+      continue;
+    }
+    const ownerMatch = /^owner:\s*([^\n]+)/i.exec(line);
+    if (ownerMatch) {
+      current.owner = ownerMatch[1].trim();
+      i += 1;
+      continue;
+    }
+    const dueMatch = /\bdue\s*:?\s*([^\n,;]+)/i.exec(line);
+    if (dueMatch && !current.due) {
+      current.due = dueMatch[1].trim();
+    }
+    const statusMatch = /\*\*\s*(on-track|at-risk|off-track|done|blocked|active)\s*\*\*/i.exec(line);
+    if (statusMatch && current.status === 'on-track') {
+      current.status = statusMatch[1].toLowerCase();
+    }
+    const pctMatch = /(\d{1,3})\s*%/.exec(line);
+    if (pctMatch && current.progress === 0) {
+      const pct = Math.max(0, Math.min(100, parseInt(pctMatch[1], 10)));
+      current.progress = pct / 100;
+    }
+    if (line.trim()) current.description = appendLine(current.description, line);
+    i += 1;
+  }
+  pushCurrent();
+
+  const postamble = postambleStart === -1 ? '' : lines.slice(postambleStart).join('\n');
+  return { goals, preamble: preamble.trimEnd() + '\n', postamble };
+}
+
+/**
+ * Parse the header text — `"F-052 — Title"`, `"Some title"`, or
+ * `"## Title with — em-dash"`. Returns a stable id derived from the
+ * header (or a slug fallback).
+ */
+function parseHeader(headerText) {
+  const m = /^([A-Za-z0-9_-]+)\s*[—\-]\s*(.+)$/.exec(headerText);
+  if (m) return { id: m[1], title: m[2].trim() };
+  const id = slugify(headerText);
+  return { id, title: headerText };
+}
+
+function slugify(s) {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64) || 'goal';
+}
+
+function inferSection(fullText, headerIndex, headerText) {
+  // Look back for a section divider (`### In Progress`, etc.).
+  const before = fullText.slice(0, fullText.indexOf(headerText));
+  if (/In Progress/i.test(before.slice(-200))) return 'in-progress';
+  if (/Next Steps?/i.test(before.slice(-200))) return 'next';
+  if (/Recent/i.test(before.slice(-200))) return 'recent';
+  if (/Backlog|Blockers/i.test(before.slice(-200))) return 'backlog';
+  return 'unknown';
+}
+
+function parseKeyResultLine(line) {
+  const m = /^\s*-\s+\[(x|X| )\]\s+(.+)$/.exec(line);
+  if (!m) return null;
+  const done = m[1].toLowerCase() === 'x';
+  const rest = m[2].trim();
+  const assignee = /\(@([a-z0-9_-]+)\)\s*$/.exec(rest);
+  return {
+    title: assignee ? rest.slice(0, assignee.index).trim() : rest,
+    done,
+    assignee: assignee ? assignee[1] : undefined,
+  };
+}
+
+function appendLine(current, line) {
+  if (!current) return line.trim();
+  return current + '\n' + line.trim();
+}
+
+/**
+ * Serialise a goal list back to PROGRESS.md-shaped text. Preserves the
+ * preamble and postamble so non-goal sections (Current State, etc.)
+ * aren't clobbered.
+ *
+ * @param {ReturnType<typeof parseProgress>} parsed
+ * @returns {string}
+ */
+export function serializeProgress(parsed) {
+  const out = [];
+  if (parsed.preamble) out.push(parsed.preamble.trimEnd());
+  for (const goal of parsed.goals) {
+    out.push(`## ${goal.id} — ${goal.title}`);
+    if (goal.owner || goal.due) {
+      const meta = [];
+      if (goal.owner) meta.push(`Owner: ${goal.owner}`);
+      if (goal.due) meta.push(`Due: ${goal.due}`);
+      out.push(meta.join(' · '));
+    }
+    out.push(`Goal is **${goal.status}**.`);
+    if (goal.description) out.push(goal.description);
+    if (goal.keyResults.length) {
+      out.push('Key results:');
+      for (const kr of goal.keyResults) {
+        const assignee = kr.assignee ? ` (@${kr.assignee})` : '';
+        out.push(`- [${kr.done ? 'x' : ' '}] ${kr.title}${assignee}`);
+      }
+    }
+    out.push('');
+  }
+  if (parsed.postamble) out.push(parsed.postamble.trimEnd());
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
+export const _internals = { STATUS_VALUES };