@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/member-handles.js

@@ -0,0 +1,216 @@
+/**
+ * A chant member's outputs and parameters, read from its source without
+ * running it (#2539, #2524 D6).
+ *
+ * `chant workspace check` resolves member links in source and never runs
+ * member code, so it can't build a member to learn its outputs. This reader
+ * parses the member's TypeScript files and picks out the two handles a join
+ * uses, the way the graph IR names them (`exports` and `imports`):
+ *
+ * - an output is the name passed to `output(ref, "Name")`, or the binding of
+ *   `export const name = stackOutput(ref)`;
+ * - a parameter is the binding of `export const name = new Parameter(...)`.
+ *
+ * Only calls whose function is imported from `@intentius/chant` or a chant
+ * lexicon count. An output name must be a string literal, or a `const` in the
+ * same file that is one. Any other name can't be read without running the
+ * code, so it is a gap: the member's list of outputs is then incomplete, and a
+ * link to a name the reader didn't find is unresolved rather than missing.
+ *
+ * The reader loads the TypeScript parser and nothing else from the project.
+ */
+import * as ts from "typescript";
+import { isInside } from "./declaration.js";
+import { kindHandles } from "./links.js";
+import { joinPath, skippedDir } from "./tree.js";
+const memberDir = (dir) => (dir === "." ? "" : dir);
+/** Directories inside a member that hold no project source. */
+const NOT_SOURCE = new Set(["dist", "coverage", "generated"]);
+const CHANT_MODULE = /^@intentius\/chant(-lexicon-[a-z0-9-]+)?(\/.*)?$/;
+function isSourceFile(name) {
+    if (!/\.(m?ts|tsx)$/.test(name) || name.endsWith(".d.ts"))
+        return false;
+    if (/\.(test|spec)\.m?tsx?$/.test(name))
+        return false;
+    return !name.startsWith("chant.config.");
+}
+/**
+ * Every source file under `dir` (tree-relative), leaving out `exclude`d
+ * directories (other members, group matches), `node_modules`, dot
+ * directories and build output.
+ */
+function sourceFiles(tree, dir, exclude) {
+    const out = [];
+    const walk = (at) => {
+        for (const e of tree.list(at) ?? []) {
+            const path = joinPath(at, e.name);
+            if (e.type === "dir") {
+                if (skippedDir(e.name) || NOT_SOURCE.has(e.name) || exclude.has(path))
+                    continue;
+                walk(path);
+            }
+            else if (isSourceFile(e.name)) {
+                out.push(path);
+            }
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+function chantImports(source) {
+    const names = new Map();
+    const namespaces = new Set();
+    for (const s of source.statements) {
+        if (!ts.isImportDeclaration(s) || !ts.isStringLiteral(s.moduleSpecifier))
+            continue;
+        const from = s.moduleSpecifier.text;
+        // The components API has its own stackOutput(stack, name), which reads an output rather than declaring one.
+        if (!CHANT_MODULE.test(from) || from.includes("/components"))
+            continue;
+        const bindings = s.importClause?.namedBindings;
+        if (!bindings)
+            continue;
+        if (ts.isNamespaceImport(bindings))
+            namespaces.add(bindings.name.text);
+        else
+            for (const el of bindings.elements)
+                names.set(el.name.text, (el.propertyName ?? el.name).text);
+    }
+    return { names, namespaces };
+}
+/** The chant function a callee names (`output`, `ns.Parameter`), or undefined. */
+function chantCallee(expr, imports) {
+    if (ts.isIdentifier(expr))
+        return imports.names.get(expr.text);
+    if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.expression) && imports.namespaces.has(expr.expression.text)) {
+        return expr.name.text;
+    }
+    return undefined;
+}
+/** The top-level `const` initializers of a file, for reading a name held in one. */
+function fileConsts(source) {
+    const consts = new Map();
+    for (const s of source.statements) {
+        if (!ts.isVariableStatement(s) || (s.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const d of s.declarationList.declarations)
+            if (ts.isIdentifier(d.name) && d.initializer)
+                consts.set(d.name.text, d.initializer);
+    }
+    return consts;
+}
+/** A string the expression is without running anything, or undefined. */
+function literalString(expr, consts, seen = new Set()) {
+    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr))
+        return expr.text;
+    if (ts.isParenthesizedExpression(expr) || ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr))
+        return literalString(expr.expression, consts, seen);
+    if (ts.isIdentifier(expr) && !seen.has(expr.text)) {
+        const init = consts.get(expr.text);
+        if (init)
+            return literalString(init, consts, new Set([...seen, expr.text]));
+    }
+    return undefined;
+}
+function isExported(s) {
+    return (ts.canHaveModifiers(s) ? ts.getModifiers(s) : undefined)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+/** Read one file's outputs and parameters into `out`. */
+function readFile(path, text, out) {
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, false);
+    const imports = chantImports(source);
+    if (imports.names.size === 0 && imports.namespaces.size === 0)
+        return;
+    const consts = fileConsts(source);
+    const lineOf = (node) => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+    // Exported bindings: stackOutput outputs and Parameter inputs are named by them.
+    for (const s of source.statements) {
+        if (!ts.isVariableStatement(s) || !isExported(s))
+            continue;
+        for (const d of s.declarationList.declarations) {
+            if (!ts.isIdentifier(d.name) || !d.initializer)
+                continue;
+            const init = d.initializer;
+            if (ts.isNewExpression(init) && chantCallee(init.expression, imports) === "Parameter") {
+                out.inputs.push({ name: d.name.text, file: path, line: lineOf(d) });
+            }
+            else if (ts.isCallExpression(init) && chantCallee(init.expression, imports) === "stackOutput") {
+                const first = init.arguments[0];
+                if (first && !ts.isStringLiteralLike(first))
+                    out.outputs.push({ name: d.name.text, file: path, line: lineOf(d) });
+            }
+        }
+    }
+    // output(ref, "Name") anywhere in the file.
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && chantCallee(node.expression, imports) === "output" && node.arguments.length >= 2) {
+            const name = literalString(node.arguments[1], consts);
+            if (name !== undefined)
+                out.outputs.push({ name, file: path, line: lineOf(node) });
+            else
+                out.gaps.push(`${path}:${lineOf(node)}: an output whose name is not a string literal`);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+}
+/**
+ * Read a chant member's outputs and parameters from the source under `dir`
+ * (tree-relative, `""` for the root), leaving out the `exclude`d directories.
+ * Runs no member code.
+ */
+export function readSourceHandles(tree, dir, exclude = new Set()) {
+    const out = { outputs: [], inputs: [], gaps: [] };
+    for (const file of sourceFiles(tree, dir, exclude)) {
+        let text;
+        try {
+            text = tree.read(file);
+        }
+        catch {
+            out.gaps.push(`${file}: the file could not be read`);
+            continue;
+        }
+        readFile(file, text, out);
+    }
+    return out;
+}
+/**
+ * Every member's handles, read in source for `chant workspace check`. A
+ * `chant` member's outputs and parameters are parsed from its TypeScript
+ * without running it; other kinds expose what the kind and the entry list.
+ * A member whose directory is missing or whose kind is unknown is left out,
+ * so links to it are unresolved.
+ */
+export function sourceMemberHandles(declaration, tree, groups, kinds) {
+    const out = new Map();
+    for (const m of declaration.members) {
+        const kind = kinds.get(m.kind);
+        if (!kind || tree.stat(memberDir(m.dir)) !== "dir")
+            continue;
+        const listed = kindHandles(m, kind);
+        if (listed) {
+            out.set(m.name, listed);
+        }
+        else {
+            // Other members' directories and group matches inside this one are not its source.
+            const exclude = new Set();
+            for (const o of declaration.members)
+                if (o !== m && o.dir !== "." && isInside(o.dir, m.dir))
+                    exclude.add(o.dir);
+            for (const g of groups)
+                for (const dir of g.matches)
+                    if (isInside(dir, m.dir))
+                        exclude.add(dir);
+            const read = readSourceHandles(tree, memberDir(m.dir), exclude);
+            out.set(m.name, {
+                member: m.name,
+                outputs: read.outputs.map((o) => ({ name: o.name })),
+                inputs: read.inputs.map((i) => ({ name: i.name })),
+                complete: read.gaps.length === 0,
+                why: read.gaps.length === 0 ? null : read.gaps.length === 1 ? read.gaps[0] : `${read.gaps[0]}, and ${read.gaps.length - 1} more`,
+                exposesNone: false,
+            });
+        }
+    }
+    return out;
+}

package/dist/workspace/member-pipeline.js

@@ -0,0 +1,258 @@
+/**
+ * Per-member CI pipelines (#2542; #2524 D19, ws-041 and ws-042).
+ *
+ * When `chant build --components --generate` or `chant run --generate` runs
+ * for a project inside a workspace member, the generator is told which
+ * member it is generating for ({@link PipelineMember}). The generated
+ * pipeline is then filtered to the member's paths, its jobs run in the
+ * member's directory, and its file is named after the member so two members
+ * never write the same file.
+ *
+ * Forges read CI files from fixed paths at the repository root, outside any
+ * member's directory. The member whose command generates such a file owns
+ * it (ws-042), and records it in its list of generated files. That list
+ * belongs in the member's `generated` entry in `chant.workspace.json` once
+ * #2541 lands. Until then it is `.chant/generated.json` in the member's
+ * directory ({@link GENERATED_RECORD_FILE}), which `WSP081` reads to allow
+ * one declarer per file (./checks/pipelines.ts).
+ *
+ * The command handlers import this module only after `findWorkspaceRoot`
+ * has found a declaration, so a project outside any workspace never loads it.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { GENERATED_MARKER } from "../discovery/files.js";
+import { ownerOf, readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError } from "./declaration.js";
+import { gitTop, workingTree } from "./tree.js";
+/**
+ * TODO(#2541): the interim home of a member's generated-file list, relative
+ * to the member's directory. #2541 moves the list into the member's entry in
+ * the declaration, and this file goes away.
+ */
+export const GENERATED_RECORD_FILE = ".chant/generated.json";
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** `path` relative to `from`, `/`-separated, `"."` for `from` itself. */
+function relPath(from, path) {
+    const rel = relative(from, path).split(sep).join("/");
+    return rel === "" ? "." : rel;
+}
+function joinRel(prefix, dir) {
+    if (prefix === ".")
+        return dir;
+    return dir === "." ? prefix : `${prefix}/${dir}`;
+}
+/**
+ * The member that owns `projectDir`, given the declaration `findWorkspaceRoot`
+ * found. Undefined when no member owns it: the directory sits in an example
+ * group's match, or outside every member of a workspace with no root member.
+ * Throws `WorkspaceReadError` when the declaration can't be read.
+ */
+export function resolveMemberContext(projectDir, found) {
+    const workspaceRoot = real(found.dir);
+    const tree = workingTree(workspaceRoot);
+    const declaration = readDeclaration(tree);
+    const groups = resolveGroups(declaration, tree);
+    const at = relPath(workspaceRoot, real(projectDir));
+    if (at.startsWith(".."))
+        return undefined;
+    const owner = ownerOf(declaration, groups, at);
+    if (!owner || !("member" in owner))
+        return undefined;
+    const member = owner.member;
+    const repoRoot = real(gitTop(workspaceRoot) ?? workspaceRoot);
+    const prefix = relPath(repoRoot, workspaceRoot);
+    const pipeline = { name: member.name, dir: joinRel(prefix, member.dir) };
+    if (member.dir === ".") {
+        const exclude = rootExclusions(declaration, groups).map((e) => joinRel(prefix, e.dir));
+        if (exclude.length > 0)
+            pipeline.exclude = exclude;
+    }
+    return {
+        declaration,
+        member,
+        workspaceRoot,
+        repoRoot,
+        memberRoot: member.dir === "." ? workspaceRoot : join(workspaceRoot, member.dir),
+        pipeline,
+    };
+}
+/** Where each forge reads a member's component pipeline from, relative to the repository root. */
+const PIPELINE_DIRS = {
+    github: ".github/workflows",
+    forgejo: ".forgejo/workflows",
+    // GitLab reads only .gitlab-ci.yml, which includes these (`include: local: .gitlab/ci/*.gitlab-ci.yml`).
+    gitlab: ".gitlab/ci",
+};
+/** The directory a forge's generated files go in for a member, relative to the repository root, or undefined for a forge chant doesn't know. */
+export function memberPipelineDir(provider) {
+    return PIPELINE_DIRS[provider];
+}
+/**
+ * The default path of a member's component pipeline for one environment,
+ * relative to the repository root: `chant-<member>-<env>.yml` in the forge's
+ * workflow directory, or `.gitlab/ci/chant-<member>-<env>.gitlab-ci.yml`.
+ * A pull-request pipeline (`kind` `"pr"`, #3465) is `chant-pr.<member>.<env>`, with the dots the apply group uses so no
+ * two member and environment pairs share one name, and it sits beside the
+ * member's deploy pipeline for the same environment.
+ */
+export function memberPipelineFile(provider, member, env, kind = "components") {
+    const dir = PIPELINE_DIRS[provider];
+    if (dir === undefined)
+        return undefined;
+    const stem = kind === "pr" ? `chant-pr.${member}.${env}` : `chant-${member}-${env}`;
+    return `${dir}/${stem}${provider === "gitlab" ? ".gitlab-ci.yml" : ".yml"}`;
+}
+/** A repository-relative path for an absolute one. */
+export function repoRelative(ctx, absolute) {
+    return relPath(ctx.repoRoot, resolve(absolute));
+}
+/** Read a member's generated-file record, or an empty one. */
+export function readGeneratedRecord(memberRoot) {
+    const file = join(memberRoot, GENERATED_RECORD_FILE);
+    if (!existsSync(file))
+        return { schema: 1, files: [] };
+    const parsed = JSON.parse(readFileSync(file, "utf-8"));
+    return { schema: 1, files: Array.isArray(parsed.files) ? parsed.files : [] };
+}
+/**
+ * Add or replace entries in a member's generated-file record, keyed by path,
+ * and write it back sorted, so regenerating the same files leaves it
+ * byte-identical.
+ */
+export function recordGeneratedFiles(memberRoot, entries) {
+    const record = readGeneratedRecord(memberRoot);
+    const byPath = new Map(record.files.map((f) => [f.path, f]));
+    for (const e of entries)
+        byPath.set(e.path, e);
+    const files = [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const file = join(memberRoot, GENERATED_RECORD_FILE);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ schema: 1, files }, null, 2) + "\n");
+    return file;
+}
+/** Quote one argument for a recorded command line when it needs it. */
+export function shellArg(arg) {
+    return /^[A-Za-z0-9._\/=:@%+,-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/** The first line of a member's generated pipeline, naming the command that regenerates it. */
+export function generatedHeader(command) {
+    return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the member's directory)\n`;
+}
+/** The generators' own default environment when `--env` is not given. */
+const DEFAULT_ENV = "production";
+/**
+ * Plan a member's component pipeline: which member, which file and which
+ * command. Undefined when the project belongs to no member. Throws with a
+ * readable message when there is no default file for the forge and no
+ * `--output`.
+ */
+export function planMemberComponentPipeline(input) {
+    const ctx = resolveMemberContext(input.projectDir, input.found);
+    if (!ctx)
+        return undefined;
+    const env = input.env ?? DEFAULT_ENV;
+    let target;
+    if (input.output) {
+        target = resolve(input.output);
+    }
+    else {
+        const file = memberPipelineFile(input.lexicon, ctx.member.name, env, input.prLoop ? "pr" : "components");
+        if (file === undefined) {
+            throw new Error(`there is no default pipeline path for ${input.lexicon} in a workspace member; pass --output <file>`);
+        }
+        target = join(ctx.repoRoot, file);
+    }
+    const file = repoRelative(ctx, target);
+    const parts = ["chant", "build", "--components", "--generate", input.lexicon, "--env", env];
+    if (input.promoteTo)
+        parts.push("--promote-to", input.promoteTo);
+    if (input.waveGate) {
+        parts.push("--wave-gate", input.waveGate.gate);
+        if (input.waveGate.canary?.length)
+            parts.push("--canary", input.waveGate.canary.join(","));
+        if (input.waveGate.base)
+            parts.push("--base", input.waveGate.base);
+    }
+    if (input.prLoop) {
+        parts.push("--pr-loop");
+        if (input.prLoop.gate)
+            parts.push("--gate", input.prLoop.gate);
+        if (input.prLoop.branch)
+            parts.push("--branch", input.prLoop.branch);
+    }
+    for (const p of input.params ?? [])
+        parts.push("--param", p);
+    if (input.paramsFile)
+        parts.push("--params-file", relPath(ctx.memberRoot, resolve(input.paramsFile)));
+    if (input.output)
+        parts.push("--output", relPath(ctx.memberRoot, target));
+    return {
+        ctx,
+        member: { ...ctx.pipeline, file },
+        file,
+        target,
+        command: parts.map(shellArg).join(" "),
+        env,
+    };
+}
+/** Write a member's pipeline with its header and record it as the member's generated file. */
+export function writeMemberComponentPipeline(plan, yaml) {
+    mkdirSync(dirname(plan.target), { recursive: true });
+    writeFileSync(plan.target, generatedHeader(plan.command) + yaml);
+    recordGeneratedFiles(plan.ctx.memberRoot, [{ path: plan.file, command: plan.command, env: plan.env }]);
+}
+/** Plan a member's Op pipelines. Undefined when the directory belongs to no member. */
+export function planMemberOpPipelines(input) {
+    const ctx = resolveMemberContext(input.projectDir, input.found);
+    if (!ctx)
+        return undefined;
+    let outDir;
+    if (input.output) {
+        outDir = resolve(input.output);
+    }
+    else {
+        const dir = memberPipelineDir(input.provider);
+        if (dir === undefined) {
+            throw new Error(`there is no default pipeline directory for ${input.provider} in a workspace member; pass --output <dir>`);
+        }
+        outDir = join(ctx.repoRoot, dir);
+    }
+    const parts = ["chant", "run", "--generate", input.provider];
+    if (input.specFile)
+        parts.push("--spec", relPath(ctx.memberRoot, resolve(input.specFile)));
+    if (input.output)
+        parts.push("--output", relPath(ctx.memberRoot, outDir));
+    return {
+        ctx,
+        member: { ...ctx.pipeline, fileDir: repoRelative(ctx, outDir) },
+        outDir,
+        command: parts.map(shellArg).join(" "),
+    };
+}
+/** Write a member's Op pipeline files with their header and record them. Returns the paths written, relative to the current directory. */
+export function writeMemberOpPipelines(plan, files) {
+    const written = [];
+    const entries = [];
+    for (const f of files) {
+        const target = join(plan.outDir, f.name);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, generatedHeader(plan.command) + f.yaml);
+        entries.push({ path: repoRelative(plan.ctx, target), command: plan.command });
+        written.push(relative(process.cwd(), target) || target);
+    }
+    recordGeneratedFiles(plan.ctx.memberRoot, entries);
+    return written;
+}
+/** A message for an error from planning: a declaration error with its file and line, or the error's own message. */
+export function describeError(err) {
+    if (err instanceof WorkspaceReadError)
+        return err.describe();
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/workspace/member-run.js

@@ -0,0 +1,117 @@
+/**
+ * `chant workspace member-run` (#2537): the one process a toolchain runs for
+ * `chant workspace build|lint|audit|graph`.
+ *
+ * `member-commands.ts` groups the members by the chant each one resolves
+ * (#2524 D3, "one process per toolchain identity") and spawns that chant's
+ * `workspace member-run` once per group. The request arrives as JSON on
+ * stdin: the level-0 command line for each member, and the member's
+ * directory. This process runs them one after another, in-process, from
+ * inside each directory, so every member gets what `chant <verb> .` would
+ * print there. It answers on stdout with one {@link PROTOCOL_PREFIX} line per
+ * member, after a header line naming the protocol and this chant's version.
+ *
+ * A chant older than this command has no header to print. The caller sees
+ * that and falls back to one level-0 process per member.
+ *
+ * Internal: not listed in `chant --help`, and the protocol may change with
+ * the caller, which is always a chant of the same or a newer release.
+ */
+import { ENV_VAR } from "../env.js";
+import { readerVersion } from "./declaration.js";
+/** Marks the lines of this protocol on stdout; anything else there is stray output. */
+export const PROTOCOL_PREFIX = "@@chant-member-run@@ ";
+export const MEMBER_RUN_PROTOCOL = 1;
+/** A `process.exit` inside a command, turned into a value. */
+class ExitRequest extends Error {
+    constructor(code) {
+        super(`process.exit(${code})`);
+        this.code = code;
+    }
+}
+/**
+ * Run `fn` with stdout, stderr and `process.exit` captured. Commands print
+ * through `console`, which writes through the stream's `write` at call time,
+ * so replacing `write` catches everything they print.
+ */
+export async function captureRun(fn) {
+    const out = [];
+    const err = [];
+    const sink = (into) => ((chunk, encoding, cb) => {
+        into.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+        const done = typeof encoding === "function" ? encoding : cb;
+        if (typeof done === "function")
+            done();
+        return true;
+    });
+    const saved = { out: process.stdout.write, err: process.stderr.write, exit: process.exit };
+    process.stdout.write = sink(out);
+    process.stderr.write = sink(err);
+    process.exit = ((code) => {
+        throw new ExitRequest(typeof code === "number" ? code : 0);
+    });
+    let exitCode;
+    try {
+        exitCode = await fn();
+    }
+    catch (e) {
+        if (e instanceof ExitRequest) {
+            exitCode = e.code;
+        }
+        else {
+            err.push(`${e instanceof Error ? e.message : String(e)}\n`);
+            exitCode = 1;
+        }
+    }
+    finally {
+        process.stdout.write = saved.out;
+        process.stderr.write = saved.err;
+        process.exit = saved.exit;
+    }
+    return { exitCode, stdout: out.join(""), stderr: err.join("") };
+}
+function emit(line) {
+    process.stdout.write(`${PROTOCOL_PREFIX}${JSON.stringify(line)}\n`);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** Run each unit of `request` in turn, answering on stdout. */
+export async function runMemberUnits(request, run) {
+    emit({ type: "header", protocol: MEMBER_RUN_PROTOCOL, chant: readerVersion() });
+    const startDir = process.cwd();
+    const startEnv = process.env[ENV_VAR];
+    for (const unit of request.units) {
+        const result = await captureRun(async () => {
+            process.chdir(unit.dir);
+            // `unit.exclude` needs no action here: discovery reads the declaration
+            // itself and leaves member `.`'s exclusions out of every walk (#2527).
+            return run(unit.argv);
+        });
+        if (startEnv === undefined)
+            delete process.env[ENV_VAR];
+        else
+            process.env[ENV_VAR] = startEnv;
+        process.chdir(startDir);
+        emit({ type: "result", id: unit.id, ...result, finishedAt: new Date().toISOString() });
+    }
+    return 0;
+}
+export async function runWorkspaceMemberRun(_ctx, run) {
+    let request;
+    try {
+        request = JSON.parse(await readStdin());
+    }
+    catch (err) {
+        console.error(`chant workspace member-run: the request on stdin is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (request.protocol !== MEMBER_RUN_PROTOCOL || !Array.isArray(request.units)) {
+        console.error(`chant workspace member-run: this chant speaks protocol ${MEMBER_RUN_PROTOCOL}, and the request asks for ${String(request.protocol)}`);
+        return 1;
+    }
+    return runMemberUnits(request, run);
+}