@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/confine.js

@@ -0,0 +1,310 @@
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { credentialRefusal, isCredentialFile } from "./credentials.js";
+import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from "@earendil-works/pi-coding-agent";
+import { NOTES_FILE } from "./notes.js";
+import { RECORD_FILE } from "./records.js";
+import { keptShellOutput, outputsDir, readOutputTool } from "./testing.js";
+import { reportLogNote } from "./activity.js";
+import { agentShell } from "./agent-shell.js";
+import { ENVIRONMENT_ERROR_TOOL } from "./environment-error.js";
+import { anotherPulseIn, COMMAND_TIMEOUT_MS, MAX_COMMAND_TIMEOUT_MS } from "./shell.js";
+export class ConfinementError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfinementError";
+    }
+}
+/** Resolve symlinks as far as the path exists, so a link cannot walk out of a root. */
+function canonical(path) {
+    let head = resolve(path);
+    const tail = [];
+    for (;;) {
+        if (existsSync(head))
+            return join(realpathSync(head), ...tail.reverse());
+        const parent = dirname(head);
+        if (parent === head)
+            return resolve(path);
+        tail.push(basename(head));
+        head = parent;
+    }
+}
+function within(path, root) {
+    const target = canonical(path);
+    const base = canonical(root);
+    return target === base || target.startsWith(base + sep);
+}
+export function insideAny(path, roots) {
+    return roots.some((root) => within(path, root));
+}
+/** What the tool was given, turned into the absolute path it will actually open. */
+function absolutize(raw, cwd) {
+    let path = raw.trim();
+    if (path.startsWith("@"))
+        path = path.slice(1);
+    if (path === "~" || path.startsWith(`~${sep}`))
+        path = join(homedir(), path.slice(1));
+    return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+}
+function refuse(path, roots, verb) {
+    throw new ConfinementError(`${path} is outside this agent's ${verb} directory. It may only ${verb} ` +
+        `${roots.join(" and ")}. Work inside those - nothing above them is yours to touch.`);
+}
+/** The working notes are written through update_notes, a line at a time - never as a file. */
+function refuseNotes(path) {
+    if (basename(path) !== NOTES_FILE)
+        return;
+    throw new ConfinementError(`${NOTES_FILE} is not written as a file. Call update_notes to add, change or remove its lines.`);
+}
+/**
+ * What is the harness's, not the agent's, to write: the project's testing scripts - the harness
+ * runs them, through run_unit_tests and run_conformance_tests - and the specs. A copy of either in
+ * the codebase is an agent running its own version of what the harness runs, or building from a
+ * spec it was never meant to hold.
+ */
+function refuseHarnessFiles(path) {
+    const name = basename(path);
+    if (isCredentialFile(path))
+        throw new ConfinementError(credentialRefusal(path));
+    if (path.split(sep).includes("test_scripts") || /^(run_unittests|run_unit_tests|run_conformance_tests|prepare_environment)[^/]*\.sh$/.test(name)) {
+        throw new ConfinementError(`${name} is a copy of the project's testing scripts, and those are not written here. They are not in your ` +
+            "workspace, and are never copied, recreated or run by you: call run_unit_tests and run_conformance_tests, " +
+            "which run them exactly as the harness does.");
+    }
+    if (name.endsWith(".plain")) {
+        throw new ConfinementError(`${name} is a ***plain spec, and specs are not written here. What you build from is in your prompt; the code is ` +
+            "what you write.");
+    }
+}
+/** The record of what the code is built from is the harness's: no agent reads it either - nothing in it is theirs to go by. */
+function refuseRecord(path) {
+    if (basename(path) !== RECORD_FILE)
+        return;
+    throw new ConfinementError(`${RECORD_FILE} is the harness's record of what the code is built from: no agent reads or writes it.`);
+}
+/** An output turri kept, named as the cut named it: not a file in the agent's folder, but read_output's to read. */
+function refuseKeptOutput(raw, path, cwd) {
+    const id = basename(raw);
+    if (id !== raw.trim() || existsSync(path) || !existsSync(join(outputsDir(cwd), id)))
+        return;
+    throw new ConfinementError(`${id} is an output turri kept, not a file in your folder: call read_output with that id.`);
+}
+function check(raw, cwd, roots, verb) {
+    if (raw === undefined)
+        return;
+    const path = absolutize(raw, cwd);
+    if (verb === "read")
+        refuseKeptOutput(raw, path, cwd);
+    if (!insideAny(path, roots))
+        refuse(path, roots, verb);
+    refuseRecord(path);
+    if (verb === "write") {
+        refuseNotes(path);
+        refuseHarnessFiles(path);
+    }
+}
+/** A glob is a path too: `../../*` escapes just as well as `..`. */
+function checkPattern(pattern) {
+    if (pattern === undefined)
+        return;
+    const parts = pattern.split("/");
+    if (isAbsolute(pattern) || pattern.startsWith("~") || parts.includes("..")) {
+        throw new ConfinementError(`'${pattern}' reaches outside this agent's directory. Patterns must stay relative to it.`);
+    }
+}
+/** Same tool, its listing without the record of what the code is built from: ls, grep and find do not show it. */
+function withoutRecord(def) {
+    return {
+        ...def,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            const result = await def.execute(toolCallId, params, signal, onUpdate, ctx);
+            const content = result.content.map((part) => part.type === "text" ? { ...part, text: part.text.split("\n").filter((line) => !line.includes(RECORD_FILE)).join("\n") } : part);
+            return { ...result, content };
+        },
+    };
+}
+/** Same tool, with the path arguments checked before it runs. */
+function guard(def, inspect) {
+    return {
+        ...def,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            inspect(params);
+            return def.execute(toolCallId, params, signal, onUpdate, ctx);
+        },
+    };
+}
+/**
+ * The same check again, one layer down, on the absolute path the tool resolved.
+ *
+ * The argument check reads the request; this reads what the tool decided the request meant.
+ * They agree in every ordinary case, and when they do not - a `~` spelt oddly, a filename
+ * normalised to another form on disk - this is the one that is true.
+ */
+function guardedOps(roots, verb) {
+    return (path) => {
+        if (!insideAny(path, roots))
+            refuse(path, roots, verb);
+        refuseRecord(path);
+        if (verb === "write") {
+            refuseNotes(path);
+            refuseHarnessFiles(path);
+        }
+    };
+}
+/**
+ * An agent's walls, in words, for its system prompt - from its fence itself, so it says exactly what is enforced, the
+ * same on every platform. An agent that does not know where its walls are spends its turns walking into them. Its own
+ * folders by absolute path and no other; matter-of-fact about what happens on a reach outside - refused, or put back -
+ * and no warning. `environmentTool`: the tool an agent reports a missing piece of the machine with, when it has one.
+ */
+export function sandboxNote(fence) {
+    const list = (dirs) => dirs.map((dir) => `\`${dir}\``).join(" and ");
+    const readOnly = fence.read.filter((dir) => !fence.write.includes(dir));
+    const isTests = (dir) => basename(dir) === "tests" || dir.split(sep).includes("tests");
+    const lines = ["<sandbox>"];
+    if (fence.write.length === 0) {
+        lines.push(`You read ${list(fence.read)}, and write nothing${fence.shell ? ": not with your file tools, not with your shell." : "."}`);
+    }
+    else if (readOnly.length === 0) {
+        lines.push(fence.write.length === 1
+            ? `You work in one folder: ${list(fence.write)}. Your file tools read and write it, and nothing else.`
+            : `You work in ${list(fence.write)}. Your file tools read and write them, and nothing else.`);
+    }
+    else {
+        const writesTests = fence.write.every(isTests);
+        const readsTests = readOnly.every(isTests);
+        const what = writesTests ? " - the code under test -" : readsTests ? " - the conformance tests the code must pass -" : "";
+        const why = writesTests ? ": you write tests, not code" : readsTests ? ": you fix the code, not the tests" : "";
+        lines.push(`You work in ${list(fence.write)}. Your file tools read and write it. They also read ${list(readOnly)}${what} but never write ` +
+            `${readOnly.length === 1 ? "it" : "them"}${why}.`);
+    }
+    if (fence.shell) {
+        const home = fence.write[0] ?? fence.read[0];
+        lines.push("", `Your shell runs on this machine, in ${home !== undefined ? `\`${home}\`` : "your folder"}, with this machine's toolchains. It also has a home ` +
+            "folder and a temporary folder of its own (`$HOME`, `$TMPDIR`), and the package caches your build tools already " +
+            "use. The network is open. Nothing else on the machine exists for you: not the specification files, not the " +
+            `project's other folders or modules, not the person's home.${readOnly.length > 0 && fence.write.length > 0 ? ` ${list(readOnly)} ${readOnly.length === 1 ? "is" : "are"} read only in your shell too.` : ""}`, "", "- Everything you need is in this prompt. Do not look outside your folder: no parent folders, no absolute paths", "  elsewhere. A command that names a path outside is refused before it runs. Anything a command changes outside is", "  put back, and you are told.");
+        const report = fence.environmentTool !== undefined
+            ? `report it as an environment error with ${fence.environmentTool}`
+            : "say so plainly - what is missing and what needs it - and end your turn";
+        lines.push(fence.write.length > 0
+            ? "- The project's dependencies are yours: declare them in the build manifest, and let the build tools fetch them."
+            : "- You install nothing.", `${fence.write.length > 0 ? "  Installing anything else is not" : "  Nor is installing anything on the machine yours"}: no toolchains, system packages, drivers, global packages or \`sudo\`. If the`, `  machine lacks something the code needs, ${report}, name what is missing, and go no further with what depends on it.`, "  The person decides.", "- Ports and processes: you may stop only what you started. If a port is taken by something else, use another port.", "  `ps` may show nothing but what you started: check a server you started with `kill -0 $!`, its log, or a request to it.", "- Temporary files go in `$TMPDIR`: `/tmp` is outside your walls.");
+    }
+    else {
+        lines.push("You have no shell. Nothing else exists for you; everything you need is in this prompt.");
+    }
+    lines.push("</sandbox>");
+    return lines.join("\n");
+}
+/** pi's bash tool over an agent's shell: each command checked, run behind its walls, audited. */
+export function hostBashOperations(shell) {
+    return {
+        exec: async (command, _cwd, { onData, signal, timeout }) => {
+            const result = await shell.run(command, {
+                onData,
+                ...(signal !== undefined ? { signal } : {}),
+                // The agent's own timeout, up to the longest allowed; the limit when it gave none.
+                timeoutMs: timeout && timeout > 0 ? Math.min(timeout * 1000, MAX_COMMAND_TIMEOUT_MS) : COMMAND_TIMEOUT_MS,
+            });
+            return { exitCode: result.exitCode };
+        },
+    };
+}
+export function confinedTools(c) {
+    const workdir = resolve(c.workdir);
+    // An agent's file tools reach its own folder and what its role is given beside it, and nothing else.
+    const read = (c.read ?? [workdir]).map((dir) => resolve(dir));
+    const write = (c.write ?? [workdir]).map((dir) => resolve(dir));
+    const readOps = guardedOps(read, "read");
+    const writeOps = guardedOps(write, "write");
+    const tools = [
+        guard(createReadToolDefinition(workdir, {
+            operations: {
+                readFile: async (path) => (readOps(path), readFileSync(path)),
+                access: async (path) => readOps(path),
+            },
+        }), (p) => check(p.path, workdir, read, "read")),
+        guard(createWriteToolDefinition(workdir, {
+            operations: {
+                writeFile: async (path, content) => (writeOps(path), writeFileSync(path, content)),
+                mkdir: async (dir) => {
+                    writeOps(dir);
+                    const { mkdirSync } = await import("node:fs");
+                    mkdirSync(dir, { recursive: true });
+                },
+            },
+        }), (p) => check(p.path, workdir, write, "write")),
+        guard(createEditToolDefinition(workdir, {
+            operations: {
+                readFile: async (path) => (writeOps(path), readFileSync(path)),
+                writeFile: async (path, content) => (writeOps(path), writeFileSync(path, content)),
+                access: async (path) => writeOps(path),
+            },
+        }), (p) => check(p.path, workdir, write, "write")),
+        withoutRecord(guard(createLsToolDefinition(workdir), (p) => check(p.path, workdir, read, "read"))),
+        withoutRecord(guard(createGrepToolDefinition(workdir), (p) => {
+            check(p.path, workdir, read, "read");
+            checkPattern(p.glob);
+        })),
+        withoutRecord(guard(createFindToolDefinition(workdir), (p) => {
+            check(p.path, workdir, read, "read");
+            checkPattern(p.pattern);
+        })),
+    ];
+    // Nothing to write to: no tool that writes.
+    if (write.length === 0) {
+        for (const name of ["write", "edit"])
+            tools.splice(tools.findIndex((tool) => tool.name === name), 1);
+    }
+    let description = `file tools fenced to ${read.join(", ")}${write.length === 0 ? ", read only" : ""}`;
+    // The shell runs on this machine behind every wall at once: the check, the module's environment, the OS sandbox
+    // where one is up, the audit - its role's fence the same as its file tools'.
+    if (c.noBash === true) {
+        description += ", no bash";
+    }
+    else {
+        const shell = agentShell({ workdir, read, write }, { busy: anotherPulseIn });
+        const bash = createBashToolDefinition(workdir, { operations: hostBashOperations(shell), exposeSessionEnvironment: false });
+        bash.description = `${bash.description}\n\n${hostEnvironmentNote()}\n\n${timeLimitNote()}`;
+        tools.push(withKeptOutput(bash, workdir));
+        description += `, bash - ${shell.description}`;
+        // Which walls are up, in the job's log.
+        reportLogNote(`  ${shell.description}`);
+        // A cut output - a command's, a test run's - is read whole through read_output, never by a path.
+        tools.push(readOutputTool(workdir));
+    }
+    // An agent that writes and runs code is given report_environment_error (pi.ts), and its walls name it.
+    return {
+        tools,
+        names: tools.map((t) => t.name),
+        description,
+        note: sandboxNote({ read, write, shell: c.noBash !== true, ...(c.noBash !== true && c.reportsEnvironment === true ? { environmentTool: ENVIRONMENT_ERROR_TOOL } : {}) }),
+    };
+}
+/** What the agent is told, with its bash, about where its commands run. */
+function hostEnvironmentNote() {
+    return ("Commands run on this machine, from your folder, with this machine's toolchains, your own $HOME and $TMPDIR, and " +
+        "the open network. A command that names a path outside your folders is refused before it runs; what one changes " +
+        "outside them is put back, and you are told. You install nothing on the machine: the project's dependencies go " +
+        "into the project, through its manifest.");
+}
+/** The shell, its cut output kept where read_output reads it rather than in a temporary file on the host. */
+function withKeptOutput(bash, workdir) {
+    return {
+        ...bash,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            const result = await bash.execute(toolCallId, params, signal, onUpdate, ctx);
+            const content = result.content.map((part) => (part.type === "text" ? { ...part, text: keptShellOutput(workdir, part.text) } : part));
+            return { ...result, content };
+        },
+    };
+}
+/** What the agent is told about how long its commands may run. */
+function timeLimitNote() {
+    return (`A command is stopped after ${Math.round(COMMAND_TIMEOUT_MS / 1000)} seconds unless you give it a timeout, and ` +
+        `after ${Math.round(MAX_COMMAND_TIMEOUT_MS / 1000)} at most. Never run one that does not end on its own in the ` +
+        "foreground: start a server or a watcher in the background (`cmd > app.log 2>&1 &`), and give a command that " +
+        "asks for input its input (`--yes`, `-B`, `CI=1`, `< /dev/null`).");
+}

package/dist/regenerate/conform.js

@@ -0,0 +1,133 @@
+import { relative, resolve } from "node:path";
+import { digestFiles } from "./codebase.js";
+import { getFrids, getInheritedFunctionalSpecs, TEST_REQUIREMENTS } from "../plain/spec.js";
+import { reportLogNote, reportStage, unitOf } from "./activity.js";
+import { conformanceDirFor, notLandedWhy, renderConformanceTests } from "./conformance.js";
+import { abandonWork, startWork } from "./lineage.js";
+import { ensureRegressionPasses } from "./regression.js";
+import { modulesRoot, projectDirOf } from "./paths.js";
+import { applySpecDiff, snapshotSpec, specGapsText } from "./regenerate.js";
+import { linesAddedSince, readNotes } from "./notes.js";
+import { sectionsOf } from "./state.js";
+import { describeStop } from "./stop-report.js";
+import { missingTestLabels } from "./test-kinds.js";
+import { findTestScripts, projectRootFor, requireTestScripts } from "./test-scripts.js";
+export async function renderSpecDiffConformance(options) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const templateDirs = options.templateDirs ?? [];
+    const applied = options.applied ?? applySpecDiff(options.diff, cwd);
+    const spec = options.spec ?? snapshotSpec(options.plainFile, { cwd, templateDirs, inModule: options.inModule });
+    const { moduleName, tree, chain } = spec;
+    const tip = chain.at(-1);
+    const stage = (label) => reportStage(`${unitOf(moduleName)}: ${label}`);
+    stage(`the spec diff is ${applied === "applied" ? "applied to the .plain files" : "already in the .plain files"} - ` +
+        `bringing the conformance tests in ${moduleName}'s codebase in line with it`);
+    // The change is tested whatever it touches - with or without a functional spec yet.
+    const frids = [...getFrids(tree)];
+    const lastFrid = frids.at(-1);
+    if ((sectionsOf(tree)[TEST_REQUIREMENTS] ?? []).length === 0) {
+        throw new Error(`${moduleName} has no ${TEST_REQUIREMENTS}, so conformance tests cannot be written: they say how conformance tests ` +
+            "are written and run. Add them first - a change to them is a spec diff like any other.");
+    }
+    stage("finding the project's testing scripts");
+    const root = projectRootFor(tip.plainFile, tip.buildDir);
+    const scripts = findTestScripts(root, tip.plainFile, tip.buildDir);
+    requireTestScripts(moduleName, scripts, { conformance: true });
+    reportLogNote(`  conformance testing script: ${relative(root, scripts.conformance)}`);
+    const buildDir = tip.buildDir;
+    const conformanceRoot = modulesRoot(projectDirOf(tip.plainFile));
+    const conformanceDir = conformanceDirFor(moduleName, conformanceRoot);
+    // From the codebase's last commit, the tests' too: the change is made to the last known good
+    // state, not to what an interrupted run left half-written. The tests and the whole suite are
+    // one unit, landed whole or undone whole.
+    const unit = startWork([buildDir, conformanceDir], moduleName);
+    // The notes as its agents find them: a spec gap they add is told with the result.
+    const notesBefore = { code: readNotes(buildDir), tests: readNotes(conformanceDir) };
+    const conformance = await renderConformanceTests({
+        plainFile: tip.plainFile,
+        frid: lastFrid,
+        templateDirs,
+        buildDir,
+        conformanceDir,
+        diff: options.diff,
+        ...(options.change !== undefined ? { change: options.change } : {}),
+        ...(options.cases !== undefined ? { cases: options.cases } : {}),
+        spec: { moduleName, tree },
+        model: options.model,
+        onDelta: options.onDelta,
+    });
+    // What the codebase now has conformance tests for, as their labels say.
+    const tested = () => frids.filter((frid) => missingTestLabels(conformanceDir, frid, []).length === 0);
+    // Read before a rollback takes the notes back: a gap is the person's to decide, whether the tests passed or not.
+    const base = { moduleName, buildDir, conformanceDir, diff: applied, conformance, specGaps: [...linesAddedSince(notesBefore.code, buildDir, "gaps"), ...linesAddedSince(notesBefore.tests, conformanceDir, "gaps")] };
+    if (!conformance.passed) {
+        abandonWork(unit, moduleName, notLandedWhy("for the spec change", conformance.unlabelled));
+        return { ...base, tested: tested(), passed: false, stoppedAt: "conformance" };
+    }
+    // The run that passed was of the whole suite - the module's tests folder holds the chain's, copied up - and the unit
+    // tests with it: on code and tests still as they were then, a second run would only say it again.
+    if (conformance.green !== undefined && sameFiles(conformance.green.code, digestFiles(buildDir)) && sameFiles(conformance.green.tests, digestFiles(conformanceDir))) {
+        stage("the whole conformance suite and the unit tests passed on the code and the tests as they are - not run again");
+        const regression = { passed: true, runs: [], repairs: [], command: scripts.conformance };
+        return { ...base, tested: tested(), regression, passed: true, stoppedAt: null };
+    }
+    stage("conformance tests pass - running the codebase's whole conformance suite");
+    const regression = await ensureRegressionPasses({
+        start: unit,
+        step: `${moduleName} spec change conformance`,
+        buildDir,
+        conformanceRoot,
+        moduleName,
+        frids,
+        tree,
+        required: getInheritedFunctionalSpecs(tree),
+        scripts,
+        model: options.model,
+        onDelta: options.onDelta,
+    });
+    return { ...base, tested: tested(), regression, passed: regression.passed, stoppedAt: regression.passed ? null : "regression" };
+}
+/** Whether two digests of a folder hold the same files, each with the same content. */
+function sameFiles(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [file, digest] of a)
+        if (b.get(file) !== digest)
+            return false;
+    return true;
+}
+/** What the conformance for a spec change did, for the agent and the person. */
+export function describeSpecDiffConformance(result) {
+    const repairs = result.regression?.repairs.length ?? 0;
+    return [
+        result.passed
+            ? `The conformance tests in ${result.moduleName}'s codebase (${result.conformanceDir}) are in line with the spec change, and the whole suite passes.`
+            : describeStop({
+                moduleName: result.moduleName,
+                at: result.stoppedAt,
+                runs: [],
+                attempts: 0,
+                conformance: result.conformance,
+                repairs: result.regression?.repairs.length,
+            }),
+        result.diff === "applied" ? "The diff was applied to the .plain files." : "The diff was already applied.",
+        result.tested.length > 0
+            ? `Functionalities with conformance tests: ${result.tested.join(", ")}.`
+            : "No functionality has labelled conformance tests yet.",
+        result.conformance.codeChanged ? "The code was changed where a test showed it did not do what the spec says." : "",
+        result.conformance.reviewWaived !== undefined
+            ? `The tests were optimised as far as the review could take them; its last suggestions are in the notes: ${result.conformance.reviewWaived.map((problem) => problem.what.trim()).join(" ").slice(0, 400)}`
+            : "",
+        repairs > 0 ? `${repairs} regression repair(s) changed the code.` : "",
+        result.conformance.testRemovals.length > 0
+            ? `Conformance tests removed and justified: ${result.conformance.testRemovals.map((r) => r.file).join(", ")}.`
+            : "",
+        ...specGapsText(result.specGaps),
+        "",
+        "<agent report>",
+        result.conformance.response,
+        "</agent report>",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}