@mindmakr/reins 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,248 @@
+/** A JSON Schema object. reins passes it through untouched. */
+export type JSONSchema = Record<string, unknown>;
+export interface Action<I = any, O = any> {
+    /** Letters, digits, `.`, `_` and `-`, up to 64 characters. */
+    name: string;
+    description: string;
+    /** JSON Schema for the input. Use an object schema. */
+    input?: JSONSchema;
+    /** Changes real data or sends something. Callers must pass `confirm: true`. */
+    consequential?: boolean;
+    /** Reads only. Passed to WebMCP as `readOnlyHint`. */
+    readOnly?: boolean;
+    run: (input: I) => O | Promise<O>;
+}
+export interface ActionInfo {
+    name: string;
+    description: string;
+    input: JSONSchema;
+    consequential: boolean;
+    readOnly: boolean;
+}
+/** Keys that are shown as they are. Everything else sensitive is redacted. */
+export interface Allow {
+    headers?: string[];
+    bodyKeys?: string[];
+    storageKeys?: string[];
+    cookies?: string[];
+    queryKeys?: string[];
+    stateKeys?: string[];
+}
+export interface Box {
+    id: string;
+    /** CSS pixels, relative to the viewport. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scrollX: number;
+    scrollY: number;
+    devicePixelRatio: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+}
+export type Measure = () => Box | null | Promise<Box | null>;
+export interface NetEntry {
+    method: string;
+    url: string;
+    status: number;
+    ms: number;
+    startMs?: number;
+    at: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    responseBody?: unknown;
+    error?: string;
+    /** Sent as `x-reins-trace` on same-origin calls while paired, so `@mindmakr/reins/node` can join the server half. */
+    traceId?: string;
+}
+export interface ErrEntry {
+    kind: 'console' | 'error' | 'rejection';
+    message: string;
+    at: number;
+    stack?: string;
+}
+export interface ComponentPerf {
+    id: string;
+    mountedAtMs: number;
+    lastRenderMs: number;
+    renders: number;
+}
+export interface PerfTimelineEntry {
+    kind: 'lifecycle' | 'component-mount' | 'api' | 'action' | 'server';
+    name: string;
+    atMs: number;
+    durationMs?: number;
+    status?: number;
+    /** Server entries (joined by the bridge from `@mindmakr/reins/node`): the trace id, time in `db.*` spans, and the spans. */
+    traceId?: string;
+    dbMs?: number;
+    spans?: Array<{
+        name: string;
+        atMs: number;
+        durationMs: number;
+        error?: string;
+    }>;
+}
+export interface ApiCall {
+    method: string;
+    url: string;
+    status: number;
+    startMs?: number;
+    ms: number;
+    traceId?: string;
+}
+export interface PerfReport {
+    lifecycle: {
+        ttfbMs: number | null;
+        domInteractiveMs: number | null;
+        domContentLoadedMs: number | null;
+        loadMs: number | null;
+        firstPaintMs: number | null;
+        firstContentfulPaintMs: number | null;
+        domNodes: number;
+        nowMs: number;
+    };
+    components: ComponentPerf[];
+    api: {
+        totalCalls: number;
+        failedCalls: number;
+        avgMs: number;
+        maxMs: number;
+        slowest: ApiCall | null;
+        /** In the page these are the full (redacted) network entries; the bridge trims them to these fields. */
+        calls: ApiCall[];
+    };
+    actions: Array<{
+        name: string;
+        startMs: number;
+        durationMs: number;
+    }>;
+    /** Built from the parts above by `withTimeline` in `@mindmakr/reins/report`. The bridge's `reins_perf` and record mode always include it. */
+    timeline?: PerfTimelineEntry[];
+    /** Added by the bridge when a `@mindmakr/reins/node` server is paired. */
+    server?: {
+        requests: number;
+        slowest: RouteStat[];
+        runtime: ServerRuntime | null;
+    };
+}
+/** One timed piece of server work: a `reinsNode.span()` call. */
+export interface ServerSpan {
+    name: string;
+    /** Milliseconds from the start of the request (or of the process, for top-level spans). */
+    startMs: number;
+    ms: number;
+    error?: string;
+}
+/** One outbound `fetch` the server made (seen through `node:diagnostics_channel`). */
+export interface ServerOutbound {
+    method: string;
+    url: string;
+    status: number;
+    startMs: number;
+    ms: number;
+    error?: string;
+}
+/** One inbound HTTP request handled by a server that uses `@mindmakr/reins/node`. */
+export interface ServerRequest {
+    method: string;
+    route: string;
+    url: string;
+    status: number;
+    ms: number;
+    /** `performance.now()` of the server process when the request started. */
+    startMs: number;
+    at: number;
+    traceId?: string;
+    /** Total time in spans whose name starts with `db.`. */
+    dbMs: number;
+    spans: ServerSpan[];
+    outbound: ServerOutbound[];
+    requestHeaders?: Record<string, string>;
+}
+export interface ServerRuntime {
+    node: string;
+    pid: number;
+    uptimeS: number;
+    rssMb: number;
+    heapUsedMb: number;
+    eventLoop: {
+        p50Ms: number;
+        p99Ms: number;
+        maxMs: number;
+    };
+}
+export interface RouteStat {
+    method: string;
+    route: string;
+    count: number;
+    avgMs: number;
+    maxMs: number;
+    avgDbMs: number;
+}
+/** What `reins_server` returns for one server. */
+export interface ServerReport {
+    runtime: ServerRuntime | null;
+    requests: ServerRequest[];
+    slowest: RouteStat[];
+    spans: ServerSpan[];
+    outbound: ServerOutbound[];
+    actions?: ActionInfo[];
+}
+export interface DomOptions {
+    panel?: string;
+    selector?: string;
+    depth?: number;
+    maxNodes?: number;
+}
+export type DomIssue = 'horizontal-clip' | 'vertical-clip' | 'zero-size';
+export interface DomNode {
+    tag: string;
+    id?: string;
+    classes?: string[];
+    panel?: string;
+    role?: string;
+    text?: string;
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    styles: Record<string, string>;
+    issues: DomIssue[];
+    children: DomNode[];
+}
+export interface SocketLike {
+    send(data: string): void;
+    close(): void;
+    onopen: ((ev?: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev?: unknown) => void) | null;
+    onerror: ((ev?: unknown) => void) | null;
+}
+export interface ConnectOptions {
+    /** Bridge WebSocket URL. Default `ws://127.0.0.1:7357`. */
+    url?: string;
+    /** Pairing token. If missing, reins fetches it from `tokenUrl`. */
+    token?: string;
+    /** Where to fetch the token. Default `/__reins/token` (served by the Vite plugin). */
+    tokenUrl?: string;
+    allow?: Allow;
+    /** Size of the network and error buffers. Default 100. */
+    bufferSize?: number;
+    /** Register actions as WebMCP tools when the browser supports it. Default true. */
+    webmcp?: boolean;
+    /** Wait for `load` and an idle moment before connecting. Default true. */
+    lazy?: boolean;
+    /** Retry when the bridge is not there or goes away. Default true. */
+    reconnect?: boolean;
+    /** Extra facts sent with the handshake, such as `{ platform: 'android' }`. */
+    meta?: Record<string, string>;
+    /** For tests and React Native. Default `globalThis.WebSocket`. */
+    WebSocket?: new (url: string) => SocketLike;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/verify-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './verify.js';
+process.exitCode = main(process.argv.slice(2));

package/dist/verify.d.ts

@@ -0,0 +1,17 @@
+/** The string the reins core carries. It must never reach a production bundle. */
+export declare const MARKER = "__REINS_DEV_ONLY__";
+/** Every file under `dir`, skipping node_modules and .git. */
+export declare function listFiles(dir: string): string[];
+/**
+ * Files under `dir` (relative paths, forward slashes) that contain the marker.
+ * Reads bytes, so it also finds the marker in Hermes bytecode and source maps.
+ */
+export declare function findMarker(dir: string, marker?: string): string[];
+/** Runs the check and returns the exit code: 0 clean, 1 marker found, 2 bad usage. */
+export declare function main(args: string[], out?: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+}, err?: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+}): number;

package/dist/verify.js

@@ -0,0 +1,60 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/** The string the reins core carries. It must never reach a production bundle. */
+export const MARKER = '__REINS_DEV_ONLY__';
+const SKIP = new Set(['node_modules', '.git']);
+/** Every file under `dir`, skipping node_modules and .git. */
+export function listFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (SKIP.has(entry.name))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listFiles(full));
+        else if (entry.isFile())
+            out.push(full);
+    }
+    return out;
+}
+/**
+ * Files under `dir` (relative paths, forward slashes) that contain the marker.
+ * Reads bytes, so it also finds the marker in Hermes bytecode and source maps.
+ */
+export function findMarker(dir, marker = MARKER) {
+    if (!statSync(dir).isDirectory())
+        throw new Error(`${dir} is not a directory`);
+    const needle = Buffer.from(marker);
+    return listFiles(dir)
+        .filter((file) => readFileSync(file).includes(needle))
+        .map((file) => relative(dir, file).split('\\').join('/'));
+}
+/** Runs the check and returns the exit code: 0 clean, 1 marker found, 2 bad usage. */
+export function main(args, out = console.log, err = console.error) {
+    const dirs = args.filter((a) => !a.startsWith('-'));
+    if (dirs.length === 0 || args.includes('--help') || args.includes('-h')) {
+        err('usage: reins-verify-bundle <dir> [<dir>...]');
+        err(`Exits 1 if any file contains ${MARKER}, which means reins dev code is in a production build.`);
+        return 2;
+    }
+    let found = 0;
+    for (const dir of dirs) {
+        let hits;
+        try {
+            hits = findMarker(dir);
+        }
+        catch (e) {
+            err(`reins-verify-bundle: ${e.message}`);
+            return 2;
+        }
+        for (const hit of hits)
+            err(`reins dev code found: ${dir}/${hit}`);
+        found += hits.length;
+    }
+    if (found > 0) {
+        err(`reins-verify-bundle: ${found} file(s) contain reins dev code. Use the @mindmakr/reins/vite, @mindmakr/reins/next or @mindmakr/reins/metro plugin, or check REINS_ENABLE.`);
+        return 1;
+    }
+    out(`reins-verify-bundle: clean (${dirs.join(', ')})`);
+    return 0;
+}

package/dist/vite.d.ts

@@ -0,0 +1,32 @@
+/** The parts of the Vite plugin API this plugin uses, so it needs no Vite types. */
+interface ResolvedConfig {
+    root: string;
+    command: 'build' | 'serve';
+    mode: string;
+}
+interface Server {
+    config: {
+        root: string;
+    };
+    middlewares: {
+        use(fn: (req: any, res: any, next: () => void) => void): void;
+    };
+}
+/** Entries that carry the dev marker, and the stubs that replace them in production builds. */
+export declare const STUBS: Record<string, string>;
+export interface ReinsViteOptions {
+    /** Keep reins in production builds. Prefer the REINS_ENABLE=1 env var, and only for staging. */
+    keep?: boolean;
+}
+/**
+ * Dev: serves the pairing token at /__reins/token from `.reins/token`.
+ * Build (not development mode): resolves `@mindmakr/reins` to `@mindmakr/reins/stub` and `@mindmakr/reins/record` to `@mindmakr/reins/record-stub`, so no reins code ships.
+ */
+export declare function reinsPlugin(options?: ReinsViteOptions): {
+    name: string;
+    enforce: "pre";
+    configResolved(config: ResolvedConfig): void;
+    resolveId(this: any, id: string, importer?: string): Promise<any>;
+    configureServer(server: Server): void;
+};
+export default reinsPlugin;

package/dist/vite.js

@@ -0,0 +1,33 @@
+import { keepInBuild, TOKEN_ROUTE, tokenResponse } from '@mindmakr/reins/server';
+/** Entries that carry the dev marker, and the stubs that replace them in production builds. */
+export const STUBS = { '@mindmakr/reins': '@mindmakr/reins/stub', '@mindmakr/reins/record': '@mindmakr/reins/record-stub' };
+/**
+ * Dev: serves the pairing token at /__reins/token from `.reins/token`.
+ * Build (not development mode): resolves `@mindmakr/reins` to `@mindmakr/reins/stub` and `@mindmakr/reins/record` to `@mindmakr/reins/record-stub`, so no reins code ships.
+ */
+export function reinsPlugin(options = {}) {
+    let stub = false;
+    return {
+        name: 'reins',
+        enforce: 'pre',
+        configResolved(config) {
+            stub = config.command === 'build' && config.mode !== 'development' && !options.keep && !keepInBuild();
+        },
+        async resolveId(id, importer) {
+            const to = stub && Object.prototype.hasOwnProperty.call(STUBS, id) ? STUBS[id] : null;
+            return to ? this.resolve(to, importer, { skipSelf: true }) : null;
+        },
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.url !== TOKEN_ROUTE)
+                    return next();
+                const { status, body } = tokenResponse(server.config.root, req.headers);
+                res.statusCode = status;
+                res.setHeader('Content-Type', 'text/plain');
+                res.setHeader('Cache-Control', 'no-store');
+                res.end(body);
+            });
+        },
+    };
+}
+export default reinsPlugin;

package/dist/webmcp.d.ts

@@ -0,0 +1,3 @@
+import type { Action } from './types.js';
+export declare const findModelContext: (g: any) => any;
+export declare function registerTool(mc: any, a: Action, run: (n: string, i: unknown, c: boolean) => Promise<unknown>): () => void;

package/dist/webmcp.js

@@ -0,0 +1,20 @@
+export const findModelContext = (g) => {
+    const m = g.document?.modelContext || g.navigator?.modelContext;
+    return m?.registerTool && m;
+};
+export function registerTool(mc, a, run) {
+    const s = a.input || { type: 'object', properties: {} }, c = !!a.consequential, reg = mc.registerTool({
+        ...a,
+        inputSchema: c ? { ...s, properties: { ...s.properties, confirm: { type: 'boolean' } }, required: [...(s.required || []), 'confirm'] } : s,
+        annotations: { readOnlyHint: !!a.readOnly && !c, destructiveHint: c },
+        execute: async ({ confirm, ...rest } = {}) => ({
+            content: [{ type: 'text', text: JSON.stringify((await run(a.name, c ? rest : { confirm, ...rest }, confirm === true)) ?? null) }],
+        }),
+    });
+    return () => {
+        try {
+            reg?.unregister ? reg.unregister() : mc.unregisterTool?.(a.name);
+        }
+        catch { }
+    };
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@mindmakr/reins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Give coding agents the reins: a tiny dev-only library to drive, inspect and debug your web and Expo apps",
+  "license": "MIT",
+  "author": "mindmakr",
+  "homepage": "https://mindmakr.github.io/reins/",
+  "bugs": "https://github.com/mindmakr/reins/issues",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "repository": { "type": "git", "url": "git+https://github.com/mindmakr/reins.git", "directory": "packages/reins" },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./stub": { "types": "./dist/stub.d.ts", "default": "./dist/stub.js" },
+    "./adapters": { "types": "./dist/adapters.d.ts", "default": "./dist/adapters.js" },
+    "./server": { "types": "./dist/server.d.ts", "default": "./dist/server.js" },
+    "./react": { "types": "./dist/react.d.ts", "default": "./dist/react.js" },
+    "./expo": { "types": "./dist/expo.d.ts", "default": "./dist/expo.js" },
+    "./expo/metro": { "types": "./dist/metro.d.ts", "default": "./dist/metro.js" },
+    "./metro": { "types": "./dist/metro.d.ts", "default": "./dist/metro.js" },
+    "./vite": { "types": "./dist/vite.d.ts", "default": "./dist/vite.js" },
+    "./next": { "types": "./dist/next.d.ts", "default": "./dist/next.js" },
+    "./next/token-route": { "types": "./dist/next-token-route.d.ts", "default": "./dist/next-token-route.js" },
+    "./verify": { "types": "./dist/verify.d.ts", "default": "./dist/verify.js" },
+    "./bridge": { "types": "./dist/bridge/index.d.ts", "default": "./dist/bridge/index.js" },
+    "./report": { "types": "./dist/report.d.ts", "default": "./dist/report.js" },
+    "./node": { "types": "./dist/node.d.ts", "default": "./dist/node.js" },
+    "./record": { "types": "./dist/record.d.ts", "default": "./dist/record.js" },
+    "./record-stub": { "types": "./dist/record-stub.d.ts", "default": "./dist/record-stub.js" }
+  },
+  "bin": {
+    "reins": "dist/cli.js",
+    "reins-verify-bundle": "dist/verify-cli.js"
+  },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "next": ">=13",
+    "playwright": ">=1.40",
+    "react": ">=17",
+    "react-native": ">=0.70"
+  },
+  "peerDependenciesMeta": {
+    "next": { "optional": true },
+    "playwright": { "optional": true },
+    "react": { "optional": true },
+    "react-native": { "optional": true }
+  },
+  "keywords": ["ai-agents", "testing", "mcp", "webmcp", "devtools", "lucid-coding"]
+}