@turri-dev/cli 0.1.28-next.d5f2680 → 0.2.1-next.47b578c

package/dist/regenerate/command-check.js

@@ -128,6 +128,77 @@ function installIn(segment) {
         return "it runs an installer";
     return undefined;
 }
+/** The files a shell reads as it starts, and the system's own configuration: what changes the person's environment. */
+const PROFILE_FILE = /(^|[\/])\.(bashrc|bash_profile|bash_login|profile|zshrc|zprofile|zshenv|zlogin|kshrc|cshrc|tcshrc)$|(^|[\/])\.config[\/]fish[\/]|^\/etc\//;
+/** Why one simple command changes a setting of the machine's, or nothing when it does not. */
+function systemSettingIn(segment) {
+    const found = programOf(segment);
+    if (found === undefined)
+        return undefined;
+    const { program, args } = found;
+    const has = (...wanted) => wanted.some((word) => args.includes(word));
+    if (program === "defaults" && has("write", "delete", "import", "rename"))
+        return "defaults writes the machine's settings";
+    if (program === "launchctl" && args.some((arg) => !["list", "print", "print-disabled", "blame", "help", "version"].includes(arg) && !arg.startsWith("-")))
+        return "launchctl changes the machine's services";
+    if (program === "systemctl" && args.some((arg) => ["enable", "disable", "start", "stop", "restart", "reload", "mask", "unmask", "set-default", "set-property", "edit", "daemon-reload"].includes(arg)))
+        return "systemctl changes the machine's services";
+    if (program === "sysctl" && (has("-w") || args.some((arg) => /^[\w.]+=/.test(arg))))
+        return "sysctl changes the kernel's settings";
+    if (["scutil", "networksetup", "pmset", "nvram", "csrutil", "spctl", "systemsetup", "update-alternatives", "chsh", "dscl", "visudo", "usermod", "useradd", "passwd", "timedatectl", "hostnamectl"].includes(program) && args.length > 0) {
+        const reads = ["--get", "-get", "-getcomputername", "status", "-g", "--list", "--display", "--query", "show", "-read", "-list"];
+        if (!args.some((arg) => reads.includes(arg) || arg.startsWith("-get")))
+            return `${program} changes the machine's settings`;
+    }
+    if (program === "xcode-select" && has("--switch", "-s", "--reset", "-r", "--install"))
+        return "xcode-select changes the machine's developer tools";
+    if (program === "git" && has("config") && has("--global", "--system"))
+        return "git config --global changes the person's git settings";
+    if ((program === "npm" || program === "pnpm" || program === "yarn") && has("config") && has("set", "delete", "edit"))
+        return `${program} config changes the person's ${program} settings`;
+    if ((program === "pip" || program === "pip3") && has("config") && has("set", "unset", "edit"))
+        return "pip config changes the person's pip settings";
+    if (program === "mise" && has("settings", "trust"))
+        return "mise changes the person's mise settings";
+    return undefined;
+}
+/**
+ * Why a command line changes the machine - installs software outside the project, or changes a setting of the
+ * machine's or the person's environment - or nothing when it does not. The project's own dependencies, installed into
+ * the project (npm install, a venv, mvn, cargo), change nothing of the machine's. turri changes the machine nowhere: not
+ * an agent, not the chat, not a release - what the machine lacks is the person's to install, in their own words.
+ */
+export function machineChange(command) {
+    if (PIPED_DOWNLOAD.test(command) || RUN_DOWNLOAD.test(command))
+        return "it runs a script downloaded from the web";
+    for (const segment of segments(command)) {
+        const why = installIn(segment) ?? systemSettingIn(segment);
+        if (why !== undefined)
+            return why;
+    }
+    for (const part of command.split(/&&|\|\||[;\n]/)) {
+        const profile = writeTargets(part).find((target) => PROFILE_FILE.test(target.replace(/^~|^\$HOME|^\$\{HOME\}/, "")));
+        if (profile !== undefined)
+            return `it writes ${profile}, which sets the person's environment`;
+    }
+    return undefined;
+}
+/** The .plain file a command line writes - a ***plain module or a test plain file - or nothing when it writes none. */
+export function writesPlain(command) {
+    for (const part of command.split(/&&|\|\||[;\n]/)) {
+        const found = writeTargets(part).find((target) => target.replace(/["']/g, "").endsWith(".plain"));
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** What turri says when a command would change the machine: what it does instead. */
+export function machineChangeReason(why) {
+    return (`turri changes nothing of this machine's - ${why}. Nothing is installed by turri, and no setting of the machine's or the ` +
+        "person's environment is changed: that is theirs to do. Find out what is there instead - off the PATH, another name for " +
+        "the same tool (python for python3), a version manager's folder - and use it, or give the person the exact command to " +
+        "run themselves, and go on once they say it is done.");
+}
 /** Downloads run as programs: a script piped to a shell, or run from a download. */
 const PIPED_DOWNLOAD = /\b(curl|wget)\b[^|;&\n]*\|\s*(sudo\s+(-\S+\s+)*)?((ba|z|da|k)?sh|python\d*|perl|ruby|node)\b/;
 const RUN_DOWNLOAD = /\b(ba|z|da|k)?sh\s+(-\w+\s+)*["']?\$\(\s*(curl|wget)\b|<\(\s*(curl|wget)\b/;
@@ -267,6 +338,9 @@ export function checkCommand(command, fence) {
         const why = installIn(segment);
         if (why !== undefined)
             return refusal("install", installReason(why));
+        const setting = systemSettingIn(segment);
+        if (setting !== undefined)
+            return refusal("system", machineChangeReason(setting));
         const found = programOf(segment);
         if (found !== undefined && (["pkill", "killall", "taskkill"].includes(found.program) || (found.program === "fuser" && found.args.some((arg) => /^-\w*k/.test(arg))))) {
             return refusal("kill", killReason());

package/dist/regenerate/confine.d.ts

@@ -31,6 +31,11 @@ export interface Confinement {
     reportsEnvironment?: boolean;
     /** Whose home and temporary folder its shell has, by the module folder they are kept for - its workdir's module when not given. */
     shellHome?: string;
+    /**
+     * The project's testing scripts are its to fix, where `write` reaches them - the sentinel's. Every other agent's file
+     * tools refuse them: the harness runs them, and an agent's copy of one is its own version of what the harness runs.
+     */
+    fixesScripts?: boolean;
 }
 export declare class ConfinementError extends Error {
     constructor(message: string);

package/dist/regenerate/confine.js

@@ -63,11 +63,11 @@ function refuseNotes(path) {
  * 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) {
+function refuseHarnessFiles(path, fixesScripts = false) {
     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)) {
+    if (!fixesScripts && (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.");
@@ -90,7 +90,7 @@ function refuseKeptOutput(raw, path, cwd) {
         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) {
+function check(raw, cwd, roots, verb, fixesScripts = false) {
     if (raw === undefined)
         return;
     const path = absolutize(raw, cwd);
@@ -101,7 +101,7 @@ function check(raw, cwd, roots, verb) {
     refuseRecord(path);
     if (verb === "write") {
         refuseNotes(path);
-        refuseHarnessFiles(path);
+        refuseHarnessFiles(path, fixesScripts);
     }
 }
 /** A glob is a path too: `../../*` escapes just as well as `..`. */
@@ -141,14 +141,14 @@ function guard(def, inspect) {
  * 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) {
+function guardedOps(roots, verb, fixesScripts = false) {
     return (path) => {
         if (!insideAny(path, roots))
             refuse(path, roots, verb);
         refuseRecord(path);
         if (verb === "write") {
             refuseNotes(path);
-            refuseHarnessFiles(path);
+            refuseHarnessFiles(path, fixesScripts);
         }
     };
 }
@@ -219,7 +219,7 @@ export function confinedTools(c) {
     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 writeOps = guardedOps(write, "write", c.fixesScripts === true);
     const tools = [
         guard(createReadToolDefinition(workdir, {
             operations: {
@@ -236,14 +236,14 @@ export function confinedTools(c) {
                     mkdirSync(dir, { recursive: true });
                 },
             },
-        }), (p) => check(p.path, workdir, write, "write")),
+        }), (p) => check(p.path, workdir, write, "write", c.fixesScripts === true)),
         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")),
+        }), (p) => check(p.path, workdir, write, "write", c.fixesScripts === true)),
         withoutRecord(guard(createLsToolDefinition(workdir), (p) => check(p.path, workdir, read, "read"))),
         withoutRecord(guard(createGrepToolDefinition(workdir), (p) => {
             check(p.path, workdir, read, "read");

package/dist/regenerate/ledger.d.ts

@@ -61,14 +61,21 @@ export type LedgerEvent = {
     kind: "notice.over";
     notice: string;
     state: string;
+} | {
+    kind: "sentinel.asked";
+    check: string;
+    module: string;
+    funcIds: string[];
 } | {
     kind: "sentinel.checking";
     module?: string;
     replaced?: string;
+    check?: string;
 } | {
     kind: "sentinel.concluded";
     verdict: string;
     module?: string;
+    check?: string;
 } | {
     kind: "chat.closed";
 } | {

package/dist/regenerate/lineage.js

@@ -301,16 +301,57 @@ export function abandonWork(start, moduleName, why) {
 export function committedText(dir, file) {
     try {
         const moduleDir = moduleDirOf(dir);
-        if (!existsSync(join(moduleDir, HISTORY_DIR)))
+        const gitDir = join(moduleDir, HISTORY_DIR);
+        if (!existsSync(gitDir))
             return undefined;
         const path = [basename(dir), file].join("/");
+        const head = headCommit(gitDir);
+        if (head === null)
+            return undefined;
+        // What a commit holds never changes: read once a commit. The panel asks for the records on every frame, and a git
+        // run each time - synchronous, on the thread that draws the screen - held the chat up for most of every second.
+        const key = head !== undefined ? `${gitDir}\0${head}\0${path}` : undefined;
+        if (key !== undefined && committedCache.has(key))
+            return committedCache.get(key) ?? undefined;
         const shown = git(moduleDir, ["show", `HEAD:${path}`]);
-        return shown.status === 0 ? shown.stdout : undefined;
+        const text = shown.status === 0 ? shown.stdout : undefined;
+        if (key !== undefined) {
+            committedCache.set(key, text ?? null);
+            if (committedCache.size > COMMITTED_CACHE_SIZE)
+                committedCache.delete(committedCache.keys().next().value);
+        }
+        return text;
     }
     catch {
         return undefined;
     }
 }
+/** `committedText`'s reads, by git dir, commit and path - null for a file the commit does not have. */
+const committedCache = new Map();
+const COMMITTED_CACHE_SIZE = 256;
+/**
+ * The commit a history's HEAD is at, read from its files without running git: null when HEAD names a branch with no
+ * commit yet, undefined when the files say nothing this reads - git is asked then.
+ */
+function headCommit(gitDir) {
+    const head = readFileSync(join(gitDir, "HEAD"), "utf8").trim();
+    if (/^[0-9a-f]{40,64}$/.test(head))
+        return head;
+    const ref = /^ref: (refs\/\S+)$/.exec(head)?.[1];
+    // A history on reftable keeps its refs in tables this does not read.
+    if (ref === undefined || existsSync(join(gitDir, "reftable")))
+        return undefined;
+    const loose = join(gitDir, ...ref.split("/"));
+    if (existsSync(loose)) {
+        const commit = readFileSync(loose, "utf8").trim();
+        return /^[0-9a-f]{40,64}$/.test(commit) ? commit : undefined;
+    }
+    const packed = join(gitDir, "packed-refs");
+    if (!existsSync(packed))
+        return null;
+    const line = readFileSync(packed, "utf8").split("\n").find((entry) => entry.endsWith(` ${ref}`));
+    return line !== undefined ? line.slice(0, line.indexOf(" ")) : null;
+}
 /**
  * Commit these paths of a module, and nothing else of it - removed, added or changed. Whatever else is in the folder,
  * uncommitted - what an interrupted job left - stays as it is, for the next unit of work to put back. Returns the commit.

package/dist/regenerate/loop.d.ts

@@ -323,6 +323,14 @@ export declare function functionalityCompletion(plainFile: string): Array<{
     codebase: string;
     modules: ModuleCompletion[];
 }>;
+/**
+ * The functional specs of a chain, completed or not, in the codebase it delivers: its furthest-built module's - see
+ * `functionalityCompletion`. A module's own chain (`resolveRequiresChain`) gives what its own codebase holds.
+ */
+export declare function codebaseCompletion(chain: ChainEntry[]): {
+    codebase: string;
+    modules: ModuleCompletion[];
+};
 export declare function createWorkLoop(options: {
     registry: JobRegistry;
     cwd: string;

package/dist/regenerate/loop.js

@@ -25,7 +25,7 @@ import { agentChanges, changeDiffInFiles } from "./change-view.js";
 import { createSteering, MAX_STEERS, markTold, steer, waitingSteer } from "./steering.js";
 import { projectDirOf } from "./paths.js";
 import { changesBetween, parseTree, serializeTree } from "./spec-steps.js";
-import { listFiles } from "./testing.js";
+import { hasFiles } from "./testing.js";
 import { makeRenames, pureRenames, renameText } from "./renames.js";
 import { casesOf, codeWork, stillWanted, whyNotWanted } from "./drift.js";
 import { testingGap } from "./testing-steps.js";
@@ -90,7 +90,7 @@ const modifiedAt = (path) => {
     }
 };
 /** Whether a module's codebase has been started: code in it, or a record. */
-const started = (entry) => listFiles(entry.buildDir).length > 0 || readRecord(entry.buildDir) !== null;
+const started = (entry) => readRecord(entry.buildDir) !== null || hasFiles(entry.buildDir);
 /** The spec a codebase is built from, as the .plain files have it now: its whole requires chain's. */
 export function chainSpec(chain) {
     // Each module's linked resources hashed where its links point: what a file holds is part of the spec.
@@ -141,7 +141,14 @@ function ownBuilt(entry) {
  * The modules above the delivered codebase have nothing completed. One entry per chain; planning nothing, calling no model.
  */
 export function functionalityCompletion(plainFile) {
-    return withParseCache(() => chainsFor(resolve(plainFile)).map((chain) => {
+    return withParseCache(() => chainsFor(resolve(plainFile)).map((chain) => codebaseCompletion(chain)));
+}
+/**
+ * The functional specs of a chain, completed or not, in the codebase it delivers: its furthest-built module's - see
+ * `functionalityCompletion`. A module's own chain (`resolveRequiresChain`) gives what its own codebase holds.
+ */
+export function codebaseCompletion(chain) {
+    return withParseCache(() => {
         let delivered = -1;
         chain.forEach((entry, index) => {
             if (readRecord(entry.buildDir) !== null)
@@ -209,7 +216,7 @@ export function functionalityCompletion(plainFile) {
             count.incomplete = entry.funcIds.filter((funcId) => !completed.includes(funcId));
         });
         return { codebase: tip.buildDir, modules: counts };
-    }));
+    });
 }
 /** The modules of a chain to build: its furthest-built one, and those above it - or, none built, all of it. */
 function toBuild(chain) {

package/dist/regenerate/os-sandbox.d.ts

@@ -82,6 +82,8 @@ export declare function setSandboxForTests(wall: Wall | undefined): void;
 export declare function sandboxAvailable(): Wall;
 /** Which wall would be up with `env`'s PATH - doctor's for a host whose engine runs with another PATH; tried each time. */
 export declare function sandboxWith(env: NodeJS.ProcessEnv): Wall;
+/** Which wall would be up with `env`'s PATH, as `sandboxWith` finds - its probes run without holding the thread up. */
+export declare function sandboxWithAsync(env?: NodeJS.ProcessEnv): Promise<Wall>;
 /** Whether `path` is one of the fence's roots or under one - for the tests and the audit. */
 export declare function underAny(path: string, roots: string[]): boolean;
 /** Where the agents' commands run, in one line for the person: which walls are up, or that only the shared ones are. */

package/dist/regenerate/os-sandbox.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
+import { spawnAsync } from "../spawn-async.js";
 /** The caps set inside the sandbox before the command runs: processes, and file size in 1024-byte blocks (8 GiB). */
 export const PROCESS_CAP = 4096;
 export const FILE_SIZE_CAP_BLOCKS = 8 * 1024 * 1024;
@@ -207,31 +208,65 @@ export function sandboxAvailable() {
 export function sandboxWith(env) {
     return env === process.env ? sandboxAvailable() : probe(env);
 }
-function probe(env = process.env) {
-    if (process.platform === "darwin") {
-        if (!existsSync("/usr/bin/sandbox-exec"))
-            return { kind: "none", why: "this macOS has no sandbox-exec (Seatbelt)" };
-        const run = spawnSync("/usr/bin/sandbox-exec", ["-p", "(version 1)(allow default)", "/usr/bin/true"], { encoding: "utf8", timeout: 10_000 });
-        return run.status === 0 ? { kind: "seatbelt" } : { kind: "none", why: `Seatbelt did not start: ${(run.stderr || String(run.error ?? "")).trim()}` };
-    }
-    if (process.platform === "linux") {
-        const tryProc = (proc) => spawnSync("bwrap", ["--ro-bind", "/", "/", ...(proc === "mount" ? ["--proc", "/proc"] : ["--ro-bind", "/proc", "/proc"]), "--dev", "/dev", "--unshare-pid", "--", "true"], {
-            encoding: "utf8",
-            timeout: 10_000,
-            env,
-        });
-        const mounted = tryProc("mount");
-        if (mounted.status === 0)
-            return { kind: "bubblewrap", proc: "mount" };
-        const output = `${mounted.stderr ?? ""}${mounted.error !== undefined ? String(mounted.error) : ""}`;
-        if (/Can't mount proc on (\/newroot)?\/proc/.test(output) && tryProc("bind").status === 0)
-            return { kind: "bubblewrap", proc: "bind" };
-        return { kind: "none", ...whyBubblewrapFailed(output) };
+/** Which wall would be up with `env`'s PATH, as `sandboxWith` finds - its probes run without holding the thread up. */
+export async function sandboxWithAsync(env = process.env) {
+    if (env === process.env && probed !== undefined)
+        return probed;
+    const settled = noProbe();
+    let wall;
+    if (settled !== undefined)
+        wall = settled;
+    else if (process.platform === "darwin")
+        wall = seatbeltWall(await spawnAsync(SEATBELT_PROBE[0], SEATBELT_PROBE.slice(1), { timeout: 10_000 }));
+    else {
+        const mounted = await spawnAsync("bwrap", bubblewrapProbe("mount"), { timeout: 10_000, env });
+        wall = bubblewrapWall(mounted, needsBind(mounted) ? await spawnAsync("bwrap", bubblewrapProbe("bind"), { timeout: 10_000, env }) : undefined);
     }
+    if (env === process.env)
+        probed = wall;
+    return wall;
+}
+function probe(env = process.env) {
+    const settled = noProbe();
+    if (settled !== undefined)
+        return settled;
+    if (process.platform === "darwin")
+        return seatbeltWall(spawnSync(SEATBELT_PROBE[0], SEATBELT_PROBE.slice(1), { encoding: "utf8", timeout: 10_000 }));
+    const tryProc = (proc) => spawnSync("bwrap", bubblewrapProbe(proc), { encoding: "utf8", timeout: 10_000, env });
+    const mounted = tryProc("mount");
+    return bubblewrapWall(mounted, needsBind(mounted) ? tryProc("bind") : undefined);
+}
+/** The wall where nothing need be run to tell: no Seatbelt to try, or a platform turri drives none on. */
+function noProbe() {
+    if (process.platform === "darwin")
+        return existsSync("/usr/bin/sandbox-exec") ? undefined : { kind: "none", why: "this macOS has no sandbox-exec (Seatbelt)" };
+    if (process.platform === "linux")
+        return undefined;
     if (process.platform === "win32")
         return { kind: "none", why: "Windows has no OS sandbox turri drives: the command check and the audit hold alone" };
     return { kind: "none", why: `${process.platform} has no OS sandbox turri drives` };
 }
+/** A sandbox that runs `true`, on macOS. */
+const SEATBELT_PROBE = ["/usr/bin/sandbox-exec", "-p", "(version 1)(allow default)", "/usr/bin/true"];
+function seatbeltWall(run) {
+    return run.status === 0 ? { kind: "seatbelt" } : { kind: "none", why: `Seatbelt did not start: ${(run.stderr || String(run.error ?? "")).trim()}` };
+}
+/** bubblewrap's arguments for a sandbox that runs `true`, its /proc mounted or bound. */
+function bubblewrapProbe(proc) {
+    return ["--ro-bind", "/", "/", ...(proc === "mount" ? ["--proc", "/proc"] : ["--ro-bind", "/proc", "/proc"]), "--dev", "/dev", "--unshare-pid", "--", "true"];
+}
+const probeOutput = (run) => `${run.stderr ?? ""}${run.error !== undefined ? String(run.error) : ""}`;
+/** Whether bubblewrap failed only to mount a /proc - tried again binding the host's. */
+function needsBind(mounted) {
+    return mounted.status !== 0 && /Can't mount proc on (\/newroot)?\/proc/.test(probeOutput(mounted));
+}
+function bubblewrapWall(mounted, bound) {
+    if (mounted.status === 0)
+        return { kind: "bubblewrap", proc: "mount" };
+    if (bound?.status === 0)
+        return { kind: "bubblewrap", proc: "bind" };
+    return { kind: "none", ...whyBubblewrapFailed(probeOutput(mounted)) };
+}
 /** Whether `path` is one of the fence's roots or under one - for the tests and the audit. */
 export function underAny(path, roots) {
     const target = real(path);

package/dist/regenerate/release.d.ts

@@ -39,6 +39,8 @@ export interface Deployment {
     unfinished: boolean;
     /** The module the spec's code lives in had nothing committed yet: the nearest one below it that had, instead. */
     instead?: string;
+    /** When the release tool shipped it: what it started since is this release's. */
+    at?: number;
 }
 /**
  * Which module to deploy for a spec: the tip of its codebase - code accumulates up a requires chain, so

package/dist/regenerate/requires.d.ts

@@ -30,6 +30,18 @@ export declare function locateModule(moduleName: string, templateDirs: string[])
 export declare function resolveRequiresChain(plainFile: string, templateDirs?: string[], buildRoot?: string, 
 /** Accept the named module without functional specs yet. Those it requires must have them. */
 options?: ParseOptions): ChainEntry[];
+/** Every .plain file in a project's folder, sorted - the modules a host lists. */
+export declare function projectPlainFiles(projectDir: string): string[];
+/**
+ * A project's .plain files in the order they are built: each after every module it requires, as its requires chain has
+ * them (`resolveRequiresChain`) - taken in the order given, by name without `files`, each brought in after what it
+ * requires. A module whose chain does not resolve - it does not parse, a module it requires is not there, a cycle - goes
+ * after what its front matter says it requires, as far as those are found. `files`, absolute or from the project: the
+ * ones to order, every other module of a chain left out; without it, every .plain file in the project's folder.
+ */
+export declare function requiresOrder(projectDir: string, options?: {
+    files?: string[];
+}): string[];
 /**
  * Whether a .plain file is an import module - one a .plain file imports, or one kept in a `template/` folder - rather than
  * a module of its own. It is no codebase: its reqs and definitions are built in the modules that import it.

package/dist/regenerate/requires.js

@@ -1,6 +1,6 @@
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, withParseCache } from "../plain/parser.js";
+import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, REQUIRES_DIRECTIVE, withParseCache } from "../plain/parser.js";
 import { getFrids, getInheritedFunctionalSpecs } from "../plain/spec.js";
 import { buildDirUnder, modulesRoot, projectDirOf } from "./paths.js";
 import { notesPath } from "./notes.js";
@@ -56,6 +56,75 @@ options = {}) {
     visit(resolve(plainFile), []);
     return chain;
 }
+/** Every .plain file in a project's folder, sorted - the modules a host lists. */
+export function projectPlainFiles(projectDir) {
+    const root = resolve(projectDir);
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(PLAIN_SOURCE_FILE_EXTENSION))
+            .map((entry) => join(root, entry.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * A project's .plain files in the order they are built: each after every module it requires, as its requires chain has
+ * them (`resolveRequiresChain`) - taken in the order given, by name without `files`, each brought in after what it
+ * requires. A module whose chain does not resolve - it does not parse, a module it requires is not there, a cycle - goes
+ * after what its front matter says it requires, as far as those are found. `files`, absolute or from the project: the
+ * ones to order, every other module of a chain left out; without it, every .plain file in the project's folder.
+ */
+export function requiresOrder(projectDir, options = {}) {
+    const root = resolve(projectDir);
+    const files = (options.files ?? projectPlainFiles(root)).map((file) => resolve(root, file));
+    const wanted = new Set(files);
+    const order = [];
+    const placed = new Set();
+    const add = (file) => {
+        if (placed.has(file))
+            return;
+        placed.add(file);
+        if (wanted.has(file))
+            order.push(file);
+    };
+    const visiting = new Set();
+    const place = (file) => {
+        if (placed.has(file) || visiting.has(file))
+            return;
+        visiting.add(file);
+        try {
+            for (const entry of resolveRequiresChain(file, [], undefined, { allowNoFunctionalities: true }))
+                add(entry.plainFile);
+        }
+        catch {
+            let requires = [];
+            try {
+                requires = (readPlainSourceMetadata(readFileSync(file, "utf8")).metadata[REQUIRES_DIRECTIVE] ?? []).filter((name) => typeof name === "string");
+            }
+            catch {
+                // Not read: nothing to put it after.
+            }
+            const dirs = resolveTemplateDirs(file);
+            for (const name of requires) {
+                try {
+                    place(resolve(locateModule(name, dirs)));
+                }
+                catch {
+                    // Not there: nothing to put it after.
+                }
+            }
+            add(file);
+        }
+        visiting.delete(file);
+    };
+    withParseCache(() => {
+        for (const file of files)
+            place(file);
+    });
+    return order;
+}
 /** The .plain files that import `plainFile` - read from beside it, and, kept in a `template/` folder, from the folder it is in. */
 function importersOf(plainFile) {
     const file = resolve(plainFile);

package/dist/regenerate/spec-steps.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -130,7 +131,23 @@ export function diffTrees(before, after, context = 3) {
     return gitDiff(before, after, context, ["spec.before", "spec.after"]);
 }
 /** git's diff of two texts, written to files of the names given. */
-function gitDiff(before, after, context, [from, to]) {
+function gitDiff(before, after, context, names) {
+    if (before === after)
+        return "";
+    // The same texts, the same diff: a project looked at again - every codebase of every chain - runs git only for what changed.
+    const key = createHash("sha1").update(`${context}\0${names.join("\0")}\0${before.length}\0${before}\0${after}`).digest("hex");
+    const kept = keptDiffs.get(key);
+    if (kept !== undefined)
+        return kept;
+    const diff = gitDiffNow(before, after, context, names);
+    keptDiffs.set(key, diff);
+    while (keptDiffs.size > KEPT_DIFFS)
+        keptDiffs.delete(keptDiffs.keys().next().value);
+    return diff;
+}
+const keptDiffs = new Map();
+const KEPT_DIFFS = 200;
+function gitDiffNow(before, after, context, [from, to]) {
     const dir = mkdtempSync(join(tmpdir(), "turri-spec-steps-"));
     try {
         // The names are paths - "plain/hubspot.plain" for a spec in a folder of the project: their folders first.

package/dist/regenerate/standing.d.ts

@@ -0,0 +1,28 @@
+import { functionalityCompletion, type DriftReport, type WorkLoop } from "./loop.ts";
+/**
+ * How each module of a project stands, in one call: what `WorkLoop.drift` and `functionalityCompletion` say of it, each
+ * as they say it alone. One look at the whole project: each file parsed once, each record read once, the modules below
+ * shared by every chain they are in - where asking module by module parses and reads the chain below each again.
+ */
+export interface ModuleStanding {
+    /** The module's .plain file. */
+    plainFile: string;
+    module: string;
+    /** `drift(plainFile)`: what is left to regenerate in every codebase of its chain - undefined when drift could not say (`driftError`). */
+    drift?: DriftReport[];
+    driftError?: string;
+    /** `functionalityCompletion(plainFile)`: its chain's functional specs completed, one entry per chain - undefined with `completionError`. */
+    completion?: ReturnType<typeof functionalityCompletion>;
+    completionError?: string;
+}
+export interface StandingOptions {
+    /**
+     * The work loop whose drift is read - the session's, which knows its running pulses and halts. Without one, a loop of
+     * its own that starts nothing, as the codebases' records have them.
+     */
+    loop?: WorkLoop;
+    /** The .plain files to look at. Without them, every .plain file in the project's folder. */
+    files?: string[];
+}
+/** Every module of a project, how it stands - see `ModuleStanding`. */
+export declare function projectStanding(projectDir: string, options?: StandingOptions): ModuleStanding[];

package/dist/regenerate/standing.js

@@ -0,0 +1,30 @@
+import { basename, resolve } from "node:path";
+import { PLAIN_SOURCE_FILE_EXTENSION, withParseCache } from "../plain/parser.js";
+import { createJobRegistry } from "./jobs.js";
+import { createWorkLoop, functionalityCompletion } from "./loop.js";
+import { projectPlainFiles } from "./requires.js";
+/** Every module of a project, how it stands - see `ModuleStanding`. */
+export function projectStanding(projectDir, options = {}) {
+    const root = resolve(projectDir);
+    const files = (options.files ?? projectPlainFiles(root)).map((file) => resolve(root, file));
+    const loop = options.loop ?? createWorkLoop({ registry: createJobRegistry(), cwd: root, dryRun: true });
+    return withParseCache(() => files.map((plainFile) => {
+        const standing = { plainFile, module: basename(plainFile, PLAIN_SOURCE_FILE_EXTENSION) };
+        try {
+            standing.drift = loop.drift(plainFile);
+        }
+        catch (error) {
+            standing.driftError = messageOf(error);
+        }
+        try {
+            standing.completion = functionalityCompletion(plainFile);
+        }
+        catch (error) {
+            standing.completionError = messageOf(error);
+        }
+        return standing;
+    }));
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/regenerate/testing.d.ts

@@ -56,6 +56,8 @@ export declare function shownOutput(dir: string, label: string, output: string):
  * harness's own bookkeeping. Installed dependencies alone can be tens of thousands of files.
  */
 export declare const NOT_CODE: Set<string>;
+/** Whether a codebase holds a file of its own - as `listFiles` counts them - stopping at the first. */
+export declare function hasFiles(root: string): boolean;
 export declare function listFiles(root: string): string[];
 /** A tool that runs the tests and lets the harness see the result, rather than taking the agent's word. */
 export declare const TEST_FILE_PATTERN: RegExp;