tslaws 0.3.2 → 0.5.0

package/README.md

@@ -159,13 +159,14 @@ See [docs/laws.md](../../docs/laws.md#the-dashboard).
 
 `tslaws mutate [files...] [--max N] [--seed N] [--json]` mutation-tests the laws: it mutates the covered code, re-runs the laws against each mutant, and lists the survivors no law caught. It handles `.tsx`/`.jsx` and projects with a lock, and takes the run flags of `check`. See [docs/laws.md](../../docs/laws.md#mutation-testing).
 
+- **Other source formats:** `tslaws.json` `bundlerPlugins` lists esbuild plugin modules (paths relative to the file) that teach the browser bundler formats like `.tsrx`. See [docs/laws.md](../../docs/laws.md#bundler-plugins).
 - **Settings:** `tslaws.json` `runs`, `bound`, `proofTimeoutMs` and `propertyTimeoutMs` set the run defaults; a command line flag beats them. See [docs/laws.md](../../docs/laws.md#settings).
 
 ## Agents cannot move the goalposts
 
 `tsc-laws.lock` holds a hash of every law declaration and the list of coverage exemptions. A change, an added law, a removed
 law or a new `@tslaws-exempt` fails the check until a person runs `tslaws accept`, which refuses to run without a terminal,
-under `CI`, or with `TSLAWS_AGENT` set. Agents propose laws in `*.proposed.laws.ts` and try them with `tslaws check
+under `CI`, or with `TSLAWS_AGENT` set, unless a person has lent it for a limited time with `tslaws delegate grant`. Agents propose laws in `*.proposed.laws.ts` and try them with `tslaws check
 --proposed` (no lock, no coverage gate); a person moves them into a `*.laws.ts` file and accepts.
 
 `hooks/claude-hook.mjs` is a Claude Code hook that blocks `git commit` and sends an agent back to work when the check fails;
@@ -176,6 +177,9 @@ under `CI`, or with `TSLAWS_AGENT` set. Agents propose laws in `*.proposed.laws.
 ```
 tslaws init [--force]
 tslaws accept [files...]
+tslaws delegate grant [--for 1h|8h|1d|7d] [--root DIR]
+tslaws delegate revoke [--root DIR]
+tslaws delegate status
 tslaws check [files...] [--json] [--summary] [--watch] [--runs N] [--seed N] [--no-prove] [--bound N]
              [--proof-timeout MS] [--property-timeout MS] [--proposed] [--compiler PATH]
 ```
@@ -183,7 +187,12 @@ tslaws check [files...] [--json] [--summary] [--watch] [--runs N] [--seed N] [--
 - `init` scaffolds `tslaws.json`, the `.tslaws` ignore entry, the agent rules in `AGENTS.md`, the Claude Code hook in
   `.claude/settings.json`, and a starter law if none exists. It never writes the lock; a person then runs `accept`.
 - `accept` records the laws and the `@tslaws-exempt` functions in `tsc-laws.lock`. It refuses to run without a terminal,
-  under `CI`, or with `TSLAWS_AGENT` set.
+  under `CI`, or with `TSLAWS_AGENT` set, unless a live delegation covers the project (never under `CI`).
+- `delegate grant` lends `accept` to agents for 1h, 8h (default), 1d or 7d (the most), for one project root. `delegate revoke`
+  withdraws it and `delegate status` lists grants; `grant` and `revoke` need a terminal and refuse under `CI` or
+  `TSLAWS_AGENT`. The grant lives in `~/.tslaws/delegation.json`, outside the repository (found through the operating
+  system's user record, not `HOME`; an agent running as the same user can still write that file). A delegated `accept` appends to `.tslaws/accept.log` and prints `DELEGATED ACCEPT`.
+  A grant is a person's decision, bounded in time, outside the repo, audited in `accept.log`. See [docs/laws.md](../../docs/laws.md#lending-accept-to-an-agent).
 - `check` exits 0 only when every law is `proved`, `bounded` or `tested`, nothing is `uncovered`, the files compile and the
   lock matches. `--json` adds a `hint` to each result, the concrete next action for an agent. `--summary` prints only the
   results that do not pass, plus the totals. `--watch` re-runs on every `.ts` change.

package/dist/browser.js

@@ -2,8 +2,10 @@
 // each input is sent to a page where the compiled law and the code it checks run against a live DOM.
 import { existsSync } from 'node:fs';
 import { mkdirSync } from 'node:fs';
-import { delimiter, join } from 'node:path';
+import { delimiter, join, relative as pathRelative, resolve, sep } from 'node:path';
 import { build as bundleWith } from 'esbuild';
+import { explainBundleError, loadBundlerPlugins } from "./bundlerPlugins.js";
+import { readConfig } from "./coverage.js";
 import { chromium, firefox, webkit } from 'playwright-core';
 import { toWire } from "./generators.js";
 import { runProperty, summarise } from "./property.js";
@@ -156,21 +158,70 @@ function projectModulesPlugin(cwd) {
         },
     };
 }
+// The compiler writes only what it compiles to .tslaws/out, so a relative import of any other source file (a `.tsrx`
+// template, a stylesheet, an image) would look for it there. Such an import resolves to the file beside the source.
+function sourceFilesPlugin(cwd) {
+    const out = join(cwd, '.tslaws', 'out');
+    return {
+        name: 'tslaws-source-files',
+        setup(build) {
+            build.onResolve({ filter: /^\.\.?\// }, (args) => {
+                if (args.resolveDir !== out && !args.resolveDir.startsWith(out + sep))
+                    return undefined;
+                const inOut = resolve(args.resolveDir, args.path);
+                if (existsSync(inOut))
+                    return undefined;
+                const source = join(cwd, pathRelative(out, inOut));
+                return existsSync(source) && !source.endsWith('.js') ? { path: source } : undefined;
+            });
+        },
+    };
+}
+const assetExtensions = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.avif',
+    '.svg',
+    '.ico',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.otf',
+    '.eot',
+];
+/** The project's `bundlerPlugins` from tslaws.json come first, so they can claim a format before the built-in resolver. */
 async function bundleOf(jsFile, cwd) {
-    const result = await bundleWith({
-        plugins: [projectModulesPlugin(cwd)],
-        entryPoints: [jsFile],
-        bundle: true,
-        write: false,
-        format: 'iife',
-        globalName: '__lawModule',
-        platform: 'browser',
-        target: 'es2022',
-        absWorkingDir: cwd,
-        logLevel: 'silent',
-        define: { 'process.env.NODE_ENV': '"development"', global: 'globalThis' },
-    });
-    return result.outputFiles[0].text;
+    const projectPlugins = await loadBundlerPlugins(cwd, readConfig(cwd).bundlerPlugins);
+    try {
+        const result = await bundleWith({
+            plugins: [...projectPlugins, sourceFilesPlugin(cwd), projectModulesPlugin(cwd)],
+            entryPoints: [jsFile],
+            bundle: true,
+            write: false,
+            // Stylesheets a law imports come out as a separate .css file, which needs an output directory to be named.
+            outdir: join(cwd, '.tslaws', 'bundle'),
+            // Images and fonts become data URLs, so a url() in the CSS or an import in the JavaScript needs no file server.
+            loader: Object.fromEntries(assetExtensions.map((extension) => [extension, 'dataurl'])),
+            format: 'iife',
+            globalName: '__lawModule',
+            platform: 'browser',
+            target: 'es2022',
+            absWorkingDir: cwd,
+            logLevel: 'silent',
+            define: { 'process.env.NODE_ENV': '"development"', global: 'globalThis' },
+        });
+        const emitted = (extension) => result.outputFiles
+            .filter((file) => file.path.endsWith(extension))
+            .map((file) => file.text)
+            .join('\n');
+        return { js: emitted('.js'), css: emitted('.css') };
+    }
+    catch (error) {
+        throw explainBundleError(error);
+    }
 }
 /** Runs the counterexample once more, leaves the DOM as it is, and photographs the page. Best effort. */
 async function capture(page, law, args, options) {
@@ -187,7 +238,7 @@ async function capture(page, law, args, options) {
 }
 /** Property-tests one law in a page; `'timeout'` when it does not finish within `options.propertyTimeoutMs`. */
 export async function runBrowserLaw(law, options) {
-    const code = await bundleOf(law.jsFile, options.cwd);
+    const { js: code, css } = await bundleOf(law.jsFile, options.cwd);
     const page = await (await launch(resolveEngine(options.browser))).newPage();
     // A watcher needs only the first few runs to linger; the rest should not eat the time limit.
     let calls = 0;
@@ -216,6 +267,9 @@ export async function runBrowserLaw(law, options) {
         : undefined;
     try {
         await page.setContent('<!doctype html><html><head><meta charset="utf-8"></head><body></body></html>');
+        // The stylesheet goes in before the script runs, as a linked one would.
+        if (css !== '')
+            await page.addStyleTag({ content: css });
         await page.addScriptTag({ content: code });
         await page.addScriptTag({ content: harness });
         const call = async (...args) => {

package/dist/bundlerPlugins.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'esbuild';
+/** What a plugin factory receives. */
+export interface BundlerPluginContext {
+    /** The project root: the directory holding tslaws.json. */
+    cwd: string;
+}
+export type BundlerPluginExport = Plugin | ((context: BundlerPluginContext) => Plugin | Promise<Plugin>);
+/** The setting the messages name. */
+export declare const bundlerPluginsSetting = "bundlerPlugins";
+/**
+ * Loads each listed module (paths relative to `cwd`, where tslaws.json lives) with a dynamic import of its file URL.
+ * Throws one error naming the setting and the module when a module is missing, throws while loading or in its
+ * factory, or does not export a plugin, so the law file reports an `error` rather than the run crashing.
+ */
+export declare function loadBundlerPlugins(cwd: string, paths: readonly string[] | undefined): Promise<Plugin[]>;
+/**
+ * Rewrites an esbuild failure into advice when the cause is a source format the bundler has no loader for (the usual
+ * sign that a `bundlerPlugins` entry is missing). Other messages pass through unchanged.
+ */
+export declare function explainBundleError(error: Error): Error;

package/dist/bundlerPlugins.js

@@ -0,0 +1,71 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        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;
+};
+// Bundler plugins: a project teaches the browser bundler a source format (`.tsrx`, `.svelte`, ...) by listing esbuild
+// plugin modules under `bundlerPlugins` in tslaws.json. Each module default-exports an esbuild Plugin, or a function
+// (sync or async) that takes `{ cwd }` and returns one.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** The setting the messages name. */
+export const bundlerPluginsSetting = 'bundlerPlugins';
+/**
+ * Loads each listed module (paths relative to `cwd`, where tslaws.json lives) with a dynamic import of its file URL.
+ * Throws one error naming the setting and the module when a module is missing, throws while loading or in its
+ * factory, or does not export a plugin, so the law file reports an `error` rather than the run crashing.
+ */
+export async function loadBundlerPlugins(cwd, paths) {
+    const plugins = [];
+    for (const path of paths ?? []) {
+        const file = isAbsolute(path) ? path : resolve(cwd, path);
+        const fail = (why) => {
+            throw new Error(`tslaws.json ${bundlerPluginsSetting}: cannot use "${path}" (${file}): ${why}`);
+        };
+        if (!existsSync(file))
+            fail('no such file; paths are relative to the directory of tslaws.json');
+        let exported;
+        try {
+            exported = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href))).default;
+        }
+        catch (error) {
+            return fail(`it failed to load: ${error.message}`);
+        }
+        let plugin = exported;
+        if (typeof exported === 'function') {
+            try {
+                plugin = await exported({ cwd });
+            }
+            catch (error) {
+                return fail(`its plugin function threw: ${error.message}`);
+            }
+        }
+        const candidate = plugin;
+        if (typeof candidate !== 'object' ||
+            candidate === null ||
+            typeof candidate.name !== 'string' ||
+            typeof candidate.setup !== 'function')
+            fail('its default export must be an esbuild plugin ({ name, setup }) or a function returning one');
+        plugins.push(plugin);
+    }
+    return plugins;
+}
+/**
+ * Rewrites an esbuild failure into advice when the cause is a source format the bundler has no loader for (the usual
+ * sign that a `bundlerPlugins` entry is missing). Other messages pass through unchanged.
+ */
+export function explainBundleError(error) {
+    const match = /No loader is configured for "(\.[^"]+)" files/.exec(error.message);
+    if (match === null)
+        return error;
+    const extension = match[1];
+    const advice = `the browser bundler cannot load "${extension}" files. Add a bundler plugin for that extension in tslaws.json ` +
+        `"${bundlerPluginsSetting}", for example { "${bundlerPluginsSetting}": ["./tools/${extension.slice(1)}-plugin.mjs"] }, ` +
+        `where the module default-exports an esbuild plugin whose onLoad({ filter: /\${extension}$/ }) returns the compiled ` +
+        `JavaScript (see "Bundler plugins" in docs/laws.md)`;
+    return new Error(`${advice}. esbuild said: ${error.message.split('\n')[0]}`);
+}

package/dist/cli.d.ts

@@ -1 +1,13 @@
+/** What a command needs from its caller. `home` is for unit tests; the CLI never sets it. */
+export interface CommandContext {
+    isTTY: boolean;
+    env: NodeJS.ProcessEnv;
+    home?: string;
+    now?: Date;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+}
+export declare function acceptCommand(cwd: string, flags: Map<string, string | true>, files: string[], ctx: CommandContext): Promise<number>;
+/** `tslaws delegate <action> [--for D] [--root DIR]`; `argv` is everything after `delegate`. */
+export declare function runDelegateCommand(argv: string[], cwd: string, ctx: CommandContext): number;
 export declare function main(args: string[]): Promise<number>;

package/dist/cli.js

@@ -15,13 +15,17 @@ import { readConfig } from "./coverage.js";
 import { mutate, renderMutation } from "./mutate.js";
 import { mutateDefaults, resolveSettings } from "./settings.js";
 import { serveUi } from "./ui.js";
+import { acceptGate, defaultDuration, describeGrants, fileHash, grantFor, logDelegatedAccept, parseDuration, personOnly, revokeFor, } from "./delegation.js";
 import { writeLock } from "./lock.js";
 const usage = `tslaws init [--force]       scaffold tslaws.json, .gitignore, AGENTS.md, Claude Code hooks and a starter law (never writes the lock)
 tslaws check [files...] [--reporter text|json|junit|github] [--json] [--summary] [--watch] [--runs N] [--seed N] [--no-prove] [--no-regressions] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--proposed] [--compiler PATH] [--browser chromium|firefox|webkit]
 tslaws ui [files...] [--port N] [--no-open] [--tab]   open a dashboard of the laws in its own desktop window (--tab: a browser tab): tree, filters, search, source, live reruns on save
 tslaws mutate [files...] [--max N] [--seed N] [--runs N] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--browser ENGINE] [--json]   mutation-test the laws: mutate covered code, report mutants no law kills
 tslaws regressions [list|clear]   show or delete the stored counterexamples (.tslaws/regressions); check replays them first, --no-regressions skips them
-tslaws accept [files...]     record the current laws in tsc-laws.lock (people only: needs a terminal)
+tslaws accept [files...]     record the current laws in tsc-laws.lock (people only: needs a terminal, or a live delegation; never under CI)
+tslaws delegate grant [--for 1h|8h|1d|7d] [--root DIR]   lend accept to an agent for a limited time (people only; default 8h, max 7d)
+tslaws delegate revoke [--root DIR]   withdraw the delegation for a project (people only)
+tslaws delegate status        list delegations and when they end
 tslaws promote [file] [--all]   move proposed laws (*.proposed.laws.ts) into the accepted *.laws.ts, asking per law (people only: needs a terminal; run accept afterwards)
 tslaws mcp [--compiler PATH]   serve check, check_proposed, explain and propose as Model Context Protocol tools on stdio (cannot accept or touch the lock)
 
@@ -65,6 +69,8 @@ function parse(args) {
         'port',
         'reporter',
         'max',
+        'for',
+        'root',
     ]);
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -83,7 +89,8 @@ function parse(args) {
                 arg === 'mutate' ||
                 arg === 'regressions' ||
                 arg === 'mcp' ||
-                arg === 'promote'))
+                arg === 'promote' ||
+                arg === 'delegate'))
             command = arg;
         else
             files.push(arg);
@@ -229,6 +236,89 @@ async function watchChecks(cwd, flags, files) {
         });
     });
 }
+const stdoutWrite = (text) => void process.stdout.write(text);
+const stderrWrite = (text) => void process.stderr.write(text);
+export async function acceptCommand(cwd, flags, files, ctx) {
+    const out = ctx.out ?? stdoutWrite;
+    const err = ctx.err ?? stderrWrite;
+    const chosen = lawFiles(cwd, flags, files);
+    if (chosen.length === 0) {
+        err('no laws files found (looking for *.laws.ts)\n');
+        return 1;
+    }
+    const gate = acceptGate({ isTTY: ctx.isTTY, env: ctx.env, root: cwd, now: ctx.now, home: ctx.home });
+    if (!gate.ok) {
+        err(`${gate.message}\n`);
+        return 1;
+    }
+    const opts = options(cwd, flags, chosen);
+    const laws = readManifest(opts.compiler, opts.files, cwd);
+    out(`${laws.length} laws in ${chosen.length} files:\n${laws.map((l) => `  ${l.file}:${l.line} ${l.name}`).join('\n')}\n`);
+    if (!gate.delegated) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question('Type ACCEPT to write tsc-laws.lock: ');
+        rl.close();
+        if (answer.trim() !== 'ACCEPT')
+            return 1;
+    }
+    const before = fileHash(opts.lockFile);
+    const exempt = exemptionsOf(opts);
+    if (exempt.length > 0)
+        out(`exempt from coverage:\n${exempt.map((e) => `  ${e}`).join('\n')}\n`);
+    writeLock(opts.lockFile, laws, exempt);
+    out('tsc-laws.lock written\n');
+    if (gate.delegated) {
+        logDelegatedAccept(cwd, gate.grant, before, fileHash(opts.lockFile), ctx.now ?? new Date());
+        out(`DELEGATED ACCEPT: a person lent this act until ${gate.grant.expires}; recorded in .tslaws/accept.log\n`);
+    }
+    return 0;
+}
+/** `tslaws delegate <action> [--for D] [--root DIR]`; `argv` is everything after `delegate`. */
+export function runDelegateCommand(argv, cwd, ctx) {
+    const { flags, files } = parse(['delegate', ...argv]);
+    return delegateCommand(cwd, files[0], flags, ctx);
+}
+function delegateCommand(cwd, action, flags, ctx) {
+    const out = ctx.out ?? stdoutWrite;
+    const err = ctx.err ?? stderrWrite;
+    const now = ctx.now ?? new Date();
+    if (action === 'status') {
+        out(`${describeGrants(now, ctx.home).join('\n')}\n`);
+        return 0;
+    }
+    if (action !== 'grant' && action !== 'revoke') {
+        err('usage: tslaws delegate grant|revoke|status\n');
+        return 1;
+    }
+    if (!personOnly({ isTTY: ctx.isTTY, env: ctx.env })) {
+        err(`delegate ${action} is a person's decision and needs a terminal; it will not run here\n`);
+        return 1;
+    }
+    const rootFlag = flags.get('root');
+    const target = rootFlag === undefined || rootFlag === true ? cwd : resolve(cwd, rootFlag);
+    if (action === 'revoke') {
+        const removed = revokeFor(target, ctx.home);
+        if (typeof removed === 'string') {
+            err(`${removed}\n`);
+            return 1;
+        }
+        out(`${removed} delegation${removed === 1 ? '' : 's'} revoked\n`);
+        return 0;
+    }
+    const lengthFlag = flags.get('for');
+    const ms = parseDuration(lengthFlag === undefined ? defaultDuration : String(lengthFlag));
+    if (ms === undefined) {
+        err('--for takes 1h, 8h, 1d or 7d (the most is 7d)\n');
+        return 1;
+    }
+    const granted = grantFor(target, ms, now, ctx.home);
+    if (typeof granted === 'string') {
+        err(`${granted}\n`);
+        return 1;
+    }
+    out(`accept is lent to agents for ${granted.root} until ${granted.expires}\n`);
+    return 0;
+}
 export async function main(args) {
     if (args.includes('--help') || args.includes('-h')) {
         process.stdout.write(`${usage}\n`);
@@ -240,31 +330,10 @@ export async function main(args) {
         process.stdout.write(`${init({ cwd, force: flags.has('force') }).join('\n')}\n\n${nextStep}\n`);
         return 0;
     }
-    if (command === 'accept') {
-        const chosen = lawFiles(cwd, flags, files);
-        if (chosen.length === 0) {
-            process.stderr.write('no laws files found (looking for *.laws.ts)\n');
-            return 1;
-        }
-        if (!process.stdin.isTTY || process.env.TSLAWS_AGENT !== undefined || process.env.CI !== undefined) {
-            process.stderr.write('accept records laws as correct and needs a person at a terminal; it will not run here\n');
-            return 1;
-        }
-        const opts = options(cwd, flags, chosen);
-        const laws = readManifest(opts.compiler, opts.files, cwd);
-        process.stdout.write(`${laws.length} laws in ${chosen.length} files:\n${laws.map((l) => `  ${l.file}:${l.line} ${l.name}`).join('\n')}\n`);
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await rl.question('Type ACCEPT to write tsc-laws.lock: ');
-        rl.close();
-        if (answer.trim() !== 'ACCEPT')
-            return 1;
-        const exempt = exemptionsOf(opts);
-        if (exempt.length > 0)
-            process.stdout.write(`exempt from coverage:\n${exempt.map((e) => `  ${e}`).join('\n')}\n`);
-        writeLock(opts.lockFile, laws, exempt);
-        process.stdout.write('tsc-laws.lock written\n');
-        return 0;
-    }
+    if (command === 'accept')
+        return acceptCommand(cwd, flags, files, { isTTY: process.stdin.isTTY === true, env: process.env });
+    if (command === 'delegate')
+        return delegateCommand(cwd, files[0], flags, { isTTY: process.stdin.isTTY === true, env: process.env });
     if (command === 'mcp')
         return serveMcp({ cwd, compiler: options(cwd, flags, []).compiler });
     if (command === 'promote') {

package/dist/coverage.d.ts

@@ -6,6 +6,8 @@ export interface CoverageConfig {
     compilerOptions?: Record<string, unknown>;
     /** End-to-end laws: the app to drive; see `parseE2eConfig`. */
     e2e?: E2eConfig;
+    /** esbuild plugin modules (paths relative to tslaws.json) that teach the browser bundler new source formats. */
+    bundlerPlugins?: string[];
     /** Run settings; a command line flag beats them and they beat the built-in default. */
     runs?: number;
     propertyTimeoutMs?: number;

package/dist/coverage.js

@@ -9,7 +9,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 import ts from 'typescript';
 import { parseE2eConfig } from "./e2e.js";
 const settingKeys = ['runs', 'propertyTimeoutMs', 'proofTimeoutMs', 'bound'];
-const configKeys = ['cover', 'compilerOptions', 'e2e', ...settingKeys];
+const configKeys = ['cover', 'compilerOptions', 'e2e', 'bundlerPlugins', ...settingKeys];
 /** Validates the top level of tslaws.json: known keys only, and the run settings are integers of at least 1. */
 export function parseConfig(raw) {
     const fail = (message) => {
@@ -27,6 +27,10 @@ export function parseConfig(raw) {
         if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < 1))
             fail(`"${key}" must be an integer of at least 1, got ${JSON.stringify(value)}`);
     }
+    const plugins = object.bundlerPlugins;
+    if (plugins !== undefined &&
+        (!Array.isArray(plugins) || plugins.some((entry) => typeof entry !== 'string' || entry === '')))
+        fail(`"bundlerPlugins" must be an array of module paths, got ${JSON.stringify(plugins)}`);
     return object;
 }
 export function readConfig(cwd) {

package/dist/delegation.d.ts

@@ -0,0 +1,68 @@
+export interface Grant {
+    root: string;
+    expires: string;
+    note?: string;
+}
+export declare const defaultDuration = "8h";
+/**
+ * The person's home directory from the operating system's user record (getpwuid on POSIX, the profile directory of the
+ * user token on Windows). HOME and USERPROFILE are ignored on purpose. An empty string means it cannot be found.
+ */
+export declare function userHome(): string;
+/** The grants file under a home directory: the real one by default, a temp directory in unit tests. */
+export declare function delegationFile(home?: string): string;
+export declare function parseDuration(text: string): number | undefined;
+/** The real path of a directory; undefined when it is missing. */
+export declare function realRoot(dir: string): string | undefined;
+export type Grants = {
+    ok: true;
+    grants: Grant[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Reads the grants. A missing file is an empty list; an unsafe or malformed one is an error. */
+export declare function readGrants(home?: string): Grants;
+export type Verdict = {
+    ok: true;
+    grant: Grant;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The live grant for a project root. Real paths are compared, and a grant naming a symlink never matches. */
+export declare function findGrant(root: string, now: Date, home?: string): Verdict;
+export interface GateInput {
+    isTTY: boolean;
+    env: NodeJS.ProcessEnv;
+    root: string;
+    now?: Date;
+    /** Home directory holding the grants; unit tests pass a temp directory. */
+    home?: string;
+}
+export type Gate = {
+    ok: true;
+    delegated: false;
+} | {
+    ok: true;
+    delegated: true;
+    grant: Grant;
+} | {
+    ok: false;
+    message: string;
+};
+/** Decides whether `accept` may run: a person at a terminal, else a live grant. CI never. */
+export declare function acceptGate(input: GateInput): Gate;
+/** The gate for acts only a person may do: a terminal, no agent marker, no CI. */
+export declare function personOnly(input: {
+    isTTY: boolean;
+    env: NodeJS.ProcessEnv;
+}): boolean;
+/** Records a grant for a project; returns it, or the reason it was refused. */
+export declare function grantFor(root: string, ms: number, now: Date, home?: string): Grant | string;
+/** Removes the grants for a project; returns how many, or the reason it was refused. */
+export declare function revokeFor(root: string, home?: string): number | string;
+export declare function describeGrants(now: Date, home?: string): string[];
+export declare function fileHash(path: string): string;
+/** Appends the audit line for a delegated accept to `<project>/.tslaws/accept.log`. */
+export declare function logDelegatedAccept(root: string, grant: Grant, before: string, after: string, now: Date): void;

package/dist/delegation.js

@@ -0,0 +1,199 @@
+// A person's time-limited delegation of `tslaws accept` to an agent. The grant lives in the person's home
+// directory, outside every project, so nothing an agent can edit in a repository can create one.
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { userInfo } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+export const defaultDuration = '8h';
+const hour = 3_600_000;
+const durations = { '1h': hour, '8h': 8 * hour, '1d': 24 * hour, '7d': 168 * hour };
+const regrant = 'run `tslaws delegate grant` at a terminal to lend accept for a limited time';
+/**
+ * The person's home directory from the operating system's user record (getpwuid on POSIX, the profile directory of the
+ * user token on Windows). HOME and USERPROFILE are ignored on purpose. An empty string means it cannot be found.
+ */
+export function userHome() {
+    try {
+        return userInfo().homedir;
+    }
+    catch {
+        return '';
+    }
+}
+/** The grants file under a home directory: the real one by default, a temp directory in unit tests. */
+export function delegationFile(home = userHome()) {
+    return join(home, '.tslaws', 'delegation.json');
+}
+export function parseDuration(text) {
+    return Object.hasOwn(durations, text) ? durations[text] : undefined;
+}
+/** The real path of a directory; undefined when it is missing. */
+export function realRoot(dir) {
+    try {
+        return realpathSync.native(resolve(dir));
+    }
+    catch {
+        return undefined;
+    }
+}
+function same(a, b) {
+    return process.platform === 'win32' || process.platform === 'darwin' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+/** The grants directory must resolve inside the real home directory, not through a symlink elsewhere. */
+function grantsDirProblem(home) {
+    if (home === '')
+        return 'the home directory is unknown (the user database gave none)';
+    const dir = join(home, '.tslaws');
+    if (!existsSync(dir))
+        return undefined;
+    const base = realRoot(home);
+    const real = realRoot(dir);
+    if (base === undefined || real === undefined)
+        return `${dir} cannot be resolved`;
+    const inside = real.length > base.length && same(real.slice(0, base.length), base) && real[base.length] === sep;
+    return inside ? undefined : `${dir} resolves outside the home directory (${real})`;
+}
+/** A home directory that is the project root, or inside it, is project-controlled and never a trust root. */
+function homeInsideRoot(home, root) {
+    const h = home === '' ? undefined : realRoot(home);
+    if (h === undefined)
+        return undefined;
+    const inside = same(h, root) || (h.length > root.length && same(h.slice(0, root.length), root) && h[root.length] === sep);
+    return inside ? `the home directory ${h} is inside the project root` : undefined;
+}
+function isGrant(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const g = value;
+    return (typeof g.root === 'string' &&
+        typeof g.expires === 'string' &&
+        Number.isFinite(Date.parse(g.expires)) &&
+        (g.note === undefined || typeof g.note === 'string'));
+}
+/** Reads the grants. A missing file is an empty list; an unsafe or malformed one is an error. */
+export function readGrants(home = userHome()) {
+    const file = delegationFile(home);
+    const place = grantsDirProblem(home);
+    if (place !== undefined)
+        return { ok: false, reason: place };
+    if (!existsSync(file))
+        return { ok: true, grants: [] };
+    try {
+        const info = statSync(file);
+        if (process.platform !== 'win32') {
+            if ((info.mode & 0o022) !== 0)
+                return { ok: false, reason: `${file} is writable by its group or others; run chmod 600 on it` };
+            if (typeof process.getuid === 'function' && info.uid !== process.getuid())
+                return { ok: false, reason: `${file} is owned by another user` };
+        }
+        const data = JSON.parse(readFileSync(file, 'utf8'));
+        if (!Array.isArray(data.grants) || !data.grants.every(isGrant))
+            return { ok: false, reason: `${file} is malformed` };
+        return { ok: true, grants: data.grants };
+    }
+    catch {
+        return { ok: false, reason: `${file} cannot be read as delegation JSON` };
+    }
+}
+function writeGrants(grants, home) {
+    const file = delegationFile(home);
+    const unknown = grantsDirProblem(home);
+    if (unknown !== undefined)
+        return unknown;
+    mkdirSync(join(home, '.tslaws'), { recursive: true, mode: 0o700 });
+    const place = grantsDirProblem(home);
+    if (place !== undefined)
+        return place;
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ grants }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    return undefined;
+}
+/** The live grant for a project root. Real paths are compared, and a grant naming a symlink never matches. */
+export function findGrant(root, now, home = userHome()) {
+    const real = realRoot(root);
+    if (real === undefined)
+        return { ok: false, reason: 'the project root does not exist' };
+    const inside = homeInsideRoot(home, real);
+    if (inside !== undefined)
+        return { ok: false, reason: inside };
+    const read = readGrants(home);
+    if (!read.ok)
+        return { ok: false, reason: read.reason };
+    const named = read.grants.filter((g) => same(g.root, real) && realRoot(g.root) !== undefined);
+    if (named.length === 0)
+        return { ok: false, reason: 'no delegation covers this project' };
+    const live = named
+        .filter((g) => Date.parse(g.expires) > now.getTime())
+        .sort((a, b) => Date.parse(b.expires) - Date.parse(a.expires))[0];
+    return live === undefined ? { ok: false, reason: 'the delegation has expired' } : { ok: true, grant: live };
+}
+/** Decides whether `accept` may run: a person at a terminal, else a live grant. CI never. */
+export function acceptGate(input) {
+    const { env } = input;
+    if (env.CI !== undefined)
+        return { ok: false, message: 'accept records laws as correct and never runs under CI, even with a delegation' };
+    if (input.isTTY && env.TSLAWS_AGENT === undefined)
+        return { ok: true, delegated: false };
+    const verdict = findGrant(input.root, input.now ?? new Date(), input.home);
+    if (verdict.ok)
+        return { ok: true, delegated: true, grant: verdict.grant };
+    return {
+        ok: false,
+        message: `accept records laws as correct and needs a person at a terminal or a live delegation (${verdict.reason}); ${regrant}`,
+    };
+}
+/** The gate for acts only a person may do: a terminal, no agent marker, no CI. */
+export function personOnly(input) {
+    return input.isTTY && input.env.TSLAWS_AGENT === undefined && input.env.CI === undefined;
+}
+/** Records a grant for a project; returns it, or the reason it was refused. */
+export function grantFor(root, ms, now, home = userHome()) {
+    const real = realRoot(root);
+    if (real === undefined)
+        return `${root} does not exist`;
+    if (!same(resolve(root), real))
+        return `${root} is a symlink to ${real}; name the real directory`;
+    const inside = homeInsideRoot(home, real);
+    if (inside !== undefined)
+        return inside;
+    const read = readGrants(home);
+    if (!read.ok)
+        return read.reason;
+    const grant = { root: real, expires: new Date(now.getTime() + ms).toISOString() };
+    const problem = writeGrants([...read.grants.filter((g) => !same(g.root, real)), grant], home);
+    return problem ?? grant;
+}
+/** Removes the grants for a project; returns how many, or the reason it was refused. */
+export function revokeFor(root, home = userHome()) {
+    const real = realRoot(root);
+    if (real === undefined)
+        return `${root} does not exist`;
+    const read = readGrants(home);
+    if (!read.ok)
+        return read.reason;
+    const kept = read.grants.filter((g) => !same(g.root, real));
+    if (kept.length !== read.grants.length) {
+        const problem = writeGrants(kept, home);
+        if (problem !== undefined)
+            return problem;
+    }
+    return read.grants.length - kept.length;
+}
+export function describeGrants(now, home = userHome()) {
+    const read = readGrants(home);
+    if (!read.ok)
+        return [`delegation unusable: ${read.reason}`];
+    if (read.grants.length === 0)
+        return ['no delegations'];
+    return read.grants.map((g) => `${Date.parse(g.expires) > now.getTime() ? 'live' : 'expired'} ${g.root} until ${g.expires}${g.note ? ` (${g.note})` : ''}`);
+}
+export function fileHash(path) {
+    return existsSync(path) ? createHash('sha256').update(readFileSync(path)).digest('hex') : 'none';
+}
+/** Appends the audit line for a delegated accept to `<project>/.tslaws/accept.log`. */
+export function logDelegatedAccept(root, grant, before, after, now) {
+    const dir = join(root, '.tslaws');
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, 'accept.log'), `${now.toISOString()} delegated expires=${grant.expires} lock-before=${before} lock-after=${after}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tslaws",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Runs and checks `law` declarations compiled by tsc-laws: property tests, SMT proofs, tamper lock.",
   "bin": {
     "tslaws": "bin/tslaws.js"
@@ -58,7 +58,9 @@
     "z3-solver": "^4.15.0"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0"
+    "@tsrx/ripple": "0.2.11",
+    "@types/node": "^24.0.0",
+    "ripple": "0.6.1"
   },
   "peerDependencies": {
     "axe-core": "^4.0.0"
@@ -69,11 +71,11 @@
     }
   },
   "optionalDependencies": {
-    "tslaws-compiler-darwin-arm64": "0.3.2",
-    "tslaws-compiler-darwin-x64": "0.3.2",
-    "tslaws-compiler-linux-arm64-gnu": "0.3.2",
-    "tslaws-compiler-linux-x64-gnu": "0.3.2",
-    "tslaws-compiler-win32-x64-msvc": "0.3.2"
+    "tslaws-compiler-darwin-arm64": "0.5.0",
+    "tslaws-compiler-darwin-x64": "0.5.0",
+    "tslaws-compiler-linux-arm64-gnu": "0.5.0",
+    "tslaws-compiler-linux-x64-gnu": "0.5.0",
+    "tslaws-compiler-win32-x64-msvc": "0.5.0"
   },
   "publishConfig": {
     "access": "public"