@turri-dev/cli 0.1.4-next.fa9223b → 0.1.5-next.6df6879

package/dist/regenerate/spec-map-view.js

@@ -52,7 +52,7 @@ export function tabBar(pages, shown, width, style, now) {
         const text = `${mark}${tabName(page)}`;
         if (page === shown)
             return style.heading(`[${text}]`);
-        return regenerating ? style.accent(text) : page.stuck ? style.error(text) : style.muted(text);
+        return regenerating ? style.accent(text) : page.stuck ? needs(style)(text) : style.muted(text);
     };
     const tabs = pages.map(label);
     const at = Math.max(0, shown === undefined ? 0 : pages.indexOf(shown));
@@ -69,6 +69,8 @@ export function tabBar(pages, shown, width, style, now) {
     }
     return truncateToWidth(lineOf(from, to), width, "…");
 }
+/** What needs the person - a stuck page, its `!` - in the warning colour: it waits on them, nothing is broken. */
+const needs = (style) => style.warning ?? style.error;
 /** Strike text through. */
 const strike = (text) => `\x1b[9m${text}\x1b[29m`;
 /** How far a group, and what is in it, is indented under its module. */
@@ -121,7 +123,7 @@ function rungGlyph(rung, style, now) {
     if (rung === "conform")
         return green(LADDER.conform);
     if (rung === "needsYou")
-        return style.error(LADDER.needsYou);
+        return needs(style)(LADDER.needsYou);
     if (rung === "takenOut")
         return style.error(LADDER.takenOut);
     if (rung === "toRegenerate")
@@ -486,7 +488,7 @@ export function specMapLines(pages, state, width, style, _jobs = [], now = Date.
         // The first item that needs the person says what for, and how to go about it - opened or closed.
         if (page.stuck && !toldWhy && rungOf(item) === "needsYou") {
             toldWhy = true;
-            for (const line of wrapped(needsLine(page), width, style.error))
+            for (const line of wrapped(needsLine(page), width, needs(style)))
                 add(line, mark);
         }
         if (state.open.has(row.key)) {
@@ -515,7 +517,9 @@ function paintOf(mark, style) {
         return style.success ?? style.added;
     if (mark === "regenerating" || mark === "planning")
         return style.accent;
-    if (mark === "stuck" || mark === "removed")
+    if (mark === "stuck")
+        return needs(style);
+    if (mark === "removed")
         return style.error;
     return style.muted;
 }
@@ -548,7 +552,7 @@ export function specMapHeader(page, width, style, waiting = "") {
     const strip = progressStrip(page, style);
     const count = total > 0 ? `${built} of ${total} ${total === 1 ? "functionality" : "functionalities"} built · ` : "";
     // Short, never cut off: what for, and how, is under the first `!`.
-    const status = page.stuck ? style.error(`${LADDER.needsYou} needs you`) : page.status;
+    const status = page.stuck ? needs(style)(`${LADDER.needsYou} needs you`) : page.status;
     // The module's file heads its column, under this line.
     return truncateToWidth(`${style.heading("regen")}${strip !== "" ? `  ${strip}` : ""}  ${count}${status}${waiting}`, width);
 }

package/dist/regenerate/test-scripts.js

@@ -2,7 +2,7 @@ import { fixMethod } from "./prompt.js";
 import { randomUUID } from "node:crypto";
 import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
-import { CONFIG_FILE, CONFIG_KEYS, projectConfigFile, readProjectConfig, stackConfigFileIn, stackOf } from "../config.js";
+import { CONFIG_FILE, CONFIG_KEYS, projectConfigFile, readProjectConfig, stackConfigFile, stackConfigFileIn, stackOf, stacksOf } from "../config.js";
 import { reportActivity, reportLogNote, reportNote } from "./activity.js";
 import { ensureInModulesScratch, modulesScratchDir } from "./paths.js";
 import { defineTool } from "@earendil-works/pi-coding-agent";
@@ -85,8 +85,14 @@ export function findTestScripts(root, plainFile, buildDir) {
     const stack = stackOf(root);
     const config = readProjectConfig(root, stack);
     const file = stack !== undefined ? `${stackConfigFileIn(root, stack)} (over ${projectConfigFile(root)})` : projectConfigFile(root);
-    // Where a script is named: the stack's file, once one is chosen.
-    const nameIn = stack !== undefined ? stackConfigFileIn(root, stack) : `${CONFIG_FILE} - or, for a project of several stacks, the stack's config.turri.<stack>.yaml`;
+    // A project of stacks with none chosen: its scripts are named in the stacks' files.
+    const stacks = stack === undefined ? stacksOf(root) : [];
+    // Where a script is named: the stack's file, once one is chosen - in a project of stacks, the one of the stack that builds it.
+    const nameIn = stack !== undefined
+        ? stackConfigFileIn(root, stack)
+        : stacks.length > 0
+            ? "the config.turri.<stack>.yaml of the stack that builds it"
+            : `${CONFIG_FILE} - or, for a project of several stacks, the stack's config.turri.<stack>.yaml`;
     if (config.testingScriptsRunOn !== undefined)
         found.runOn = config.testingScriptsRunOn;
     for (const kind of Object.keys(SCRIPT_KEYS)) {
@@ -139,6 +145,22 @@ export function findTestScripts(root, plainFile, buildDir) {
             }
         }
     }
+    // A project of stacks, none chosen: the scripts are likely in a stack's file - the note says which, and how to choose it.
+    if (stacks.length > 0) {
+        for (const kind of Object.keys(SCRIPT_KEYS)) {
+            if (found[kind] !== undefined)
+                continue;
+            const named = stacks.flatMap((each) => {
+                const script = kind === "unit" ? readProjectConfig(root, each).unittestsScript : readProjectConfig(root, each).conformanceTestsScript;
+                return script !== undefined ? [`${stackConfigFile(each)} names ${script.trim()}`] : [];
+            });
+            notes[kind] = [
+                ...(notes[kind] !== undefined ? [notes[kind]] : []),
+                `No stack is chosen, so ${CONFIG_FILE} alone is read - this project's stacks are ${stacks.join(", ")}${named.length > 0 ? `, and ${named.join("; ")}` : ""}. ` +
+                    "Choose the stack that builds this module: stack on regenerate, or /stack, in the chat; --stack <name> on the command line.",
+            ].join(" ");
+        }
+    }
     if (Object.keys(notes).length > 0)
         found.notes = notes;
     return found;
@@ -297,6 +319,10 @@ export function setScriptTimeoutForTests(ms) {
  * own paths start - and whether they run on the code in place (the default), rather than on a fresh copy
  * (`testing-scripts-run-on: copy`).
  */
+/** Whether the testing scripts run on the code in `buildDir` itself, not on a copy of it. */
+export function scriptsRunInPlace(buildDir) {
+    return projectOfBuild(buildDir).inPlace;
+}
 function projectOfBuild(buildDir) {
     const parts = resolve(buildDir).split(sep);
     const index = parts.lastIndexOf("plain_modules");
@@ -401,30 +427,70 @@ const lastPassing = new Map();
 export function lastPassingMs(buildDir, script) {
     return lastPassing.get(`${resolve(buildDir)}\n${script}`);
 }
+/** Files changed in place for a run under way, and what each held: put back however the run ends - the process exiting too. */
+const changedInPlace = new Map();
+let restoreOnExit = false;
+function putBack(path) {
+    const original = changedInPlace.get(path);
+    if (original === undefined)
+        return;
+    writeFileSync(path, original);
+    changedInPlace.delete(path);
+}
 /**
- * A script that takes the code folder - the unit testing script - run where the testing scripts
- * run. `change`: what to do to the fresh copy before it runs - only where there is a copy; never in place.
+ * `run` with `change` made to the code itself, and undone once it ends - passed, failed, timed out, thrown, or the process
+ * exiting. Killed outright, the change is left: the next unit of work starts from the last commit (lineage.ts startWork).
+ */
+async function withChangeInPlace(buildDir, change, run) {
+    const path = resolve(buildDir, change.file);
+    if (changedInPlace.has(path))
+        throw new Error(`${change.file} is being changed for another run already.`);
+    if (!restoreOnExit) {
+        restoreOnExit = true;
+        process.once("exit", () => {
+            for (const changed of [...changedInPlace.keys()])
+                putBack(changed);
+        });
+    }
+    changedInPlace.set(path, readFileSync(path));
+    try {
+        writeFileSync(path, change.text);
+        return await run();
+    }
+    finally {
+        putBack(path);
+    }
+}
+/**
+ * A script that takes the code folder - the unit testing script - run where the testing scripts run. `change`: one file
+ * as it is for this run - made to the fresh copy, or, in place, to the code itself and undone once the run ends.
  */
 export async function runOnCode(buildDir, script, what, change, 
 /** A time limit of its own, in place of a test run's. */
 limitMs) {
     const project = projectOfBuild(buildDir);
+    const passed = (run, started) => {
+        if (change === undefined && run.exitCode === 0)
+            lastPassing.set(`${resolve(buildDir)}\n${script}`, Date.now() - started);
+        return run;
+    };
     if (project.inPlace) {
-        if (change !== undefined)
-            throw new Error("This runs only where the testing scripts run on a copy: here they run in place, on the code itself.");
-        return runScript(project.root, script, [resolve(buildDir)], buildDir);
+        const inPlace = () => runScript(project.root, script, [resolve(buildDir)], buildDir, limitMs !== undefined ? { limitMs } : {});
+        const started = Date.now();
+        if (change === undefined)
+            return passed(await inPlace(), started);
+        reportActivity(`  changing ${change.file} in place for the ${what} - put back once it has run`);
+        return withChangeInPlace(buildDir, change, inPlace);
     }
     const staging = stagingFor(buildDir);
     rmSync(staging.root, { recursive: true, force: true });
     ensureInModulesScratch(buildDir, staging.root);
     try {
         reportActivity(`  copying ${stageBuild(buildDir, staging.build)} files of the code for the ${what}`);
-        change?.(staging.build);
+        if (change !== undefined)
+            writeFileSync(join(staging.build, change.file), change.text);
         const started = Date.now();
-        const run = await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs);
-        if (change === undefined && run.exitCode === 0)
-            lastPassing.set(`${resolve(buildDir)}\n${script}`, Date.now() - started);
-        return run;
+        return passed(await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs), started);
     }
     finally {
         rmSync(staging.root, { recursive: true, force: true });

package/dist/regenerate/unit-review.js

@@ -96,7 +96,7 @@ export function unitReviewTask(options) {
                 "  assertion so loose any answer passes, an expected value computed the way the code computes it.",
                 ...(options.canItFail === true
                     ? [
-                        "- A test you doubt can fail, check: can_it_fail puts a bug in a copy of the code - a condition turned round, a",
+                        "- A test you doubt can fail, check: can_it_fail puts a bug in the code for one run - a condition turned round, a",
                         "  value changed - and runs the unit tests on it. A test that still passes cannot fail: raise it as bad, with the",
                         `  bug it missed. ${REVIEWER_CAN_IT_FAIL_RUNS} runs a session: spend them on the tests the work rests on.`,
                     ]

package/dist/regenerate-cli.js

@@ -19,10 +19,15 @@ its conformance tests too when they are on.
   --start-over             start over, without asking, a codebase regenerated without a module it now requires -
                            with no terminal to ask and without it, the run stops there
   --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
+  --from-scratch-chain     the same for every module of its requires chain, built again from the bottom - after
+                           modules were split or moved
   --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner and the conformance chooser
   --coding-model <p/id>    its coding-model, --model too: the agents that build; p/id:level for how hard a model thinks
   --judge-model <p/id>     its judge-model: the judge and the test review
   --review <true|false>    its review: whether the code and its tests are reviewed once they pass
+  --mutation-testing <true|false>
+                           its mutation-testing: whether the coding agent and the reviewer can put a bug in the code
+                           for one test run (can_it_fail), to see that a test catches it
   --conformance-tests <all|chosen|module|false>
                            its conformance-tests: which conformance tests are written and run
   --build-dir <dir>        as the run ends, however it ends, export the code there: the furthest-built codebase's
@@ -31,7 +36,7 @@ its conformance tests too when they are on.
                            as it starts, as each pulse ends and as it exits (docs/headless.md)
 
   PLAIN_TEMPLATE_DIRS      colon-separated template directories`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--dry-run", "--start-over", "--from-scratch"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
+const { positional, options } = parseArgs(process.argv.slice(2), ["--dry-run", "--start-over", "--from-scratch", "--from-scratch-chain"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review", "--mutation-testing"]);
 const { report, buildDir } = headlessOptions(options, true);
 const named = positional[0] ?? readProjectConfig(process.cwd()).module;
 // Functional specs named after the file: regenerated again though their spec did not change.
@@ -40,9 +45,10 @@ if (!named) {
     console.error(`${USAGE}\n\nNo file given, and ${CONFIG_FILE} names no module.`);
     process.exit(1);
 }
+const scratch = options["from-scratch-chain"] !== undefined ? "chain" : options["from-scratch"] !== undefined ? "module" : undefined;
 // A dry run starts nothing, and from scratch deletes before it plans: the two do not go together.
-if (options["from-scratch"] !== undefined && options["dry-run"] !== undefined) {
-    console.error("--from-scratch deletes the module's code before anything is planned: it cannot be a dry run.");
+if (scratch !== undefined && options["dry-run"] !== undefined) {
+    console.error(`--from-scratch${scratch === "chain" ? "-chain" : ""} deletes the code before anything is planned: it cannot be a dry run.`);
     process.exit(1);
 }
 runLoop({
@@ -54,8 +60,8 @@ runLoop({
     startOver: options["start-over"] !== undefined,
     ask: (loop) => again.length > 0
         ? loop.regenerateAgain(named, again)
-        : options["from-scratch"] !== undefined
-            ? loop.fromScratch(named)
+        : scratch !== undefined
+            ? loop.fromScratch(named, { chain: scratch === "chain" })
             : loop.bringUp(named),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);

package/dist/release-cli.js

@@ -4,6 +4,7 @@ import { configForSpec, modelSpec, projectModels, readProjectConfig } from "./co
 import { createDeployState } from "./release-tools.js";
 import { runReleaseAgent } from "./release-agent.js";
 import { listDeployed, runningDeployed, stopDeployed } from "./regenerate/release.js";
+import { c } from "./module-report.js";
 const USAGE = `usage: turri release [file.plain] [options]
 
 Releases the module on top of the spec's requires chain, which holds the code of the ones below, and
@@ -20,12 +21,6 @@ harness-model (the agent's model).
   --in-module <module>     the codebase to take, when modules built on this one branch
   --guidance <text>        how this project releases it: the scripts to run, in order
   --model <provider/id>    the agent's model (default: harness-model)`;
-const c = {
-    dim: (s) => `\x1b[2m${s}\x1b[0m`,
-    bold: (s) => `\x1b[1m${s}\x1b[0m`,
-    green: (s) => `\x1b[32m${s}\x1b[0m`,
-    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
-};
 const PROBLEMS = "If you are having problems, use chat mode to deploy: run turri and ask to try it.";
 function parseArgs(argv) {
     const positional = [];
@@ -76,7 +71,7 @@ function followLogs() {
                 closeSync(fd);
                 offsets.set(item.log, size);
                 for (const line of buffer.toString("utf8").split("\n").filter((l) => l !== ""))
-                    console.log(`${c.cyan(`[${item.name}]`)} ${line}`);
+                    console.log(`${c.accent(`[${item.name}]`)} ${line}`);
             }
             if (running.length === 0) {
                 clearInterval(timer);
@@ -119,7 +114,7 @@ async function main() {
     console.log(`\n\n${c.dim(PROBLEMS)}`);
     if (runningDeployed().length === 0)
         process.exit(0);
-    console.log(c.green(c.bold("\nRunning - Ctrl-C stops it.")) + c.dim(" Its output follows.\n"));
+    console.log(c.success(c.bold("\nRunning - Ctrl-C stops it.")) + c.dim(" Its output follows.\n"));
     await followLogs();
     process.exit(0);
 }

package/dist/review/live.js

@@ -79,7 +79,8 @@ export function createLiveReviewer(opts) {
             pending.push(finding);
             all.push(finding);
         }
-        if (violations.length === 0) {
+        // No verdict - its turn stopped before it gave one - clears nothing: the scope is looked at again next pass.
+        if (captured !== undefined && violations.length === 0) {
             cleared.push(scope);
         }
         else if (captured?.question) {

package/dist/run-report.js

@@ -22,6 +22,9 @@ const emptyTotals = () => ({
     llm_calls: 0,
     agent_turns: 0,
     compactions: 0,
+    provider_retries: 0,
+    provider_stalls: 0,
+    turns_stopped: 0,
     model_seconds: 0,
 });
 function addUsage(totals, usage) {
@@ -43,8 +46,14 @@ function addEvent(totals, event, tokens) {
     }
     else if (event.kind === "turn")
         totals.agent_turns += 1;
-    else
+    else if (event.kind === "compaction")
         totals.compactions += 1;
+    else if (event.kind === "provider_retry")
+        totals.provider_retries += 1;
+    else if (event.kind === "provider_stall")
+        totals.provider_stalls += 1;
+    else
+        totals.turns_stopped += 1;
 }
 function sumTotals(a, b) {
     const sum = emptyTotals();
@@ -193,6 +202,20 @@ export function startRunReport(options) {
             assumption: gap.assumption,
         }));
     });
+    /** Each request the provider failed and was waited out or stalled on, and each turn turri ended itself: why, and where. */
+    const turnIncidentsOf = () => events
+        .filter((event) => event.kind === "provider_retry" || event.kind === "provider_stall" || event.kind === "stopped")
+        .map((event) => ({
+        kind: event.kind,
+        pulse_id: event.job ?? null,
+        role: event.role ?? null,
+        model: event.model ?? null,
+        ...(event.kind === "stopped"
+            ? { reason: event.reason ?? null }
+            : event.kind === "provider_stall"
+                ? { silent_seconds: Math.round((event.waitMs ?? 0) / 1000) }
+                : { error: event.error ?? null, attempt: event.attempt ?? null, of: event.of ?? null, wait_seconds: Math.round((event.waitMs ?? 0) / 100) / 10 }),
+    }));
     const functionalitiesOf = (counts) => {
         if (counts === undefined)
             return null;
@@ -240,6 +263,7 @@ export function startRunReport(options) {
             build_dir: options.buildDir !== undefined ? resolve(options.buildDir) : null,
             conformance_tests: options.conformanceTests,
             review: options.review ?? null,
+            mutation_testing: options.mutationTesting ?? null,
             models: {
                 ...Object.fromEntries(Object.entries(options.models).map(([role, choice]) => [role, { model: choice.model ?? null, thinking: choice.thinking ?? null }])),
                 observed: Object.fromEntries([...new Set(events.map((event) => event.role ?? "unknown"))].sort().map((role) => [role, [...new Set(events.filter((event) => (event.role ?? "unknown") === role).map((event) => event.model ?? "unknown"))].sort()])),
@@ -258,6 +282,7 @@ export function startRunReport(options) {
             pulses: pulsesOf(jobs, now),
             functionalities: functionalitiesOf(attempt(sources.completion)),
             spec_gaps: specGapsOf(jobs),
+            turn_incidents: turnIncidentsOf(),
             ...(exitParts ?? {}),
             logs: {
                 jobs_dir: fromProject(join(projectRoot, ".turri", "jobs")),

package/dist/screen-padding.js

@@ -0,0 +1,72 @@
+import { HStack, Spacer, VStack } from "@earendil-works/pi-tui";
+/**
+ * Room around the whole of turri's screen: a row above and below, two columns either side - a cell is about twice as
+ * tall as it is wide.
+ *
+ * pi draws its screen one of two ways, and each is padded as it is drawn: full screen (pi's default), a layout - its
+ * root put in the middle of blank rows and columns; the regular screen, the lines its render gives - asked for in fewer
+ * columns, indented, with blank lines above and below. Overlays are laid over the whole terminal, so one that should
+ * keep to the padding is given it as its margin.
+ */
+export const SCREEN_PADDING = { top: 1, right: 2, bottom: 1, left: 2 };
+/** The columns inside the padding. */
+export function paddedColumns(columns) {
+    return Math.max(1, columns - SCREEN_PADDING.left - SCREEN_PADDING.right);
+}
+/** The rows inside the padding. */
+export function paddedRows(rows) {
+    return Math.max(1, rows - SCREEN_PADDING.top - SCREEN_PADDING.bottom);
+}
+/** Each padded layout root, to what it pads. */
+const content = new WeakMap();
+/** What a layout root pads - the root itself when it is not padded. */
+export function unpadded(root) {
+    return content.get(root) ?? root;
+}
+/** A blank column as wide as the padding on its side: the row gives it what it measures. */
+const blankColumns = (columns) => ({ render: () => [" ".repeat(columns)], invalidate() { } });
+function padded(root) {
+    const row = new HStack([
+        { component: blankColumns(SCREEN_PADDING.left), basis: SCREEN_PADDING.left },
+        { component: root, basis: 0, grow: 1 },
+        { component: blankColumns(SCREEN_PADDING.right), basis: SCREEN_PADDING.right },
+    ]);
+    const whole = new VStack([
+        { component: new Spacer(SCREEN_PADDING.top), basis: SCREEN_PADDING.top },
+        // As pi lays out its own transcript: the rows the padding leaves, whatever it measures.
+        { component: row, basis: 0, grow: 1, minSize: 1 },
+        { component: new Spacer(SCREEN_PADDING.bottom), basis: SCREEN_PADDING.bottom },
+    ]);
+    content.set(whole, root);
+    return whole;
+}
+/**
+ * pi's screen drawn inside the padding, from its next frame - and every layout root it is given after, so the chat
+ * narrowed beside the docked panel (`narrowChat`) is padded too. Once a screen: pi starts a new one when it changes how
+ * it draws, which is padded when it is passed in.
+ */
+export function padScreen(tui) {
+    const screen = tui;
+    if (screen.turriPadded === true)
+        return;
+    if (typeof screen.setLayoutRoot === "function") {
+        // Full screen before pi has given it its layout: padded at a later frame.
+        if (screen.layoutRoot === undefined)
+            return;
+        screen.turriPadded = true;
+        const set = screen.setLayoutRoot;
+        screen.setLayoutRoot = function (root) {
+            set.call(this, root === undefined ? undefined : padded(unpadded(root)));
+        };
+        screen.setLayoutRoot(screen.layoutRoot);
+        return;
+    }
+    screen.turriPadded = true;
+    // Read from the prototype: the screen's own render, not one laid over it.
+    const render = Object.getPrototypeOf(tui).render;
+    const left = " ".repeat(SCREEN_PADDING.left);
+    screen.render = function (width) {
+        const lines = render.call(this, paddedColumns(width)).map((line) => `${left}${line}`);
+        return [...new Array(SCREEN_PADDING.top).fill(""), ...lines, ...new Array(SCREEN_PADDING.bottom).fill("")];
+    };
+}

package/dist/stacks.js

@@ -7,9 +7,7 @@ import { readdirSync } from "node:fs";
 import { join } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { chooseStack, chosenStack, hasProjectConfig, stackConfigFile, stacksOf } from "./config.js";
-/** The words that choose no stack: the project's config alone. */
-const NONE = ["none", "off", "base", "-"];
+import { chooseStack, chosenStack, hasProjectConfig, NO_STACK, stackConfigFile, stacksOf } from "./config.js";
 /** The stacks of the projects here: the folder's own, and those of the projects one folder down (specs kept in plain/). */
 export function knownStacks(root) {
     const below = (() => {
@@ -29,7 +27,7 @@ export function knownStacks(root) {
 export function switchStack(root, name) {
     const stacks = knownStacks(root);
     const wanted = name?.trim() ?? "";
-    if (wanted === "" || NONE.includes(wanted.toLowerCase())) {
+    if (wanted === "" || NO_STACK.includes(wanted.toLowerCase())) {
         chooseStack(undefined);
         return "No stack chosen: everything is built with the project's config.turri.yaml alone, from now on.";
     }
@@ -79,7 +77,7 @@ export function registerStacks(pi, cwd) {
             "For the session; a pulse already running keeps the stack it started with. Without a name, says the stacks and the one chosen.",
         promptSnippet: "choose the stack - its testing scripts and settings - that everything is built with",
         promptGuidelines: [
-            "Switch the stack only when the user asks for it, or for work on a part of the project another stack builds - a backend's, a frontend's - and say which you chose.",
+            "Switch the stack only when the user asks for it, and say which you chose. To build a part of the project another stack builds - a backend's, a frontend's - pass that stack as stack to regenerate, conform or glimpse instead: it is pinned to that module's pulses, and the session's choice stays as it is.",
         ],
         parameters: Type.Object({
             name: Type.Optional(Type.String({ description: "The stack to choose, or none. Omitted: the stacks there are, and the one chosen" })),

package/dist/validate-cli.js

@@ -1,4 +1,5 @@
 import { checkPlainTargets, formatCheckResults } from "./plain/check.js";
+import { c } from "./module-report.js";
 const USAGE = `usage: turri validate <file.plain | directory> [options]
 
 Validates a ***plain specification statically: parses it, resolves its imports and
@@ -8,12 +9,6 @@ required modules, and reports every error without rendering anything.
   --json                 machine-readable output
 
   PLAIN_TEMPLATE_DIRS    colon-separated template directories`;
-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`,
-};
 const argv = process.argv.slice(2);
 const templateDirs = [];
 const positional = [];
@@ -43,10 +38,10 @@ if (json) {
 else {
     const output = formatCheckResults(results)
         .split("\n")
-        .map((line) => line.startsWith("PASS") ? c.green(line) : line.startsWith("FAIL") ? c.red(line) : c.dim(line))
+        .map((line) => line.startsWith("PASS") ? c.success(line) : line.startsWith("FAIL") ? c.error(line) : c.dim(line))
         .join("\n");
     console.log(output);
     const failed = results.filter((r) => !r.ok).length;
-    console.log(`\n${failed === 0 ? c.green(c.bold("all specs valid")) : c.red(c.bold(`${failed} of ${results.length} failed`))}`);
+    console.log(`\n${failed === 0 ? c.success(c.bold("all specs valid")) : c.error(c.bold(`${failed} of ${results.length} failed`))}`);
 }
 process.exit(results.every((r) => r.ok) ? 0 : 1);

package/docs/README.md

@@ -1,20 +1,13 @@
 # turri documentation
 
-turri implements regenerative software: the \*\*\*plain specs are the durable definition of
-what a system does, and the code is generated from them, validated against them, and regenerated
-as they change. The [project README](../README.md) says why, and how to install and start; these
-pages go into each part.
+turri implements regenerative software: the \*\*\*plain specs are the durable definition of what a system does, and the code is generated from them, validated against them, and regenerated as they change. The [project README](../README.md) says why, and how to install and start; these pages go into each part.
 
 ## Start here
 
-1. [Installation](installation.md) - get a machine ready: `turri doctor`, and what turri needs of
-   this machine.
-2. [Using turri](using.md) - the conversation, the skills and tools, background jobs and
-   their logs, choosing the model that renders, the command line.
-3. [Authoring \*\*\*plain](authoring-plain.md) - writing the specs: what a spec is made of, the
-   authoring rules, the skills that write and fix specs.
-4. [Rendering](regenerating.md) - turning the specs into code: what each build does, in which order,
-   and what has to pass before it moves on.
+1. [Installation](installation.md) - get a machine ready: `turri doctor`, and what turri needs of this machine.
+2. [Using turri](using.md) - the conversation, the skills and tools, background jobs and their logs, choosing the model that renders, the command line.
+3. [Authoring \*\*\*plain](authoring-plain.md) - writing the specs: what a spec is made of, the authoring rules, the skills that write and fix specs.
+4. [Rendering](regenerating.md) - turning the specs into code: what each build does, in which order, and what has to pass before it moves on.
 
 ## By question