@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/questioning.js

@@ -0,0 +1,109 @@
+/**
+ * How many questions an interview may put to the person in each phase it caps, and how broad each is - the
+ * questioning level, the first thing a skill with `metadata.questioning` asks. Light, medium and thorough cap each such
+ * phase at 3, 5 and 10 questions; best judgement leaves it to the agent, which says when it has asked enough. Every
+ * level covers the same ground: fewer questions are broader ones, and what they leave open the agent decides itself.
+ * The level limits the questions, never the spec changes. The phase's closing confirmation, asked with
+ * `confirms_phase`, is never counted.
+ */
+export const QUESTIONING_LEVELS = [
+    {
+        name: "light",
+        cap: 3,
+        option: "Light - at most 3 broad questions a phase, turri decides the details",
+        breadth: "Ask broad questions: each settles a whole area of the phase at once - the features and their order, what the product does end to end - proposing what fits the brief for the person to confirm or correct. The details are yours.",
+    },
+    {
+        name: "medium",
+        cap: 5,
+        option: "Medium - at most 5 questions a phase, each a feature or topic",
+        breadth: "Ask about one feature or topic a question, with its main rules in the same question. The edge cases are yours.",
+    },
+    {
+        name: "thorough",
+        cap: 10,
+        option: "Thorough - at most 10 narrow questions a phase, edge cases included",
+        breadth: "Ask narrow questions: one feature, rule or edge case a question, with follow-ups on the ones that matter most.",
+    },
+    {
+        name: "best judgement",
+        option: "Best judgement - turri decides how much each phase asks",
+        breadth: "Ask as broadly or as narrowly as each area needs - narrow where the person's answer changes the product, broad or not at all where the brief already says.",
+    },
+];
+const BEST_JUDGEMENT = QUESTIONING_LEVELS.at(-1);
+/** The level an answer picks: by its name, wherever it is in the answer; anything else is best judgement. */
+export function levelOf(answer) {
+    const said = answer.toLowerCase();
+    return QUESTIONING_LEVELS.find((level) => said.startsWith(level.name)) ?? QUESTIONING_LEVELS.find((level) => said.includes(level.name.split(" ")[0])) ?? BEST_JUDGEMENT;
+}
+/** The question the harness puts first, and what the person reads above it. */
+export function questioningQuestion(phases) {
+    const named = phases.length === 1 ? `the ${phases[0]} phase` : `the ${phases.slice(0, -1).join(", ")} and ${phases.at(-1)} phases`;
+    return {
+        question: `How many questions should I ask you in ${named}?`,
+        options: QUESTIONING_LEVELS.map((level) => level.option),
+        context: `Light, medium and thorough cap each of ${named} at 3, 5 and 10 questions - broader with fewer, so every level ` +
+            "covers the same ground, only in less or more depth. What the questions leave open, turri decides itself and " +
+            "says what it chose. With best judgement, turri asks as much as it judges each phase needs. Each phase still " +
+            "ends with your confirmation of its summary.",
+    };
+}
+export function createQuestioning(options) {
+    const { level, phases } = options;
+    const asked = { ...(options.from?.asked ?? {}) };
+    const over = new Set(options.from?.over ?? []);
+    let phase = "";
+    const capped = () => phases.includes(phase);
+    const state = () => ({ level: level.name, asked: { ...asked }, over: [...over] });
+    const changed = () => options.onChange?.(state());
+    const decideTheRest = "Decide what is left yourself, as a careful engineer would, in the light of the intent brief, and say in one line what you chose.";
+    return {
+        level,
+        enter(next) {
+            phase = next;
+        },
+        refusal(confirmsPhase) {
+            if (!capped() || confirmsPhase || !over.has(phase))
+                return undefined;
+            const why = level.cap !== undefined && (asked[phase] ?? 0) >= level.cap
+                ? `${level.name} questioning allows ${level.cap} questions in the ${phase} phase, and all ${level.cap} are asked`
+                : `you ended the ${phase} phase's questions`;
+            return `This question was not asked: ${why}. ${decideTheRest} Only the phase's closing confirmation, with confirms_phase, may still be asked.`;
+        },
+        answered(confirmsPhase) {
+            if (!capped() || confirmsPhase)
+                return;
+            asked[phase] = (asked[phase] ?? 0) + 1;
+            if (level.cap !== undefined && asked[phase] >= level.cap)
+                over.add(phase);
+            changed();
+        },
+        end() {
+            if (!capped())
+                return `The ${phase} phase's questions are not capped: ask what it needs.`;
+            over.add(phase);
+            changed();
+            return `The ${phase} phase's questions are over. ${decideTheRest} End the phase with its summary and its confirmation, asked with confirms_phase.`;
+        },
+        note(next, first) {
+            const chosen = `The person chose ${level.name} questioning${first ? " - the harness asked it, so do not ask it again" : ""}.`;
+            if (!phases.includes(next)) {
+                return first ? `${chosen} It caps the questions of the ${phases.join(" and ")} phases, not this one.` : undefined;
+            }
+            const limit = level.cap !== undefined
+                ? `Ask at most ${level.cap} questions with ask_user in this phase, follow-ups included; past them ask_user refuses. To stop sooner, call end_questions.`
+                : "Stop asking once the phase is settled enough to build: call end_questions.";
+            return [
+                chosen,
+                limit,
+                level.breadth,
+                "Whatever the level, the questions cover all of the phase's topics: the level sets their depth, not their reach.",
+                "The phase's closing confirmation is asked with confirms_phase: true and is not counted.",
+                `What the questions leave open: ${decideTheRest}`,
+                "The level limits the questions, never the spec changes: write as many as the phase needs, decided ones included.",
+            ].join(" ");
+        },
+        state,
+    };
+}

package/dist/quiet.js

@@ -0,0 +1,125 @@
+/**
+ * Keeps library chatter out of the terminal while a tool runs.
+ *
+ * A skill run spawns many nested agent sessions - an executor, two judges per gate, a fix
+ * agent, each queued render - and libraries underneath them write to the console. In the
+ * TUI every one of those writes interrupts the differential renderer, which abandons the
+ * current frame and leaves it stranded in scrollback. Dozens of "Working" lines pile up.
+ *
+ * Only the `console` methods are intercepted, never `process.stdout.write` itself: that is
+ * how pi draws the TUI, and silencing it would blank the screen. Library noise goes
+ * through `console`; pi's rendering does not.
+ */
+const METHODS = ["log", "info", "warn", "error", "debug", "trace"];
+/**
+ * Warnings that say nothing a person can act on, dropped wherever they are printed. Google's SDK
+ * says this once per client, so once per agent, when both keys are set - pi offers the google
+ * provider on GEMINI_API_KEY, and a machine set up for other tools often has GOOGLE_API_KEY too.
+ */
+const NOISE = [/^Both GOOGLE_API_KEY and GEMINI_API_KEY are set\. Using GOOGLE_API_KEY\.$/];
+function isNoise(args) {
+    return args.length === 1 && typeof args[0] === "string" && NOISE.some((pattern) => pattern.test(args[0]));
+}
+let noiseDropped = false;
+/** Drop the NOISE warnings for good, from here on - captured or not. Safe to call more than once. */
+export function dropNoise() {
+    if (noiseDropped)
+        return;
+    noiseDropped = true;
+    for (const method of ["warn", "error", "log", "info", "debug"]) {
+        const print = console[method];
+        console[method] = (...args) => {
+            if (!isNoise(args))
+                print.apply(console, args);
+        };
+    }
+}
+/** Buffers currently collecting. Nested and concurrent captures all see the same writes. */
+const active = new Set();
+const original = new Map();
+function install() {
+    if (original.size > 0)
+        return;
+    for (const method of METHODS) {
+        original.set(method, console[method]);
+        console[method] = (...args) => {
+            if (isNoise(args))
+                return;
+            const line = args
+                .map((arg) => (typeof arg === "string" ? arg : safeStringify(arg)))
+                .join(" ");
+            for (const buffer of active)
+                buffer.push(line);
+        };
+    }
+}
+function restore() {
+    if (active.size > 0 || original.size === 0)
+        return;
+    for (const [method, fn] of original)
+        console[method] = fn;
+    original.clear();
+}
+function safeStringify(value) {
+    try {
+        return typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Run `fn` with console output collected instead of printed. */
+export async function captureConsole(fn) {
+    // An escape hatch for debugging: with this set, library output goes to the terminal as
+    // it used to, which is how the capture itself can be measured.
+    if (process.env.TURRI_NO_CAPTURE === "1")
+        return { result: await fn(), output: [] };
+    const buffer = [];
+    active.add(buffer);
+    install();
+    try {
+        return { result: await fn(), output: buffer };
+    }
+    finally {
+        active.delete(buffer);
+        restore();
+    }
+}
+/**
+ * Capture that spans something other than one promise - a whole agent turn, say.
+ *
+ * `captureConsole` covers work it can wrap. A conversation's own model calls happen inside
+ * pi's agent loop, where there is nothing to wrap, so those are bracketed by hand instead.
+ * `end` is safe to call twice and safe to skip: an unbalanced `begin` leaves the console
+ * patched, so callers must end it from a handler that always runs.
+ */
+export function beginCapture() {
+    if (process.env.TURRI_NO_CAPTURE === "1")
+        return { end: () => [] };
+    const buffer = [];
+    active.add(buffer);
+    install();
+    let ended = false;
+    return {
+        end: () => {
+            if (ended)
+                return buffer;
+            ended = true;
+            active.delete(buffer);
+            restore();
+            return buffer;
+        },
+    };
+}
+/** One line noting what was swallowed, or nothing when it was quiet. */
+export function describeCaptured(output) {
+    if (output.length === 0)
+        return null;
+    const unique = [...new Set(output.map((line) => line.trim()).filter(Boolean))];
+    const shown = unique.slice(0, 3);
+    const rest = unique.length - shown.length;
+    return (`(${output.length} line${output.length === 1 ? "" : "s"} of library output suppressed: ` +
+        shown.join(" | ") +
+        (rest > 0 ? ` | and ${rest} more` : "") +
+        ")");
+}

package/dist/regenerate/activity.js

@@ -0,0 +1,187 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Say which functional spec is being built now - shown with the job, and in its transcript. */
+export function reportSpec(spec) {
+    store.getStore()?.spec?.(spec);
+}
+/** Say the spec contradicts itself, to the job this runs for. */
+export function reportSpecConflict(conflict) {
+    store.getStore()?.specConflict?.(conflict);
+}
+/** Raised inside a job that was asked to stop, so the work unwinds instead of carrying on. */
+export class JobStoppedError extends Error {
+    constructor() {
+        super("Stopped on request.");
+        this.name = "JobStoppedError";
+    }
+}
+/** The stop signal of the job this code is running for, if it is running for one. */
+export function currentStopSignal() {
+    return store.getStore()?.signal;
+}
+/** The job this code is running for, if it is running for one. */
+export function currentJob() {
+    return store.getStore()?.job;
+}
+export function reportTranscript(entry) {
+    store.getStore()?.transcript(entry);
+}
+/**
+ * What a stage is about, said so the person knows what the name is: "module backend", or "module
+ * backend, functionality 2". A stage leads with it: `${unitOf(moduleName, frid)}: running the tests`.
+ */
+export function unitOf(moduleName, frid) {
+    return frid === undefined ? `module ${moduleName}` : `module ${moduleName}, functionality ${frid}`;
+}
+export function reportUsage(usage) {
+    store.getStore()?.usage(usage);
+}
+export function reportAgent(report) {
+    store.getStore()?.agent?.(report);
+}
+/** Add one agent report to a job's tally, by label - its first report starts its row. */
+export function addAgentReport(tallies, report) {
+    let tally = tallies.find((entry) => entry.label === report.label);
+    if (tally === undefined) {
+        tally = { label: report.label, turns: 0, compactions: 0, usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 } };
+        tallies.push(tally);
+    }
+    if (report.model !== undefined)
+        tally.model = report.model;
+    tally.turns += report.turns ?? 0;
+    tally.compactions += report.compactions ?? 0;
+    const spent = report.usage;
+    if (spent !== undefined) {
+        tally.usage = {
+            input: tally.usage.input + spent.input,
+            output: tally.usage.output + spent.output,
+            cacheRead: tally.usage.cacheRead + spent.cacheRead,
+            cacheWrite: tally.usage.cacheWrite + spent.cacheWrite,
+            cost: tally.usage.cost + spent.cost,
+        };
+    }
+}
+/** A job's agents, a line each: "app 1 reviewer · 3 turns · 1 compaction · 210.4k tok · $0.41". */
+export function describeAgents(tallies) {
+    return tallies.map((tally) => {
+        const spent = describeUsage(tally.usage);
+        return [
+            tally.label,
+            `${tally.turns} turn${tally.turns === 1 ? "" : "s"}`,
+            ...(tally.compactions > 0 ? [`${tally.compactions} compaction${tally.compactions === 1 ? "" : "s"}`] : []),
+            ...(spent !== "" ? [spent] : []),
+            ...(tally.model !== undefined ? [tally.model] : []),
+        ].join(" · ");
+    });
+}
+/** "1.2k tok · $0.03", or "" when nothing has been spent yet. */
+export function describeUsage(usage) {
+    if (usage === undefined)
+        return "";
+    const tokens = usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+    if (tokens === 0)
+        return "";
+    const size = tokens >= 1_000_000 ? `${(tokens / 1_000_000).toFixed(1)}M` : tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : `${tokens}`;
+    return usage.cost > 0 ? `${size} tok · $${usage.cost.toFixed(2)}` : `${size} tok`;
+}
+const store = new AsyncLocalStorage();
+export function withActivity(sink, run) {
+    return store.run(sink, run);
+}
+export function reportStage(label) {
+    store.getStore()?.stage(label);
+}
+export function reportActivity(line) {
+    store.getStore()?.activity(line);
+}
+/** Say something about the machinery under the work: shown as activity, and kept in the job's log, which the activity is not. */
+export function reportNote(line) {
+    const sink = store.getStore();
+    sink?.activity(line);
+    sink?.note?.(line);
+}
+/** Say something for the job's log alone: the machinery, not what its agents are doing. */
+export function reportLogNote(line) {
+    store.getStore()?.note?.(line);
+}
+export function reportNow(label, options) {
+    store.getStore()?.now(label, options);
+}
+const MAX_ARG = 60;
+function clip(text) {
+    const one = text.replace(/\s+/g, " ").trim();
+    return one.length > MAX_ARG ? `${one.slice(0, MAX_ARG - 1)}…` : one;
+}
+/**
+ * Paths as they are inside `plain_modules`: everything up to and including it left out, wherever
+ * a path to it appears - `/Users/…/project/plain_modules/app/code/main.py` is `app/code/main.py`.
+ * The rest of the path is the same for every line, and is what pushes the part that differs off
+ * the end of it.
+ */
+export function withinModules(text) {
+    return text.replace(/(?:(?:\/|~\/)(?:[^\s'"`/]+\/)*|(?<![\w.-]))plain_modules\//g, "");
+}
+/**
+ * What the person is shown a tool as, where that is not the name its agent calls it by. The agent's name says
+ * what the call takes - `write_spec_diff` takes a diff of the spec - and the shown one speaks turri's language.
+ */
+const SHOWN_AS = {
+    write_spec_diff: "mutate",
+};
+/** A tool's name as the person is shown it. */
+export function shownName(name) {
+    return SHOWN_AS[name] ?? name;
+}
+/** A tool call as one short line. Unknown tools still show up, by name. */
+export function describeToolCall(name, args) {
+    const text = (key) => (typeof args?.[key] === "string" ? withinModules(args[key]) : undefined);
+    const path = text("path");
+    const command = text("command");
+    const pattern = text("pattern");
+    switch (name) {
+        case "write":
+            return `✎ write ${path ?? ""}`.trimEnd();
+        case "edit":
+            return `✎ edit ${path ?? ""}`.trimEnd();
+        // Every kind of call has its mark, so every line has the same shape - a reviewer that only reads as well.
+        case "read":
+            return `○ read ${path ?? ""}`.trimEnd();
+        case "ls":
+        case "find":
+        case "grep":
+            return `⌕ ${name} ${clip(pattern ?? path ?? "")}`.trimEnd();
+        case "web_search":
+        case "web_fetch":
+            return `⇢ ${name} ${clip(text("query") ?? text("url") ?? "")}`.trimEnd();
+        case "bash":
+            return `$ ${clip(command ?? "")}`;
+        case "run_unit_tests":
+        case "run_conformance_tests":
+            return `▶ ${name === "run_unit_tests" ? "unit tests" : "conformance tests"}: the project's script`;
+        // turri's own tools: what they do, at a glance.
+        case "read_output":
+            return `○ read_output`;
+        case "my_diff":
+            return `± my_diff`;
+        case "update_notes":
+            return `✐ update_notes`;
+        case "copy_resource":
+            return `⎘ copy_resource ${path ?? text("to") ?? ""}`.trimEnd();
+        case "can_it_fail":
+            return `? can_it_fail`;
+        case "ask_explorer":
+            return `? ask_explorer`;
+        default:
+            // A hand-over - submit_work, submit_review, a verdict - ends with a check; anything else, a dot.
+            return `${/^submit_/.test(name) ? "✓" : "•"} ${shownName(name)}`;
+    }
+}
+/** The outcome of a test run, or nothing for tools whose outcome is not worth a line. */
+export function describeToolResult(name, result, isError) {
+    if (name !== "run_unit_tests" && name !== "run_conformance_tests") {
+        return isError ? `  ✗ ${shownName(name)} failed` : undefined;
+    }
+    const exitCode = result?.details?.exitCode;
+    if (typeof exitCode !== "number")
+        return undefined;
+    return exitCode === 0 ? "  ✓ passing" : `  ✗ failing (exit ${exitCode})`;
+}

package/dist/regenerate/agent-env.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { readProjectConfig, stackOf } from "../config.js";
+import { registerSecrets } from "./masking.js";
+import { projectRootOf, modulesScratchDir } from "./paths.js";
+/**
+ * The environment every agent command gets, on this machine.
+ *
+ * Not the host's: the shell turri was started in holds the providers' API keys, cloud credentials, tokens and an SSH
+ * agent, and an agent's command - or the code it runs - could read any of them. So only an allow-list passes: the path,
+ * the locale, the terminal, the user, and the variables that locate the host's toolchains. Then turri's own: a HOME of
+ * the module's own, kept between pulses, so a tool's settings and an agent's dotfiles never land in the person's; a
+ * TMPDIR; the package caches in the project, so a dependency downloads once; and git stopped at the module, so a
+ * project that is itself a repository is not found from the code. Last, what the project passes on purpose -
+ * `agent-env:` in its config - which never replaces turri's own.
+ */
+/** Passed from the host as they are. */
+const ALLOWED = ["PATH", "LANG", "TERM", "TZ", "USER", "LOGNAME", "COLORTERM"];
+const ALLOWED_PREFIXES = ["LC_"];
+/**
+ * The variables that locate a toolchain, each with where it is in the person's home when the host sets none - a fake
+ * HOME would otherwise hide it. Without a default, only the host's.
+ */
+const TOOLCHAIN_LOCATORS = {
+    JAVA_HOME: undefined,
+    GOROOT: undefined,
+    GOPATH: undefined,
+    DOTNET_ROOT: undefined,
+    ANDROID_HOME: undefined,
+    ANDROID_SDK_ROOT: undefined,
+    FLUTTER_ROOT: undefined,
+    M2_HOME: undefined,
+    MAVEN_HOME: undefined,
+    GRADLE_HOME: undefined,
+    RUSTUP_HOME: ".rustup",
+    NVM_DIR: ".nvm",
+    PYENV_ROOT: ".pyenv",
+    SDKMAN_DIR: ".sdkman",
+    VOLTA_HOME: ".volta",
+    ASDF_DATA_DIR: ".asdf",
+    // mise and fnm keep their installs under ~/.local/share; uv the Pythons it fetches.
+    MISE_DATA_DIR: ".local/share/mise",
+    FNM_DIR: ".local/share/fnm",
+    RBENV_ROOT: ".rbenv",
+    UV_PYTHON_INSTALL_DIR: ".local/share/uv/python",
+    BUN_INSTALL: ".bun",
+    PNPM_HOME: undefined,
+};
+/** The variables that locate a toolchain - their folders are what the OS sandbox lets a command read of the person's. */
+export const TOOLCHAIN_VARIABLES = Object.keys(TOOLCHAIN_LOCATORS);
+/** Where package managers keep their caches: in the project's scratch area, so a dependency downloads once. */
+export function packageCacheDir(dir) {
+    return join(modulesScratchDir(dir), "cache");
+}
+/** Every package manager's cache, pointed into `cache`. */
+export function cacheEnv(cache) {
+    return {
+        XDG_CACHE_HOME: cache,
+        MAVEN_OPTS: `-Dmaven.repo.local=${join(cache, "m2")}`,
+        GRADLE_USER_HOME: join(cache, "gradle"),
+        CARGO_HOME: join(cache, "cargo"),
+        npm_config_cache: join(cache, "npm"),
+        YARN_CACHE_FOLDER: join(cache, "yarn"),
+        PIP_CACHE_DIR: join(cache, "pip"),
+        UV_CACHE_DIR: join(cache, "uv"),
+        GOCACHE: join(cache, "go-build"),
+        GOMODCACHE: join(cache, "go-mod"),
+    };
+}
+/** The git identity an agent's commits in a scratch repository get - never the person's. */
+const GITCONFIG = "[user]\n\tname = turri\n\temail = turri@localhost\n[init]\n\tdefaultBranch = main\n";
+/**
+ * The environment of a command an agent runs in `moduleDir` - `plain_modules/<module>`. `hostEnv`: the environment
+ * turri was started in; `home`: the person's home folder.
+ */
+export function agentEnvironment(moduleDir, options = {}) {
+    const hostEnv = options.hostEnv ?? process.env;
+    const home = options.home ?? homedir();
+    const module = resolve(moduleDir);
+    const name = basename(module);
+    const env = {};
+    for (const [key, value] of Object.entries(hostEnv)) {
+        if (value === undefined)
+            continue;
+        if (ALLOWED.includes(key) || ALLOWED_PREFIXES.some((prefix) => key.startsWith(prefix)))
+            env[key] = value;
+    }
+    for (const [key, inHome] of Object.entries(TOOLCHAIN_LOCATORS)) {
+        const given = hostEnv[key];
+        if (given !== undefined && given !== "")
+            env[key] = given;
+        else if (inHome !== undefined && existsSync(join(home, inHome)))
+            env[key] = join(home, inHome);
+    }
+    const { values, missing } = passedCredentials(module, hostEnv);
+    // From now on their values are masked in everything an agent is shown and turri writes.
+    registerSecrets(values);
+    Object.assign(env, values);
+    Object.assign(env, turrisOwn(module, name));
+    return { env, passed: Object.keys(values).sort(), values, missing };
+}
+/** HOME, TMPDIR, the caches and git's ceiling: what no setting of the project's replaces. */
+function turrisOwn(module, name) {
+    const scratch = modulesScratchDir(module);
+    const fakeHome = join(scratch, "home", name);
+    mkdirSync(fakeHome, { recursive: true });
+    const gitconfig = join(fakeHome, ".gitconfig");
+    if (!existsSync(gitconfig))
+        writeFileSync(gitconfig, GITCONFIG);
+    const tmp = join(scratch, "tmp", name);
+    mkdirSync(tmp, { recursive: true });
+    // There before the first command: bubblewrap binds every writable folder, and refuses one that is not.
+    mkdirSync(packageCacheDir(module), { recursive: true });
+    // Java takes its temporary folder and its home from the system, not from TMPDIR and HOME - on macOS a per-user folder
+    // and the person's home, both outside the sandbox. Every JVM reads JAVA_TOOL_OPTIONS, a test JVM Surefire or Gradle
+    // forks too, and an agent's own MAVEN_OPTS does not replace it: Maven without its repository setting falls back to the
+    // module's home, not the person's ~/.m2. (Each JVM says on stderr that it picked them up.)
+    return {
+        ...cacheEnv(packageCacheDir(module)),
+        JAVA_TOOL_OPTIONS: `-Djava.io.tmpdir=${tmp} -Duser.home=${fakeHome}`,
+        HOME: fakeHome,
+        TMPDIR: tmp,
+        GIT_CEILING_DIRECTORIES: module,
+        ...(process.platform === "darwin" ? { [DARWIN_TEMP_SUFFIX]: darwinTempSuffix(module, name) } : {}),
+    };
+}
+/**
+ * On macOS, what a program asks the system for as the per-user temporary folder - not TMPDIR - is that folder with this
+ * suffix added: a folder of the module's own inside it. The JVM keeps its attach sockets there (`.java_pid<pid>`), which
+ * Mockito's inline mocks, jcmd and jstack attach through; the sandbox reaches this folder alone, never the person's
+ * JVMs' sockets beside it.
+ */
+export const DARWIN_TEMP_SUFFIX = "DIRHELPER_USER_DIR_SUFFIX";
+/** The module's own folder in macOS's per-user temporary folder: named for it, and for where it is. */
+function darwinTempSuffix(module, name) {
+    return `turri-${name.replace(/[^\w.-]/g, "_")}-${createHash("sha256").update(resolve(module)).digest("hex").slice(0, 8)}`;
+}
+/** What `agent-env:` - the project's, with the chosen stack's added - passes, and what of it is not there. Reads only. */
+export function passedCredentials(module, hostEnv) {
+    const root = projectRootOf(module);
+    const setting = readProjectConfig(root, stackOf(root)).agentEnv;
+    const values = {};
+    const missing = [];
+    if (setting === undefined)
+        return { values, missing };
+    for (const file of setting.files) {
+        const path = resolve(root, file);
+        if (!existsSync(path)) {
+            missing.push({ name: file, why: `no such file: ${path}` });
+            continue;
+        }
+        Object.assign(values, parseDotenv(readFileSync(path, "utf8")));
+    }
+    for (const name of setting.vars) {
+        const value = hostEnv[name];
+        if (value === undefined)
+            missing.push({ name, why: "not set in the environment turri was started in" });
+        else if (value === "")
+            missing.push({ name, why: "set, but empty, in the environment turri was started in" });
+        else
+            values[name] = value;
+    }
+    return { values, missing };
+}
+/** A dotenv file's variables: `KEY=value`, `export KEY=value`, quoted or not; comments and blank lines skipped. */
+export function parseDotenv(text) {
+    const values = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (match === null)
+            continue;
+        let value = match[2];
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.lastIndexOf(quote) > 0) {
+            value = value.slice(1, value.lastIndexOf(quote));
+            if (quote === '"')
+                value = value.replace(/\\n/g, "\n").replace(/\\"/g, '"');
+        }
+        else {
+            value = value.replace(/\s+#.*$/, "");
+        }
+        values[match[1]] = value;
+    }
+    return values;
+}