@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/regression.js

@@ -0,0 +1,181 @@
+import { existsSync } from "node:fs";
+import { ask, BEGIN, createExecutor } from "../pi.js";
+import { getSpecificationsForFrid } from "../plain/spec.js";
+import { conformanceDirFor } from "./conformance.js";
+import { reportActivity, reportStage, unitOf } from "./activity.js";
+import { confinedTools } from "./confine.js";
+import { projectRootOf } from "./paths.js";
+import { buildRegressionFixPrompt, sectionModules } from "./prompt.js";
+import { abandonWork, markWork, recordHistory } from "./lineage.js";
+import { missingToolchainError } from "./environment-error.js";
+import { workspaceBlock } from "./workspace.js";
+import { CODER_COMPACTION } from "./compaction.js";
+import { NOTES_TURN, notesForSession, withNotes } from "./notes.js";
+import { createScriptTool, MissingTestScriptError, runConformanceScript, runUnitScript, staticChecksOnly, withTestingScripts } from "./test-scripts.js";
+import { createWebTools, WEB_TOOLS } from "./web.js";
+import { ATTEMPTS } from "./stop-report.js";
+import { keepingTestsUnchanged, listFiles } from "./testing.js";
+/**
+ * The regression gate: every conformance test of a codebase - its own and those it inherits - run together with
+ * the unit tests, and the code repaired by an agent that may not touch the tests until they all pass. A conformance
+ * job ends on it: tests that pass on their own are not done until the whole suite passes with them.
+ */
+/** On top of the file tools, which are fenced to the build directory by `confine.ts`. */
+const FIX_TOOLS = ["run_unit_tests", "run_conformance_tests", "update_notes"];
+const DEFAULT_MAX_REGRESSION_ROUNDS = ATTEMPTS.regression;
+/** The module's conformance tests, when there are any: the chain's, copied up, and its own. */
+function conformanceDirs(conformanceRoot, moduleName) {
+    const dir = conformanceDirFor(moduleName, conformanceRoot);
+    return existsSync(dir) && listFiles(dir).length > 0 ? [dir] : [];
+}
+/** Repair the implementation after the merged suite went red. */
+async function repairRegression(input) {
+    const [specifications] = getSpecificationsForFrid(input.tree, input.frids[input.frids.length - 1]);
+    const runs = [];
+    const fence = confinedTools({ workdir: input.buildDir, reportsEnvironment: true });
+    const notes = notesForSession(input.buildDir, `${input.step} regression repair`);
+    reportStage(`${unitOf(input.moduleName)}: starting the repair agent${input.model ? ` (${input.model})` : ""}`);
+    const session = await createExecutor({
+        cwd: input.buildDir,
+        customTools: [
+            notes.tool,
+            ...createWebTools(),
+            ...fence.tools,
+            createScriptTool({ kind: "unit", script: input.scripts.unit, run: () => runUnitScript(input.buildDir, input.scripts.unit), runs }),
+            createScriptTool({
+                kind: "conformance",
+                script: input.scripts.conformance,
+                run: () => runConformanceScript(input.buildDir, input.testsDirs, input.scripts),
+                runs: [],
+            }),
+        ],
+        tools: [...fence.names, ...FIX_TOOLS, ...WEB_TOOLS],
+        model: input.model,
+        label: `${input.step} repair agent`, role: "coding",
+        checkEnvironment: { run: () => runUnitScript(input.buildDir, input.scripts.unit), script: input.scripts.unit },
+        system: `${fence.note}\n\n${workspaceBlock({ dir: input.buildDir, hasMyDiff: FIX_TOOLS.includes("my_diff") })}`,
+        task: withNotes(withTestingScripts(buildRegressionFixPrompt({
+            moduleName: input.moduleName,
+            frids: input.frids,
+            specifications,
+            modules: sectionModules(input.tree, input.moduleName),
+            required: input.required,
+            failure: input.failure,
+        }), input.scripts, ["conformance", "unit"], projectRootOf(input.buildDir)), input.buildDir),
+        compaction: { instructions: CODER_COMPACTION },
+    });
+    try {
+        reportStage(`${unitOf(input.moduleName)}: turri is repairing the code so every functionality's conformance tests pass together`);
+        const { report, restored } = await keepingTestsUnchanged({
+            dirs: input.testsDirs,
+            label: input.moduleName,
+            start: () => ask(session, BEGIN, input.onDelta),
+            again: (prompt) => ask(session, prompt, input.onDelta),
+        });
+        if (restored.length > 0)
+            reportActivity(`  put back ${restored.length} conformance test file(s) the repair agent changed`);
+        reportStage(`${unitOf(input.moduleName)}: checking the working notes were left`);
+        await notes.ensureWritten((next) => ask(session, next, input.onDelta, NOTES_TURN));
+        return restored.length > 0
+            ? `${report}\n\n(The harness put back ${restored.length} conformance test file(s) this repair changed.)`
+            : report;
+    }
+    finally {
+        session.dispose();
+    }
+}
+/**
+ * Run every conformance test built so far, and repair the code until they all pass.
+ *
+ * This is the gate between one functionality and the next. A functionality that passed on
+ * its own is not finished until the ones before it still pass alongside it, and each
+ * repair changes the code - so the suite is run again after every one.
+ */
+export async function ensureRegressionPasses(input) {
+    const dirs = conformanceDirs(input.conformanceRoot, input.moduleName);
+    const runs = [];
+    const repairs = [];
+    let command = null;
+    if (dirs.length === 0) {
+        reportActivity(`  ${input.moduleName} has no conformance tests yet - nothing to keep passing`);
+        return { passed: true, runs, repairs, command };
+    }
+    if (input.scripts.conformanceOff === true) {
+        reportActivity(`  conformance is off: ${input.moduleName}'s conformance tests were not run`);
+        return { passed: true, runs, repairs, command, conformanceOff: true };
+    }
+    // There are tests: the project's conformance testing script runs them, or nothing does.
+    if (input.scripts.conformance === undefined)
+        throw new MissingTestScriptError(input.moduleName, "conformance");
+    const start = input.start ?? markWork([input.buildDir, ...dirs]);
+    const maxRounds = input.maxRounds ?? DEFAULT_MAX_REGRESSION_ROUNDS;
+    for (let round = 0; round <= maxRounds; round += 1) {
+        reportStage(round === 0
+            ? `${unitOf(input.moduleName)}: running the codebase's whole conformance suite - every functionality's tests together (${input.frids.join(", ")})`
+            : `${unitOf(input.moduleName)}: repair ${round} done - running the whole conformance suite again`);
+        const result = await runConformanceScript(input.buildDir, dirs, input.scripts);
+        // The script cannot find its toolchain: no repair would pass it - the pulse stops, and the person is told.
+        const lacking = result.exitCode !== 0 ? missingToolchainError(result, { moduleName: input.moduleName, script: input.scripts.conformance, kind: "conformance" }) : undefined;
+        if (lacking !== undefined) {
+            abandonWork(start, input.moduleName, "the conformance testing script could not run");
+            throw lacking;
+        }
+        command = result.command;
+        runs.push({ command, exitCode: result.exitCode, frids: input.frids });
+        // The suite passes and its static checks do not: the findings are in the tests, which no repair may touch - the
+        // conformance tests' own job fixes them.
+        if (staticChecksOnly(result)) {
+            reportStage(`${unitOf(input.moduleName)}: the whole conformance suite passes, and the tests' static checks do not - a repair of the code cannot fix them - stopping`);
+            abandonWork(start, input.moduleName, "the conformance tests' static checks do not pass");
+            return { passed: false, runs, repairs, command };
+        }
+        reportActivity(result.exitCode === 0 ? "  ✓ whole suite passing" : `  ✗ whole suite failing (exit ${result.exitCode})`);
+        input.onEvent?.({ type: "run", command, exitCode: result.exitCode, frids: input.frids });
+        // The whole suite passing is half of it: the unit tests have to pass with it.
+        let failure = result.output;
+        let passing = result.exitCode === 0;
+        if (passing && input.scripts.unit !== undefined) {
+            reportStage(`${unitOf(input.moduleName)}: the whole conformance suite passes - running the unit testing script too`);
+            const unit = await runUnitScript(input.buildDir, input.scripts.unit);
+            const lackingUnit = unit.exitCode !== 0 ? missingToolchainError(unit, { moduleName: input.moduleName, script: input.scripts.unit, kind: "unit" }) : undefined;
+            if (lackingUnit !== undefined) {
+                abandonWork(start, input.moduleName, "the unit testing script could not run");
+                throw lackingUnit;
+            }
+            runs.push({ command: unit.command, exitCode: unit.exitCode, frids: input.frids });
+            input.onEvent?.({ type: "run", command: unit.command, exitCode: unit.exitCode, frids: input.frids });
+            if (unit.exitCode !== 0) {
+                reportActivity(`  ✗ unit tests failing (exit ${unit.exitCode}) with the conformance suite passing`);
+                passing = false;
+                failure = `The conformance suite passes, but the code's unit tests do not - and both have to.\n\n${unit.output}`;
+            }
+        }
+        if (passing) {
+            reportStage(`${unitOf(input.moduleName)}: the whole conformance suite passes, and the unit tests with it${repairs.length > 0 ? ` after ${repairs.length} repair${repairs.length === 1 ? "" : "s"}` : ""}`);
+            if (repairs.length > 0) {
+                recordHistory(input.buildDir, `regression ${input.moduleName} (pass after ${repairs.length} repair(s))`);
+            }
+            return { passed: true, runs, repairs, command };
+        }
+        if (round === maxRounds)
+            break;
+        input.onEvent?.({ type: "repair", frids: input.frids });
+        reportStage(`${unitOf(input.moduleName)}: an earlier functionality broke - repairing (round ${round + 1} of ${maxRounds})`);
+        repairs.push(await repairRegression({
+            testsDirs: dirs,
+            buildDir: input.buildDir,
+            moduleName: input.moduleName,
+            frids: input.frids,
+            tree: input.tree,
+            required: input.required,
+            failure,
+            step: input.step ?? `${input.moduleName} ${input.frids.at(-1)}`,
+            scripts: input.scripts,
+            model: input.model,
+            onDelta: input.onDelta,
+        }));
+    }
+    reportStage(`${unitOf(input.moduleName)}: the whole conformance suite still fails after ${repairs.length} repair${repairs.length === 1 ? "" : "s"} - stopping`);
+    abandonWork(start, input.moduleName, `the whole conformance suite still fails after ${repairs.length} repair(s)`);
+    return { passed: false, runs, repairs, command };
+}

package/dist/regenerate/release.js

@@ -0,0 +1,262 @@
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from "node:fs";
+import { connect } from "node:net";
+import { dirname, join, relative } from "node:path";
+import { HISTORY_DIR } from "./lineage.js";
+import { NOTES_FILE } from "./notes.js";
+import { distDirFor, ensureInScratch, projectDirOf } from "./paths.js";
+import { findCodebaseTip } from "./requires.js";
+import { RECORD_FILE } from "./records.js";
+function git(moduleDir, args) {
+    return spawnSync("git", ["--git-dir", join(moduleDir, HISTORY_DIR), "--work-tree", moduleDir, ...args], { cwd: moduleDir, encoding: "utf8" });
+}
+/** The module's last commit, when it has one with code in it. */
+function committedCode(moduleDir) {
+    if (!existsSync(join(moduleDir, HISTORY_DIR)))
+        return undefined;
+    const commit = git(moduleDir, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+    if (commit.status !== 0)
+        return undefined;
+    // A commit with no code folder in it has nothing to run.
+    if (git(moduleDir, ["rev-parse", "--verify", "--quiet", "HEAD:code"]).status !== 0)
+        return undefined;
+    return commit.stdout.trim();
+}
+/**
+ * Which module to deploy for a spec: the tip of its codebase - code accumulates up a requires chain, so
+ * the top module holds everything below it. Before the tip has anything committed, the nearest module
+ * below it that has.
+ */
+export function deployTarget(plainFile, inModule) {
+    const { tip, chain } = findCodebaseTip(plainFile, { allowNoFunctionalities: true, ...(inModule !== undefined ? { inModule } : {}) });
+    const candidates = [tip, ...[...chain].reverse().filter((entry) => entry.moduleName !== tip.moduleName)];
+    for (const entry of candidates) {
+        const commit = committedCode(dirname(entry.buildDir));
+        if (commit !== undefined)
+            return { entry, commit, ...(entry.moduleName !== tip.moduleName ? { instead: tip.moduleName } : {}) };
+    }
+    throw new Error(`Nothing is built yet for ${tip.moduleName}${candidates.length > 1 ? " or the modules it requires" : ""}: there is no code to deploy. Render it first.`);
+}
+/**
+ * Export the module's code at its last commit into `dist/<module>`, replacing whatever was there - the
+ * harness's own files (what the code is built from, the agents' notes) left out.
+ */
+export function exportModule(plainFile, inModule) {
+    const { entry, commit, instead } = deployTarget(plainFile, inModule);
+    const moduleDir = dirname(entry.buildDir);
+    const dir = distDirFor(projectDirOf(entry.plainFile), entry.moduleName);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const exported = spawnSync("bash", ["-o", "pipefail", "-c", 'git --git-dir "$1" archive --format=tar "$2" | tar -x -f - -C "$3"', "export", join(moduleDir, HISTORY_DIR), `${commit}:code`, dir], { encoding: "utf8" });
+    if (exported.status !== 0)
+        throw new Error(`Could not export ${entry.moduleName}'s code at ${commit.slice(0, 8)}: ${(exported.stderr ?? "").trim()}`);
+    for (const file of [RECORD_FILE, NOTES_FILE])
+        rmSync(join(dir, file), { force: true });
+    const [short, subject, when] = git(moduleDir, ["log", "-1", "--format=%h%x1f%s%x1f%cr", commit]).stdout.trim().split("\x1f");
+    const unfinished = git(moduleDir, ["status", "--porcelain", "--untracked-files=all", "--", "code"]).stdout.trim() !== "";
+    return {
+        moduleName: entry.moduleName,
+        plainFile: entry.plainFile,
+        way: "dist",
+        dir,
+        buildDir: entry.buildDir,
+        commit: short ?? commit.slice(0, 8),
+        subject: subject ?? "",
+        when: when ?? "",
+        unfinished,
+        ...(instead !== undefined ? { instead } : {}),
+    };
+}
+/**
+ * The host codebase a guided release works in: the git repository the project is in - an embedded project's host -
+ * or else `fallback`, where turri runs.
+ */
+export function hostDirOf(plainFile, fallback) {
+    const top = spawnSync("git", ["-C", projectDirOf(plainFile), "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    return top.status === 0 && top.stdout.trim() !== "" ? top.stdout.trim() : fallback;
+}
+/** Where a path is, said from the current directory when it is below it. */
+export function shortPath(path) {
+    const fromHere = relative(process.cwd(), path);
+    return fromHere === "" || fromHere.startsWith("..") ? path : fromHere;
+}
+/** What was deployed, in a line or three. */
+export function describeDeployment(deployment) {
+    return [
+        `Deployed ${deployment.moduleName} to ${shortPath(deployment.dir)} - commit ${deployment.commit}, ${deployment.when}: ${deployment.subject}.`,
+        ...(deployment.hostDir !== undefined ? [`Its guidance takes it on from there, in ${shortPath(deployment.hostDir)}.`] : []),
+        ...(deployment.instead !== undefined ? [`${deployment.instead}, the module on top, has nothing built yet - this is ${deployment.moduleName}, the module below it.`] : []),
+        ...(deployment.unfinished
+            ? [
+                deployment.hostDir === undefined
+                    ? "A pulse is at work on the module right now: what it has written so far is not finished, and is left out."
+                    : `A pulse is at work on the module right now: what it has written so far is not finished, and is left out of ${shortPath(deployment.dir)} - but ${shortPath(deployment.buildDir)} holds it, so take the code from ${shortPath(deployment.dir)}, never from there.`,
+            ]
+            : []),
+    ].join("\n");
+}
+const processes = new Map();
+/** Everything deploy started, running or ended, oldest first. */
+export function listDeployed() {
+    return [...processes.values()].map((entry) => entry.info);
+}
+/** The ones still running. */
+export function runningDeployed(moduleName) {
+    return listDeployed().filter((info) => info.exited === undefined && (moduleName === undefined || info.moduleName === moduleName));
+}
+/** Where a project's deployed processes write their output: its scratch, not the code in dist. */
+export function deployLogDir(projectDir) {
+    const scratch = join(projectDir, ".turri");
+    return ensureInScratch(scratch, join(scratch, "deploy"));
+}
+/** The end of a log, for when something did not come up. */
+export function logTail(log, lines = 40, chars = 4000) {
+    try {
+        const text = readFileSync(log, "utf8").split("\n").slice(-lines).join("\n");
+        return text.length > chars ? text.slice(-chars) : text;
+    }
+    catch {
+        return "";
+    }
+}
+function signalGroup(pid, signal) {
+    try {
+        // Its own process group: the server and whatever it started.
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/** Stop one deployed process, or every one of a module, or every one: politely, then not. Returns the names stopped. */
+export async function stopDeployed(which = {}) {
+    const targets = [...processes.values()].filter(({ info }) => info.exited === undefined && (which.name === undefined || info.name === which.name) && (which.moduleName === undefined || info.moduleName === which.moduleName));
+    for (const { info } of targets)
+        signalGroup(info.pid, "SIGTERM");
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline && targets.some(({ info }) => info.exited === undefined))
+        await sleep(100);
+    for (const { info } of targets)
+        if (info.exited === undefined)
+            signalGroup(info.pid, "SIGKILL");
+    return targets.map(({ info }) => info.name);
+}
+/** Stop everything at once, without waiting: for when turri itself is going. */
+export function stopAllDeployedNow() {
+    for (const { info } of processes.values())
+        if (info.exited === undefined)
+            signalGroup(info.pid, "SIGTERM");
+}
+let exitHooked = false;
+function stopOnExit() {
+    if (exitHooked)
+        return;
+    exitHooked = true;
+    process.on("exit", stopAllDeployedNow);
+}
+function portOf(url) {
+    if (url.port !== "")
+        return Number(url.port);
+    return url.protocol === "https:" ? 443 : 80;
+}
+/** Whether something already answers on the port. */
+function portTaken(host, port) {
+    return new Promise((done) => {
+        const socket = connect({ host: host === "0.0.0.0" ? "127.0.0.1" : host.replace(/^\[|\]$/g, ""), port });
+        const finish = (taken) => {
+            socket.destroy();
+            done(taken);
+        };
+        socket.setTimeout(700, () => finish(false));
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+    });
+}
+/** What holds a port, as lsof says it - or nothing when it cannot say. */
+function holderOf(port) {
+    const found = spawnSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
+    return found.status === 0 ? found.stdout.trim().split("\n").slice(0, 4).join("\n") : "";
+}
+async function answers(url) {
+    try {
+        await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(2000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** How long a server is given to answer at its URL, and to stay up when it has none. */
+export const READY_TIMEOUT_MS = Number(process.env.TURRI_DEPLOY_READY_TIMEOUT ?? 60) * 1000;
+const ALIVE_AFTER_MS = 4000;
+/**
+ * Start something that keeps running - a server, a frontend's dev server - in `dir`, on this machine,
+ * in its own process group, its output to a log. One already running under the name is stopped first.
+ *
+ * With a URL, it is ready once something answers there - any answer - and not when it exits first or
+ * nothing answers in time. A port something else holds already is said, with what holds it, and
+ * nothing is started: an app moved to a port of the harness's choosing would not be the one the
+ * person was told about. With no URL, it only has to still be running a few seconds on.
+ */
+export async function startDeployed(input) {
+    await stopDeployed({ name: input.name });
+    let url;
+    if (input.url !== undefined) {
+        try {
+            url = new URL(input.url);
+        }
+        catch {
+            return { ok: false, text: `'${input.url}' is not a URL. Give the one it serves at, e.g. http://localhost:5173.` };
+        }
+        const port = portOf(url);
+        if (await portTaken(url.hostname, port)) {
+            const holder = holderOf(port);
+            return {
+                ok: false,
+                text: `Port ${port} is in use already - by something turri did not start - so ${input.name} was not started.${holder !== "" ? `\n${holder}` : ""}\nTell the person which port and what holds it; do not move the app to another port.`,
+            };
+        }
+    }
+    mkdirSync(input.logDir, { recursive: true });
+    const log = join(input.logDir, `${input.moduleName}-${input.name.replace(/[^\w.-]+/g, "-")}.log`);
+    const fd = openSync(log, "w");
+    const child = spawn("bash", ["-c", input.command], { cwd: input.dir, detached: true, stdio: ["ignore", fd, fd], env: process.env });
+    closeSync(fd);
+    if (child.pid === undefined)
+        return { ok: false, text: `${input.name} could not be started.` };
+    const info = { name: input.name, moduleName: input.moduleName, command: input.command, dir: input.dir, log, pid: child.pid, startedAt: Date.now(), ...(input.url !== undefined ? { url: input.url } : {}) };
+    child.on("exit", (code, signal) => {
+        info.exited = { code, signal };
+    });
+    child.on("error", () => {
+        info.exited ??= { code: null, signal: null };
+    });
+    processes.set(input.name, { info, child });
+    stopOnExit();
+    const failed = (why) => {
+        const tail = logTail(log);
+        return { ok: false, text: `${input.name} ${why}.${tail !== "" ? `\nThe end of its output (${shortPath(log)}):\n${tail}` : ""}`, process: info };
+    };
+    const ended = () => `exited${info.exited?.code !== null && info.exited?.code !== undefined ? ` with ${info.exited.code}` : ""} before it was ready`;
+    if (url === undefined) {
+        await sleep(ALIVE_AFTER_MS);
+        if (info.exited !== undefined)
+            return failed(ended());
+        return { ok: true, text: `${input.name} is running (pid ${info.pid}); its output is in ${shortPath(log)}.`, process: info };
+    }
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (info.exited !== undefined)
+            return failed(ended());
+        if (await answers(url.href))
+            return { ok: true, text: `${input.name} is up at ${url.href} (pid ${info.pid}); its output is in ${shortPath(log)}.`, process: info };
+        await sleep(1000);
+    }
+    return failed(`is running, but nothing answered at ${url.href} in ${Math.round(READY_TIMEOUT_MS / 1000)}s`);
+}