@volter/twin-sentry 0.1.0

package/dist/src/sentry-mirror-ui.js

@@ -0,0 +1,162 @@
+// Sentry MIRROR UI — a Sentry-dashboard-like view served as a React/TSX app (Bun-bundled,
+// the repo convention). It renders by consuming the twin's OWN Web API on the same origin
+// (/api/0/...) — the same endpoints a real client uses. API↔UI parity: every screen is
+// backed by real twin state, never a hand-made fixture.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the
+// pack's OWN fetch adapter (createSentryTwinFetch) as its API backend and reads every byte
+// of state back over the wire, exactly as a browser does.
+//
+// The pure format/level helpers live here so they can be unit-tested AND shared by the
+// React client (Bun tree-shakes the server-only exports out of the browser bundle).
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createSentryTwinFetch } from "./sentry-server.js";
+import { DEFAULT_ORG, DEFAULT_PROJECT } from "./sentry-ingest.js";
+const CLIENT_ENTRY = () => new URL('../client/sentry-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/sentry-mirror.css', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+/** Map a Sentry level to a UI tone class. */
+export function levelTone(level) {
+    const l = String(level ?? '').toLowerCase();
+    if (l === 'fatal' || l === 'error' || l === 'warning' || l === 'info' || l === 'debug')
+        return l;
+    return 'muted';
+}
+/** Map an issue status to a UI tone class. */
+export function statusTone(status) {
+    const s = String(status ?? '').toLowerCase();
+    if (s === 'resolved')
+        return 'resolved';
+    if (s === 'ignored' || s === 'muted')
+        return 'ignored';
+    if (s === 'unresolved')
+        return 'unresolved';
+    return 'muted';
+}
+/** "12.3k", "1.2M", "999" — Sentry's compact event-count formatting. */
+export function formatCount(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return '0';
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1).replace(/\.0$/, '')}k`;
+    return String(Math.trunc(n));
+}
+/** Relative "time ago" for a lastSeen/firstSeen ISO string (deterministic given `now`). */
+export function timeAgo(iso, now = Date.now()) {
+    if (typeof iso !== 'string' || !iso)
+        return '—';
+    const t = Date.parse(iso);
+    if (Number.isNaN(t))
+        return '—';
+    const s = Math.max(0, Math.floor((now - t) / 1000));
+    if (s < 60)
+        return `${s}s ago`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m ago`;
+    if (s < 86400)
+        return `${Math.floor(s / 3600)}h ago`;
+    return `${Math.floor(s / 86400)}d ago`;
+}
+export function latestStacktrace(event) {
+    if (!event || typeof event !== 'object')
+        return [];
+    const entries = event.entries;
+    if (!Array.isArray(entries))
+        return [];
+    const ex = entries.find((e) => e && typeof e === 'object' && e.type === 'exception');
+    const values = ex && ex.data?.values;
+    if (!Array.isArray(values))
+        return [];
+    const top = values[values.length - 1];
+    const frames = top?.stacktrace?.frames;
+    return Array.isArray(frames) ? frames : [];
+}
+/** The event's tags as a flat [key,value] list for rendering. */
+export function eventTags(event) {
+    if (!event || typeof event !== 'object')
+        return [];
+    const tags = event.tags;
+    if (!Array.isArray(tags))
+        return [];
+    return tags
+        .filter((t) => t && typeof t === 'object')
+        .map((t) => ({ key: String(t.key), value: String(t.value) }));
+}
+// ---------------------------------------------------------------------------
+// Server-only: bundle the React client + serve it alongside the twin Web API.
+// ---------------------------------------------------------------------------
+let clientBundle = null;
+export function buildSentryMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY())
+            .catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+const APP_SHELL = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <base href="/"><title>Sentry (twin)</title>
+    <link rel="stylesheet" href="assets/styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="assets/app.js"></script>
+  </body>
+</html>`;
+/** Serve the Sentry dashboard mirror UI (React app) + its backing Web API. */
+export async function createSentryMirrorServer(options = {}) {
+    const twin = createSentryTwinFetch(options);
+    const server = await serveHttp({
+        // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+        // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+        // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+        // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+        // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+        // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+        // on loopback, so the verify's fetches deterministically reach THIS server.
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+                try {
+                    return new Response(await buildSentryMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+                }
+                catch (error) {
+                    return new Response(String(error), { status: 500 });
+                }
+            }
+            if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+                return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // everything else → the twin's OWN FETCH ADAPTER (composition, R2): the Web API the React
+            // client calls (/api/0/...), the SDK's ingest path (/api/:projectId/envelope/) and the
+            // uniform doors (GET /twin) all come from the SAME closure `createSentryTwinServer` serves,
+            // so the mirror port cannot drift from the API port — one serving code path, one truth.
+            return twin(request);
+        },
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+/** The app-shell HTML (pure, for tests). */
+export function sentryMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function sentryMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}
+/** The default org/project the mirror lists issues for (matches the seeded defaults). */
+export const MIRROR_DEFAULT_ORG = DEFAULT_ORG;
+export const MIRROR_DEFAULT_PROJECT = DEFAULT_PROJECT;

package/dist/src/sentry-perform-harness.d.ts

@@ -0,0 +1,9 @@
+import { type SentryExecute } from './sentry-connector.js';
+export declare function performPending(execute: SentryExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    confirmed: string[];
+    externalIds: Record<string, string>;
+}>;

package/dist/src/sentry-perform-harness.js

@@ -0,0 +1,20 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). Not on the serve path.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { pushSentryAction } from "./sentry-connector.js";
+export async function performPending(execute, opts) {
+    const confirmed = [];
+    const externalIds = {};
+    for (const entry of deployableEntries('sentry', opts.root)) {
+        if (entry.operation !== 'issue.update')
+            continue; // only triage crosses
+        const { externalId } = await pushSentryAction(execute, { operation: entry.operation, subject: entry.subject, fields: entry.fields ?? {} });
+        confirmAction({
+            service: 'sentry', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+            occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
+            ...(opts.root !== undefined ? { root: opts.root } : {}),
+        });
+        confirmed.push(entry.id);
+        externalIds[entry.id] = externalId;
+    }
+    return { pushed: confirmed.length, confirmed, externalIds };
+}

package/dist/src/sentry-server.d.ts

@@ -0,0 +1,14 @@
+/** Options every Sentry-twin HTTP surface needs, independent of who owns the socket. */
+export interface SentryTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createSentryTwinFetch(options?: SentryTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createSentryTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/sentry-server.js

@@ -0,0 +1,27 @@
+// Sentry twin HTTP server — serve the full Sentry twin handler over HTTP so the real
+// `@sentry/node` SDK (pointed at a twin DSN whose host is this server) POSTs captured
+// events to /api/:projectId/envelope/ and they become grouped issues, AND the Web API
+// (/api/0/...) answers reads/writes. Writable by default; pass readOnly to reject writes.
+// No real Sentry is ever contacted (D4) — fully local + offline.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`); this file contributes only VALUES. The
+// vendor's 204 deletes return `{ status: 204, body: null }`, which the adapter's null-body rule
+// serves as a genuinely empty response. The server is one line of Bun.serve around that closure.
+import { serveHttp } from '@volter/world-core';
+import { handleSentryTwinRequest } from "./sentry-twin.js";
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+export function createSentryTwinFetch(options = {}) {
+    return createTwinFetchFromHandler(handleSentryTwinRequest, {
+        ...options,
+        manifest: statefulTwinManifest({ vendor: 'sentry', twinOf: 'the Sentry error-monitoring API', stores: 'ingested error/transaction envelopes, readable back per project' }),
+    });
+}
+export async function createSentryTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createSentryTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/sentry-twin.d.ts

@@ -0,0 +1,17 @@
+import { type SentryWebhookDelivery } from './sentry-events.js';
+export type SentryRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string | undefined>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** Injected webhook deliverer (fake in tests / HTTP live). Offline by default (no-op). */
+    deliver?: SentryWebhookDelivery;
+};
+export type SentryResponse = {
+    status: number;
+    body: unknown;
+};
+export declare function handleSentryTwinRequest(req: SentryRequest): Promise<SentryResponse>;