@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/config.js

@@ -0,0 +1,489 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { copyFileSync, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { load as loadYaml } from "js-yaml";
+import { projectDirOf } from "./regenerate/paths.js";
+/**
+ * The project's `config.turri.yaml`, at its root - the folder that holds `plain_modules` - or, before it had one, its `config.yaml`.
+ *
+ * One file for what a project says about how it is built:
+ *
+ * ```yaml
+ * module: prism_cli.plain                                   # what `turri regenerate` builds by default
+ * harness-model:                                            # the model you chat with in `turri`
+ *   model: anthropic/claude-opus-5-5
+ *   thinking: high
+ * coding-model:                                             # the rendering agents (default: harness-model)
+ *   model: google/gemini-3.1-flash
+ *   thinking: medium
+ * judge-model:                                              # the judge and the test review (default: coding-model)
+ *   model: google/gemini-3.1-pro
+ * conformance-tests: chosen                                 # all, chosen (those with acceptance tests, and those the chooser picks after each pulse), module (the chooser picks, and plans, once the module is regenerated) or false (default: false)
+ * conformance-budget: 30%                                   # under chosen or module: how many functional specs a module may have chosen, beside those with acceptance tests - a count or a share (default: no limit)
+ * review: false                                             # review the code and its tests once they pass (default: true)
+ * allow-to-stop-jobs: false                                 # stop a running job the spec moved on from (default: true)
+ * release-after-pulse: true                                 # release what each pulse lands, as its last stage, before the next pulse (default: false)
+ * rules-off: [integrations]                                 # ***plain rules to leave out of the prompts, by name (default: none)
+ * unittests-script: test_scripts/run_unittests.sh           # the testing scripts - see test-scripts.ts
+ * conformance-tests-script: test_scripts/run_conformance_tests.sh
+ * prepare-environment-script: test_scripts/prepare_environment.sh  # optional: run before the conformance testing script - see test-scripts.ts
+ * testing-scripts-run-on: in-place                         # what the testing scripts run on: in-place (default), or copy - see test-scripts.ts
+ * turn-limit: 150                                           # seconds each turn of an agent a render starts has (default: 120; 0 for none)
+ * models:                                                   # each agent role's own model, thinking and turn limit - see AGENT_ROLES
+ *   default: amazon-bedrock/global.openai.gpt-6-luna         #   every role not named
+ *   coding: { model: amazon-bedrock/eu.anthropic.claude-sonnet-5, thinking: high, turn-limit: 150 }
+ *   explorer: google/gemini-3.1-flash-lite
+ * ```
+ *
+ * `models:` names a model, a thinking level and a turn limit per agent role (AGENT_ROLES), each falling back as
+ * roleModel says: a role it does not name takes `default`, and what an entry leaves out it takes from there too.
+ * `harness-model`, `coding-model` and `judge-model` are the same as `models: chat`, `coding` and `judge`, which win
+ * over them. The turn limit is the role's own, else `default`'s, else `turn-limit:`, else two minutes - the
+ * config is the only place it is set.
+ *
+ * Each model is a model reference and a thinking level (off, minimal, low, medium, high, xhigh, max),
+ * either of which may be left out; a bare string is the model alone. What a model leaves out it takes
+ * from the one it inherits: judge-model from coding-model, coding-model from harness-model. They are
+ * defaults: `--harness-model` / `--coding-model` / `--judge-model` on the command line win over them,
+ * and so does a model chosen during the conversation (pi's /model, engine). `model:` is read
+ * as `coding-model`, which it was before there were two.
+ *
+ * Keys are written with dashes; underscores are read the same (`conformance_tests`). Keys it
+ * does not know - a codeplain `config.yaml`, read while it is the old file, carries several - are ignored, and so is a value of
+ * the wrong type. Everything is optional, and what is given on the command line wins.
+ *
+ * A project whose parts do not share a stack - a Python backend and a React frontend beside each other - keeps a
+ * stack's own settings in `config.turri.<stack>.yaml` beside `config.turri.yaml`: `config.turri.backend.yaml` for the
+ * stack `backend` - its testing scripts, its toolchains. A stack is chosen, never worked out: `/stack` in the chat,
+ * `--stack <name>` (or `TURRI_STACK`) on the command line. With one chosen, everything turri builds from then on is
+ * built with `config.turri.yaml` and the stack's file over it, key by key - a model it names takes what it leaves out
+ * from the project's - and a pulse already running keeps the stack it started with. With none, `config.turri.yaml`
+ * alone. `module:` and `harness-model:` are the project's alone - there is one conversation - and are not read from a
+ * stack's file.
+ */
+/** turri's settings for a project, in a file of its own: a `config.yaml` beside it may be another tool's. */
+export const CONFIG_FILE = "config.turri.yaml";
+/**
+ * Where turri's settings were before they had a file of their own. A project with no `config.turri*.yaml` yet is read
+ * from it - and a `config.<name>.yaml` beside it as the stack `<name>` - and turri never writes it: the first setting
+ * turri writes copies them to the new names (`adoptLegacyConfig`), and from then on the old files are not read.
+ */
+export const LEGACY_CONFIG_FILE = "config.yaml";
+/** A stack's config file's name: `config.turri.backend.yaml` for the stack `backend`. */
+export function stackConfigFile(stack) {
+    return `config.turri.${stack}.yaml`;
+}
+function legacyStackConfigFile(stack) {
+    return `config.${stack}.yaml`;
+}
+function namesIn(root) {
+    try {
+        return readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+}
+/** The stacks in the old naming, `config.<stack>.yaml`. */
+function legacyStacks(root) {
+    return namesIn(root)
+        .map((name) => /^config\.(?!turri(?:\.|$))(.+)\.yaml$/.exec(name)?.[1])
+        .filter((name) => name !== undefined)
+        .sort();
+}
+/** Whether a folder's settings are still in the old files: a config.yaml or a config.<stack>.yaml, and no config.turri*.yaml. */
+export function usesLegacyConfig(root) {
+    const names = namesIn(root);
+    if (names.some((name) => /^config\.turri(?:\..+)?\.yaml$/.test(name)))
+        return false;
+    return names.includes(LEGACY_CONFIG_FILE) || legacyStacks(root).length > 0;
+}
+/** The file the project's settings are read from, by name: config.turri.yaml, or config.yaml while the folder has only the old files. */
+export function projectConfigFile(root) {
+    return usesLegacyConfig(root) ? LEGACY_CONFIG_FILE : CONFIG_FILE;
+}
+/** The file a stack's settings are read from, by name - the old name while the folder has only the old files. */
+export function stackConfigFileIn(root, stack) {
+    return usesLegacyConfig(root) ? legacyStackConfigFile(stack) : stackConfigFile(stack);
+}
+/** Whether a folder holds a project's settings: a config.turri.yaml, a stack's file, or the old files. */
+export function hasProjectConfig(root) {
+    return existsSync(join(root, CONFIG_FILE)) || stacksOf(root).length > 0 || usesLegacyConfig(root);
+}
+/** The stacks a project folder has files for, by name. */
+export function stacksOf(root) {
+    if (usesLegacyConfig(root))
+        return legacyStacks(root);
+    return namesIn(root)
+        .map((name) => /^config\.turri\.(.+)\.yaml$/.exec(name)?.[1])
+        .filter((name) => name !== undefined)
+        .sort();
+}
+/**
+ * Before turri first writes a setting in a folder whose settings are still in the old files: config.yaml copied to
+ * config.turri.yaml, and each config.<stack>.yaml to config.turri.<stack>.yaml, so nothing is lost when the old files
+ * stop being read. The old files are left as they are. Gives back the files written, by name.
+ */
+export function adoptLegacyConfig(root, options = {}) {
+    if (!usesLegacyConfig(root))
+        return [];
+    const copies = [
+        // `projectFile: false`: the stacks' files alone - turri init-config writes config.turri.yaml itself.
+        ...(options.projectFile !== false && existsSync(join(root, LEGACY_CONFIG_FILE)) ? [[LEGACY_CONFIG_FILE, CONFIG_FILE]] : []),
+        ...legacyStacks(root).map((stack) => [legacyStackConfigFile(stack), stackConfigFile(stack)]),
+    ];
+    for (const [from, to] of copies)
+        copyFileSync(join(root, from), join(root, to));
+    return copies.map(([, to]) => to);
+}
+/** The stack a pulse runs with: the one chosen as it started, whatever is chosen since. */
+const pinnedStack = new AsyncLocalStorage();
+/** The stack chosen now - `/stack`, `--stack`, `TURRI_STACK` - or, inside a pulse, the one it started with. */
+export function chosenStack() {
+    const pinned = pinnedStack.getStore();
+    if (pinned !== undefined)
+        return pinned.stack;
+    return text(process.env.TURRI_STACK);
+}
+/** Choose the stack everything is built with from now on - or none, the project's config alone. Kept in TURRI_STACK. */
+export function chooseStack(stack) {
+    if (stack === undefined || stack.trim() === "")
+        delete process.env.TURRI_STACK;
+    else
+        process.env.TURRI_STACK = stack.trim();
+}
+/** Run `work` with `stack` as the one chosen, whatever is chosen meanwhile: a pulse keeps the stack it started with. */
+export function withStack(stack, work) {
+    return pinnedStack.run({ stack }, work);
+}
+/** The stack a project folder is built with now: the one chosen, when the folder has a file for it. */
+export function stackOf(root) {
+    const stack = chosenStack();
+    return stack !== undefined && stacksOf(root).includes(stack) ? stack : undefined;
+}
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * The agents turri starts, by what they do - each can be given its own model, thinking and turn limit (`models:`).
+ * The code fixer of a conformance run and the repair agent are coding agents; the unit-test and conformance arbiters
+ * are both `arbiter`.
+ */
+export const AGENT_ROLES = ["chat", "chooser", "planner", "diagnosis", "release", "coding", "conformance", "explorer", "reviewer", "test-reviewer", "judge", "arbiter", "debugger"];
+/**
+ * How hard each role thinks when nothing names a level - not the config's `models:`, nor a `:level` on the model it is
+ * given. The agents that do the work - write the code and the tests, explore, release - think little: they work from a
+ * spec that leaves little to guess, and every turn of theirs is many. The ones that judge - review, weigh, plan, find a
+ * cause - think more: a wrong call there costs pulses. The conversation keeps its own level, pi's.
+ */
+export const ROLE_THINKING = {
+    coding: "low",
+    conformance: "low",
+    explorer: "low",
+    release: "low",
+    reviewer: "medium",
+    "test-reviewer": "medium",
+    judge: "medium",
+    arbiter: "medium",
+    debugger: "medium",
+    planner: "medium",
+    chooser: "medium",
+    diagnosis: "medium",
+};
+/** The roles on the conversation's side: without their own entry they take the chat's model, not `default`. */
+// The release is not: it follows steps - a script, a start command - and runs on the coding model, thinking low.
+const CHAT_SIDE = ["chat", "chooser", "planner", "diagnosis"];
+function isThinkingLevel(value) {
+    return typeof value === "string" && THINKING_LEVELS.includes(value);
+}
+/**
+ * A model choice as the one string every agent is given, in pi's own form: "provider/id", with
+ * ":level" when it names how hard to think - ":level" alone for the default model thinking so.
+ */
+export function modelSpec(choice) {
+    if (choice === undefined || (choice.model === undefined && choice.thinking === undefined))
+        return undefined;
+    return `${choice.model ?? ""}${choice.thinking !== undefined ? `:${choice.thinking}` : ""}`;
+}
+/** A model spec back into its model and thinking level - "provider/id:high", "provider/id", ":high". */
+export function splitModelSpec(spec) {
+    const given = spec?.trim() ?? "";
+    if (given === "")
+        return {};
+    const colon = given.lastIndexOf(":");
+    const level = colon === -1 ? undefined : given.slice(colon + 1);
+    if (colon !== -1 && isThinkingLevel(level)) {
+        const model = given.slice(0, colon);
+        return { ...(model !== "" ? { model } : {}), thinking: level };
+    }
+    return { model: given };
+}
+/**
+ * A model spec's model alone, its thinking left behind: what a judging role falls back on when it runs on the coding
+ * model - the model, not how hard the coding agent was told to think. Its role's level (ROLE_THINKING) applies instead.
+ */
+export function modelOnly(spec) {
+    const { model } = splitModelSpec(spec);
+    return model !== undefined ? { model } : {};
+}
+/** A choice with what it leaves out taken from the one it inherits from - or that one, when it is not given at all. */
+export function inheritModel(own, from) {
+    if (own === undefined)
+        return from;
+    const model = own.model ?? from?.model;
+    const thinking = own.thinking ?? from?.thinking;
+    return { ...(model !== undefined ? { model } : {}), ...(thinking !== undefined ? { thinking } : {}) };
+}
+/**
+ * The three models as they hold: the judge inherits from the coding model, the coding model from the harness model -
+ * `models:` over them: `chat` over harness-model, `coding` over coding-model, `judge` over judge-model, and `default`
+ * between the harness model and the rest.
+ */
+export function projectModels(config) {
+    const models = config.models ?? {};
+    const harness = inheritModel(choiceOf(models.chat), config.harnessModel);
+    const coding = inheritModel(choiceOf(models.coding), inheritModel(config.codingModel, inheritModel(choiceOf(models.default), harness)));
+    // The judge falls back on the coding model, not on how hard it thinks: a judging role thinks as ROLE_THINKING has it.
+    const codingModel = coding?.model !== undefined ? { model: coding.model } : undefined;
+    return { harness, coding, judge: inheritModel(choiceOf(models.judge), inheritModel(config.judgeModel, inheritModel(choiceOf(models.default), codingModel))) };
+}
+/** A role entry's model and thinking alone. */
+function choiceOf(entry) {
+    if (entry === undefined || (entry.model === undefined && entry.thinking === undefined))
+        return undefined;
+    return { ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.thinking !== undefined ? { thinking: entry.thinking } : {}) };
+}
+/**
+ * What the config itself says a role runs on - its own entry, the legacy key that names it (judge-model for the judge
+ * and the test review), then `default` (the chat's side: the chat's model instead) - or nothing when it says nothing
+ * of it, and the role runs on what it is given: the job's model, which the command line and the conversation choose.
+ * The coding role always runs on what it is given: its config is already in it (projectModels).
+ */
+export function roleModel(config, role) {
+    if (role === "coding")
+        return undefined;
+    const models = config.models ?? {};
+    const own = choiceOf(models[role]);
+    // The debugger looks at the coding agent's failure: without its own entry it runs on the model it is given - a stronger one.
+    if (role === "debugger")
+        return own;
+    if (CHAT_SIDE.includes(role))
+        return own === undefined ? undefined : inheritModel(own, inheritModel(choiceOf(models.chat), config.harnessModel));
+    const legacy = role === "judge" || role === "test-reviewer" ? config.judgeModel : undefined;
+    return inheritModel(own, inheritModel(legacy, choiceOf(models.default)));
+}
+/** How long each turn of a role's agents may take, in milliseconds: its own, `default`'s, `turn-limit:`'s - or undefined, the harness's default. */
+export function roleTurnLimitMs(config, role) {
+    const models = config.models ?? {};
+    const seconds = (role !== undefined ? models[role]?.turnLimit : undefined) ?? models.default?.turnLimit ?? config.turnLimit;
+    return seconds !== undefined ? seconds * 1000 : undefined;
+}
+/** A whole number of at least 1, as the config gives it - or nothing. */
+function positiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : undefined;
+}
+/** A model as the config gives it: a string, or `model:` and `thinking:`. */
+function modelChoice(value) {
+    if (typeof value === "string")
+        return text(value) !== undefined ? splitModelSpec(value) : undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const model = text(raw.model) ?? text(raw.name) ?? text(raw.ref);
+    const thinking = isThinkingLevel(raw.thinking) ? raw.thinking : undefined;
+    if (model === undefined && thinking === undefined)
+        return undefined;
+    return { ...(model !== undefined ? { model } : {}), ...(thinking !== undefined ? { thinking } : {}) };
+}
+/** A role's entry under `models:`: a model string, or `model:`, `thinking:` and `turn-limit:`. */
+function roleChoice(value) {
+    const choice = modelChoice(value);
+    const raw = value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const turnLimit = turnLimitSetting(raw["turn-limit"] ?? raw.turn_limit);
+    if (choice === undefined && turnLimit === undefined)
+        return undefined;
+    return { ...(choice ?? {}), ...(turnLimit !== undefined ? { turnLimit } : {}) };
+}
+/** A turn limit in seconds: a whole number, 0 for none. */
+function turnLimitSetting(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.round(value) : undefined;
+}
+/** `models:` - each role's entry, by its name; `default` for every role not named. */
+function modelsSetting(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const models = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const name = key.replace(/_/g, "-");
+        if (name !== "default" && !AGENT_ROLES.includes(name))
+            continue;
+        const choice = roleChoice(entry);
+        if (choice !== undefined)
+            models[name] = choice;
+    }
+    return Object.keys(models).length > 0 ? models : undefined;
+}
+/** The config keys, as written in the file. */
+export const CONFIG_KEYS = {
+    module: "module",
+    harnessModel: "harness-model",
+    codingModel: "coding-model",
+    judgeModel: "judge-model",
+    conformanceTests: "conformance-tests",
+    conformanceBudget: "conformance-budget",
+    review: "review",
+    allowToStopJobs: "allow-to-stop-jobs",
+    releaseAfterPulse: "release-after-pulse",
+    unittestsScript: "unittests-script",
+    conformanceTestsScript: "conformance-tests-script",
+    prepareEnvironmentScript: "prepare-environment-script",
+    testingScriptsRunOn: "testing-scripts-run-on",
+    parallelJobs: "parallel-jobs",
+    rulesOff: "rules-off",
+    compactAt: "compact-at",
+    maxSpecsPerPulse: "max-specs-per-pulse",
+    maxLinesPerPulse: "max-lines-per-pulse",
+    agentEnv: "agent-env",
+    toolchains: "toolchains",
+    models: "models",
+    turnLimit: "turn-limit",
+};
+function whatScriptsRunOn(value) {
+    return value === "copy" || value === "in-place" ? value : undefined;
+}
+/** `conformance-tests:` - true or all, chosen, module, false. Anything else is not read. */
+function conformanceSetting(value) {
+    if (typeof value === "boolean")
+        return value;
+    const word = typeof value === "string" ? value.trim().toLowerCase() : undefined;
+    return word === "all" ? true : word === "chosen" ? "chosen" : word === "module" ? "module" : word === "false" ? false : word === "true" ? true : undefined;
+}
+/** Whether `conformance-tests:` turns the conformance tests on: all (true), chosen or module. Not set, they are off, as with false. */
+export function conformanceSwitchedOn(setting) {
+    return setting === true || setting === "chosen" || setting === "module";
+}
+/** When the chooser decides which functional specs get conformance tests: after each code pulse, once the module is regenerated, or never - every one, or none. */
+export function choosingWhen(setting) {
+    return setting === "chosen" ? "pulse" : setting === "module" ? "module" : undefined;
+}
+/** `conformance-budget:` - a whole number, or a share such as `30%`. Anything else is not read. */
+function budgetSetting(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0)
+        return { count: value };
+    const share = typeof value === "string" ? /^\s*(\d+(?:\.\d+)?)\s*%\s*$/.exec(value) : null;
+    if (share !== null && Number(share[1]) <= 100)
+        return { share: Number(share[1]) / 100 };
+    return undefined;
+}
+/** How many functional specs a module of `count` may have chosen under a budget: the count, or the share rounded up - at least one. */
+export function budgetFor(budget, count) {
+    return "count" in budget ? budget.count : Math.max(1, Math.ceil(budget.share * count));
+}
+function text(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+/**
+ * The project's config - with a stack's over it, when one is named - or nothing of it when there is no file or it does
+ * not parse.
+ */
+export function readProjectConfig(root, stack) {
+    const project = readConfigFile(join(root, projectConfigFile(root)));
+    if (stack === undefined)
+        return project;
+    const own = readConfigFile(join(root, stackConfigFileIn(root, stack)));
+    // The project's alone: one conversation, one module built when none is named.
+    const merged = { ...project };
+    for (const key of Object.keys(CONFIG_KEYS)) {
+        if (key === "module" || key === "harnessModel" || key === "parallelJobs" || key === "rulesOff" || key === "compactAt" || key === "toolchains" || key === "agentEnv" || own[key] === undefined)
+            continue;
+        merged[key] = own[key];
+    }
+    merged.agentEnv = joinAgentEnv(project.agentEnv, own.agentEnv);
+    merged.toolchains = project.toolchains !== undefined && own.toolchains !== undefined ? [...new Set([...project.toolchains, ...own.toolchains])] : (own.toolchains ?? project.toolchains);
+    merged.codingModel = inheritModel(own.codingModel, project.codingModel);
+    merged.judgeModel = inheritModel(own.judgeModel, project.judgeModel);
+    merged.models = joinModels(project.models, own.models);
+    return withoutUndefined(merged);
+}
+/** A module's `models:` over the project's, role by role - each entry taking what it leaves out from the project's; the chat's the project's alone. */
+function joinModels(project, own) {
+    if (own === undefined)
+        return project;
+    const joined = { ...(project ?? {}) };
+    for (const [role, entry] of Object.entries(own)) {
+        if (role === "chat")
+            continue;
+        const base = project?.[role];
+        const choice = inheritModel(choiceOf(entry), choiceOf(base));
+        const turnLimit = entry.turnLimit ?? base?.turnLimit;
+        joined[role] = { ...(choice ?? {}), ...(turnLimit !== undefined ? { turnLimit } : {}) };
+    }
+    return joined;
+}
+/** A module's `agent-env:` added to the project's. */
+function joinAgentEnv(project, own) {
+    if (project === undefined || own === undefined)
+        return own ?? project;
+    return { files: [...new Set([...project.files, ...own.files])], vars: [...new Set([...project.vars, ...own.vars])] };
+}
+/** An `agent-env:` as the config gives it: dotenv files and variable names, or nothing when it names neither. */
+function agentEnvSetting(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const list = (items) => (Array.isArray(items) ? items : typeof items === "string" ? [items] : []).filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim());
+    const raw = value;
+    const setting = { files: list(raw.files), vars: list(raw.vars) };
+    return setting.files.length > 0 || setting.vars.length > 0 ? setting : undefined;
+}
+function withoutUndefined(config) {
+    return Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
+}
+/** The config a spec is built with: its project's, with the stack chosen over it. */
+export function configForSpec(plainFile) {
+    const root = projectDirOf(resolve(plainFile));
+    return readProjectConfig(root, stackOf(root));
+}
+/** One config file, read, or nothing of it when it is not there or does not parse. */
+function readConfigFile(path) {
+    let parsed;
+    try {
+        if (!statSync(path).isFile())
+            return {};
+        parsed = loadYaml(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const raw = Object.fromEntries(Object.entries(parsed).map(([key, value]) => [key.replace(/_/g, "-"), value]));
+    const conformance = raw[CONFIG_KEYS.conformanceTests];
+    return {
+        module: text(raw[CONFIG_KEYS.module]),
+        harnessModel: modelChoice(raw[CONFIG_KEYS.harnessModel]),
+        codingModel: modelChoice(raw[CONFIG_KEYS.codingModel]) ?? modelChoice(raw.model),
+        judgeModel: modelChoice(raw[CONFIG_KEYS.judgeModel]),
+        conformanceTests: conformanceSetting(conformance),
+        conformanceBudget: budgetSetting(raw[CONFIG_KEYS.conformanceBudget]),
+        review: typeof raw[CONFIG_KEYS.review] === "boolean" ? raw[CONFIG_KEYS.review] : undefined,
+        allowToStopJobs: typeof raw[CONFIG_KEYS.allowToStopJobs] === "boolean" ? raw[CONFIG_KEYS.allowToStopJobs] : undefined,
+        releaseAfterPulse: typeof raw[CONFIG_KEYS.releaseAfterPulse] === "boolean" ? raw[CONFIG_KEYS.releaseAfterPulse] : undefined,
+        unittestsScript: text(raw[CONFIG_KEYS.unittestsScript]),
+        conformanceTestsScript: text(raw[CONFIG_KEYS.conformanceTestsScript]),
+        prepareEnvironmentScript: text(raw[CONFIG_KEYS.prepareEnvironmentScript]),
+        testingScriptsRunOn: whatScriptsRunOn(raw[CONFIG_KEYS.testingScriptsRunOn]),
+        agentEnv: agentEnvSetting(raw[CONFIG_KEYS.agentEnv]),
+        toolchains: Array.isArray(raw[CONFIG_KEYS.toolchains])
+            ? raw[CONFIG_KEYS.toolchains].filter((path) => typeof path === "string" && path.trim() !== "").map((path) => path.trim())
+            : undefined,
+        rulesOff: Array.isArray(raw[CONFIG_KEYS.rulesOff]) ? raw[CONFIG_KEYS.rulesOff].filter((name) => typeof name === "string") : undefined,
+        compactAt: typeof raw[CONFIG_KEYS.compactAt] === "number" && Number.isInteger(raw[CONFIG_KEYS.compactAt]) && raw[CONFIG_KEYS.compactAt] >= 1000
+            ? raw[CONFIG_KEYS.compactAt]
+            : undefined,
+        parallelJobs: typeof raw[CONFIG_KEYS.parallelJobs] === "number" && Number.isInteger(raw[CONFIG_KEYS.parallelJobs]) && raw[CONFIG_KEYS.parallelJobs] >= 1
+            ? raw[CONFIG_KEYS.parallelJobs]
+            : undefined,
+        maxSpecsPerPulse: positiveInteger(raw[CONFIG_KEYS.maxSpecsPerPulse]),
+        maxLinesPerPulse: positiveInteger(raw[CONFIG_KEYS.maxLinesPerPulse]),
+        models: modelsSetting(raw[CONFIG_KEYS.models]),
+        turnLimit: turnLimitSetting(raw[CONFIG_KEYS.turnLimit]),
+    };
+}

package/dist/conform-cli.js

@@ -0,0 +1,29 @@
+import { parseArgs, runLoop } from "./loop-cli.js";
+const USAGE = `usage: turri conform <file.plain> [frid ...] [options]
+
+Writes and runs the black-box conformance tests of a module's functional specs - those named, or
+every one - on the code as it is built, as the chat's conform does, whatever the config's
+conformance-tests says: from the spec's test reqs and acceptance tests, with the whole suite the
+module inherits, a failure fixed in the test or the code, whichever is wrong. Every functional spec
+tested goes in one pulse, as far as the size guardrail lets.
+
+  --one-by-one             a pulse a functional spec instead
+  --model <provider/id>    model for the agents (default: config.turri.yaml's coding-model)`;
+const { positional, options } = parseArgs(process.argv.slice(2), ["--one-by-one"], USAGE);
+const [plainFile, ...frids] = positional;
+if (plainFile === undefined) {
+    console.error(USAGE);
+    process.exit(1);
+}
+runLoop({
+    plainFile,
+    ...(options.model !== undefined ? { model: options.model } : {}),
+    ask: (loop) => loop.conformance(plainFile, {
+        ...(frids.length > 0 ? { frids } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options["one-by-one"] !== undefined ? { separately: true } : {}),
+    }),
+}).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/cultivate-cli.js

@@ -0,0 +1,110 @@
+import { createInterface } from "node:readline/promises";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { describeGates, runSkill } from "./genome.js";
+import { runAsk } from "./ask.js";
+import { skillRunDir } from "./regenerate/paths.js";
+import { loadSkill } from "./skill.js";
+import { discoverSkills } from "./skills.js";
+import { PACKAGE_ROOT } from "./environment.js";
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+const reporter = {
+    step: (name, attempt) => console.log(`\n${c.bold(c.cyan(`> step ${name}`))} ${c.dim(`attempt ${attempt}`)}`),
+    artifact: (path, body) => {
+        console.log(c.dim(`  ${path}:`));
+        for (const line of body.split("\n"))
+            console.log(c.dim(`  | ${line}`));
+    },
+    gate: (name, judges) => console.log(judges === 0
+        ? `${c.bold(c.yellow(`> gate ${name}`))} ${c.dim("no artifact - failing without spending judges")}`
+        : `${c.bold(c.yellow(`> gate ${name}`))} ${c.dim(`${judges} independent judges`)}`),
+    livePass: (step, scope, findings) => console.log(findings === 0
+        ? c.dim(`  review ${step}: ${scope} - clean`)
+        : `  ${c.yellow(`review ${step}`)}: ${scope} ${c.dim(`- ${findings} to fix`)}`),
+    liveReview: (name, passes, findings) => console.log(findings === 0
+        ? `${c.bold(c.yellow(`> gate ${name}`))} ${c.dim(`reviewer read along in ${passes} passes, nothing outstanding`)}`
+        : `${c.bold(c.yellow(`> gate ${name}`))} ${c.dim(`${findings} unresolved from the reviewer - failing without spending judges`)}`),
+    judge: (index, model, verdict, violations) => {
+        const mark = verdict === "pass" ? c.green("pass") : c.red(verdict);
+        console.log(`  judge ${index + 1} ${c.dim(`(${model})`)}: ${mark}${violations ? c.dim(` (${violations})`) : ""}`);
+    },
+    outcome: (name, decision, critique) => {
+        const colour = {
+            advance: c.green,
+            retry: c.yellow,
+            escalate: c.yellow,
+            abort: c.red,
+        };
+        console.log(`  ${c.bold(colour[decision](decision))} ${c.dim(`<- gate ${name}`)}`);
+        if (critique)
+            for (const line of critique.split("\n"))
+                console.log(c.dim(`    ${line}`));
+    },
+};
+async function main() {
+    const args = process.argv.slice(2);
+    const modelIndex = args.indexOf("--model");
+    const model = modelIndex === -1 ? undefined : args[modelIndex + 1];
+    const skillArg = args.filter((arg, i) => !arg.startsWith("--") && i !== modelIndex + 1)[0];
+    if (!skillArg) {
+        console.error("usage: turri cultivate <skill name | path-to-skill-dir> [--model provider/id]");
+        process.exit(1);
+    }
+    const cwd = process.cwd();
+    // A folder with a SKILL.md, or a skill by name: turri's own or the project's (skills.ts).
+    const named = existsSync(join(skillArg, "SKILL.md")) ? undefined : discoverSkills(PACKAGE_ROOT, cwd).skills.find((found) => found.name === skillArg);
+    const skillDir = named?.dir ?? skillArg;
+    const skill = loadSkill(skillDir);
+    console.log(c.bold(`skill: ${skill.name}`));
+    for (const line of describeGates(skill))
+        console.log(`  ${c.dim(line)}`);
+    const result = await runSkill({
+        skillDir,
+        cwd,
+        runDir: skillRunDir(cwd, skill.name),
+        model,
+        report: reporter,
+        // The CLI has no dialogs, so options are numbered and either the number or the text
+        // is accepted - the point is still to pick rather than to type the answer out.
+        askUser: (request) => runAsk(request, {
+            // The terminal scrolls a long brief itself: it is printed whole, above the question.
+            select: async (title, options, context) => {
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                const list = options.map((option, i) => `  ${c.bold(String(i + 1))}. ${option}`).join("\n");
+                const reply = (await rl.question(`\n${context !== undefined ? `${context}\n\n` : ""}${c.bold(c.cyan("? "))}${title}\n${list}\n> `)).trim();
+                rl.close();
+                const index = Number.parseInt(reply, 10);
+                if (Number.isInteger(index) && index >= 1 && index <= options.length)
+                    return options[index - 1];
+                return reply === "" ? undefined : reply;
+            },
+            input: async (title, context) => {
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                const reply = (await rl.question(`\n${context !== undefined ? `${context}\n\n` : ""}${c.bold(c.cyan("? "))}${title}\n> `)).trim();
+                rl.close();
+                return reply === "" ? undefined : reply;
+            },
+        }),
+        escalate: async ({ question, critique }) => {
+            console.log(`\n${c.bold(c.yellow("! human review required"))}`);
+            console.log(c.dim(critique));
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+            rl.close();
+            return answer === "y";
+        },
+    });
+    console.log(`\n${result.ok ? c.green(c.bold("run complete")) : c.red(c.bold("run aborted at a gate"))} ${c.dim(`artifacts in ${relative(cwd, skillRunDir(cwd, skill.name))}`)}`);
+    process.exit(result.ok ? 0 : 1);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/drift-cli.js

@@ -0,0 +1,25 @@
+import { readProjectConfig, CONFIG_FILE } from "./config.js";
+import { createJobRegistry } from "./regenerate/jobs.js";
+import { createWorkLoop, describeDrift } from "./regenerate/loop.js";
+const USAGE = `usage: turri drift [file.plain]
+
+How far the module's code has drifted from its spec, in each codebase where it lives: what is left to
+regenerate, and the conformance tests left to write. Plans nothing, starts nothing, calls no model.`;
+const [given] = process.argv.slice(2).filter((arg) => !arg.startsWith("-"));
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const named = given ?? readProjectConfig(process.cwd()).module;
+if (named === undefined) {
+    console.error(`${USAGE}\n\nNo file given, and ${CONFIG_FILE} names no module.`);
+    process.exit(1);
+}
+try {
+    const loop = createWorkLoop({ registry: createJobRegistry(), cwd: process.cwd(), planner: false, dryRun: true });
+    console.log(describeDrift(loop.drift(named)));
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+}