@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/dist/skill.js

@@ -0,0 +1,149 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import matter from "gray-matter";
+const REVIEW_DEFAULTS = {
+    judges: 2,
+    quorum: "all",
+    onFail: "retry",
+    maxRetries: 2,
+};
+/**
+ * Parse the skill's steps.
+ *
+ * A `## Steps` section declares them explicitly: each `###` heading under it is a step.
+ * Without that section the whole skill is one step - which is what most skills are, and
+ * what the Agent Skills standard describes. Steps are never inferred from arbitrary `###`
+ * headings elsewhere in the body: prose skills are full of those, and reading them as
+ * executable steps would run a skill's explanatory subsections as work.
+ */
+function parseSteps(name, body) {
+    const stepsHeading = /^##\s+Steps\s*$/im.exec(body);
+    if (stepsHeading === null) {
+        const instructions = body.trim();
+        return instructions === "" ? [] : [{ name, instructions }];
+    }
+    const afterSteps = body.slice(stepsHeading.index + stepsHeading[0].length);
+    const nextSection = /^##\s+(?!#)/m.exec(afterSteps);
+    const lines = (nextSection === null ? afterSteps : afterSteps.slice(0, nextSection.index)).split("\n");
+    const steps = [];
+    let current;
+    for (const line of lines) {
+        const heading = /^###\s+(.+?)\s*$/.exec(line);
+        if (heading) {
+            if (current)
+                steps.push({ name: current.name, instructions: current.instructions.join("\n").trim() });
+            current = { name: heading[1].trim(), instructions: [] };
+            continue;
+        }
+        if (current)
+            current.instructions.push(line);
+    }
+    if (current)
+        steps.push({ name: current.name, instructions: current.instructions.join("\n").trim() });
+    return steps;
+}
+export function loadSkill(skillDir) {
+    const dir = resolve(skillDir);
+    const raw = readFileSync(join(dir, "SKILL.md"), "utf8");
+    const { data, content } = matter(raw);
+    const name = String(data.name ?? "");
+    const description = String(data.description ?? "");
+    if (!name || !description) {
+        throw new Error(`${dir}/SKILL.md: 'name' and 'description' are required by the Agent Skills spec`);
+    }
+    const rawGates = data.metadata?.gates ?? [];
+    const gatesByStep = new Map();
+    for (const g of rawGates) {
+        if (!g.after)
+            throw new Error(`${name}: every gate needs an 'after: <step>'`);
+        if (!g.review?.rubric)
+            throw new Error(`${name}: gate after '${g.after}' has no 'review.rubric'`);
+        const live = g.continuous;
+        if (live !== undefined && !live.rubric) {
+            throw new Error(`${name}: continuous review after '${g.after}' has no 'rubric'`);
+        }
+        gatesByStep.set(g.after, {
+            after: g.after,
+            continuous: live === undefined
+                ? undefined
+                : {
+                    rubric: live.rubric,
+                    // One judge per pass. The pass runs on every write, so a second opinion
+                    // costs a multiple of the phase rather than a single review.
+                    judges: live.judges ?? 1,
+                    model: live.model,
+                    judgeTools: live.judge_tools ?? live.judgeTools ?? [],
+                },
+            review: {
+                rubric: g.review.rubric,
+                judges: g.review.judges ?? REVIEW_DEFAULTS.judges,
+                model: g.review.model,
+                quorum: g.review.quorum ?? REVIEW_DEFAULTS.quorum,
+                judgeTools: g.review.judge_tools ?? g.review.judgeTools ?? [],
+                onFail: g.review.on_fail ?? g.review.onFail ?? REVIEW_DEFAULTS.onFail,
+                maxRetries: g.review.max_retries ?? g.review.maxRetries ?? REVIEW_DEFAULTS.maxRetries,
+            },
+        });
+    }
+    // What each step does, for the person: `metadata.phases`, a short line a step by its name.
+    const rawPhases = data.metadata?.phases ?? {};
+    if (typeof rawPhases !== "object" || rawPhases === null || Array.isArray(rawPhases)) {
+        throw new Error(`${name}: 'metadata.phases' is a line a step, by the step's name`);
+    }
+    const abouts = new Map(Object.entries(rawPhases).map(([step, about]) => [step, String(about ?? "").trim()]));
+    const steps = parseSteps(name, content).map((s) => {
+        const about = abouts.get(s.name);
+        return { ...s, ...(about !== undefined && about !== "" ? { about } : {}), gate: gatesByStep.get(s.name) };
+    });
+    if (steps.length === 0)
+        throw new Error(`${name}: the skill body is empty`);
+    for (const stepName of abouts.keys()) {
+        if (!steps.some((s) => s.name === stepName)) {
+            throw new Error(`${name}: 'metadata.phases' describes unknown step '${stepName}'`);
+        }
+    }
+    const questioning = data.metadata?.questioning;
+    const capped = Array.isArray(questioning) ? questioning.map(String) : [];
+    for (const stepName of capped) {
+        if (!steps.some((s) => s.name === stepName)) {
+            throw new Error(`${name}: 'metadata.questioning' names unknown step '${stepName}'`);
+        }
+    }
+    const perAnswer = data.metadata?.["spec-diff-per-answer"];
+    const diffPerAnswer = Array.isArray(perAnswer) ? perAnswer.map(String) : [];
+    for (const stepName of diffPerAnswer) {
+        if (!steps.some((s) => s.name === stepName)) {
+            throw new Error(`${name}: 'metadata.spec-diff-per-answer' names unknown step '${stepName}'`);
+        }
+    }
+    for (const stepName of gatesByStep.keys()) {
+        if (!steps.some((s) => s.name === stepName)) {
+            throw new Error(`${name}: gate references unknown step '${stepName}'`);
+        }
+    }
+    return {
+        name,
+        description,
+        dir,
+        // What a skill may use is what its frontmatter names, and nothing else: no list, no tools.
+        allowedTools: Array.isArray(data["allowed-tools"]) ? data["allowed-tools"] : [],
+        steps,
+        paced: data.metadata?.paced !== false,
+        questioning: capped,
+        diffPerAnswer,
+    };
+}
+export function readRubric(skill, review) {
+    return readFileSync(join(skill.dir, review.rubric), "utf8").trim();
+}
+/**
+ * The status line while a skill runs: which phase, and how far through the skill it is.
+ * The phase is counted from 1 and includes the one in progress, so "3 of 6" means two are
+ * done. A retry after a failed gate says so - the same phase twice is not progress.
+ */
+export function skillStatus(skill, step, attempt) {
+    const index = skill.steps.findIndex((s) => s.name === step);
+    const position = index === -1 ? "" : ` (phase ${index + 1} of ${skill.steps.length})`;
+    const retry = attempt > 1 ? `, attempt ${attempt}` : "";
+    return `${skill.name}: ${step}${position}${retry}`;
+}

package/dist/skills.js

@@ -0,0 +1,74 @@
+/**
+ * Where skills are found: turri's own, in `genome/skills/` of this package, and the project's - `.turri/skills/` and
+ * `.agents/skills/` in the project's folder, a folder a skill with its SKILL.md, in the format of turri's own. A
+ * project's skill is run the same way: its steps, its gates and judges, the tools its frontmatter names.
+ *
+ * A name is one skill: turri's own come first, then `.turri/skills/`, then `.agents/skills/`, and a skill whose name is
+ * taken already is left out and said to be - a project's `brood` never quietly stands in for turri's.
+ */
+import { readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { loadSkill } from "./skill.js";
+/** A project's skill folders, in the order they are read, relative to the project. */
+export const PROJECT_SKILL_DIRS = [join(".turri", "skills"), join(".agents", "skills")];
+function folders(root, includeFixtures) {
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && (!entry.name.startsWith("_") || includeFixtures))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Every skill turri can run in `projectDir`: its own from `packageRoot`, then the project's. */
+export function discoverSkills(packageRoot, projectDir) {
+    const catalogue = { skills: [], pending: [], shadowed: [] };
+    const builtIn = join(packageRoot, "genome", "skills");
+    for (const name of folders(builtIn, process.env.TURRI_INCLUDE_FIXTURES === "1")) {
+        try {
+            catalogue.skills.push({ ...loadSkill(join(builtIn, name)), origin: "turri" });
+        }
+        catch {
+            catalogue.pending.push(name);
+        }
+    }
+    if (projectDir === undefined)
+        return catalogue;
+    for (const dir of PROJECT_SKILL_DIRS) {
+        const root = join(projectDir, dir);
+        for (const name of folders(root, true)) {
+            const where = relative(projectDir, join(root, name));
+            let skill;
+            try {
+                skill = loadSkill(join(root, name));
+            }
+            catch {
+                catalogue.pending.push(where);
+                continue;
+            }
+            const taken = catalogue.skills.find((other) => other.name === skill.name);
+            if (taken !== undefined) {
+                catalogue.shadowed.push(`${where} (${skill.name} is ${taken.origin === "turri" ? "turri's own" : `${taken.origin.project}`})`);
+                continue;
+            }
+            catalogue.skills.push({ ...skill, origin: { project: where } });
+        }
+    }
+    return catalogue;
+}
+/** A skill's line in cultivate's list: a project's says so, and where it is. */
+export function catalogueLine(skill) {
+    const whose = skill.origin === "turri" ? "" : ` (this project's, ${skill.origin.project})`;
+    return `- ${skill.name}${whose}: ${skill.description}`;
+}
+/** What is said under the list about the skills it leaves out. */
+export function leftOutNote(catalogue) {
+    return [
+        ...(catalogue.pending.length > 0 ? [`Failed to load and therefore not runnable: ${catalogue.pending.join(", ")}.`] : []),
+        ...(catalogue.shadowed.length > 0 ? [`Left out, their names taken: ${catalogue.shadowed.join(", ")}.`] : []),
+    ]
+        .map((line) => `\n\n${line}`)
+        .join("");
+}

package/dist/spec-diff-cli.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { checkPlainFile } from "./plain/check.js";
+import { applySpecDiff, revertSpecDiff } from "./regenerate/regenerate.js";
+import { parseArgs, runLoop } from "./loop-cli.js";
+const USAGE = `usage: turri spec-diff <file.plain> <diff-file> [options]
+
+Applies a change to the specs, given as a git diff of the .plain files, and builds it: the headless
+counterpart of regenerate, given a diff. The diff is applied first, unless it is already in; then, as
+turri regenerate does, what is left to build is planned into jobs and built.
+
+  --model <provider/id>    model for the agents (default: config.turri.yaml's coding-model)
+  --start-over             start over, without asking, a codebase regenerated without a module it now requires`;
+const { positional, options } = parseArgs(process.argv.slice(2), ["--start-over"], USAGE);
+const [plainFile, diffFile] = positional;
+if (plainFile === undefined || diffFile === undefined) {
+    console.error(USAGE);
+    process.exit(1);
+}
+const diff = readFileSync(diffFile, "utf8");
+const cwd = process.cwd();
+applySpecDiff(diff, cwd);
+const check = checkPlainFile(resolve(plainFile));
+if (!check.ok) {
+    revertSpecDiff(diff, cwd);
+    console.error(`Nothing was changed: with this diff ${plainFile} no longer parses. ${check.error}`);
+    process.exit(1);
+}
+runLoop({
+    plainFile,
+    ...(options.model !== undefined ? { model: options.model } : {}),
+    startOver: options["start-over"] !== undefined,
+    ask: (loop) => loop.bringUp(plainFile, options.model !== undefined ? { model: options.model } : {}),
+}).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/spec-tools.js

@@ -0,0 +1,155 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata } from "./plain/parser.js";
+import { resolveTemplateDirs } from "./regenerate/paths.js";
+import { applySpecDiff, plainFilesOf, revertSpecDiff } from "./regenerate/regenerate.js";
+import { MissingFunctionalitiesError } from "./plain/errors.js";
+import { describeModules } from "./regenerate/loop.js";
+import { reviewNote } from "./tools.js";
+/**
+ * Writing a spec change as a diff, and building it, as one step.
+ *
+ * In an interview whose unit of work is a spec change, every change is meant to be built the
+ * moment it is written. Left to two tool calls - change the file, then start the render - the
+ * second is the one that gets forgotten, and nothing notices. So the diff is applied and its
+ * build queued in the same call: a change cannot reach the specs without its render being
+ * started. A new change needs an answer since the last one; a correction does not.
+ */
+export function createSpecDiffTools(options) {
+    const { loop, cwd, liveReview } = options;
+    const skillPaced = options.paced !== false;
+    const isPaced = () => skillPaced && options.free?.() !== true;
+    /** An answer has come since the last change: it is owed one. */
+    let owed = false;
+    let answeredSinceLastDiff = true;
+    const writeDiff = defineTool({
+        name: "write_spec_diff",
+        label: "Write spec diff",
+        description: "Apply a change to the ***plain specs, given as a git diff of the .plain files, and start building it in " +
+            "the background. The diff is applied with git; if the specs no longer parse, it is undone and nothing is " +
+            "built. Any section may change - definitions, implementation reqs, functional specs, added, changed or removed - and " +
+            "every change is built, whatever it touches.",
+        promptSnippet: "apply a git diff of the .plain specs and start building it",
+        promptGuidelines: [
+            "Every change to a .plain file in the product phase goes through write_spec_diff, as a git diff with paths relative to the project root. It writes the change and starts its build in one step.",
+            skillPaced
+                ? "One change per answer, and a new one only after the user has answered a question about it. Set fixes_earlier to correct something already written."
+                : "Write the changes one after another, on your own: no answer is needed between them, and none is asked for. Set fixes_earlier to correct something already written.",
+            "To take something out of what is already written and queued - the user drops a page or a feature - write the diff that removes it from every spec that names it, with fixes_earlier. What is left to build is worked out from the spec each time, and a build the change undoes is stopped by itself; never stop builds to drop a change - it stays in the files.",
+        ],
+        parameters: Type.Object({
+            plain_file: Type.String({ description: "The .plain file of the module the change is built for" }),
+            diff: Type.String({ description: "The change, as a git diff (diff --git a/<file> b/<file> ...)" }),
+            fixes_earlier: Type.Optional(Type.Boolean({ description: "This corrects something already written - a contradiction, a review finding" })),
+            guidance: Type.Optional(Type.String({
+                description: "How to plan the queue for this change, in a sentence or two - which functional specs go together, what first - as the " +
+                    "user said it or as the interview settled it. A strong preference for the planner. Omit when there is none.",
+            })),
+        }),
+        async execute(_id, params) {
+            const paced = isPaced();
+            if (paced && params.fixes_earlier !== true && !answeredSinceLastDiff) {
+                throw new Error("No question has been answered since the last spec change. Each change comes from its own answer: ask " +
+                    "the user with ask_user first. To correct something already written, set fixes_earlier.");
+            }
+            const touched = plainFilesOf(params.diff);
+            if (touched.length === 0)
+                throw new Error("The diff changes no .plain file. Nothing was written.");
+            const result = applySpecDiff(params.diff, cwd);
+            // A change that breaks a spec is not written at all, so nothing is ever built from a
+            // file that cannot be parsed. A module with no functional specs yet is not broken. An import
+            // module - definitions only, say - is not a module of its own: it is parsed as the modules
+            // that import it read it, the one the change is built for among them.
+            const importers = (file) => {
+                const name = basename(file, ".plain");
+                const dir = dirname(resolve(cwd, file));
+                return readdirSync(dir)
+                    .filter((entry) => entry.endsWith(".plain"))
+                    .map((entry) => join(dir, entry))
+                    .filter((path) => {
+                    try {
+                        return (readPlainSourceMetadata(readFileSync(path, "utf8")).metadata[IMPORT_DIRECTIVE] ?? []).includes(name);
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            };
+            const imported = importedNames(resolveTemplateDirs(resolve(cwd, params.plain_file)));
+            const toParse = [
+                ...new Set([params.plain_file, ...touched].flatMap((file) => imported.has(basename(file, ".plain")) ? importers(file).filter((path) => !imported.has(basename(path, ".plain"))) : [resolve(cwd, file)])),
+            ];
+            for (const path of toParse) {
+                const file = relative(cwd, path);
+                try {
+                    plainFileParser(basename(path), resolveTemplateDirs(path), { allowNoFunctionalities: true });
+                }
+                catch (error) {
+                    if (error instanceof MissingFunctionalitiesError)
+                        continue;
+                    if (result === "applied")
+                        revertSpecDiff(params.diff, cwd);
+                    const reason = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Nothing was written: with this change ${file} no longer parses. ${reason}`);
+                }
+            }
+            if (params.fixes_earlier !== true)
+                answeredSinceLastDiff = false;
+            owed = false;
+            liveReview?.notice(`${params.plain_file}, after the change to ${touched.join(", ")}`);
+            // In the files, the change is work: the loop works out what is left to build and plans it.
+            const statuses = await loop.bringUp(params.plain_file, params.guidance !== undefined ? { guidance: params.guidance } : {});
+            const lines = [
+                result === "applied" ? `Applied the change to ${touched.join(", ")}.` : `The change to ${touched.join(", ")} was already applied.`,
+                `Building in the background:\n${describeModules(statuses)}\n`,
+                // An interview goes back to its questions; a skill that writes on its own, straight to its next change - a stop to ask ends it.
+                paced
+                    ? "Carry on with the interview."
+                    : skillPaced
+                        ? "Carry on: write the next change you decided yourself, or ask the next question - every answer is written as a change before the question after it."
+                        : "Write the next change now, without stopping to ask: this skill goes on until everything it is to write is written.",
+            ];
+            return {
+                content: [{ type: "text", text: lines.join(" ") + reviewNote(liveReview) }],
+                details: { jobIds: statuses.flatMap((status) => (status.running !== undefined ? [status.running.jobId] : [])), files: touched },
+            };
+        },
+    });
+    return {
+        tools: [writeDiff],
+        pace: {
+            answered(owesChange = true) {
+                answeredSinceLastDiff = true;
+                if (owesChange)
+                    owed = true;
+            },
+            owed: () => owed,
+        },
+    };
+}
+/** The module names some .plain file in these folders imports: import modules, not codebases. */
+export function importedNames(dirs) {
+    const names = new Set();
+    for (const dir of dirs) {
+        let entries;
+        try {
+            entries = readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            try {
+                const imports = readPlainSourceMetadata(readFileSync(join(dir, entry), "utf8")).metadata[IMPORT_DIRECTIVE];
+                for (const name of imports ?? [])
+                    names.add(name);
+            }
+            catch {
+                // A file that does not read imports nothing.
+            }
+        }
+    }
+    return names;
+}

package/dist/stack.js

@@ -0,0 +1,158 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { plainFileParser, withParseCache } from "./plain/parser.js";
+import { resolveTemplateDirs } from "./regenerate/paths.js";
+import { sectionsOf } from "./regenerate/state.js";
+import { onThisMachine } from "./regenerate/test-scripts.js";
+/** Words in implementation reqs, and the toolchain each means. */
+const STACKS = [
+    { toolchain: "Python", commands: ["python3", "python"], words: /\b(python|fastapi|django|flask|pytest|pydantic|sqlalchemy|uvicorn)\b/gi },
+    { toolchain: "Node", commands: ["node"], words: /\b(node(\.js)?|typescript|javascript|react|vite|next\.js|express|vue|svelte|npm|vitest|jest|playwright)\b/gi },
+    { toolchain: "Java", commands: ["java"], words: /\b(java|spring( boot)?|maven|gradle|junit|kotlin)\b/gi },
+    { toolchain: "Go", commands: ["go"], words: /\b(golang|go \d+\.\d+|go modules?|written in go)\b/gi },
+    { toolchain: "Rust", commands: ["cargo"], words: /\b(rust|cargo|tokio|axum)\b/gi },
+    { toolchain: "C/C++", commands: ["cc", "gcc", "clang"], words: /(\bc\+\+|\bcmake\b|\bgcc\b|\bclang\b|\bwritten in c\b)/gi },
+    { toolchain: "Zig", commands: ["zig"], words: /\bzig\b/gi },
+    { toolchain: "Odin", commands: ["odin"], words: /\bodin\b/gi },
+    { toolchain: "Ruby", commands: ["ruby"], words: /\b(ruby|rails)\b/gi },
+    { toolchain: "PHP", commands: ["php"], words: /\b(php|laravel|symfony)\b/gi },
+    { toolchain: "Elixir", commands: ["elixir"], words: /\b(elixir|phoenix)\b/gi },
+];
+/** The toolchains a text of implementation reqs names. */
+export function stackOf(text) {
+    const needs = [];
+    for (const stack of STACKS) {
+        const words = [...new Set([...text.matchAll(stack.words)].map((match) => match[0].toLowerCase()))];
+        if (words.length > 0)
+            needs.push({ toolchain: stack.toolchain, commands: stack.commands, words });
+    }
+    return needs;
+}
+/** The implementation reqs of every module in a project's folder, as the parser has them - imports in. */
+export function projectImplementationReqs(project) {
+    let files;
+    try {
+        files = readdirSync(project).filter((name) => name.endsWith(".plain"));
+    }
+    catch {
+        return [];
+    }
+    // One parse a module for all of them: each parse goes down its requires chain, and a project of long chains would
+    // parse the modules at the bottom once for every module above them.
+    return withParseCache(() => {
+        const modules = [];
+        for (const name of files) {
+            const path = join(project, name);
+            try {
+                const [module, tree] = plainFileParser(basename(path), resolveTemplateDirs(path), { allowNoFunctionalities: true });
+                modules.push({ module, reqs: sectionsOf(tree)["implementation reqs"] });
+            }
+            catch {
+                // A file that does not parse, or an import module read on its own, names nothing here.
+            }
+        }
+        return modules;
+    });
+}
+/** Whether a command is on this machine's PATH. */
+const onPath = (command) => onThisMachine(command) !== undefined;
+/** What a project's modules need of this machine, and which of it the machine lacks. */
+export function stackOnMachine(project, has = onPath) {
+    return projectImplementationReqs(project).map(({ module, reqs }) => {
+        const needs = stackOf(reqs.join("\n"));
+        return { module, needs, missing: needs.filter((need) => !need.commands.some(has)) };
+    });
+}
+/**
+ * The standard library's languages, and what builds and tests their stacks here - every command needed. Python's stacks
+ * run through uv, which fetches Python itself; TypeScript's through npm; Java's through the Maven or Gradle wrapper,
+ * which needs only Java.
+ */
+export const STDLIB_LANGUAGES = [
+    { language: "Python", commands: ["uv"] },
+    { language: "TypeScript", commands: ["node", "npm"] },
+    { language: "Go", commands: ["go"] },
+    { language: "Rust", commands: ["cargo"] },
+    { language: "Java", commands: ["java"] },
+];
+/**
+ * Whether a toolchain's command is really there: on the PATH - and Java on macOS, which keeps a `/usr/bin/java` that only
+ * asks to install a JDK, by `java_home` finding one.
+ */
+function toolchainHere(command) {
+    if (!onPath(command))
+        return false;
+    if (command === "java" && process.platform === "darwin")
+        return spawnSync("/usr/libexec/java_home", [], { stdio: "ignore" }).status === 0;
+    return true;
+}
+/** Which of the standard library's languages this machine can build and test now, and which it lacks a command of. */
+export function languagesOnMachine(has = toolchainHere) {
+    const ready = STDLIB_LANGUAGES.filter(({ commands }) => commands.every(has));
+    return { ready, missing: STDLIB_LANGUAGES.filter((entry) => !ready.includes(entry)) };
+}
+/**
+ * What a spec-writing agent and the conversation are told of this machine before a stack is chosen: the languages it
+ * can build now. The agents install nothing, so a stack in a language the machine lacks stops at its first build -
+ * offering one is offering a project that cannot be regenerated here until the person installs it.
+ */
+export function toolchainsBlock(has = toolchainHere) {
+    const { ready, missing } = languagesOnMachine(has);
+    const named = (entries) => entries.map(({ language, commands }) => `${language} (${commands.join(", ")})`).join(", ");
+    return [
+        "<toolchains on this machine>",
+        ready.length > 0 ? `It can build and test now: ${named(ready)}.` : "It can build none of the standard library's languages now.",
+        ...(missing.length > 0 ? [`It lacks, to build: ${named(missing)} - not installed.`] : []),
+        "Every frontend stack - React, Vue, Svelte, Angular - is TypeScript, and needs Node and npm.",
+        "Choosing a stack, offer only those in a language it can build now, and choose only among them. A stack in a",
+        "language it lacks cannot be regenerated here until the person installs its toolchain - nothing is installed for them;",
+        "asked for one anyway, say what to install first, and that `turri doctor` checks it.",
+        "</toolchains on this machine>",
+    ].join("\n");
+}
+/** The toolchain commands a testing script is checked for. */
+const SCRIPT_COMMANDS = new Set([
+    "python3", "python", "pip", "pip3", "pytest", "uv", "poetry", "node", "npm", "npx", "yarn", "pnpm", "bun", "deno", "java", "javac",
+    "mvn", "gradle", "go", "cargo", "rustc", "cc", "gcc", "clang", "make", "cmake", "zig", "ruby", "bundle", "php", "composer", "elixir",
+    "mix", "dotnet", "flutter", "dart", "swift",
+]);
+/** Folders of the system a script names a program in by its whole path. */
+const SYSTEM_PATH = /(?:^|[\s"'`$(=])(\/(?:usr|opt|Library|Applications|bin|sbin|lib|etc)\/[\w.+/-]+)/g;
+/**
+ * What in a testing script this machine does not have: a program named by a whole path that is not there - a
+ * macOS-only `/usr/libexec/java_home` on Linux - and a toolchain it runs that is not on the PATH. The script is the
+ * person's: this is for them to fix, before an agent ever sees it fail.
+ */
+export function scriptAgainstMachine(text, machine = {}) {
+    const has = machine.has ?? onPath;
+    const exists = machine.exists ?? existsSync;
+    const found = [];
+    const lines = text.split("\n").map((line) => line.replace(/(^|\s)#.*$/, ""));
+    for (const line of lines) {
+        for (const match of line.matchAll(SYSTEM_PATH)) {
+            const path = match[1];
+            if (!exists(path) && !found.some((item) => item.includes(`\`${path}\``)))
+                found.push(`names \`${path}\`, which this machine does not have`);
+        }
+        for (const part of line.split(/&&|\|\||[;|]|\$\(|`/)) {
+            const words = part.trim().split(/\s+/).filter((word) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(word) && word !== "exec" && word !== "export" && word !== "timeout" && !/^\d+[smh]?$/.test(word));
+            const command = words[0];
+            if (command === undefined || !SCRIPT_COMMANDS.has(command) || has(command))
+                continue;
+            const said = `runs \`${command}\`, which is not on this machine's PATH`;
+            if (!found.includes(said))
+                found.push(said);
+        }
+    }
+    return found;
+}
+/** A testing script's text, or nothing when it cannot be read. */
+export function readScript(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}