@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/plugins/host.js

@@ -0,0 +1,277 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { SitefileError } from '../errors.js';
+import { WasmPlugin } from './wasm.js';
+export const DEFAULT_PLUGIN_POLICY = { timeoutMs: 60_000, maxOutputBytes: 64 * 1024 * 1024 };
+/** A directory TRANSFORM runs at most this many wasm or tool calls at a time (a JS plugin, one). */
+export const TRANSFORM_JOBS = Math.max(1, Math.min(4, os.availableParallelism()));
+/** Prefix that marks protocol lines on the child's stdout; anything else is plugin output. */
+const MARK = '\u0000SITEFILE:';
+/** Runs inside the sandboxed process (passed with -e, so it needs no file access). */
+const RUNNER = String.raw `
+const MARK = '\u0000SITEFILE:';
+const send = (msg) => process.stdout.write(MARK + JSON.stringify(msg) + '\n');
+// Plugin console output goes to stderr so stdout stays a clean channel.
+for (const k of ['log', 'info', 'debug']) console[k] = (...a) => process.stderr.write(a.map(String).join(' ') + '\n');
+const toB64 = (v) => Buffer.from(typeof v === 'string' ? Buffer.from(v, 'utf8') : v).toString('base64');
+const isBytes = (v) => typeof v === 'string' || v instanceof Uint8Array;
+let transform;
+let buf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf('\n')) !== -1) {
+    const line = buf.slice(0, nl);
+    buf = buf.slice(nl + 1);
+    handle(JSON.parse(line)).catch((e) => send({ type: 'fatal', message: String(e && e.stack || e) }));
+  }
+});
+async function handle(msg) {
+  if (msg.type === 'load') {
+    try {
+      const mod = await import(msg.url);
+      const api = mod.default && typeof mod.default.transform === 'function' ? mod.default : mod;
+      const version = api.apiVersion ?? mod.apiVersion ?? 1;
+      if (typeof api.transform !== 'function') throw new Error('the module must export transform(request), or a default object with transform');
+      if (version !== 1) throw new Error('unsupported plugin apiVersion ' + JSON.stringify(version) + ' (this Sitefile supports 1)');
+      transform = api.transform;
+      // 'export const cache = false' opts a (non-deterministic) plugin out of the result cache.
+      const cache = api.cache ?? mod.cache;
+      send({ type: 'ready', cache: cache !== false });
+    } catch (e) {
+      send({ type: 'load-error', message: e && e.message ? e.message : String(e) });
+    }
+    return;
+  }
+  if (msg.type === 'transform') {
+    const req = msg.request;
+    if (req.input) {
+      req.input.bytes = new Uint8Array(Buffer.from(req.input.bytes, 'base64'));
+    }
+    try {
+      let out = await transform(req);
+      if (isBytes(out)) out = { bytes: out };
+      if (out && isBytes(out.bytes)) return send({ type: 'result', id: msg.id, bytes: toB64(out.bytes) });
+      if (out && out.files && typeof out.files === 'object') {
+        const files = {};
+        for (const [k, v] of Object.entries(out.files)) {
+          if (!isBytes(v)) throw new Error('files[' + JSON.stringify(k) + '] must be a string or Uint8Array');
+          files[k] = toB64(v);
+        }
+        return send({ type: 'result', id: msg.id, files });
+      }
+      throw new Error('transform() must return a string, a Uint8Array, { bytes } or { files }');
+    } catch (e) {
+      send({ type: 'error', id: msg.id, message: e && e.message ? e.message : String(e) });
+    }
+  }
+}
+`;
+class PluginProcess {
+    name;
+    policy;
+    log;
+    child;
+    buf = '';
+    stderr = '';
+    nextId = 1;
+    pending = new Map();
+    /** False when the module exports `cache = false`; known once it has loaded. */
+    cacheable = true;
+    ready;
+    exited;
+    constructor(name, file, policy, log, span) {
+        this.name = name;
+        this.policy = policy;
+        this.log = log;
+        const dir = path.dirname(file);
+        this.child = spawn(process.execPath, ['--permission', `--allow-fs-read=${dir}`, '--disable-warning=ExperimentalWarning', '--input-type=module', '-e', RUNNER], { cwd: dir, env: {}, stdio: ['pipe', 'pipe', 'pipe'] });
+        this.child.stdout.setEncoding('utf8');
+        this.child.stderr.setEncoding('utf8');
+        this.child.stdout.on('data', (chunk) => this.onStdout(chunk));
+        this.child.stderr.on('data', (chunk) => {
+            this.stderr = (this.stderr + chunk).slice(-8192);
+            for (const line of chunk.split('\n'))
+                if (line.trim())
+                    this.log(line);
+        });
+        let onReady = () => { };
+        let onLoadError = () => { };
+        this.ready = new Promise((res, rej) => {
+            onReady = res;
+            onLoadError = rej;
+        });
+        // Awaited by call(); marking it handled keeps an unused failed plugin from crashing the process.
+        this.ready.catch(() => { });
+        this.onReadyMsg = onReady;
+        this.onLoadError = (m) => onLoadError(new SitefileError('E_PLUGIN', `PLUGIN ${name}: ${m}`, span));
+        this.child.on('error', (e) => this.fail(`could not start: ${e.message}`));
+        this.child.on('exit', (code, signal) => this.fail(signal ? `stopped by ${signal}` : `exited with code ${code}`));
+        this.write({ type: 'load', url: new URL(`file://${file}`).href });
+    }
+    onReadyMsg;
+    onLoadError;
+    write(msg) {
+        this.child.stdin.write(JSON.stringify(msg) + '\n');
+    }
+    onStdout(chunk) {
+        this.buf += chunk;
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) !== -1) {
+            const line = this.buf.slice(0, nl);
+            this.buf = this.buf.slice(nl + 1);
+            if (!line.startsWith(MARK)) {
+                if (line.trim())
+                    this.log(line);
+                continue;
+            }
+            if (line.length > this.policy.maxOutputBytes * 1.4 + 1024) {
+                this.fail(`a result is larger than ${this.policy.maxOutputBytes} bytes`);
+                return;
+            }
+            this.onMessage(JSON.parse(line.slice(MARK.length)));
+        }
+        if (this.buf.length > this.policy.maxOutputBytes * 1.4 + 1024)
+            this.fail(`a result is larger than ${this.policy.maxOutputBytes} bytes`);
+    }
+    onMessage(msg) {
+        switch (msg['type']) {
+            case 'ready':
+                this.cacheable = msg['cache'] !== false;
+                this.onReadyMsg();
+                return;
+            case 'load-error':
+                this.onLoadError(String(msg['message']));
+                return;
+            case 'fatal':
+                this.fail(String(msg['message']));
+                return;
+        }
+        const p = this.pending.get(msg['id']);
+        if (!p)
+            return;
+        this.pending.delete(msg['id']);
+        if (msg['type'] === 'error')
+            return p.reject(new Error(String(msg['message'])));
+        try {
+            if (typeof msg['bytes'] === 'string')
+                return p.resolve({ kind: 'file', bytes: this.decode(msg['bytes']) });
+            const files = Object.entries(msg['files']).map(([k, v]) => [k, this.decode(v)]);
+            p.resolve({ kind: 'files', files });
+        }
+        catch (e) {
+            p.reject(e);
+        }
+    }
+    decode(b64) {
+        const bytes = new Uint8Array(Buffer.from(b64, 'base64'));
+        if (bytes.byteLength > this.policy.maxOutputBytes)
+            throw new Error(`result is larger than ${this.policy.maxOutputBytes} bytes`);
+        return bytes;
+    }
+    fail(reason) {
+        if (this.exited)
+            return;
+        this.exited = reason;
+        const tail = this.stderr.trim() ? `\n${this.stderr.trim().split('\n').slice(-5).join('\n')}` : '';
+        const err = new Error(`${reason}${tail}`);
+        this.onLoadError(err.message);
+        for (const p of this.pending.values())
+            p.reject(err);
+        this.pending.clear();
+        if (this.child.exitCode === null)
+            this.child.kill('SIGKILL');
+    }
+    async call(request, span) {
+        await this.ready;
+        if (this.exited)
+            throw new SitefileError('E_PLUGIN', `PLUGIN ${this.name} ${this.exited}`, span);
+        const id = this.nextId++;
+        const wire = {
+            ...request,
+            ...(request.input ? { input: { ...request.input, bytes: Buffer.from(request.input.bytes).toString('base64') } } : {}),
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.fail(`timed out after ${this.policy.timeoutMs} ms`);
+            }, this.policy.timeoutMs);
+            this.pending.set(id, {
+                resolve: (r) => {
+                    clearTimeout(timer);
+                    resolve(r);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(new SitefileError('E_PLUGIN', `PLUGIN ${this.name}: ${e.message}`, span));
+                },
+            });
+            this.write({ type: 'transform', id, request: wire });
+        });
+    }
+    close() {
+        this.exited ??= 'closed';
+        this.child.stdin.end();
+        if (this.child.exitCode === null)
+            this.child.kill();
+    }
+}
+export class PluginHost {
+    policy;
+    log;
+    registered = new Map();
+    procs = new Map();
+    stats = { spawned: 0, calls: 0 };
+    constructor(policy = DEFAULT_PLUGIN_POLICY, log = () => { }) {
+        this.policy = policy;
+        this.log = log;
+    }
+    /**
+     * `file` is the plugin's absolute real path (already sandbox- and integrity-checked).
+     * For a `.wasm` plugin, pass the checked module bytes. Runners start lazily.
+     */
+    register(name, file, span, wasm) {
+        if (!this.registered.has(name))
+            this.registered.set(name, { file, span, ...(wasm ? { wasm } : {}) });
+    }
+    /** Whether a registered plugin is a WebAssembly module. */
+    isWasm(name) {
+        return this.registered.get(name)?.wasm !== undefined;
+    }
+    /** A registered wasm plugin's module bytes. */
+    wasmBytes(name) {
+        return this.registered.get(name)?.wasm;
+    }
+    async call(name, request, span) {
+        let p = this.procs.get(name);
+        if (!p) {
+            const reg = this.registered.get(name);
+            if (!reg)
+                throw new SitefileError('E_UNDEFINED', `unknown plugin '${name}'`, span);
+            p = reg.wasm
+                ? new WasmPlugin(name, reg.wasm, this.policy, TRANSFORM_JOBS)
+                : new PluginProcess(name, reg.file, this.policy, (l) => this.log(`[plugin ${name}] ${l}`), reg.span);
+            this.procs.set(name, p);
+            this.stats.spawned++;
+        }
+        this.stats.calls++;
+        return p.call(request, span);
+    }
+    /** The folder a registered plugin lives in. */
+    folderOf(name) {
+        const f = this.registered.get(name)?.file;
+        return f === undefined ? undefined : path.dirname(f);
+    }
+    /** Whether results of this plugin may be cached (false after it exported `cache = false`). */
+    cacheable(name) {
+        return this.procs.get(name)?.cacheable ?? true;
+    }
+    close() {
+        for (const p of this.procs.values())
+            p.close();
+        this.procs.clear();
+        this.registered.clear();
+    }
+}
+//# sourceMappingURL=host.js.map

package/lib/src/plugins/wasm.d.ts

@@ -0,0 +1,23 @@
+import { type SourceSpan } from '../errors.js';
+import type { PluginPolicy, PluginRequest, PluginResult } from './host.js';
+/** Compile and check a module against ABI v1; throws E_PLUGIN with a precise reason. */
+export declare function checkWasmPlugin(name: string, bytes: Uint8Array, span?: SourceSpan): void;
+/**
+ * A wasm plugin: up to `lanes` workers, so a directory TRANSFORM can run several calls at once.
+ * A call waits for a free worker, and its time limit starts when that worker takes it.
+ */
+export declare class WasmPlugin {
+    readonly name: string;
+    private readonly bytes;
+    private readonly policy;
+    private readonly lanes;
+    /** No imports means no clock or randomness: results depend only on the request. */
+    readonly cacheable = true;
+    private readonly idle;
+    private readonly all;
+    private readonly waiting;
+    constructor(name: string, bytes: Uint8Array, policy: PluginPolicy, lanes?: number);
+    private lane;
+    call(request: PluginRequest, span?: SourceSpan): Promise<PluginResult>;
+    close(): void;
+}

package/lib/src/plugins/wasm.js

@@ -0,0 +1,249 @@
+import { Worker } from 'node:worker_threads';
+import { SitefileError } from '../errors.js';
+/**
+ * WebAssembly renderer plugins (ABI v1).
+ *
+ * A plugin is a `wasm32-unknown-unknown` module with **no imports**, so it has
+ * no way to reach files, the network, the clock or randomness: it can only
+ * compute. It exports:
+ *
+ *   memory                                  its linear memory
+ *   sitefile_alloc(len: i32) -> i32         reserve `len` bytes, return a pointer
+ *   sitefile_transform(ptr: i32, len: i32) -> i64
+ *                                           read the request at ptr..ptr+len and
+ *                                           return (resultPtr << 32) | resultLen
+ *   sitefile_api_version() -> i32           optional; must return 1
+ *
+ * Request and result are UTF-8 JSON. The request matches the JS plugin
+ * request (docs/PLUGINS.md) with `input.bytes` base64-encoded. The result is
+ * one of `{ "bytes": <base64> }`, `{ "text": "…" }`,
+ * `{ "files": { "a.txt": <base64>, … } }` or `{ "error": "message" }`.
+ *
+ * Each call gets a fresh instance (no state carries over between calls), in a
+ * worker thread that is terminated when a call exceeds the time limit.
+ */
+const REQUIRED_EXPORTS = [
+    ['memory', 'memory'],
+    ['sitefile_alloc', 'function'],
+    ['sitefile_transform', 'function'],
+];
+/** Compile and check a module against ABI v1; throws E_PLUGIN with a precise reason. */
+export function checkWasmPlugin(name, bytes, span) {
+    let mod;
+    try {
+        mod = new WebAssembly.Module(bytes);
+    }
+    catch (e) {
+        throw new SitefileError('E_PLUGIN', `PLUGIN ${name}: not a valid WebAssembly module (${e.message})`, span);
+    }
+    const imports = WebAssembly.Module.imports(mod);
+    if (imports.length > 0) {
+        const list = imports.map((i) => `${i.module}.${i.name} (${i.kind})`).join(', ');
+        throw new SitefileError('E_PLUGIN', `PLUGIN ${name}: WebAssembly plugins can't import anything, so they can't reach files, the network or the clock; this module imports ${list}`, span);
+    }
+    const exports = new Map(WebAssembly.Module.exports(mod).map((e) => [e.name, e.kind]));
+    for (const [ename, kind] of REQUIRED_EXPORTS) {
+        if (exports.get(ename) !== kind) {
+            throw new SitefileError('E_PLUGIN', `PLUGIN ${name}: a WebAssembly plugin must export ${kind} '${ename}' (see docs/PLUGINS.md)`, span);
+        }
+    }
+}
+/** Runs inside the worker; plain JS (eval'd), so it can't use TypeScript. */
+const WORKER = String.raw `
+const { parentPort, workerData } = require('node:worker_threads');
+const mod = new WebAssembly.Module(workerData.bytes);
+parentPort.on('message', ({ id, request }) => {
+  try {
+    const { exports: ex } = new WebAssembly.Instance(mod, {});
+    if (typeof ex.sitefile_api_version === 'function' && ex.sitefile_api_version() !== 1) {
+      throw new Error('sitefile_api_version() must return 1');
+    }
+    const ptr = ex.sitefile_alloc(request.length) >>> 0;
+    if (ptr + request.length > ex.memory.buffer.byteLength) throw new Error('sitefile_alloc returned a pointer outside memory');
+    new Uint8Array(ex.memory.buffer, ptr, request.length).set(request);
+    const packed = BigInt.asUintN(64, BigInt(ex.sitefile_transform(ptr, request.length)));
+    const outPtr = Number(packed >> 32n);
+    const outLen = Number(packed & 0xffffffffn);
+    const size = ex.memory.buffer.byteLength;
+    if (size > workerData.maxMemory) throw new Error('used ' + size + ' bytes of memory, more than the ' + workerData.maxMemory + ' allowed');
+    if (outPtr + outLen > size) throw new Error('sitefile_transform returned a result outside memory');
+    const out = new Uint8Array(ex.memory.buffer, outPtr, outLen).slice();
+    parentPort.postMessage({ id, out }, [out.buffer]);
+  } catch (e) {
+    parentPort.postMessage({ id, error: e && e.message ? e.message : String(e) });
+  }
+});
+`;
+/** Largest linear memory a wasm plugin may use (default 1 GiB). */
+const DEFAULT_MAX_MEMORY = 1024 * 1024 * 1024;
+/**
+ * A wasm plugin: up to `lanes` workers, so a directory TRANSFORM can run several calls at once.
+ * A call waits for a free worker, and its time limit starts when that worker takes it.
+ */
+export class WasmPlugin {
+    name;
+    bytes;
+    policy;
+    lanes;
+    /** No imports means no clock or randomness: results depend only on the request. */
+    cacheable = true;
+    idle = [];
+    all = [];
+    waiting = [];
+    constructor(name, bytes, policy, lanes = 1) {
+        this.name = name;
+        this.bytes = bytes;
+        this.policy = policy;
+        this.lanes = lanes;
+    }
+    async lane() {
+        const free = this.idle.pop();
+        if (free)
+            return free;
+        if (this.all.length < Math.max(1, this.lanes)) {
+            const lane = new WasmLane(this.name, this.bytes, this.policy);
+            this.all.push(lane);
+            return lane;
+        }
+        return new Promise((resolve) => this.waiting.push(resolve));
+    }
+    async call(request, span) {
+        const lane = await this.lane();
+        try {
+            return await lane.call(request, span);
+        }
+        finally {
+            const next = this.waiting.shift();
+            if (next)
+                next(lane);
+            else
+                this.idle.push(lane);
+        }
+    }
+    close() {
+        for (const lane of this.all)
+            lane.close();
+        this.all.length = 0;
+        this.idle.length = 0;
+    }
+}
+/** One worker thread running a wasm plugin's calls one at a time. */
+class WasmLane {
+    name;
+    bytes;
+    policy;
+    worker;
+    nextId = 1;
+    pending = new Map();
+    failed;
+    constructor(name, bytes, policy) {
+        this.name = name;
+        this.bytes = bytes;
+        this.policy = policy;
+    }
+    start() {
+        if (this.worker)
+            return this.worker;
+        const w = new Worker(WORKER, {
+            eval: true,
+            workerData: { bytes: this.bytes, maxMemory: DEFAULT_MAX_MEMORY },
+            // The worker's own JS heap; wasm memory is checked after each call.
+            resourceLimits: { maxOldGenerationSizeMb: 256 },
+            env: {},
+            stdout: true,
+            stderr: true,
+        });
+        w.on('message', (m) => {
+            const p = this.pending.get(m.id);
+            if (!p)
+                return;
+            this.pending.delete(m.id);
+            if (m.error !== undefined)
+                p.reject(new Error(m.error));
+            else
+                p.resolve(m.out);
+        });
+        w.on('error', (e) => this.fail(e instanceof Error ? e.message : String(e)));
+        w.on('exit', (code) => this.fail(`stopped (exit code ${code})`));
+        this.worker = w;
+        return w;
+    }
+    fail(reason) {
+        for (const p of this.pending.values())
+            p.reject(new Error(reason));
+        this.pending.clear();
+        this.worker = undefined;
+        this.failed = reason;
+    }
+    async call(request, span) {
+        const wire = {
+            ...request,
+            ...(request.input ? { input: { ...request.input, bytes: Buffer.from(request.input.bytes).toString('base64') } } : {}),
+        };
+        const json = new TextEncoder().encode(JSON.stringify(wire));
+        const worker = this.start();
+        const id = this.nextId++;
+        const out = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                void worker.terminate();
+                this.worker = undefined;
+                reject(new Error(`timed out after ${this.policy.timeoutMs} ms`));
+            }, this.policy.timeoutMs);
+            this.pending.set(id, {
+                resolve: (o) => {
+                    clearTimeout(timer);
+                    resolve(o);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            worker.postMessage({ id, request: json }, [json.buffer]);
+        }).catch((e) => {
+            throw new SitefileError('E_PLUGIN', `PLUGIN ${this.name}: ${e.message}`, span);
+        });
+        this.failed = undefined;
+        return this.parse(out, span);
+    }
+    parse(out, span) {
+        if (out.byteLength > this.policy.maxOutputBytes) {
+            throw new SitefileError('E_PLUGIN', `PLUGIN ${this.name}: result is larger than ${this.policy.maxOutputBytes} bytes`, span);
+        }
+        let msg;
+        try {
+            msg = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(out));
+        }
+        catch (e) {
+            throw new SitefileError('E_PLUGIN', `PLUGIN ${this.name}: the result is not UTF-8 JSON (${e.message})`, span);
+        }
+        const bad = (why) => new SitefileError('E_PLUGIN', `PLUGIN ${this.name}: ${why}`, span);
+        if (msg === null || typeof msg !== 'object' || Array.isArray(msg))
+            throw bad('the result must be a JSON object');
+        const r = msg;
+        if (typeof r['error'] === 'string')
+            throw bad(r['error']);
+        const b64 = (v, what) => {
+            if (typeof v !== 'string' || !/^[A-Za-z0-9+/]*={0,2}$/.test(v))
+                throw bad(`${what} must be a base64 string`);
+            return new Uint8Array(Buffer.from(v, 'base64'));
+        };
+        if ('bytes' in r)
+            return { kind: 'file', bytes: b64(r['bytes'], 'bytes') };
+        if (typeof r['text'] === 'string')
+            return { kind: 'file', bytes: new TextEncoder().encode(r['text']) };
+        if (r['files'] !== null && typeof r['files'] === 'object' && !Array.isArray(r['files'])) {
+            const files = Object.entries(r['files']).map(([k, v]) => [k, b64(v, `files["${k}"]`)]);
+            return { kind: 'files', files };
+        }
+        throw bad('the result must have "bytes", "text", "files" or "error"');
+    }
+    close() {
+        const w = this.worker;
+        this.worker = undefined;
+        if (w)
+            void w.terminate();
+    }
+}
+//# sourceMappingURL=wasm.js.map

package/lib/src/profile.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `--profile <file>`: a timing trace of one build in the Chrome trace event format
+ * (open it in chrome://tracing, https://ui.perfetto.dev or speedscope).
+ *
+ * Every event is a complete event (`ph: "X"`, microseconds) on process 1. The
+ * build runs on thread 1; import N (0-based, in Sitefile order) on thread N+2,
+ * because imports resolve concurrently. Events appear in the file in the order
+ * they started in the Sitefile (imports in declaration order), so two builds of
+ * the same Sitefile list the same events in the same order with the same names,
+ * categories and args; only `ts` and `dur` differ. The Rust implementation
+ * (rust/src/profile.rs) writes the same events.
+ */
+export type ProfileArgs = Record<string, string | number | boolean>;
+export interface ProfileSpan {
+    /** Start the clock (for reserved spans; `begin` starts it at once). */
+    start(): void;
+    /** Stop the clock, adding args. */
+    end(args?: ProfileArgs): void;
+}
+export declare class Profiler {
+    readonly command: string;
+    private readonly t0;
+    private readonly slots;
+    private readonly threads;
+    constructor(command: string);
+    private now;
+    /** Reserve an event's place in the file now; its clock starts with `start()`. */
+    reserve(name: string, cat: string, args?: ProfileArgs, tid?: number): ProfileSpan;
+    /** Start an event now. */
+    begin(name: string, cat: string, args?: ProfileArgs, tid?: number): ProfileSpan;
+    nameThread(tid: number, name: string): void;
+    /**
+     * The trace as JSON text, one event per line. Events still open (the build failed
+     * inside them) end now with `incomplete: true`; reserved events that never started
+     * are left out.
+     */
+    toJSON(): string;
+}
+/** The span helpers the executor uses: a no-op without a profiler. */
+export declare function begin(p: Profiler | undefined, name: string, cat: string, args?: ProfileArgs): ProfileSpan;
+/** Reserve an event's place now (its clock starts with `start()`): a no-op without a profiler. */
+export declare function reserve(p: Profiler | undefined, name: string, cat: string, args?: ProfileArgs): ProfileSpan;

package/lib/src/profile.js

@@ -0,0 +1,68 @@
+import { performance } from 'node:perf_hooks';
+const NOOP = { start() { }, end() { } };
+export class Profiler {
+    command;
+    t0 = performance.now();
+    slots = [];
+    threads = new Map([[1, 'build']]);
+    constructor(command) {
+        this.command = command;
+    }
+    now() {
+        return Math.round((performance.now() - this.t0) * 1000);
+    }
+    /** Reserve an event's place in the file now; its clock starts with `start()`. */
+    reserve(name, cat, args = {}, tid = 1) {
+        const slot = { name, cat, tid, args: { ...args } };
+        this.slots.push(slot);
+        return {
+            start: () => {
+                slot.ts = this.now();
+            },
+            end: (more) => {
+                if (slot.ts === undefined || slot.dur !== undefined)
+                    return;
+                slot.dur = this.now() - slot.ts;
+                if (more)
+                    Object.assign(slot.args, more);
+            },
+        };
+    }
+    /** Start an event now. */
+    begin(name, cat, args = {}, tid = 1) {
+        const s = this.reserve(name, cat, args, tid);
+        s.start();
+        return s;
+    }
+    nameThread(tid, name) {
+        this.threads.set(tid, name);
+    }
+    /**
+     * The trace as JSON text, one event per line. Events still open (the build failed
+     * inside them) end now with `incomplete: true`; reserved events that never started
+     * are left out.
+     */
+    toJSON() {
+        const now = this.now();
+        const lines = [JSON.stringify({ name: 'process_name', ph: 'M', pid: 1, tid: 1, args: { name: `sitefile ${this.command}` } })];
+        for (const [tid, name] of [...this.threads].sort((a, b) => a[0] - b[0])) {
+            lines.push(JSON.stringify({ name: 'thread_name', ph: 'M', pid: 1, tid, args: { name } }));
+        }
+        for (const s of this.slots) {
+            if (s.ts === undefined)
+                continue;
+            const args = s.dur === undefined ? { ...s.args, incomplete: true } : s.args;
+            lines.push(JSON.stringify({ name: s.name, cat: s.cat, ph: 'X', ts: s.ts, dur: s.dur ?? now - s.ts, pid: 1, tid: s.tid, args }));
+        }
+        return `{"traceEvents":[\n${lines.join(',\n')}\n],\n"displayTimeUnit":"ms"}\n`;
+    }
+}
+/** The span helpers the executor uses: a no-op without a profiler. */
+export function begin(p, name, cat, args) {
+    return p ? p.begin(name, cat, args) : NOOP;
+}
+/** Reserve an event's place now (its clock starts with `start()`): a no-op without a profiler. */
+export function reserve(p, name, cat, args) {
+    return p ? p.reserve(name, cat, args) : NOOP;
+}
+//# sourceMappingURL=profile.js.map