@monosmith/plugin-sdk 0.0.0-stage → 0.2.0

package/serve/request-pool.store.js

@@ -0,0 +1,110 @@
+/** The requests waiting for a worker are limited to this many; the host never has more in flight than the plugin declared, so more means a host that breaks the protocol. */
+export const MAX_QUEUED = 1024;
+/**
+ * The state of the serve loop: the requests in flight, the ones waiting for a
+ * worker, and a bounded number of workers running them. Requests start in the
+ * order they arrive and may finish in any order. The Go SDK's request pool,
+ * with the same rules.
+ */
+export class RequestPool {
+    #limit = 1;
+    #running = 0;
+    #queue = [];
+    #inflight = new Map();
+    #idle = [];
+    #run;
+    #failure;
+    /** `run` answers one request; if it throws, the first error is kept in {@link failure} and the pool goes on. */
+    constructor(run) {
+        this.#run = run;
+    }
+    #start(first) {
+        this.#running++;
+        void this.#work(first);
+    }
+    async #work(first) {
+        for (let pooled = first; pooled !== undefined; pooled = this.#next()) {
+            try {
+                await this.#run(pooled);
+            }
+            catch (error) {
+                this.#failure ??= error;
+            }
+        }
+    }
+    #next() {
+        if (this.#queue.length > 0 && this.#running <= this.#limit)
+            return this.#queue.shift();
+        this.#running--;
+        if (this.#running === 0)
+            for (const resolve of this.#idle.splice(0))
+                resolve();
+        return undefined;
+    }
+    /** The first error a run threw, if any. */
+    get failure() {
+        return this.#failure;
+    }
+    /** How many workers may run at once. Raising it starts waiting requests; lowering it lets running ones finish. */
+    setLimit(limit) {
+        this.#limit = Math.max(1, limit);
+        while (this.#running < this.#limit && this.#queue.length > 0)
+            this.#start(this.#queue.shift());
+    }
+    /** Takes a request: it runs at once on a free worker, or waits its turn. */
+    submit(request) {
+        if (this.#inflight.has(request.id))
+            return 'duplicate';
+        if (this.#running >= this.#limit && this.#queue.length >= MAX_QUEUED)
+            return 'full';
+        const pooled = { request, controller: new AbortController(), cancelled: false };
+        this.#inflight.set(request.id, pooled);
+        if (this.#running >= this.#limit)
+            this.#queue.push(pooled);
+        else
+            this.#start(pooled);
+        return 'admitted';
+    }
+    /**
+     * Forgets an answered request; call it before the answer is written, so a
+     * host that reuses the id right away is not refused as a duplicate.
+     */
+    release(pooled) {
+        this.#inflight.delete(pooled.request.id);
+    }
+    /**
+     * Stops the request with an id. One that had not started is taken out of
+     * the queue and returned, because no worker will ever answer it. An unknown
+     * id is ignored.
+     */
+    cancel(id) {
+        const pooled = this.#inflight.get(id);
+        if (pooled === undefined)
+            return undefined;
+        pooled.cancelled = true;
+        pooled.controller.abort();
+        const at = this.#queue.indexOf(pooled);
+        if (at === -1)
+            return undefined;
+        this.#queue.splice(at, 1);
+        this.#inflight.delete(id);
+        return pooled;
+    }
+    /** Stops every request. The ones that had not started are returned, to be answered. */
+    cancelAll() {
+        for (const pooled of this.#inflight.values()) {
+            pooled.cancelled = true;
+            pooled.controller.abort();
+        }
+        const waiting = this.#queue.splice(0);
+        for (const pooled of waiting)
+            this.#inflight.delete(pooled.request.id);
+        return waiting;
+    }
+    /** Resolves once no worker is running. */
+    idle() {
+        if (this.#running === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => { this.#idle.push(resolve); });
+    }
+}

package/serve/serve.use-case.d.ts

@@ -0,0 +1,31 @@
+import type { SmithPlugin } from './plugin.contract.ts';
+import type { ServeStreams } from './protocol-streams.contract.ts';
+/**
+ * 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 declare function serve(plugin: SmithPlugin): Promise<never>;
+/**
+ * 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 by a bounded
+ * pool of as many at a time as the plugin declared in `concurrency` (one, in
+ * order, when it said nothing), and the answers may be written in any 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.
+ * A `cancellable` plugin has the signal of a request aborted when the host
+ * sends `cancel` for it, and at shutdown or the end of the input.
+ */
+export declare function serveStreams(plugin: SmithPlugin, streams: ServeStreams): Promise<void>;

package/serve/serve.use-case.js

@@ -0,0 +1,180 @@
+import { MessageParseError, ParamsError, decodeParams, parseRequest, writeFailure, writeResult } from '../codec/index.js';
+import { workerLimit } from '../concurrency/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';
+import { RequestPool } from './request-pool.store.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 by a bounded
+ * pool of as many at a time as the plugin declared in `concurrency` (one, in
+ * order, when it said nothing), and the answers may be written in any 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.
+ * A `cancellable` plugin has the signal of a request aborted when the host
+ * sends `cancel` for it, and at shutdown or the end of the input.
+ */
+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 pool = new RequestPool(async (pooled) => { await run(session, pooled); });
+    const session = { initialized: false, plugin, output: streams.output, pool, cancellable: plugin.cancellable === true };
+    try {
+        for await (const chunk of streams.input) {
+            for (const body of reader.push(chunk)) {
+                if (pool.failure !== undefined)
+                    throw pool.failure;
+                const shutdown = await receive(session, body);
+                if (shutdown)
+                    return;
+            }
+        }
+    }
+    finally {
+        await drain(session);
+    }
+    if (pool.failure !== undefined)
+        throw pool.failure;
+}
+/** Handles one frame. Returns whether it was `shutdown`, after which the loop ends. */
+async function receive(session, body) {
+    let request;
+    try {
+        request = parseRequest(body);
+    }
+    catch (error) {
+        if (!(error instanceof MessageParseError))
+            throw error;
+        await send(session.output, writeFailure(null, ERROR_CODES.ParseError, error.message));
+        return false;
+    }
+    if (request.id === null) {
+        await notified(session, request);
+        return false;
+    }
+    const id = request.id;
+    if (!session.initialized && request.method !== 'initialize') {
+        await send(session.output, writeFailure(id, ERROR_CODES.InvalidRequest, 'initialize must come first'));
+        return false;
+    }
+    if (request.method === 'initialize') {
+        const outcome = await dispatchRequest(session.plugin, request);
+        if (outcome.ok) {
+            session.initialized = true;
+            session.pool.setLimit(workerLimit(JSON.parse(outcome.resultJson).concurrency));
+        }
+        await send(session.output, outcome.ok ? writeResult(id, outcome.resultJson) : writeFailure(id, outcome.code, outcome.message));
+        return false;
+    }
+    if (request.method === 'shutdown') {
+        // Everything read before shutdown, started or still waiting, is answered with its result first, as in the Go SDK; only a cancel message stops a request.
+        await session.pool.idle();
+        await send(session.output, writeResult(id, '{}'));
+        return true;
+    }
+    switch (session.pool.submit({ ...request, id })) {
+        case 'duplicate': {
+            await send(session.output, writeFailure(id, ERROR_CODES.InvalidRequest, `request id ${id} is already in flight`));
+            break;
+        }
+        case 'full': {
+            await send(session.output, writeFailure(id, ERROR_CODES.InvalidRequest, 'too many requests in flight: the host must not send more than the plugin\'s declared concurrency'));
+            break;
+        }
+        case 'admitted': {
+            break;
+        }
+    }
+    return false;
+}
+/**
+ * Handles a message without an `id`. `cancel` is the only one the protocol
+ * defines for a plugin; every other is ignored, and so is a `cancel` to a
+ * plugin that is not `cancellable`, or one that names no request.
+ */
+async function notified(session, request) {
+    if (request.method !== 'cancel' || !session.cancellable)
+        return;
+    let params;
+    try {
+        params = decodeParams('cancel', request.params);
+    }
+    catch (error) {
+        if (error instanceof ParamsError)
+            return;
+        throw error;
+    }
+    const waiting = session.pool.cancel(params.id);
+    if (waiting !== undefined)
+        await answerCancelled(session.output, waiting);
+}
+/** A worker's job: handle one request and answer it. */
+async function run(session, pooled) {
+    const outcome = await dispatchRequest(session.plugin, pooled.request, pooled.controller.signal);
+    const answer = !outcome.ok && outcome.code === ERROR_CODES.PluginFailure && pooled.cancelled
+        ? { ok: false, code: ERROR_CODES.RequestCancelled, message: `request cancelled: ${outcome.message}` }
+        : outcome;
+    session.pool.release(pooled);
+    await send(session.output, answer.ok ? writeResult(pooled.request.id, answer.resultJson) : writeFailure(pooled.request.id, answer.code, answer.message));
+}
+function answerCancelled(output, pooled) {
+    return send(output, writeFailure(pooled.request.id, ERROR_CODES.RequestCancelled, 'request cancelled before it started'));
+}
+/**
+ * Ends the work in flight when the loop returns (the input ended, the host is gone): a
+ * cancellable plugin is asked to stop and what had not started is refused;
+ * any other finishes what it is doing.
+ */
+async function drain(session) {
+    if (session.cancellable) {
+        for (const waiting of session.pool.cancelAll())
+            await answerCancelled(session.output, waiting);
+    }
+    await session.pool.idle();
+}
+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;