ts-bin-rpc 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -1,17 +1,19 @@
 # ts-bin-rpc
 
 A code-first TypeScript RPC with a binary wire format. Your router's TypeScript types are the
-schema: [`ts-bin-rpc-cli`](https://www.npmjs.com/package/ts-bin-rpc-cli) reads them and generates
-codecs. The client gets lazy views over the response bytes, and numeric arrays arrive as
-`TypedArray` columns with no parsing.
-
-This package is the runtime: `ts-bin-rpc/server`, `ts-bin-rpc/client`, `ts-bin-rpc/node`, the
-numeric brands and the codec runtime the generated code imports.
+schema: the `tbr` command reads them, keeps a lockfile of field IDs and generates codecs. The
+client gets lazy views over the response bytes, and numeric arrays arrive as `TypedArray` columns
+with no parsing.
 
 ```sh
 npm install ts-bin-rpc@alpha
-npm install -D ts-bin-rpc-cli@alpha typescript@7.1.0-beta
+npm install -D typescript@7.1.0-beta   # for tbr
+npx tbr generate                       # --watch to regenerate on save; tbr check in CI
 ```
 
+The package provides `ts-bin-rpc/server`, `ts-bin-rpc/client`, `ts-bin-rpc/node`, the numeric
+brands, the codec runtime the generated code imports, and `tbr`. TypeScript is an optional peer
+dependency that only `tbr` needs.
+
 **Alpha.** The wire format may change before 1.0. Docs: https://tom4ikss.github.io/ts-bin-RPC/.
 Source and issues: https://github.com/Tom4ikss/ts-bin-RPC. MIT license.

package/dist/cli/build.js

@@ -0,0 +1,245 @@
+import { TYPED_ARRAYS } from './ir.js';
+const NUMBER_BRANDS = { u8: 'u8', i8: 'i8', u16: 'u16', i16: 'i16', u32: 'u32', i32: 'i32', f32: 'f32', f64: 'f64' };
+const BIGINT_BRANDS = { u64: 'u64', i64: 'i64' };
+const UNSUPPORTED = {
+    any: "type 'any' is not serializable",
+    unknown: "type 'unknown' is not serializable",
+    never: "type 'never' is not serializable",
+    symbol: 'symbols are not serializable',
+    nonPrimitive: "type 'object' is not serializable; declare the fields",
+    void: "'void' is only allowed as a procedure result",
+    undefined: "'undefined' alone is not serializable",
+    null: "'null' alone is not serializable",
+    function: 'functions and methods are not serializable',
+    tuple: 'tuples are not supported yet; use an object or an array',
+};
+class Builder {
+    schema = { procedures: [], objects: {}, enums: {}, unions: {} };
+    errors = [];
+    memo = new Map();
+    owners = new Map();
+    src;
+    constructor(src) { this.src = src; }
+    fail(ctx, message, location = ctx.location) {
+        this.errors.push({ path: ctx.path, message, location });
+    }
+    procedure(entry) {
+        const ctx = { path: entry.path, anon: entry.path, location: entry.location };
+        if ('problem' in entry)
+            return this.fail(ctx, entry.problem);
+        if (entry.overloads > 1)
+            return this.fail(ctx, 'overloaded procedures are not supported');
+        if (entry.params.length > 2)
+            return this.fail(ctx, 'a procedure takes at most (input, ctx)');
+        let input = null;
+        let inputOptional = false;
+        const p0 = entry.params[0];
+        const k0 = p0 && this.src.describe(p0.type).k;
+        // `(_: void, ctx)`: a procedure that needs ctx but takes no input.
+        if (p0 && k0 !== 'void' && k0 !== 'undefined') {
+            const r = this.slot(p0.type, { path: `${entry.path} → input`, anon: `${entry.path}:input`, location: entry.location });
+            if (r?.nullable)
+                this.fail(ctx, 'a procedure input cannot be null');
+            input = r?.type ?? null;
+            inputOptional = p0.optional || !!r?.optional;
+        }
+        let output = null;
+        const ret = this.src.describe(entry.returns);
+        if (ret.k !== 'void' && ret.k !== 'undefined') {
+            const r = this.slot(entry.returns, { path: `${entry.path} → output`, anon: `${entry.path}:output`, location: entry.location });
+            if (r && (r.optional || r.nullable))
+                this.fail(ctx, 'a procedure result cannot be null or undefined; wrap it in an object with an optional field');
+            output = r?.type ?? null;
+        }
+        const proc = { path: entry.path, input, inputOptional, output, location: entry.location };
+        this.schema.procedures.push(proc);
+    }
+    // A position that may carry `| undefined` and `| null`: fields and procedure input/output.
+    slot(ref, ctx) {
+        const d = this.src.describe(ref);
+        if (d.k !== 'union') {
+            const type = this.type(ref, ctx);
+            return type && { type, optional: false, nullable: false };
+        }
+        let optional = false, nullable = false;
+        const rest = [];
+        const visit = (members) => {
+            for (const m of members) {
+                const md = this.src.describe(m);
+                if (md.k === 'undefined' || md.k === 'void')
+                    optional = true;
+                else if (md.k === 'null')
+                    nullable = true;
+                else if (md.k === 'union' && md.members.some((x) => isNullish(this.src.describe(x))))
+                    visit(md.members); // `type MaybeRole = Role | null`
+                else
+                    rest.push(m);
+            }
+        };
+        visit(d.members);
+        if (!rest.length) {
+            this.fail(ctx, `'${this.src.text(ref)}' has no serializable part`);
+            return undefined;
+        }
+        const type = rest.length === 1 ? this.type(rest[0], ctx) : this.multi(ref, rest, d.alias, ctx);
+        return type && { type, optional, nullable };
+    }
+    type(ref, ctx) {
+        const d = this.src.describe(ref);
+        switch (d.k) {
+            case 'string': return { kind: 'string' };
+            case 'number': return { kind: 'scalar', scalar: 'f64' };
+            case 'boolean': return { kind: 'scalar', scalar: 'bool' };
+            case 'bigint': return { kind: 'scalar', scalar: 'i64' };
+            case 'literal': return { kind: 'const', value: d.value };
+            case 'brand': {
+                const scalar = (d.base === 'number' ? NUMBER_BRANDS : BIGINT_BRANDS)[d.tag];
+                if (!scalar) {
+                    this.fail(ctx, `unknown numeric brand '${d.tag}' on ${d.base}`);
+                    return undefined;
+                }
+                return { kind: 'scalar', scalar };
+            }
+            case 'union': {
+                if (d.members.some((m) => isNullish(this.src.describe(m)))) {
+                    this.fail(ctx, `'${this.src.text(ref)}': null/undefined are only allowed on fields and procedure inputs, not inside arrays`);
+                    return undefined;
+                }
+                return this.multi(ref, d.members, d.alias, ctx);
+            }
+            case 'array': {
+                const element = this.type(d.element, { ...ctx, path: `${ctx.path}[]`, anon: `${ctx.anon}[]` });
+                return element && { kind: 'array', element };
+            }
+            case 'builtin': {
+                if (d.name === 'Date')
+                    return { kind: 'scalar', scalar: 'timestamp' };
+                if (d.name === 'Uint8Array')
+                    return { kind: 'bytes' };
+                if (TYPED_ARRAYS.includes(d.name))
+                    return { kind: 'typedArray', array: d.name };
+                const hint = d.name.includes('Map') || d.name.includes('Set') ? ' (planned after alpha)' : '';
+                this.fail(ctx, `'${d.name}' is not supported${hint}`);
+                return undefined;
+            }
+            case 'object': return this.object(ref, d, ctx);
+            case 'other':
+                this.fail(ctx, `type '${d.text}' is not serializable`);
+                return undefined;
+            default:
+                this.fail(ctx, UNSUPPORTED[d.k] ?? `type '${this.src.text(ref)}' is not serializable`);
+                return undefined;
+        }
+    }
+    // Unions without null/undefined: booleans, string literal enums, discriminated unions of objects.
+    multi(whole, members, alias, ctx) {
+        const known = this.memo.get(whole.id);
+        if (known)
+            return known;
+        const ds = members.map((m) => this.src.describe(m));
+        if (ds.every((d) => d.k === 'literal' && typeof d.value === 'boolean'))
+            return { kind: 'scalar', scalar: 'bool' };
+        if (ds.every((d) => d.k === 'literal' && typeof d.value === 'string')) {
+            const name = this.claim(alias ?? ctx.anon, whole.id, ctx);
+            const values = ds.map((d) => d.value).sort();
+            this.schema.enums[name] = { name, values };
+            const t = { kind: 'enum', name };
+            this.memo.set(whole.id, t);
+            return t;
+        }
+        if (ds.every((d) => d.k === 'object')) {
+            const objs = ds;
+            const disc = findDiscriminant(this.src, objs);
+            if (!disc) {
+                this.fail(ctx, `union of objects needs a discriminant: a field present in every variant with distinct string literal values ('${this.src.text(whole)}')`);
+                return undefined;
+            }
+            const name = this.claim(alias ?? ctx.anon, whole.id, ctx);
+            const t = { kind: 'union', name };
+            this.memo.set(whole.id, t);
+            const variants = members.map((m, i) => {
+                const tag = disc.tags[i];
+                const obj = this.type(m, { path: `${ctx.path} (${tag})`, anon: `${name}#${tag}`, location: ctx.location });
+                return { tag, object: obj?.kind === 'object' ? obj.name : '' };
+            }).sort((a, b) => (a.tag < b.tag ? -1 : 1));
+            this.schema.unions[name] = { name, discriminant: disc.field, variants };
+            return t;
+        }
+        if (ds.every((d) => d.k === 'literal' && typeof d.value === 'number')) {
+            this.fail(ctx, `numeric literal unions are not supported yet ('${this.src.text(whole)}'); use string literals or a numeric brand`);
+        }
+        else {
+            this.fail(ctx, `union '${this.src.text(whole)}' is not serializable; supported: string literal unions, discriminated unions of objects, T | null, T | undefined`);
+        }
+        return undefined;
+    }
+    object(ref, d, ctx) {
+        const known = this.memo.get(ref.id);
+        if (known)
+            return known;
+        if (d.indexSignature) {
+            this.fail(ctx, `index signatures and Record<string, T> are not supported yet ('${this.src.text(ref)}')`);
+            return undefined;
+        }
+        const name = this.claim(d.name ?? ctx.anon, ref.id, ctx, d.location);
+        const t = { kind: 'object', name };
+        this.memo.set(ref.id, t); // before the fields: recursive types refer back by name
+        const def = { name, fields: [], location: d.location };
+        this.schema.objects[name] = def;
+        for (const p of d.props) {
+            const f = this.field(p, name);
+            if (f)
+                def.fields.push(f);
+        }
+        return t;
+    }
+    field(p, owner) {
+        const ctx = { path: `${owner}.${p.name}`, anon: `${owner}.${p.name}`, location: p.location };
+        if (p.name.startsWith('__@')) {
+            this.fail(ctx, 'symbol-keyed properties are not serializable');
+            return undefined;
+        }
+        const r = this.slot(p.type, ctx);
+        if (!r)
+            return undefined;
+        return { name: p.name, type: r.type, optional: r.optional || p.optional, nullable: r.nullable, renamedFrom: p.renamedFrom, location: p.location };
+    }
+    // Names are the identity of types in the lockfile: two different types may not share one.
+    claim(name, id, ctx, location = ctx.location) {
+        const prev = this.owners.get(name);
+        if (prev && prev.id !== id) {
+            const where = prev.location ? ` (other one at ${prev.location.file}:${prev.location.line})` : '';
+            this.fail(ctx, `two different types are named '${name}'${where}; rename one of them`, location);
+        }
+        else if (!prev) {
+            this.owners.set(name, { id, location });
+        }
+        return name;
+    }
+}
+function isNullish(d) {
+    return d.k === 'undefined' || d.k === 'null' || d.k === 'void';
+}
+function findDiscriminant(src, objs) {
+    const candidates = objs[0].props.map((p) => p.name);
+    for (const field of candidates) {
+        const tags = [];
+        for (const o of objs) {
+            const p = o.props.find((x) => x.name === field);
+            const d = p && !p.optional ? src.describe(p.type) : undefined;
+            if (d?.k !== 'literal' || typeof d.value !== 'string')
+                break;
+            tags.push(d.value);
+        }
+        if (tags.length === objs.length && new Set(tags).size === tags.length)
+            return { field, tags };
+    }
+    return undefined;
+}
+export function buildSchema(src, routerFile, exportName) {
+    const b = new Builder(src);
+    for (const entry of src.router(routerFile, exportName))
+        b.procedure(entry);
+    b.schema.procedures.sort((x, y) => (x.path < y.path ? -1 : 1));
+    return { schema: b.schema, errors: b.errors };
+}

package/dist/cli/cli.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env -S node --experimental-strip-types --no-warnings
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx, extraExtensions, ignoreCase) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        if (extraExtensions) {
+            for (var extension in extraExtensions) {
+                var suffix = path.slice(-extension.length);
+                if (suffix === extension || ignoreCase && suffix.toLowerCase() === extension.toLowerCase()) {
+                    var output = extraExtensions[extension];
+                    return output === extension ? path : path.slice(0, -extension.length) + output;
+                }
+            }
+        }
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// tbr generate | check | decode: schema IR, lockfile, generated codecs and a message dump.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { decodeError, FLAG_ERROR, VerifyError } from 'ts-bin-rpc/runtime';
+import { buildSchema } from './build.js';
+import { emitCodecs } from './emit.js';
+import { emptyLock, parseLock, stringifyLock, updateLock } from './lock.js';
+import { formatLocation } from './ir.js';
+import { printErrors, printSchema } from './print.js';
+import { Ts71Source } from './source.js';
+const USAGE = `usage: tbr generate | check [options]
+       tbr decode <file|-> (--proc <path> [--input] | --type <Name>) [options]
+
+  --project <tsconfig>     TypeScript project (default: tsconfig.json)
+  --router <file#export>   router to compile (default: src/router.ts#appRouter)
+  --lock <file>            lockfile (default: tbr.lock.json next to the tsconfig)
+  --out <file>             generated codecs (default: tbr.gen.ts next to the router)
+  --dry-run                generate: print the schema and the lockfile instead of writing
+  --allow-breaking         generate: accept breaking changes
+  --watch, -w              generate: regenerate on every change to the project's files
+  --proc <path>            decode: the message is the output of this procedure (with --input: its input)
+  --type <Name>            decode: the message is this object type
+`;
+export function run(argv, out = (s) => process.stdout.write(s), options = {}) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            project: { type: 'string', default: 'tsconfig.json' },
+            router: { type: 'string', default: 'src/router.ts#appRouter' },
+            lock: { type: 'string' },
+            out: { type: 'string' },
+            'dry-run': { type: 'boolean', default: false },
+            'allow-breaking': { type: 'boolean', default: false },
+            watch: { type: 'boolean', short: 'w', default: false },
+            proc: { type: 'string' },
+            type: { type: 'string' },
+            input: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+    const command = positionals[0];
+    if (values.help || (command !== 'generate' && command !== 'check' && command !== 'decode')) {
+        out(USAGE);
+        return values.help ? 0 : 2;
+    }
+    const project = path.resolve(values.project);
+    const root = path.dirname(project);
+    const [routerFile, exportName = 'appRouter'] = values.router.split('#');
+    const lockPath = path.resolve(values.lock ?? path.join(root, 'tbr.lock.json'));
+    const outPath = path.resolve(values.out ?? path.join(path.dirname(path.resolve(root, routerFile)), 'tbr.gen.ts'));
+    if (command === 'decode') {
+        if (!positionals[1] || !!values.proc === !!values.type) {
+            out(USAGE);
+            return 2;
+        }
+        return decode(positionals[1], outPath, values, out);
+    }
+    const paths = { root, router: path.resolve(root, routerFile), exportName, lockPath, outPath };
+    if (values.watch) {
+        if (command !== 'generate') {
+            out('--watch works with generate only\n');
+            return 2;
+        }
+        return watch(project, paths, values, out, options.signal);
+    }
+    const src = new Ts71Source(project);
+    try {
+        return command === 'check' ? check(src, paths, out) : generate(src, paths, readLock(lockPath), values, out);
+    }
+    finally {
+        src.close();
+    }
+}
+function readLock(lockPath) {
+    const exists = fs.existsSync(lockPath);
+    return { exists, lock: exists ? parseLock(fs.readFileSync(lockPath, 'utf8')) : emptyLock() };
+}
+const rel = (p) => path.relative(process.cwd(), p) || p;
+/** The schema, or null after printing why it cannot be built. */
+function schemaOf(src, p, out) {
+    const built = buildSchema(src, p.router, p.exportName);
+    if (!built.errors.length)
+        return built.schema;
+    out(`${built.errors.length} type(s) cannot be sent over the wire:\n` + printErrors(built.errors));
+    return null;
+}
+function check(src, p, out) {
+    const schema = schemaOf(src, p, out);
+    if (!schema)
+        return 1;
+    const prev = readLock(p.lockPath);
+    if (!prev.exists) {
+        out(`${rel(p.lockPath)} does not exist; run tbr generate\n`);
+        return 1;
+    }
+    const { lock, changes } = updateLock(prev.lock, schema);
+    if (stringifyLock(lock) === fs.readFileSync(p.lockPath, 'utf8')) {
+        out(`${rel(p.lockPath)} is up to date\n`);
+        return 0;
+    }
+    out(`${rel(p.lockPath)} is out of date:\n` + printChanges(changes));
+    out(changes.some((c) => c.severity !== 'safe') ? 'the contract has breaking changes\n' : 'run tbr generate\n');
+    return 1;
+}
+/**
+ * Updates the lockfile from `prev` and writes the codecs. In watch mode `prev` is the lockfile as it was
+ * when watching started, so a field that is added and renamed between two saves never reaches it.
+ */
+function generate(src, p, prev, o, out) {
+    const schema = schemaOf(src, p, out);
+    if (!schema)
+        return 1;
+    const { lock, changes } = updateLock(prev.lock, schema);
+    const text = stringifyLock(lock);
+    const current = fs.existsSync(p.lockPath) ? fs.readFileSync(p.lockPath, 'utf8') : null;
+    if (changes.length)
+        out(printChanges(changes));
+    const blocking = changes.filter((c) => c.severity === 'error' || (c.severity === 'breaking' && !o['allow-breaking']));
+    if (blocking.length) {
+        const hint = blocking.some((c) => c.severity === 'error') ? '' : '; rerun with --allow-breaking to accept them';
+        out(`${blocking.length} change(s) not applied${hint}\n`);
+        return 1;
+    }
+    if (o['dry-run']) {
+        out(printSchema(schema) + `\n// ${rel(p.lockPath)}\n` + text);
+        return 0;
+    }
+    if (text === current)
+        out(`${rel(p.lockPath)} is up to date\n`);
+    else {
+        fs.writeFileSync(p.lockPath, text);
+        out(`${current === null ? 'created' : 'updated'} ${rel(p.lockPath)}\n`);
+    }
+    let from = path.relative(path.dirname(p.outPath), p.router).split(path.sep).join('/');
+    if (!from.startsWith('.'))
+        from = `./${from}`;
+    const code = emitCodecs(schema, lock, { router: { from, name: p.exportName } });
+    if (fs.existsSync(p.outPath) && fs.readFileSync(p.outPath, 'utf8') === code)
+        out(`${rel(p.outPath)} is up to date\n`);
+    else {
+        fs.writeFileSync(p.outPath, code);
+        out(`wrote ${rel(p.outPath)}\n`);
+    }
+    return 0;
+}
+const WATCHED = /\.[mc]?tsx?$|(^|[\\/])tsconfig[^\\/]*\.json$/;
+const DEBOUNCE_MS = 30;
+/**
+ * generate --watch: one TypeScript project kept open, a fresh snapshot per batch of changes (the compiler
+ * reuses unchanged files), regeneration on every save. Resolves when `signal` aborts.
+ */
+function watch(project, p, o, out, signal) {
+    const src = new Ts71Source(project);
+    let base = readLock(p.lockPath);
+    let written = base.exists ? fs.readFileSync(p.lockPath, 'utf8') : null;
+    const pending = new Map();
+    let timer;
+    const regenerate = (label) => {
+        const start = performance.now();
+        let code;
+        try {
+            code = generate(src, p, base, o, out);
+        }
+        catch (e) {
+            out(`${e instanceof Error ? e.message : String(e)}\n`);
+            code = 1;
+        }
+        if (fs.existsSync(p.lockPath))
+            written = fs.readFileSync(p.lockPath, 'utf8');
+        out(`${label} in ${(performance.now() - start).toFixed(0)} ms${code ? ', waiting for changes' : ''}\n`);
+    };
+    const flush = () => {
+        timer = undefined;
+        const files = { changed: [], created: [], deleted: [] };
+        for (const [f, kind] of pending)
+            files[kind].push(f);
+        pending.clear();
+        const start = performance.now();
+        src.update(files);
+        const names = [...files.changed, ...files.created, ...files.deleted].map(rel);
+        out(`\n${names.join(', ')} changed (snapshot ${(performance.now() - start).toFixed(0)} ms)\n`);
+        regenerate('regenerated');
+    };
+    regenerate('generated');
+    out(`watching ${path.relative(process.cwd(), p.root) || '.'} for changes\n`);
+    const watcher = fs.watch(p.root, { recursive: true }, (event, name) => {
+        if (!name)
+            return;
+        const file = path.join(p.root, name);
+        if (file === p.lockPath) {
+            // Someone else changed the lockfile (git checkout, a teammate's pull): it is the new base.
+            const now = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+            if (now === written)
+                return;
+            written = now;
+            base = readLock(p.lockPath);
+            out(`\n${rel(file)} changed outside of watch; using it as the base\n`);
+            regenerate('regenerated');
+            return;
+        }
+        if (file === p.outPath || !WATCHED.test(name) || name.split(/[\\/]/).some((s) => s === 'node_modules' || s.startsWith('.')))
+            return;
+        const kind = event === 'change' ? 'changed' : fs.existsSync(file) ? 'created' : 'deleted';
+        pending.set(file, pending.get(file) === 'created' && kind === 'changed' ? 'created' : kind);
+        clearTimeout(timer);
+        timer = setTimeout(flush, DEBOUNCE_MS);
+    });
+    return new Promise((resolve) => {
+        const stop = () => {
+            clearTimeout(timer);
+            watcher.close();
+            src.close();
+            resolve(0);
+        };
+        if (signal?.aborted)
+            stop();
+        else
+            signal?.addEventListener('abort', stop, { once: true });
+    });
+}
+async function decode(file, genPath, o, out) {
+    const bytes = new Uint8Array(fs.readFileSync(file === '-' ? 0 : file));
+    try {
+        if (bytes.length > 3 && bytes[3] & FLAG_ERROR) {
+            const e = decodeError(bytes);
+            const data = e.data && JSON.parse(new TextDecoder().decode(e.data));
+            out(dump({ error: { code: e.code, message: e.message, data } }));
+            return 0;
+        }
+        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(genPath).href)));
+        const what = o.type ? `type '${o.type}'` : `${o.input ? 'input' : 'output'} of '${o.proc}'`;
+        const proc = o.proc ? mod.procedures[o.proc] : undefined;
+        const codec = o.type ? mod.codecs[o.type] : o.input ? proc?.input : proc?.output;
+        if (!codec) {
+            out(`${path.relative(process.cwd(), genPath)} has no ${what}\n`);
+            return 1;
+        }
+        out(dump(codec.decode(bytes)));
+        return 0;
+    }
+    catch (e) {
+        if (!(e instanceof VerifyError))
+            throw e;
+        out(`invalid message: ${e.message}\n`);
+        return 1;
+    }
+}
+/** JSON with bigints as strings and typed arrays as arrays. */
+function dump(v) {
+    const json = JSON.stringify(v, (_, x) => (typeof x === 'bigint' ? x.toString() : ArrayBuffer.isView(x) && !(x instanceof DataView) ? Array.from(x, Number) : x), 2);
+    return json + '\n';
+}
+function printChanges(changes) {
+    const order = { error: 0, breaking: 1, safe: 2 };
+    return [...changes]
+        .sort((a, b) => order[a.severity] - order[b.severity])
+        .map((c) => `  ${c.severity.padEnd(8)} ${c.path}: ${c.message}${c.location ? `  (${formatLocation(c.location)})` : ''}\n`)
+        .join('');
+}
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === import.meta.filename) {
+    process.stdout.on('error', (e) => {
+        if (e.code === 'EPIPE')
+            process.exit(process.exitCode ?? 0); // `tbr generate --dry-run | head`
+        throw e;
+    });
+    const stop = new AbortController();
+    process.once('SIGINT', () => stop.abort()); // --watch: close the TypeScript process, then exit
+    Promise.resolve(run(process.argv.slice(2), undefined, { signal: stop.signal })).then((code) => (process.exitCode = code));
+}