@monosmith/plugin-sdk 0.0.0-stage → 0.1.0

package/serve/serve.use-case.js

@@ -0,0 +1,93 @@
+import { MessageParseError, parseRequest, writeFailure, writeResult } from '../codec/index.js';
+import { FrameReader, frameMessage } from '../framing/index.js';
+import { ERROR_CODES } from '../protocol/index.js';
+import { halfImplemented } from './capabilities-of.algorithm.js';
+import { claimStdout } from './claim-stdout.use-case.js';
+import { dispatchRequest } from './dispatch-request.use-case.js';
+/**
+ * Runs a plugin on the process's standard input and output, and exits when the
+ * host sends `shutdown` or closes the stream. Use it as the whole body of the
+ * plugin's entry point:
+ *
+ * ```ts
+ * await serve({ describe: () => ({ ... }), discover: (params) => ({ ... }) })
+ * ```
+ *
+ * Standard output carries only the protocol's frames: whatever else the plugin
+ * or a library writes there goes to standard error instead. A failure of the
+ * stream exits with status 1 after the reason is printed.
+ */
+export async function serve(plugin) {
+    const output = claimStdout();
+    try {
+        await serveStreams(plugin, { input: process.stdin, output });
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        // serve is the plugin's main, like the Go SDK's serve.Main: it ends the process, whatever handles the plugin left open.
+        // eslint-disable-next-line unicorn/no-process-exit
+        process.exit(1);
+    }
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(0);
+}
+/**
+ * Answers requests from `input` on `output` until the host sends `shutdown`
+ * or the input ends, then resolves. This is the loop {@link serve} runs, on
+ * streams you choose: a test serves a plugin in-process over pipes with it.
+ *
+ * Semantics of the Go SDK's `serve.Serve`: requests are answered one at a time,
+ * in order; a request before `initialize` is refused (InvalidRequest);
+ * a notification (no `id`) gets no answer; an unreadable frame body is answered
+ * with ParseError and the loop goes on; an unreadable header ends it with an error.
+ */
+export async function serveStreams(plugin, streams) {
+    const log = streams.log ?? ((message) => process.stderr.write(`${message}\n`));
+    for (const member of halfImplemented(plugin)) {
+        log(`plugin: ${member} needs its pair (install with uninstall, declared with rewrite) to be advertised; it will not be called`);
+    }
+    const reader = new FrameReader();
+    const session = { initialized: false };
+    for await (const chunk of streams.input) {
+        for (const body of reader.push(chunk)) {
+            const shutdown = await answer(plugin, streams.output, session, body);
+            if (shutdown)
+                return;
+        }
+    }
+}
+/** Answers one frame. Returns whether it was `shutdown`, after which the loop ends. */
+async function answer(plugin, output, session, body) {
+    let request;
+    try {
+        request = parseRequest(body);
+    }
+    catch (error) {
+        if (!(error instanceof MessageParseError))
+            throw error;
+        await send(output, writeFailure(null, ERROR_CODES.ParseError, error.message));
+        return false;
+    }
+    // A notification has no reply; version 1 defines none for plugins.
+    if (request.id === null)
+        return false;
+    if (!session.initialized && request.method !== 'initialize') {
+        await send(output, writeFailure(request.id, ERROR_CODES.InvalidRequest, 'initialize must come first'));
+        return false;
+    }
+    const outcome = await dispatchRequest(plugin, request);
+    if (request.method === 'initialize' && outcome.ok)
+        session.initialized = true;
+    await send(output, outcome.ok ? writeResult(request.id, outcome.resultJson) : writeFailure(request.id, outcome.code, outcome.message));
+    return request.method === 'shutdown';
+}
+function send(output, body) {
+    return new Promise((resolve, reject) => {
+        output.write(frameMessage(body), (error) => {
+            if (error === null || error === undefined)
+                resolve();
+            else
+                reject(error);
+        });
+    });
+}

package/tasks/contribute-tasks.algorithm.d.ts

@@ -0,0 +1,15 @@
+import type { ContributeResult, Contribution, Project } from '../protocol/index.ts';
+/**
+ * The answer to `contribute` when every project gets the same kind of
+ * addition: calls `contribution` for each project and keys the result by
+ * project name. Return `undefined` for a project the plugin has nothing to add
+ * to; it is left out.
+ *
+ * ```ts
+ * contribute: ({ projects }) => contributeTo(projects, () => ({
+ *   tasks: { 'layout-check': task(['node', checker, 'layout-check'], { cache: true }) },
+ *   dependsOn: { lint: ['layout-check'] },
+ * }))
+ * ```
+ */
+export declare function contributeTo(projects: readonly Project[], contribution: (project: Project) => Contribution | undefined): ContributeResult;

package/tasks/contribute-tasks.algorithm.js

@@ -0,0 +1,22 @@
+/**
+ * The answer to `contribute` when every project gets the same kind of
+ * addition: calls `contribution` for each project and keys the result by
+ * project name. Return `undefined` for a project the plugin has nothing to add
+ * to; it is left out.
+ *
+ * ```ts
+ * contribute: ({ projects }) => contributeTo(projects, () => ({
+ *   tasks: { 'layout-check': task(['node', checker, 'layout-check'], { cache: true }) },
+ *   dependsOn: { lint: ['layout-check'] },
+ * }))
+ * ```
+ */
+export function contributeTo(projects, contribution) {
+    const result = {};
+    for (const project of projects) {
+        const added = contribution(project);
+        if (added !== undefined)
+            result[project.name] = added;
+    }
+    return { projects: result };
+}

package/tasks/index.d.ts

@@ -0,0 +1,2 @@
+export { buildTask, task } from './task.algorithm.ts';
+export { contributeTo } from './contribute-tasks.algorithm.ts';

package/tasks/index.js

@@ -0,0 +1,2 @@
+export { buildTask, task } from './task.algorithm.js';
+export { contributeTo } from './contribute-tasks.algorithm.js';

package/tasks/task.algorithm.d.ts

@@ -0,0 +1,18 @@
+import type { Task } from '../protocol/index.ts';
+/**
+ * A task the host can run, hash and cache. The command is an argv array and is
+ * never passed through a shell. Other members are the options.
+ *
+ * ```ts
+ * task(['node', 'check.js'], { inputs: ['widget.json'], cache: true, description: 'check the manifest' })
+ * ```
+ */
+export declare function task(command: string[], options?: Omit<Task, 'command'>): Task;
+/**
+ * The `build` task of a project: cached, built into the project's directory
+ * under `dist/` (which is also its `outputs`, restored on a cache hit), and run
+ * after the build of every project this one imports (`^build`). `outputDir` is
+ * the directory the command is told to write into, `../../dist/libs/core` for
+ * `libs/core`, to pass in its argv.
+ */
+export declare function buildTask(root: string, command: (outputDir: string) => string[], options?: Omit<Task, 'command'>): Task;

package/tasks/task.algorithm.js

@@ -0,0 +1,23 @@
+import { buildDirFromProject } from '../build-dir/index.js';
+/**
+ * A task the host can run, hash and cache. The command is an argv array and is
+ * never passed through a shell. Other members are the options.
+ *
+ * ```ts
+ * task(['node', 'check.js'], { inputs: ['widget.json'], cache: true, description: 'check the manifest' })
+ * ```
+ */
+export function task(command, options = {}) {
+    return { command, ...options };
+}
+/**
+ * The `build` task of a project: cached, built into the project's directory
+ * under `dist/` (which is also its `outputs`, restored on a cache hit), and run
+ * after the build of every project this one imports (`^build`). `outputDir` is
+ * the directory the command is told to write into, `../../dist/libs/core` for
+ * `libs/core`, to pass in its argv.
+ */
+export function buildTask(root, command, options = {}) {
+    const outputDir = buildDirFromProject(root);
+    return { command: command(outputDir), outputs: [outputDir], dependsOn: ['^build'], cache: true, ...options };
+}

package/templating/file-exists.error.d.ts

@@ -0,0 +1,6 @@
+/** A target file already exists: templates are written for a new project and never overwrite what is there. */
+export declare class FileExistsError extends Error {
+    /** The existing file, relative to the root. */
+    readonly path: string;
+    constructor(path: string);
+}

package/templating/file-exists.error.js

@@ -0,0 +1,10 @@
+/** A target file already exists: templates are written for a new project and never overwrite what is there. */
+export class FileExistsError extends Error {
+    /** The existing file, relative to the root. */
+    path;
+    constructor(path) {
+        super(`${path}: file already exists`);
+        this.name = 'FileExistsError';
+        this.path = path;
+    }
+}

package/templating/index.d.ts

@@ -0,0 +1,4 @@
+export { writeTemplates } from './write-templates.use-case.ts';
+export { renderTemplate } from './render-template.algorithm.ts';
+export { FileExistsError } from './file-exists.error.ts';
+export { TemplateError } from './template.error.ts';

package/templating/index.js

@@ -0,0 +1,4 @@
+export { writeTemplates } from './write-templates.use-case.js';
+export { renderTemplate } from './render-template.algorithm.js';
+export { FileExistsError } from './file-exists.error.js';
+export { TemplateError } from './template.error.js';

package/templating/parse-template.algorithm.d.ts

@@ -0,0 +1,11 @@
+import type { TemplateNode } from './template-syntax.contract.ts';
+/**
+ * Parses a template with `[[ ]]` delimiters. The language is the subset of Go's
+ * `text/template` that project templates use: `[[.Field]]` and `[[.A.B]]`,
+ * `[[if]]`, `[[else if]]`, `[[else]]`, `[[with]]`, `[[range]]` and `[[end]]`, the
+ * functions `eq ne lt le gt ge not and or len index print printf`, string,
+ * number and boolean literals, parentheses, pipes, comments, and the `-`
+ * trim markers (`[[- x -]]`). Variables, `define`, `template` and `block`
+ * are not supported and are reported as such.
+ */
+export declare function parseTemplate(text: string, name: string): TemplateNode[];

package/templating/parse-template.algorithm.js

@@ -0,0 +1,197 @@
+import { tokenizeAction } from './tokenize-action.algorithm.js';
+import { TemplateError } from './template.error.js';
+const OPEN = '[[';
+const CLOSE = ']]';
+const UNSUPPORTED = new Set(['define', 'template', 'block', 'break', 'continue']);
+/**
+ * Parses a template with `[[ ]]` delimiters. The language is the subset of Go's
+ * `text/template` that project templates use: `[[.Field]]` and `[[.A.B]]`,
+ * `[[if]]`, `[[else if]]`, `[[else]]`, `[[with]]`, `[[range]]` and `[[end]]`, the
+ * functions `eq ne lt le gt ge not and or len index print printf`, string,
+ * number and boolean literals, parentheses, pipes, comments, and the `-`
+ * trim markers (`[[- x -]]`). Variables, `define`, `template` and `block`
+ * are not supported and are reported as such.
+ */
+export function parseTemplate(text, name) {
+    const fail = (message) => {
+        throw new TemplateError(name, message);
+    };
+    const root = [];
+    const stack = [];
+    const target = () => {
+        const top = stack.at(-1);
+        if (top === undefined)
+            return root;
+        return top.inElse ? top.otherwise : top.body;
+    };
+    for (const piece of splitPieces(text, fail)) {
+        if ('literal' in piece) {
+            if (piece.literal !== '')
+                target().push({ type: 'text', text: piece.literal });
+        }
+        else if (piece.action.startsWith('/*')) {
+            if (!piece.action.endsWith('*/'))
+                fail('unclosed comment');
+        }
+        else {
+            applyAction(piece.action, stack, target, fail);
+        }
+    }
+    const open = stack.at(-1);
+    if (open !== undefined)
+        fail(`unclosed ${open.type}: missing [[end]]`);
+    return root;
+}
+/** The literal text and the actions of a template, in order, with the `-` trim markers applied. */
+function splitPieces(text, fail) {
+    const pieces = [];
+    let position = 0;
+    let trimNext = false;
+    while (position < text.length) {
+        const open = text.indexOf(OPEN, position);
+        let literal = text.slice(position, open === -1 ? text.length : open);
+        if (trimNext)
+            literal = literal.trimStart();
+        trimNext = false;
+        if (open === -1) {
+            pieces.push({ literal });
+            break;
+        }
+        const close = findClose(text, open + OPEN.length);
+        if (close === -1)
+            fail(`unclosed action at offset ${open}`);
+        let action = text.slice(open + OPEN.length, close);
+        if (/^-\s/.test(action)) {
+            literal = literal.trimEnd();
+            action = action.slice(1);
+        }
+        if (/\s-$/.test(action)) {
+            trimNext = true;
+            action = action.slice(0, -1);
+        }
+        pieces.push({ literal }, { action: action.trim() });
+        position = close + CLOSE.length;
+    }
+    return pieces;
+}
+/** The offset of the `]]` that ends the action, skipping string literals. */
+function findClose(text, from) {
+    for (let i = from; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"') {
+            i++;
+            while (i < text.length && text[i] !== '"')
+                i += text[i] === '\\' ? 2 : 1;
+        }
+        else if (c === '`') {
+            i = text.indexOf('`', i + 1);
+            if (i === -1)
+                return -1;
+        }
+        else if (text.startsWith(CLOSE, i)) {
+            return i;
+        }
+    }
+    return -1;
+}
+function applyAction(action, stack, target, fail) {
+    const tokens = tokenizeAction(action, fail);
+    const first = tokens[0];
+    const keyword = first?.t === 'word' ? first.value : '';
+    switch (keyword) {
+        case 'if':
+        case 'with':
+        case 'range': {
+            stack.push({ type: keyword, pipeline: parsePipeline(tokens.slice(1), fail), body: [], otherwise: [], inElse: false, chained: false });
+            break;
+        }
+        case 'else': {
+            startElse(tokens, stack, fail);
+            break;
+        }
+        case 'end': {
+            if (tokens.length > 1)
+                fail('unexpected tokens after end');
+            closeFrames(stack, target, fail);
+            break;
+        }
+        default: {
+            if (UNSUPPORTED.has(keyword)) {
+                fail(`"${keyword}" is not supported by the SDK's templates (the supported subset: fields, if, else, with, range, end, and the functions eq ne lt le gt ge not and or len index print printf)`);
+            }
+            else {
+                if (tokens.length === 0)
+                    fail('empty action');
+                target().push({ type: 'action', pipeline: parsePipeline(tokens, fail) });
+            }
+        }
+    }
+}
+function startElse(tokens, stack, fail) {
+    const top = stack.at(-1) ?? fail('unexpected else');
+    if (top.inElse)
+        fail('multiple else in one block');
+    top.inElse = true;
+    const next = tokens[1];
+    if (next?.t === 'word' && next.value === 'if') {
+        stack.push({ type: 'if', pipeline: parsePipeline(tokens.slice(2), fail), body: [], otherwise: [], inElse: false, chained: true });
+    }
+    else if (tokens.length > 1) {
+        fail('unexpected tokens after else');
+    }
+}
+/** Ends the innermost block, and the `else if` blocks chained to it. */
+function closeFrames(stack, target, fail) {
+    let frame;
+    do {
+        frame = stack.pop() ?? fail('unexpected end');
+        target().push({ type: frame.type, pipeline: frame.pipeline, body: frame.body, otherwise: frame.otherwise });
+    } while (frame.chained);
+}
+function parsePipeline(tokens, fail) {
+    const [pipeline, used] = pipelineFrom(tokens, 0, fail);
+    if (used < tokens.length)
+        fail('unexpected ")" in action');
+    return pipeline;
+}
+function pipelineFrom(tokens, start, fail) {
+    const pipeline = [];
+    let command = [];
+    let i = start;
+    for (; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.t === 'close')
+            break;
+        if (token.t === 'pipe') {
+            if (command.length === 0)
+                fail('missing value before |');
+            pipeline.push(command);
+            command = [];
+        }
+        else if (token.t === 'open') {
+            const [inner, next] = pipelineFrom(tokens, i + 1, fail);
+            if (tokens[next]?.t !== 'close')
+                fail('unclosed (');
+            command.push({ kind: 'pipeline', pipeline: inner });
+            i = next;
+        }
+        else {
+            command.push(operandOf(token));
+        }
+    }
+    if (command.length === 0)
+        fail(pipeline.length > 0 ? 'missing command after |' : 'missing value for the action');
+    pipeline.push(command);
+    return [pipeline, i];
+}
+function operandOf(token) {
+    if (token.t === 'field')
+        return { kind: 'field', root: token.root, path: token.path };
+    if (token.t === 'string' || token.t === 'number')
+        return { kind: token.t, value: token.value };
+    if (token.t !== 'word')
+        throw new Error('unreachable');
+    if (token.value === 'true' || token.value === 'false')
+        return { kind: 'bool', value: token.value === 'true' };
+    return token.value === 'nil' ? { kind: 'nil' } : { kind: 'name', name: token.value };
+}

package/templating/render-template.algorithm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Renders a `[[ ]]` template with the data, the way the Go SDK's `templating`
+ * does with `text/template` and `missingkey=error`: a field the data does not
+ * have is an error, not an empty string. See {@link parseTemplate} for the
+ * language. `name` is only used in error messages.
+ */
+export declare function renderTemplate(text: string, data: unknown, name?: string): string;

package/templating/render-template.algorithm.js

@@ -0,0 +1,87 @@
+import { parseTemplate } from './parse-template.algorithm.js';
+import { TEMPLATE_FUNCTIONS, byKey, format, isObject, isTruthy } from './template-functions.algorithm.js';
+import { TemplateError } from './template.error.js';
+/**
+ * Renders a `[[ ]]` template with the data, the way the Go SDK's `templating`
+ * does with `text/template` and `missingkey=error`: a field the data does not
+ * have is an error, not an empty string. See {@link parseTemplate} for the
+ * language. `name` is only used in error messages.
+ */
+export function renderTemplate(text, data, name = 'template') {
+    const fail = (message) => {
+        throw new TemplateError(name, message);
+    };
+    return render(parseTemplate(text, name), { dot: data, root: data }, fail);
+}
+function render(nodes, scope, fail) {
+    return nodes.map(node => renderNode(node, scope, fail)).join('');
+}
+function renderNode(node, scope, fail) {
+    if (node.type === 'text')
+        return node.text;
+    const value = evaluatePipeline(node.pipeline, scope, fail);
+    if (node.type === 'action')
+        return format(value);
+    if (node.type === 'if')
+        return render(isTruthy(value) ? node.body : node.otherwise, scope, fail);
+    if (node.type === 'with')
+        return isTruthy(value) ? render(node.body, { dot: value, root: scope.root }, fail) : render(node.otherwise, scope, fail);
+    const items = rangeItems(value, fail);
+    return items.length === 0 ? render(node.otherwise, scope, fail) : items.map(item => render(node.body, { dot: item, root: scope.root }, fail)).join('');
+}
+/** What `range` loops over: the elements of an array, or the values of a map in key order. */
+function rangeItems(value, fail) {
+    if (Array.isArray(value))
+        return value;
+    if (value === null || value === undefined)
+        return [];
+    return isObject(value) ? Object.keys(value).sort(byKey).map(key => value[key]) : fail(`range can't iterate over ${format(value)}`);
+}
+const NONE = Symbol('nothing piped');
+function evaluatePipeline(pipeline, scope, fail) {
+    let piped = NONE;
+    for (const command of pipeline)
+        piped = evaluateCommand(command, scope, piped, fail);
+    return piped;
+}
+function evaluateCommand(command, scope, piped, fail) {
+    const [head, ...rest] = command;
+    if (head.kind === 'name')
+        return callFunction(head.name, rest, scope, piped, fail);
+    if (rest.length > 0)
+        return fail('can\'t give an argument to a value that is not a function');
+    return piped === NONE ? evaluateOperand(head, scope, fail) : fail('can\'t pipe into a value that is not a function');
+}
+function callFunction(name, operands, scope, piped, fail) {
+    const fn = Object.hasOwn(TEMPLATE_FUNCTIONS, name) ? TEMPLATE_FUNCTIONS[name] : undefined;
+    if (fn === undefined)
+        return fail(`function "${name}" not defined`);
+    const args = operands.map(operand => evaluateOperand(operand, scope, fail));
+    if (piped !== NONE)
+        args.push(piped);
+    try {
+        return fn(args);
+    }
+    catch (error) {
+        return fail(`error calling ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function evaluateOperand(operand, scope, fail) {
+    if (operand.kind === 'nil')
+        return null;
+    if ('value' in operand)
+        return operand.value;
+    if (operand.kind === 'pipeline')
+        return evaluatePipeline(operand.pipeline, scope, fail);
+    if (operand.kind === 'name')
+        return evaluateCommand([operand], scope, NONE, fail);
+    let value = operand.root ? scope.root : scope.dot;
+    for (const key of operand.path) {
+        if (!isObject(value))
+            return fail(`can't evaluate field ${key} in ${value === null || value === undefined ? 'nil' : typeof value}`);
+        if (!Object.hasOwn(value, key))
+            return fail(`map has no entry for key "${key}"`);
+        value = value[key];
+    }
+    return value;
+}

package/templating/template-functions.algorithm.d.ts

@@ -0,0 +1,10 @@
+export type TemplateFunction = (args: unknown[]) => unknown;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/** Keys in the order Go sorts the keys of a map in. */
+export declare function byKey(a: string, b: string): number;
+/** Go's truth: false, 0, nil, and an empty string, array or map are false; everything else is true. */
+export declare function isTruthy(value: unknown): boolean;
+/** A value as `text/template` prints it. */
+export declare function format(value: unknown): string;
+/** The functions of `text/template` the subset has. */
+export declare const TEMPLATE_FUNCTIONS: Readonly<Record<string, TemplateFunction>>;

package/templating/template-functions.algorithm.js

@@ -0,0 +1,104 @@
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Keys in the order Go sorts the keys of a map in. */
+export function byKey(a, b) {
+    return Number(a > b) - Number(a < b);
+}
+/** Go's truth: false, 0, nil, and an empty string, array or map are false; everything else is true. */
+export function isTruthy(value) {
+    if ([undefined, null, false, 0, ''].includes(value))
+        return false;
+    return Array.isArray(value) ? value.length > 0 : !isObject(value) || Object.keys(value).length > 0;
+}
+/** A value as `text/template` prints it. */
+export function format(value) {
+    if (value === undefined || value === null)
+        return '<no value>';
+    if (Array.isArray(value))
+        return `[${value.map(item => format(item)).join(' ')}]`;
+    if (!isObject(value))
+        return String(value);
+    const entries = Object.keys(value).sort(byKey).map(key => `${key}:${format(value[key])}`);
+    return `map[${entries.join(' ')}]`;
+}
+function comparable(a, b) {
+    const kind = typeof a;
+    if (typeof b !== kind || !['string', 'number', 'boolean'].includes(kind))
+        throw new TypeError('incompatible types for comparison');
+    return kind;
+}
+function ordered(test) {
+    return ([a, b]) => {
+        if (comparable(a, b) === 'boolean')
+            throw new TypeError('invalid type for comparison');
+        return test(a === b ? 0 : (Number(a > b) || -1));
+    };
+}
+function indexInto(current, key) {
+    if (Array.isArray(current)) {
+        if (typeof key !== 'number' || key < 0 || key >= current.length)
+            throw new RangeError(`index out of range: ${format(key)}`);
+        return current[key];
+    }
+    if (isObject(current))
+        return Object.hasOwn(current, String(key)) ? current[String(key)] : undefined;
+    throw new TypeError(`can't index ${format(current)}`);
+}
+/** What Sprint puts between operands: a space when neither side is a string. */
+function sprint(args) {
+    return args.reduce((out, arg, i) => {
+        const space = i > 0 && typeof arg !== 'string' && typeof args[i - 1] !== 'string';
+        return `${out}${space ? ' ' : ''}${format(arg)}`;
+    }, '');
+}
+/** The functions of `text/template` the subset has. */
+export const TEMPLATE_FUNCTIONS = {
+    eq: ([first, ...others]) => {
+        if (others.length === 0)
+            throw new TypeError('missing argument for comparison');
+        return others.some((other) => {
+            if (first === null || other === null)
+                return first === other;
+            comparable(first, other);
+            return first === other;
+        });
+    },
+    ne: ([a, b]) => {
+        if (a === null || b === null)
+            return a !== b;
+        comparable(a, b);
+        return a !== b;
+    },
+    lt: ordered(difference => difference < 0),
+    le: ordered(difference => difference <= 0),
+    gt: ordered(difference => difference > 0),
+    ge: ordered(difference => difference >= 0),
+    not: ([value]) => !isTruthy(value),
+    and: args => args.find(arg => !isTruthy(arg)) ?? args.at(-1),
+    or: args => args.find(arg => isTruthy(arg)) ?? args.at(-1),
+    len: ([value]) => {
+        if (typeof value === 'string')
+            return Buffer.byteLength(value);
+        if (Array.isArray(value))
+            return value.length;
+        if (isObject(value))
+            return Object.keys(value).length;
+        throw new TypeError(`len of ${format(value)}`);
+    },
+    index: ([value, ...keys]) => keys.reduce((current, key) => indexInto(current, key), value),
+    print: args => sprint(args),
+    printf: ([pattern, ...args]) => {
+        if (typeof pattern !== 'string')
+            throw new TypeError('printf needs a format string');
+        let next = 0;
+        return pattern.replaceAll(/%([%sdvqt])/g, (_match, verb) => {
+            if (verb === '%')
+                return '%';
+            if (next >= args.length)
+                throw new RangeError(`missing argument for %${verb}`);
+            const arg = args[next++];
+            return verb === 'q' ? JSON.stringify(String(arg)) : format(arg);
+        });
+    },
+};

package/templating/template-syntax.contract.d.ts

@@ -0,0 +1,33 @@
+/** One operand of a command: a field of the data, a literal, a parenthesised pipeline or a function name. */
+export type Operand = {
+    kind: 'field';
+    root: boolean;
+    path: string[];
+} | {
+    kind: 'string' | 'number' | 'bool';
+    value: string | number | boolean;
+} | {
+    kind: 'nil';
+} | {
+    kind: 'pipeline';
+    pipeline: Pipeline;
+} | {
+    kind: 'name';
+    name: string;
+};
+/** Operands in a row: a function call (`eq .Kind "app"`) or a single value. */
+export type Command = Operand[];
+/** Commands joined by `|`, each receiving the previous one's value as its last argument. */
+export type Pipeline = Command[];
+export type TemplateNode = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'action';
+    pipeline: Pipeline;
+} | {
+    type: 'if' | 'with' | 'range';
+    pipeline: Pipeline;
+    body: TemplateNode[];
+    otherwise: TemplateNode[];
+};