@mindmakr/reins 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { devEnabled } from './env.js';
+import { redactDeep } from './redact.js';
+import type { Action, ActionInfo, Box, ConnectOptions, DomNode, DomOptions, ErrEntry, Measure, NetEntry, PerfReport } from './types.js';
+export * from './types.js';
+export { devEnabled, redactDeep };
+export declare const DEV_MARKER = "__REINS_DEV_ONLY__";
+export declare const VERSION = "0.1.0";
+export interface ReinsHandle {
+    version: string;
+    actions(): ActionInfo[];
+    run(name: string, input?: unknown, opts?: {
+        confirm?: boolean;
+    }): Promise<unknown>;
+    state(name?: string): Record<string, unknown>;
+    network(limit?: number): NetEntry[];
+    errors(limit?: number): ErrEntry[];
+    panel(id: string): Promise<Box | null>;
+    perf(): PerfReport;
+    dom(opts?: DomOptions): Promise<DomNode | null>;
+}
+export type Reins = ReturnType<typeof createReins>;
+export declare function createReins(g?: any): {
+    run: (n: string, i?: unknown, o?: {
+        confirm?: boolean;
+    }) => Promise<unknown>;
+    actions: () => ActionInfo[];
+    network: (limit?: number) => NetEntry[];
+    errors: (limit?: number) => ErrEntry[];
+    perf: () => PerfReport;
+    dom: (o?: DomOptions) => Promise<DomNode | null>;
+    panel: (id: string, o?: {
+        scroll?: boolean;
+    }) => Promise<Box | null>;
+    marker: string;
+    action: <I = any, O = any>(def: Action<I, O>) => () => void;
+    state: (name: string, get: () => unknown) => () => void;
+    registerPanel: (id: string, measure: Measure) => () => void;
+    markComponent: (id: string, phase?: "mount" | "render") => void;
+    panels: () => string[];
+    connect: (o?: ConnectOptions) => Promise<boolean>;
+    disconnect: () => void;
+    isPaired: () => boolean;
+    record: (o?: ConnectOptions | false) => boolean;
+    snapshot: (name?: string) => Record<string, unknown>;
+};
+export declare const reins: {
+    run: (n: string, i?: unknown, o?: {
+        confirm?: boolean;
+    }) => Promise<unknown>;
+    actions: () => ActionInfo[];
+    network: (limit?: number) => NetEntry[];
+    errors: (limit?: number) => ErrEntry[];
+    perf: () => PerfReport;
+    dom: (o?: DomOptions) => Promise<DomNode | null>;
+    panel: (id: string, o?: {
+        scroll?: boolean;
+    }) => Promise<Box | null>;
+    marker: string;
+    action: <I = any, O = any>(def: Action<I, O>) => () => void;
+    state: (name: string, get: () => unknown) => () => void;
+    registerPanel: (id: string, measure: Measure) => () => void;
+    markComponent: (id: string, phase?: "mount" | "render") => void;
+    panels: () => string[];
+    connect: (o?: ConnectOptions) => Promise<boolean>;
+    disconnect: () => void;
+    isPaired: () => boolean;
+    record: (o?: ConnectOptions | false) => boolean;
+    snapshot: (name?: string) => Record<string, unknown>;
+};
+export default reins;

package/dist/index.js

@@ -0,0 +1,267 @@
+import { devEnabled } from './env.js';
+import { msg, patchNetwork, R, ring, watchErrors } from './network.js';
+import { redactDeep, redactPairs, redactUrl } from './redact.js';
+import { findModelContext, registerTool } from './webmcp.js';
+export * from './types.js';
+export { devEnabled, redactDeep };
+export const DEV_MARKER = '__REINS_DEV_ONLY__';
+export const VERSION = '0.1.0';
+const NAME = /^[\w][\w.-]{0,63}$/;
+const fail = (s) => {
+    throw new Error('reins: ' + s);
+};
+export function createReins(g = globalThis) {
+    const M = () => new Map(), actions = M(), states = M(), measures = M(), comps = M();
+    let opts = {}, net = ring(100), errs = ring(100), sock = null, paired = false, rec = false, undo = [], mc = null, connecting = null, retry = null, delay = 2000;
+    const nowMs = () => R(g.performance?.now?.()), findPanel = (id) => g.document?.querySelector?.(`[data-reins="${id.replace(/["\\]/g, '\\$&')}"]`), boxOf = (r) => ({ x: R(r.left), y: R(r.top), width: R(r.width), height: R(r.height) }), locUrl = () => g.location?.href && redactUrl('' + g.location.href, opts.allow?.queryKeys), send = (m) => sock?.send(JSON.stringify(m)), keep = (map, k, v) => (map.set(k, v), () => void (map.get(k) === v && (v._u?.(), map.delete(k)))), addTool = (a) => {
+        a._u?.();
+        try {
+            undo.push((a._u = registerTool(mc, a, (n, i, c) => runAction(n, i, c, 'webmcp'))));
+        }
+        catch { }
+    };
+    function action(def) {
+        if (!NAME.test(def?.name))
+            fail('bad action name');
+        if (typeof def.run != 'function')
+            fail('no run function');
+        if (paired && mc)
+            addTool(def);
+        return keep(actions, def.name, def);
+    }
+    const state = (name, get) => keep(states, name, get);
+    const registerPanel = (id, measure) => keep(measures, id, measure);
+    function markComponent(id, phase) {
+        if (!id)
+            return;
+        const t = nowMs(), c = comps.get(id);
+        if (!c || phase == 'mount')
+            comps.set(id, { id, mountedAtMs: t, lastRenderMs: t, renders: (c?.renders || 0) + 1 });
+        else
+            (c.lastRenderMs = t), c.renders++;
+    }
+    const list = () => [...actions.values()].map(({ name, description, input = { type: 'object', properties: {} }, consequential, readOnly }) => ({
+        name,
+        description,
+        input,
+        consequential: !!consequential,
+        readOnly: !!readOnly,
+    }));
+    const mustBePaired = () => !undo[0] && fail('not paired');
+    async function runAction(name, input, confirm, via) {
+        mustBePaired();
+        const a = actions.get(name), p = g.performance, mark = 'reins:' + name;
+        let error;
+        try {
+            if (!a)
+                fail('unknown action');
+            if (a.consequential && !confirm)
+                fail('confirm: true required');
+            p?.mark?.(mark);
+            return await a.run(input ?? {});
+        }
+        catch (e) {
+            error = msg(e);
+            throw e;
+        }
+        finally {
+            if (via != 'bridge')
+                send({ type: 'audit', entry: { method: 'run', name, via, ok: !error, error, at: Date.now() } });
+            try {
+                p?.measure?.('[reins] ' + name, mark);
+            }
+            catch { }
+        }
+    }
+    function snapshot(name) {
+        mustBePaired();
+        const out = {};
+        for (const k of name ? [name] : states.keys()) {
+            const get = states.get(k) || fail('unknown state');
+            try {
+                out[k] = redactDeep(get(), opts.allow?.stateKeys);
+            }
+            catch (e) {
+                out[k] = { error: msg(e) };
+            }
+        }
+        return out;
+    }
+    function panels() {
+        const ids = new Set(measures.keys());
+        g.document?.querySelectorAll?.('[data-reins]').forEach((el) => ids.add(el.getAttribute('data-reins')));
+        return [...ids];
+    }
+    async function panel(id, o = {}) {
+        const m = measures.get(id);
+        if (m)
+            return m();
+        const el = findPanel(id);
+        if (!el)
+            return null;
+        if (o.scroll)
+            el.scrollIntoView?.({ block: 'center' });
+        return {
+            id,
+            ...boxOf(el.getBoundingClientRect()),
+            scrollX: g.scrollX || 0,
+            scrollY: g.scrollY || 0,
+            devicePixelRatio: g.devicePixelRatio || 1,
+            viewportWidth: g.innerWidth,
+            viewportHeight: g.innerHeight,
+        };
+    }
+    function perf() {
+        const p = g.performance, ent = (t) => p?.getEntriesByType?.(t) || [], nav = ent('navigation')[0], paints = ent('paint'), num = (v) => (v >= 0 && v !== null ? R(v) : null), pt = (n) => num(paints.find((e) => e.name == 'first-' + n)?.startTime), lifecycle = {
+            ttfbMs: num(nav?.responseStart),
+            domInteractiveMs: num(nav?.domInteractive),
+            domContentLoadedMs: num(nav?.domContentLoadedEventEnd),
+            loadMs: num(nav?.loadEventEnd),
+            firstPaintMs: pt('paint'),
+            firstContentfulPaintMs: pt('contentful-paint'),
+            domNodes: g.document?.getElementsByTagName?.('*')?.length || 0,
+            nowMs: nowMs(),
+        }, components = [...comps.values()].sort((a, b) => a.mountedAtMs - b.mountedAtMs), 
+        // Full (redacted) entries; the bridge trims them to the timing fields.
+        calls = net.list(), act = ent('measure').flatMap((m) => (m.name?.startsWith?.('[reins] ') ? [{ name: m.name, startMs: R(m.startTime), durationMs: R(m.duration) }] : []));
+        let sum = 0, failedCalls = 0, slowest = null;
+        for (const c of calls) {
+            sum += c.ms;
+            if (!c.status || c.status >= 400)
+                failedCalls++;
+            if (!slowest || c.ms > slowest.ms)
+                slowest = c;
+        }
+        // The timeline is built from these parts by `withTimeline` in `@mindmakr/reins/report`, in the bridge and in record mode.
+        return {
+            lifecycle,
+            components,
+            api: { totalCalls: calls.length, failedCalls, avgMs: R(calls.length && sum / calls.length), maxMs: slowest?.ms || 0, slowest, calls },
+            actions: act,
+        };
+    }
+    // The inspector is a file of its own, loaded on the first call: a page that is never inspected never loads it.
+    const dom = (o = {}) => import('./dom.js').then((m) => m.inspect(g, o));
+    const network = (limit) => net.list(limit), errors = (limit) => errs.list(limit), runner = (via) => (n, i, o) => runAction(n, i, !!o?.confirm, via), methods = {
+        list: () => ({ actions: list(), states: [...states.keys()], panels: panels() }),
+        run: (p) => runAction(p.name, p.input, p.confirm === true, 'bridge'),
+        state: (p) => snapshot(p.name),
+        network: (p) => network(p.limit).filter((e) => !p.url || e.url.includes(p.url)),
+        errors: (p) => errors(p.limit),
+        panel: (p) => panel(p.id, p),
+        perf,
+        dom,
+    }, base = { actions: list, network, errors, perf, dom, panel }, handleForHumans = Object.freeze({ version: VERSION, ...base, run: runner('devtools'), state: snapshot });
+    // `undo` starts with the network and error patches, so it is non-empty exactly while reins is live (paired or recording).
+    function start() {
+        if (undo[0])
+            return;
+        const allow = opts.allow || {}, sz = opts.bufferSize || 100;
+        net = ring(sz);
+        errs = ring(sz);
+        undo = [patchNetwork(g, net.push, allow, () => paired), watchErrors(g, errs.push)];
+        if (g.location?.href)
+            states.set('location', locUrl);
+        for (const k of ['localStorage', 'sessionStorage'])
+            if (g[k])
+                states.set(k, () => redactPairs(Object.entries(g[k]), allow.storageKeys));
+        if (g.document?.cookie != null)
+            states.set('cookies', () => redactPairs(g.document.cookie.split(/; */).filter(Boolean).map((c) => c.split('=')), allow.cookies));
+    }
+    function pair(s) {
+        sock = s;
+        paired = true;
+        delay = 2000;
+        start();
+        undo.push(() => delete g.__reins__);
+        mc = opts.webmcp !== false && findModelContext(g);
+        if (mc)
+            actions.forEach(addTool);
+        try {
+            g.__reins__ = handleForHumans;
+        }
+        catch { }
+    }
+    // Undoes everything after the first `n` entries: 2 keeps the patches running for record mode.
+    const off = (n) => undo.splice(n).forEach((f) => f());
+    function unpair() {
+        paired = false;
+        sock = mc = null;
+        off(rec ? 2 : 0);
+    }
+    /** Record mode (`@mindmakr/reins/record`): starts the buffers without a bridge, in dev builds only. `false` stops it. */
+    const record = (o) => ((rec = o !== false && devEnabled()), paired || (rec ? ((opts = o || opts), start()) : off(0)), rec);
+    async function open() {
+        if (g.document && opts.lazy !== false)
+            await new Promise((r) => (g.document.readyState == 'complete' ? setTimeout(r) : g.addEventListener('load', r, { once: true })));
+        let token = opts.token;
+        if (!token && g.fetch) {
+            const res = await g.fetch(opts.tokenUrl || '/__reins/token', { cache: 'no-store' });
+            token = res.ok && (await res.text()).trim();
+        }
+        if (!token)
+            fail('no token');
+        return new Promise((res, rej) => {
+            const s = new (opts.WebSocket || g.WebSocket)(opts.url || 'ws://127.0.0.1:7357');
+            let done = false;
+            s.onopen = () => s.send(JSON.stringify({ type: 'hello', token, marker: DEV_MARKER, version: VERSION, url: locUrl(), title: g.document?.title, meta: opts.meta }));
+            s.onmessage = async (ev) => {
+                try {
+                    const m = JSON.parse('' + ev.data);
+                    if (!done) {
+                        done = true;
+                        return m.type == 'welcome' ? (pair(s), res(true)) : (s.close(), rej());
+                    }
+                    if (m.type == 'call')
+                        try {
+                            send({ type: 'result', id: m.id, ok: true, result: (await (methods[m.method] || fail('bad method'))(m.params || {})) ?? null });
+                        }
+                        catch (e) {
+                            send({ type: 'result', id: m.id, ok: false, error: msg(e) });
+                        }
+                }
+                catch { }
+            };
+            s.onclose = () => (!done ? rej() : sock == s && (unpair(), schedule()));
+        });
+    }
+    function schedule() {
+        connecting = null;
+        if (opts.reconnect !== false && !retry)
+            retry = setTimeout(() => ((retry = null), connect(opts)), delay < 30000 ? (delay *= 2) / 2 : delay);
+    }
+    function connect(o = {}) {
+        if (!devEnabled())
+            return Promise.resolve(false);
+        if (!connecting) {
+            opts = o;
+            connecting = open().catch(() => (schedule(), false));
+        }
+        return connecting;
+    }
+    function disconnect() {
+        opts = { reconnect: false };
+        clearTimeout(retry);
+        retry = connecting = null;
+        const s = sock;
+        unpair();
+        s?.close();
+    }
+    return {
+        marker: DEV_MARKER,
+        action,
+        state,
+        registerPanel,
+        markComponent,
+        panels,
+        connect,
+        disconnect,
+        isPaired: () => paired,
+        record,
+        snapshot,
+        ...base,
+        run: runner('api'),
+    };
+}
+export const reins = createReins();
+export default reins;

package/dist/metro.d.ts

@@ -0,0 +1,16 @@
+type MetroConfig = Record<string, any>;
+export interface ReinsMetroOptions {
+    /** Project folder holding `.reins/`. Default: current folder. */
+    projectRoot?: string;
+    /** Keep reins in production bundles. Prefer REINS_ENABLE=1, and only for staging. */
+    keep?: boolean;
+}
+/** Whether this Metro run should swap reins for its stub. `expo export` and release builds set NODE_ENV=production. */
+export declare function shouldStub(options?: ReinsMetroOptions, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Wraps a Metro config:
+ * - dev: serves the pairing token at /__reins/token on the Metro server;
+ * - production: resolves `@mindmakr/reins` to `@mindmakr/reins/stub` and `@mindmakr/reins/record` to `@mindmakr/reins/record-stub`.
+ */
+export declare function withReins(config: MetroConfig, options?: ReinsMetroOptions): MetroConfig;
+export default withReins;

package/dist/metro.js

@@ -0,0 +1,45 @@
+// Metro config helper for reins. Runs in Node, never in the app.
+import { keepInBuild, TOKEN_ROUTE, tokenResponse } from '@mindmakr/reins/server';
+/** Whether this Metro run should swap reins for its stub. `expo export` and release builds set NODE_ENV=production. */
+export function shouldStub(options = {}, env = process.env) {
+    return env.NODE_ENV === 'production' && !options.keep && !keepInBuild(env);
+}
+/**
+ * Wraps a Metro config:
+ * - dev: serves the pairing token at /__reins/token on the Metro server;
+ * - production: resolves `@mindmakr/reins` to `@mindmakr/reins/stub` and `@mindmakr/reins/record` to `@mindmakr/reins/record-stub`.
+ */
+export function withReins(config, options = {}) {
+    const root = options.projectRoot || process.cwd();
+    const server = config.server || {};
+    const resolver = config.resolver || {};
+    const prevEnhance = server.enhanceMiddleware;
+    const prevResolve = resolver.resolveRequest;
+    const stub = shouldStub(options);
+    return {
+        ...config,
+        server: {
+            ...server,
+            enhanceMiddleware(middleware, metroServer) {
+                const inner = prevEnhance ? prevEnhance(middleware, metroServer) : middleware;
+                return (req, res, next) => {
+                    if (req.url !== TOKEN_ROUTE)
+                        return inner(req, res, next);
+                    const { status, body } = tokenResponse(root, req.headers);
+                    res.statusCode = status;
+                    res.setHeader('Content-Type', 'text/plain');
+                    res.setHeader('Cache-Control', 'no-store');
+                    res.end(body);
+                };
+            },
+        },
+        resolver: {
+            ...resolver,
+            resolveRequest(context, moduleName, platform) {
+                const name = stub && moduleName === '@mindmakr/reins' ? '@mindmakr/reins/stub' : stub && moduleName === '@mindmakr/reins/record' ? '@mindmakr/reins/record-stub' : moduleName;
+                return prevResolve ? prevResolve(context, name, platform) : context.resolveRequest(context, name, platform);
+            },
+        },
+    };
+}
+export default withReins;

package/dist/network.d.ts

@@ -0,0 +1,14 @@
+import type { Allow, ErrEntry, NetEntry } from './types.js';
+export interface Ring<T> {
+    push(item: T): void;
+    list(limit?: number): T[];
+}
+export declare const R: (n: any) => number;
+export declare const msg: (v: any) => string;
+export declare function ring<T>(size: number): Ring<T>;
+/**
+ * Wraps `fetch` to record redacted calls. While `trace()` is true, same-origin calls also carry an
+ * `x-reins-trace` id, so `@mindmakr/reins/node` can join the server half. Cross-origin calls never get it.
+ */
+export declare function patchNetwork(g: any, record: (e: NetEntry) => void, { queryKeys, headers, bodyKeys }: Allow, trace: () => any): () => void;
+export declare function watchErrors(g: any, record: (e: ErrEntry) => void): () => void;

package/dist/network.js

@@ -0,0 +1,50 @@
+import { REDACTED, redactBody, redactHeaders, redactUrl } from './redact.js';
+export const R = (n) => Math.round(n || 0);
+export const msg = (v) => {
+    try {
+        return '' + (v?.message || (typeof v == 'object' ? JSON.stringify(v) : v));
+    }
+    catch {
+        return '' + v;
+    }
+};
+export function ring(size) {
+    const a = [];
+    return {
+        push: (x) => void (a.push(x) > size && a.shift()),
+        list: (n) => a.slice(n ? -n : 0),
+    };
+}
+/**
+ * Wraps `fetch` to record redacted calls. While `trace()` is true, same-origin calls also carry an
+ * `x-reins-trace` id, so `@mindmakr/reins/node` can join the server half. Cross-origin calls never get it.
+ */
+export function patchNetwork(g, record, { queryKeys, headers, bodyKeys }, trace) {
+    const now = () => R(g.performance?.now?.() ?? Date.now()), f = g.fetch, tid = Math.random().toString(36).slice(2, 8), hdr = (h, o = {}) => (h?.forEach ? h.forEach((v, k) => (o[k] = v)) : Object.assign(o, h), redactHeaders(o, headers));
+    let n = 0;
+    if (!f)
+        return () => { };
+    g.fetch = function (u, o = {}) {
+        const startMs = now(), req = u?.url ? u : {}, b = o.body, e = {
+            method: (o.method || req.method || 'GET').toUpperCase(),
+            url: redactUrl('' + (req.url || u), queryKeys),
+            startMs,
+            at: Date.now(),
+            requestHeaders: hdr(o.headers || req.headers),
+            requestBody: b == null ? undefined : typeof b == 'string' ? redactBody(b, bodyKeys) : REDACTED,
+        }, fin = (status, h) => ((e.status = status), (e.ms = now() - startMs), (e.responseHeaders = hdr(h)), record(e));
+        try {
+            if (trace() && new URL(req.url || u, g.location.href).origin == g.location.origin)
+                (o = { ...o, headers: new g.Headers(o.headers || req.headers) }).headers.set('x-reins-trace', (e.traceId = tid + '-' + ++n));
+        }
+        catch { }
+        return f.call(this, u, o).then((r) => (fin(r.status, r.headers), bodyKeys?.length && r.clone?.().text().then((t) => (e.responseBody = redactBody(t, bodyKeys)), () => { }), r), (err) => ((e.error = msg(err)), fin(0), Promise.reject(err)));
+    };
+    return () => (g.fetch = f);
+}
+export function watchErrors(g, record) {
+    const add = (kind, v) => record({ kind, message: msg(v).slice(0, 2000), stack: v?.stack, at: Date.now() }), c = g.console, orig = c?.error, ev = (m, fn) => (g.addEventListener?.(m, fn), () => g.removeEventListener?.(m, fn)), u1 = ev('error', (e) => add('error', e.error || e.message)), u2 = ev('unhandledrejection', (e) => add('rejection', e.reason));
+    if (orig)
+        c.error = (...a) => (add('console', a.map(msg).join(' ')), orig.apply(c, a));
+    return () => ((orig && (c.error = orig)), u1(), u2());
+}

package/dist/next-token-route.d.ts

@@ -0,0 +1,9 @@
+/**
+ * App Router handler that serves the pairing token in development.
+ * Add `app/api/reins-token/route.ts` with:
+ *   export { GET } from '@mindmakr/reins/next/token-route';
+ *   export const dynamic = 'force-dynamic';
+ * and connect with `reins.connect({ tokenUrl: '/api/reins-token' })`.
+ * In production it always answers 404.
+ */
+export declare function GET(request: Request): Promise<Response>;

package/dist/next-token-route.js

@@ -0,0 +1,17 @@
+import { tokenResponse } from '@mindmakr/reins/server';
+/**
+ * App Router handler that serves the pairing token in development.
+ * Add `app/api/reins-token/route.ts` with:
+ *   export { GET } from '@mindmakr/reins/next/token-route';
+ *   export const dynamic = 'force-dynamic';
+ * and connect with `reins.connect({ tokenUrl: '/api/reins-token' })`.
+ * In production it always answers 404.
+ */
+export async function GET(request) {
+    if (process.env.NODE_ENV === 'production')
+        return new Response('Not found', { status: 404 });
+    const headers = {};
+    request.headers.forEach((v, k) => (headers[k] = v));
+    const { status, body } = tokenResponse(process.cwd(), headers);
+    return new Response(body, { status, headers: { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' } });
+}

package/dist/next.d.ts

@@ -0,0 +1,13 @@
+type NextConfig = Record<string, any>;
+export interface ReinsNextOptions {
+    /** Keep reins in production builds. Prefer REINS_ENABLE=1, and only for staging. */
+    keep?: boolean;
+}
+/** Whether a build should swap reins for its stub. */
+export declare function shouldStub(dev: boolean, options?: ReinsNextOptions, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Wraps a Next.js config. Production builds resolve `@mindmakr/reins` to `@mindmakr/reins/stub` (and `@mindmakr/reins/record` to `@mindmakr/reins/record-stub`),
+ * with webpack and with Turbopack.
+ */
+export declare function withReins(nextConfig?: NextConfig, options?: ReinsNextOptions): NextConfig;
+export default withReins;

package/dist/next.js

@@ -0,0 +1,27 @@
+import { keepInBuild } from '@mindmakr/reins/server';
+/** Whether a build should swap reins for its stub. */
+export function shouldStub(dev, options = {}, env = process.env) {
+    return !dev && !options.keep && !keepInBuild(env);
+}
+/**
+ * Wraps a Next.js config. Production builds resolve `@mindmakr/reins` to `@mindmakr/reins/stub` (and `@mindmakr/reins/record` to `@mindmakr/reins/record-stub`),
+ * with webpack and with Turbopack.
+ */
+export function withReins(nextConfig = {}, options = {}) {
+    const prodBuild = process.env.NODE_ENV === 'production';
+    const out = {
+        ...nextConfig,
+        webpack(config, ctx) {
+            if (shouldStub(ctx.dev, options)) {
+                config.resolve = config.resolve || {};
+                config.resolve.alias = { ...(config.resolve.alias || {}), '@mindmakr/reins$': '@mindmakr/reins/stub', '@mindmakr/reins/record$': '@mindmakr/reins/record-stub' };
+            }
+            return typeof nextConfig.webpack === 'function' ? nextConfig.webpack(config, ctx) : config;
+        },
+    };
+    if (shouldStub(!prodBuild, options)) {
+        out.turbopack = { ...(nextConfig.turbopack || {}), resolveAlias: { ...((nextConfig.turbopack || {}).resolveAlias || {}), '@mindmakr/reins/record': '@mindmakr/reins/record-stub', '@mindmakr/reins': '@mindmakr/reins/stub' } };
+    }
+    return out;
+}
+export default withReins;

package/dist/node.d.ts

@@ -0,0 +1,80 @@
+import type { Action, ActionInfo, ServerReport } from './types.js';
+export declare const VERSION = "0.1.0";
+/** The header the browser core adds to same-origin calls while paired. */
+export declare const TRACE_HEADER = "x-reins-trace";
+export interface NodeConnectOptions {
+    /** Bridge WebSocket URL. Default `ws://127.0.0.1:7357`. */
+    url?: string;
+    /** Pairing token. Default: read from `tokenFile`. */
+    token?: string;
+    /** Default `<cwd>/.reins/token`, which the bridge writes. Read again before each attempt, because the bridge renews it. */
+    tokenFile?: string;
+    /** Extra facts for the handshake, such as `{ name: 'api' }`. `platform` is always `node`. */
+    meta?: Record<string, string>;
+    /** Retry when the bridge is not there or goes away. Default true. */
+    reconnect?: boolean;
+    /** Query keys and headers shown as they are; everything sensitive is redacted. */
+    allow?: {
+        queryKeys?: string[];
+        headers?: string[];
+    };
+    /** Requests kept. Default 200. */
+    bufferSize?: number;
+    /**
+     * Record without a bridge, from the moment `connect()` is called. For tests and scripts that read `report()`
+     * themselves. Default false: nothing is recorded until the bridge pairs, and recording stops when it goes away.
+     */
+    standalone?: boolean;
+    /** For tests. Default: the global WebSocket (Node 22+), else the `ws` package. */
+    WebSocket?: new (url: string) => any;
+}
+export interface MiddlewareOptions {
+    /**
+     * Add a `Server-Timing` header (total, `db.*` time and event-loop p99, plus the route) to each response,
+     * so a dev HUD can show server time without extra requests. Dev only, numbers and the route only. Default false.
+     */
+    serverTiming?: boolean;
+}
+/** Whether this process may run reins: not in production unless REINS_ENABLE=1 (private staging only). */
+export declare function nodeEnabled(env?: Record<string, string | undefined>): boolean;
+/** Creates an instance. Most apps use the `reinsNode` singleton. */
+export declare function createReinsNode(env?: Record<string, string | undefined>): {
+    connect: (o?: NodeConnectOptions) => Promise<boolean>;
+    disconnect: () => void;
+    clear: () => void;
+    isPaired: () => boolean;
+    isActive: () => boolean;
+    middleware: (o?: MiddlewareOptions) => (req: any, res: any, next: (err?: unknown) => void) => void;
+    wrapHandler: <H extends (req: any, res: any, ...rest: any[]) => any>(handler: H, o?: MiddlewareOptions) => H;
+    fastify: (app: {
+        addHook(name: string, fn: (...a: any[]) => void): unknown;
+    }) => {
+        addHook(name: string, fn: (...a: any[]) => void): unknown;
+    };
+    span: <T>(name: string, fn: () => T) => T;
+    action: <I = any, O = any>(def: Action<I, O>) => () => void;
+    actions: () => ActionInfo[];
+    run: (name: string, input?: unknown, confirm?: boolean) => Promise<unknown>;
+    report: () => ServerReport;
+};
+export type ReinsNode = ReturnType<typeof createReinsNode>;
+export declare const reinsNode: {
+    connect: (o?: NodeConnectOptions) => Promise<boolean>;
+    disconnect: () => void;
+    clear: () => void;
+    isPaired: () => boolean;
+    isActive: () => boolean;
+    middleware: (o?: MiddlewareOptions) => (req: any, res: any, next: (err?: unknown) => void) => void;
+    wrapHandler: <H extends (req: any, res: any, ...rest: any[]) => any>(handler: H, o?: MiddlewareOptions) => H;
+    fastify: (app: {
+        addHook(name: string, fn: (...a: any[]) => void): unknown;
+    }) => {
+        addHook(name: string, fn: (...a: any[]) => void): unknown;
+    };
+    span: <T>(name: string, fn: () => T) => T;
+    action: <I = any, O = any>(def: Action<I, O>) => () => void;
+    actions: () => ActionInfo[];
+    run: (name: string, input?: unknown, confirm?: boolean) => Promise<unknown>;
+    report: () => ServerReport;
+};
+export default reinsNode;