@mindmakr/reins 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mindmakr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @mindmakr/reins
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The reins core: actions, state, network and error buffers, panels and WebMCP. No dependencies, under 5 KB min+gzip.
+
+See the [main README](https://github.com/mindmakr/reins#readme) for setup and the security model.
+
+MIT � mindmakr

package/dist/adapters.d.ts

@@ -0,0 +1,25 @@
+/** State source for any store with `getState()`: Zustand, Redux, Redux Toolkit. */
+export declare const fromStore: (store: {
+    getState(): unknown;
+}) => () => unknown;
+export declare const zustand: (store: {
+    getState(): unknown;
+}) => () => unknown;
+export declare const redux: (store: {
+    getState(): unknown;
+}) => () => unknown;
+/** State source for a TanStack (React) Query client: one entry per cached query. */
+export declare const reactQuery: (client: {
+    getQueryCache(): {
+        getAll(): any[];
+    };
+}) => () => {
+    key: any;
+    status: any;
+    fetchStatus: any;
+    updatedAt: any;
+    error: string | undefined;
+    data: any;
+}[];
+/** State source for the current route. Pass a getter for routers that keep their own location. */
+export declare const routerLocation: (get?: () => unknown) => () => unknown;

package/dist/adapters.js

@@ -0,0 +1,24 @@
+import { redactUrl } from './redact.js';
+/** State source for any store with `getState()`: Zustand, Redux, Redux Toolkit. */
+export const fromStore = (store) => () => store.getState();
+export const zustand = fromStore;
+export const redux = fromStore;
+/** State source for a TanStack (React) Query client: one entry per cached query. */
+export const reactQuery = (client) => () => client
+    .getQueryCache()
+    .getAll()
+    .map((q) => ({
+    key: q.queryKey,
+    status: q.state.status,
+    fetchStatus: q.state.fetchStatus,
+    updatedAt: q.state.dataUpdatedAt,
+    error: q.state.error ? String(q.state.error) : undefined,
+    data: q.state.data,
+}));
+/** State source for the current route. Pass a getter for routers that keep their own location. */
+export const routerLocation = (get) => () => {
+    if (get)
+        return get();
+    const l = globalThis.location;
+    return l ? { pathname: l.pathname, search: redactUrl(l.search), hash: l.hash } : null;
+};

package/dist/bridge/args.d.ts

@@ -0,0 +1,15 @@
+export interface BridgeArgs {
+    command: 'bridge' | 'help';
+    port?: number;
+    dir: string;
+    origins: string[];
+    cdp?: string;
+    rotate: boolean;
+    mcp: boolean;
+    allowNoOrigin: boolean;
+}
+export declare const USAGE = "usage:\n  reins bridge [options]\n  reins verify <dir> [<dir>...]\n  reins report [--from <session.json>] [--compare <before.json> <after.json>] [--out <dir|file.md>]\n\nStarts the reins bridge on 127.0.0.1 and an MCP server on stdio, checks a production bundle for reins dev code, or renders saved session reports.\n\n  --port <n>         WebSocket port (default 7357)\n  --dir <path>       project folder for .reins/ (default: current folder)\n  --origin <origin>  also allow this exact page origin (repeatable); localhost is always allowed\n  --cdp <url>        Chrome DevTools endpoint for reins_snap, e.g. http://127.0.0.1:9222\n  --no-rotate        keep the same token after a page pairs\n  --no-mcp           do not start the MCP server (WebSocket only)\n  --browser-only     refuse clients without an Origin header (no React Native)\n";
+/** What to tell the person when the bridge port is taken, which happens when two agent sessions each start a bridge. */
+export declare const portInUse: (port: number) => string;
+/** Parses `reins` arguments. Throws on unknown flags. */
+export declare function parseArgs(argv: string[], cwd: string): BridgeArgs;

package/dist/bridge/args.js

@@ -0,0 +1,59 @@
+export const USAGE = `usage:
+  reins bridge [options]
+  reins verify <dir> [<dir>...]
+  reins report [--from <session.json>] [--compare <before.json> <after.json>] [--out <dir|file.md>]
+
+Starts the reins bridge on 127.0.0.1 and an MCP server on stdio, checks a production bundle for reins dev code, or renders saved session reports.
+
+  --port <n>         WebSocket port (default 7357)
+  --dir <path>       project folder for .reins/ (default: current folder)
+  --origin <origin>  also allow this exact page origin (repeatable); localhost is always allowed
+  --cdp <url>        Chrome DevTools endpoint for reins_snap, e.g. http://127.0.0.1:9222
+  --no-rotate        keep the same token after a page pairs
+  --no-mcp           do not start the MCP server (WebSocket only)
+  --browser-only     refuse clients without an Origin header (no React Native)
+`;
+/** What to tell the person when the bridge port is taken, which happens when two agent sessions each start a bridge. */
+export const portInUse = (port) => `reins: port ${port} is already in use. Another reins bridge is probably running (a second agent session or terminal, in this project or another).
+reins: stop that one, or start this one with --port <n> and give the app the same port: reins.connect({ url: 'ws://127.0.0.1:<n>' }).`;
+/** Parses `reins` arguments. Throws on unknown flags. */
+export function parseArgs(argv, cwd) {
+    const out = { command: 'help', dir: cwd, origins: [], rotate: true, mcp: true, allowNoOrigin: true };
+    const args = [...argv];
+    const cmd = args.shift();
+    if (cmd !== 'bridge')
+        return out;
+    out.command = 'bridge';
+    const value = (flag) => {
+        const v = args.shift();
+        if (!v || v.startsWith('--'))
+            throw new Error(`${flag} needs a value`);
+        return v;
+    };
+    while (args.length) {
+        const a = args.shift();
+        if (a === '--port') {
+            const n = Number(value(a));
+            if (!Number.isInteger(n) || n < 0 || n > 65535)
+                throw new Error('--port must be 0-65535');
+            out.port = n;
+        }
+        else if (a === '--dir')
+            out.dir = value(a);
+        else if (a === '--origin')
+            out.origins.push(value(a));
+        else if (a === '--cdp')
+            out.cdp = value(a);
+        else if (a === '--no-rotate')
+            out.rotate = false;
+        else if (a === '--no-mcp')
+            out.mcp = false;
+        else if (a === '--browser-only')
+            out.allowNoOrigin = false;
+        else if (a === '--help' || a === '-h')
+            out.command = 'help';
+        else
+            throw new Error(`unknown option ${a}`);
+    }
+    return out;
+}

package/dist/bridge/audit.d.ts

@@ -0,0 +1,13 @@
+export interface AuditEntry {
+    source: 'agent' | 'page' | 'bridge';
+    event: string;
+    name?: string;
+    args?: unknown;
+    ok?: boolean;
+    error?: string;
+    ms?: number;
+    [key: string]: unknown;
+}
+export type Audit = (entry: AuditEntry) => void;
+/** Appends one JSON line per event to `.reins/audit.log` and echoes it to stderr. Arguments are redacted. */
+export declare function fileAudit(projectDir: string, echo?: (line: string) => void): Audit;

package/dist/bridge/audit.js

@@ -0,0 +1,13 @@
+import { appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { redactDeep } from '@mindmakr/reins';
+import { reinsDir } from './token.js';
+/** Appends one JSON line per event to `.reins/audit.log` and echoes it to stderr. Arguments are redacted. */
+export function fileAudit(projectDir, echo = (l) => process.stderr.write(l + '\n')) {
+    const file = join(reinsDir(projectDir), 'audit.log');
+    return (entry) => {
+        const line = JSON.stringify({ at: new Date().toISOString(), ...entry, args: entry.args === undefined ? undefined : redactDeep(entry.args) });
+        appendFileSync(file, line + '\n');
+        echo(`[reins] ${entry.source} ${entry.event}${entry.name ? ' ' + entry.name : ''}${entry.ok === false ? ' failed: ' + entry.error : ''}`);
+    };
+}

package/dist/bridge/clipboard.d.ts

@@ -0,0 +1,2 @@
+/** Copies a PNG file to the OS clipboard. Returns false when no clipboard tool is available. No shell strings: the path goes through an env var or argv. */
+export declare function copyImage(file: string): boolean;

package/dist/bridge/clipboard.js

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+/** Copies a PNG file to the OS clipboard. Returns false when no clipboard tool is available. No shell strings: the path goes through an env var or argv. */
+export function copyImage(file) {
+    const env = { ...process.env, REINS_SNAP: file };
+    try {
+        if (process.platform === 'win32') {
+            execFileSync('powershell', [
+                '-NoProfile',
+                '-STA',
+                '-Command',
+                'Add-Type -AssemblyName System.Windows.Forms; Add-Type -AssemblyName System.Drawing; [System.Windows.Forms.Clipboard]::SetImage([System.Drawing.Image]::FromFile($env:REINS_SNAP))',
+            ], { env, stdio: 'ignore' });
+        }
+        else if (process.platform === 'darwin') {
+            execFileSync('osascript', ['-e', 'set the clipboard to (read (POSIX file (system attribute "REINS_SNAP")) as «class PNGf»)'], { env, stdio: 'ignore' });
+        }
+        else {
+            try {
+                execFileSync('xclip', ['-selection', 'clipboard', '-t', 'image/png', '-i', file], { stdio: 'ignore' });
+            }
+            catch {
+                execFileSync('wl-copy', ['--type', 'image/png'], { input: readFileSync(file), stdio: ['pipe', 'ignore', 'ignore'] });
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/bridge/hub.d.ts

@@ -0,0 +1,56 @@
+import { type WebSocket } from 'ws';
+import type { Audit } from './audit.js';
+export declare const DEFAULT_PORT = 7357;
+/** The bridge listens on loopback only. There is no option to change this. */
+export declare const HOST = "127.0.0.1";
+export interface HubOptions {
+    /** Project folder; the token goes to `<dir>/.reins/token`. */
+    dir: string;
+    /** Default 7357. Use 0 for a free port (tests). */
+    port?: number;
+    /** Extra allowed origins, matched exactly. Localhost origins are always allowed. */
+    origins?: string[];
+    /** Allow clients that send no Origin (React Native). Default true; the token is still required. */
+    allowNoOrigin?: boolean;
+    /** Issue a new token after each successful pairing. Default true. */
+    rotate?: boolean;
+    audit?: Audit;
+    log?: (msg: string) => void;
+    handshakeMs?: number;
+    callMs?: number;
+}
+export interface Client {
+    id: number;
+    url?: string;
+    title?: string;
+    meta?: Record<string, string>;
+    socket: WebSocket;
+}
+/** The WebSocket side of the bridge: pairs pages that present the token, then forwards calls to them. */
+export declare class Hub {
+    private opts;
+    token: string;
+    readonly clients: Client[];
+    /** When the bridge started; a session report covers the audit log from here on. */
+    readonly startedAt: number;
+    private server;
+    private pending;
+    private nextCall;
+    private nextClient;
+    private constructor();
+    static start(opts: HubOptions): Promise<Hub>;
+    get port(): number;
+    private log;
+    private audit;
+    private issueToken;
+    private accept;
+    /** Whether a client is a `@mindmakr/reins/node` server rather than a page or an app. */
+    static isNode(c: Client): boolean;
+    /** The most recently paired page or app (not a Node server). Browser methods go here. */
+    current(): Client | undefined;
+    /** Paired `@mindmakr/reins/node` servers, oldest first. */
+    nodeClients(): Client[];
+    /** Sends a call to a client (default: the newest page or app) and waits for its result. */
+    request(method: string, params?: Record<string, unknown>, target?: Client): Promise<any>;
+    close(): Promise<void>;
+}

package/dist/bridge/hub.js

@@ -0,0 +1,162 @@
+import { WebSocketServer } from 'ws';
+import { isOriginAllowed } from './origin.js';
+import { newToken, removeToken, tokensMatch, writeToken } from './token.js';
+export const DEFAULT_PORT = 7357;
+/** The bridge listens on loopback only. There is no option to change this. */
+export const HOST = '127.0.0.1';
+/** The WebSocket side of the bridge: pairs pages that present the token, then forwards calls to them. */
+export class Hub {
+    constructor(opts) {
+        this.opts = opts;
+        this.token = '';
+        this.clients = [];
+        /** When the bridge started; a session report covers the audit log from here on. */
+        this.startedAt = Date.now();
+        this.pending = new Map();
+        this.nextCall = 1;
+        this.nextClient = 1;
+    }
+    static start(opts) {
+        const hub = new Hub(opts);
+        hub.issueToken();
+        return new Promise((resolve, reject) => {
+            hub.server = new WebSocketServer({
+                host: HOST,
+                port: opts.port ?? DEFAULT_PORT,
+                maxPayload: 4 * 1024 * 1024,
+                verifyClient: (info, cb) => {
+                    const origin = info.origin || info.req.headers.origin;
+                    if (isOriginAllowed(origin, opts.origins, opts.allowNoOrigin ?? true))
+                        return cb(true);
+                    hub.audit({ source: 'bridge', event: 'refused', ok: false, error: `origin not allowed: ${origin}` });
+                    cb(false, 403, 'origin not allowed');
+                },
+            });
+            hub.server.once('listening', () => resolve(hub));
+            hub.server.once('error', reject);
+            hub.server.on('connection', (socket) => hub.accept(socket));
+        });
+    }
+    get port() {
+        return this.server.address().port;
+    }
+    log(msg) {
+        (this.opts.log ?? ((m) => process.stderr.write(m + '\n')))(msg);
+    }
+    audit(entry) {
+        if (this.opts.audit)
+            this.opts.audit(entry);
+    }
+    issueToken() {
+        this.token = newToken();
+        writeToken(this.opts.dir, this.token);
+    }
+    accept(socket) {
+        let client = null;
+        const timer = setTimeout(() => socket.close(4401, 'no handshake'), this.opts.handshakeMs ?? 5000);
+        socket.on('message', (data) => {
+            let m;
+            try {
+                m = JSON.parse(String(data));
+            }
+            catch {
+                return;
+            }
+            // JSON such as `null` or `1` parses fine; reading `.type` off it would throw inside this listener and stop the bridge.
+            if (!m || typeof m !== 'object') {
+                if (!client) {
+                    clearTimeout(timer);
+                    socket.close(4401, 'bad handshake');
+                }
+                return;
+            }
+            if (!client) {
+                clearTimeout(timer);
+                if (m.type === 'hello' && tokensMatch(m.token, this.token)) {
+                    client = { id: this.nextClient++, url: m.url, title: m.title, meta: m.meta, socket };
+                    this.clients.push(client);
+                    socket.send(JSON.stringify({ type: 'welcome', client: client.id }));
+                    this.audit({ source: 'bridge', event: 'paired', name: client.url, ok: true });
+                    this.log(`[reins] paired with ${client.url ?? 'an app'} (client ${client.id})`);
+                    if (this.opts.rotate !== false)
+                        this.issueToken();
+                }
+                else {
+                    this.audit({ source: 'bridge', event: 'refused', ok: false, error: 'bad or missing token' });
+                    socket.send(JSON.stringify({ type: 'refused', reason: 'bad or missing token' }));
+                    socket.close(4401, 'bad token');
+                }
+                return;
+            }
+            if (m.type === 'result') {
+                const p = this.pending.get(m.id);
+                if (!p || p.client !== client)
+                    return;
+                this.pending.delete(m.id);
+                clearTimeout(p.timer);
+                if (m.ok)
+                    p.resolve(m.result);
+                else
+                    p.reject(new Error(String(m.error)));
+            }
+            else if (m.type === 'audit' && m.entry) {
+                const e = m.entry;
+                this.audit({ source: 'page', event: String(e.method), name: e.name, via: e.via, ok: e.ok, error: e.error });
+            }
+        });
+        socket.on('close', () => {
+            clearTimeout(timer);
+            const i = client ? this.clients.indexOf(client) : -1;
+            if (i >= 0) {
+                this.clients.splice(i, 1);
+                this.log(`[reins] client ${client.id} disconnected`);
+                for (const [id, p] of this.pending)
+                    if (p.client === client) {
+                        this.pending.delete(id);
+                        clearTimeout(p.timer);
+                        p.reject(new Error('the app disconnected'));
+                    }
+            }
+        });
+        socket.on('error', () => { });
+    }
+    /** Whether a client is a `@mindmakr/reins/node` server rather than a page or an app. */
+    static isNode(c) {
+        return !!c.meta && c.meta.platform === 'node';
+    }
+    /** The most recently paired page or app (not a Node server). Browser methods go here. */
+    current() {
+        return this.clients.filter((c) => !Hub.isNode(c)).pop();
+    }
+    /** Paired `@mindmakr/reins/node` servers, oldest first. */
+    nodeClients() {
+        return this.clients.filter(Hub.isNode);
+    }
+    /** Sends a call to a client (default: the newest page or app) and waits for its result. */
+    request(method, params = {}, target) {
+        const client = target ?? this.current();
+        if (!client) {
+            return Promise.reject(new Error('No app is paired. Open the app in dev mode (it must call reins.connect()) and make sure the dev server serves .reins/token.'));
+        }
+        const id = this.nextCall++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`the app did not answer "${method}" in time`));
+            }, this.opts.callMs ?? 15000);
+            this.pending.set(id, { resolve, reject, timer, client });
+            client.socket.send(JSON.stringify({ type: 'call', id, method, params }));
+        });
+    }
+    close() {
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error('bridge closed'));
+        }
+        this.pending.clear();
+        for (const c of this.clients)
+            c.socket.terminate();
+        removeToken(this.opts.dir);
+        return new Promise((resolve) => this.server.close(() => resolve()));
+    }
+}

package/dist/bridge/index.d.ts

@@ -0,0 +1,11 @@
+export { parseArgs, USAGE, type BridgeArgs } from './args.js';
+export { fileAudit, type Audit, type AuditEntry } from './audit.js';
+export { copyImage } from './clipboard.js';
+export { DEFAULT_PORT, HOST, Hub, type Client, type HubOptions } from './hub.js';
+export { startMcp, VERSION } from './mcp.js';
+export { isOriginAllowed } from './origin.js';
+export { parseReportArgs, REPORT_USAGE, reportMain, type ReportArgs } from './report-cli.js';
+export { gatherSession, latestSession, readAudit, readSession, serverReports, writeSession } from './session.js';
+export { snap, type SnapOptions, type SnapResult } from './snap.js';
+export { newToken, removeToken, tokenPath, tokensMatch, writeToken } from './token.js';
+export { callTool, TOOLS, type Tool, type ToolContext } from './tools.js';

package/dist/bridge/index.js

@@ -0,0 +1,11 @@
+export { parseArgs, USAGE } from './args.js';
+export { fileAudit } from './audit.js';
+export { copyImage } from './clipboard.js';
+export { DEFAULT_PORT, HOST, Hub } from './hub.js';
+export { startMcp, VERSION } from './mcp.js';
+export { isOriginAllowed } from './origin.js';
+export { parseReportArgs, REPORT_USAGE, reportMain } from './report-cli.js';
+export { gatherSession, latestSession, readAudit, readSession, serverReports, writeSession } from './session.js';
+export { snap } from './snap.js';
+export { newToken, removeToken, tokenPath, tokensMatch, writeToken } from './token.js';
+export { callTool, TOOLS } from './tools.js';

package/dist/bridge/mcp.d.ts

@@ -0,0 +1,5 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type ToolContext } from './tools.js';
+export declare const VERSION = "0.1.0";
+/** Serves the reins tools over MCP on stdio. stdout belongs to MCP; logs go to stderr. */
+export declare function startMcp(ctx: ToolContext): Promise<Server>;

package/dist/bridge/mcp.js

@@ -0,0 +1,22 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { callTool, TOOLS } from './tools.js';
+export const VERSION = '0.1.0';
+/** Serves the reins tools over MCP on stdio. stdout belongs to MCP; logs go to stderr. */
+export async function startMcp(ctx) {
+    ctx.snaps ?? (ctx.snaps = []);
+    const server = new Server({ name: 'reins', version: VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        try {
+            const result = await callTool(ctx, req.params.name, (req.params.arguments ?? {}));
+            return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: String(err.message ?? err) }], isError: true };
+        }
+    });
+    await server.connect(new StdioServerTransport());
+    return server;
+}

package/dist/bridge/origin.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether a WebSocket Origin may connect.
+ * Default: any http(s) origin on localhost, 127.0.0.1 or ::1, any port.
+ * Extra origins are matched exactly, for example `http://my-app.test:3000`.
+ * A missing Origin (React Native, Node) is allowed only when `allowNoOrigin` is true; the token is still required.
+ */
+export declare function isOriginAllowed(origin: string | undefined, extra?: string[], allowNoOrigin?: boolean): boolean;

package/dist/bridge/origin.js

@@ -0,0 +1,23 @@
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/**
+ * Whether a WebSocket Origin may connect.
+ * Default: any http(s) origin on localhost, 127.0.0.1 or ::1, any port.
+ * Extra origins are matched exactly, for example `http://my-app.test:3000`.
+ * A missing Origin (React Native, Node) is allowed only when `allowNoOrigin` is true; the token is still required.
+ */
+export function isOriginAllowed(origin, extra = [], allowNoOrigin = true) {
+    if (!origin)
+        return allowNoOrigin;
+    if (extra.includes(origin))
+        return true;
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return false;
+    return LOCAL_HOSTS.has(url.hostname) || url.hostname.endsWith('.localhost');
+}

package/dist/bridge/report-cli.d.ts

@@ -0,0 +1,13 @@
+export declare const REPORT_USAGE = "usage:\n  reins report [--from <session.json>] [--out <dir|file.md>]\n  reins report --compare <before.json> <after.json> [--out <dir|file.md>]\n\nRe-renders a saved session (default: the newest in .reins/sessions) as Markdown, or prints a\nbefore/after table of two sessions. Prints to stdout; --out also writes the file.";
+export interface ReportArgs {
+    from?: string;
+    compare?: [string, string];
+    out?: string;
+    help?: boolean;
+}
+/** Parses `reins report` arguments. Throws on unknown flags. */
+export declare function parseReportArgs(argv: string[]): ReportArgs;
+/** Where `--out` writes: a `.md` path as is, otherwise `<dir>/<name>`. */
+export declare const outFile: (out: string, cwd: string, name: string) => string;
+/** Runs `reins report`. Returns the exit code: 0 done, 2 bad usage or unreadable input. */
+export declare function reportMain(argv: string[], cwd?: string, print?: (s: string) => boolean, err?: (s: string) => boolean): number;

package/dist/bridge/report-cli.js

@@ -0,0 +1,82 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { compareSessions, renderMarkdown } from '@mindmakr/reins/report';
+import { latestSession, linkFrom, readSession } from './session.js';
+export const REPORT_USAGE = `usage:
+  reins report [--from <session.json>] [--out <dir|file.md>]
+  reins report --compare <before.json> <after.json> [--out <dir|file.md>]
+
+Re-renders a saved session (default: the newest in .reins/sessions) as Markdown, or prints a
+before/after table of two sessions. Prints to stdout; --out also writes the file.`;
+/** Parses `reins report` arguments. Throws on unknown flags. */
+export function parseReportArgs(argv) {
+    const out = {};
+    const args = [...argv];
+    const value = (flag) => {
+        const v = args.shift();
+        if (!v || v.startsWith('--'))
+            throw new Error(`${flag} needs a value`);
+        return v;
+    };
+    while (args.length) {
+        const a = args.shift();
+        if (a === '--from')
+            out.from = value(a);
+        else if (a === '--out')
+            out.out = value(a);
+        else if (a === '--compare')
+            out.compare = [value(a), value(a)];
+        else if (a === '--help' || a === '-h')
+            out.help = true;
+        else
+            throw new Error(`unknown option ${a}`);
+    }
+    return out;
+}
+/** Where `--out` writes: a `.md` path as is, otherwise `<dir>/<name>`. */
+export const outFile = (out, cwd, name) => (out.endsWith('.md') ? resolve(cwd, out) : join(resolve(cwd, out), name));
+/** Runs `reins report`. Returns the exit code: 0 done, 2 bad usage or unreadable input. */
+export function reportMain(argv, cwd = process.cwd(), print = (s) => process.stdout.write(s + '\n'), err = (s) => process.stderr.write(s + '\n')) {
+    let args;
+    try {
+        args = parseReportArgs(argv);
+    }
+    catch (e) {
+        err(`reins report: ${e.message}\n\n${REPORT_USAGE}`);
+        return 2;
+    }
+    if (args.help) {
+        err(REPORT_USAGE);
+        return 0;
+    }
+    try {
+        let markdown;
+        let file;
+        if (args.compare) {
+            const [a, b] = args.compare.map((f) => readSession(resolve(cwd, f)));
+            markdown = compareSessions(a, b).markdown;
+            if (args.out)
+                file = outFile(args.out, cwd, 'compare.md');
+        }
+        else {
+            const from = args.from ? resolve(cwd, args.from) : latestSession(cwd);
+            if (!from)
+                throw new Error('no session found: run reins_report first, or pass --from <session.json>');
+            const session = readSession(from);
+            if (args.out)
+                file = outFile(args.out, cwd, basename(from).replace(/\.json$/, '') + '.md');
+            markdown = renderMarkdown(session, file ? { link: linkFrom(cwd, file) } : {});
+        }
+        if (file) {
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, markdown);
+            err(`reins report: wrote ${file}`);
+        }
+        print(markdown);
+        return 0;
+    }
+    catch (e) {
+        err(`reins report: ${e.message}`);
+        return 2;
+    }
+}

package/dist/bridge/session.d.ts

@@ -0,0 +1,24 @@
+import { type AuditLine, type SessionData } from '@mindmakr/reins/report';
+import type { ServerReport } from '@mindmakr/reins';
+import type { Hub } from './hub.js';
+import type { ToolContext } from './tools.js';
+/** Asks every paired `@mindmakr/reins/node` server for its report. Servers that do not answer are skipped. */
+export declare function serverReports(hub: Hub): Promise<ServerReport[]>;
+/** How much of the end of the audit log a report reads. The log is never trimmed, so it can be far larger. */
+export declare const AUDIT_TAIL_BYTES: number;
+/** Audit log lines written since `since` (ms), oldest first. Missing log: none. Reads only the end of the file. */
+export declare function readAudit(projectDir: string, since: number, max?: number, tailBytes?: number): AuditLine[];
+/** Gathers a session from the paired app and servers: everything `reins_report` puts in the files. */
+export declare function gatherSession(ctx: ToolContext, title?: string): Promise<SessionData>;
+/** Snap links relative to where the Markdown file lives. */
+export declare const linkFrom: (projectDir: string, mdFile: string) => (p: string) => string;
+/** Writes `.reins/sessions/<time>-<slug>.json` and `.md`. Returns the paths and the Markdown. */
+export declare function writeSession(projectDir: string, session: SessionData): {
+    md: string;
+    json: string;
+    markdown: string;
+};
+/** Reads a session JSON and checks its schema version. */
+export declare function readSession(file: string): SessionData;
+/** The newest session JSON under `<projectDir>/.reins/sessions`, if any. */
+export declare function latestSession(projectDir: string): string | undefined;