@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/workspace.js

@@ -0,0 +1,99 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { projectImplementationReqs, stackOf } from "../stack.js";
+import { MODULES_DIR, projectRootOf } from "./paths.js";
+import { RECORD_FILE } from "./records.js";
+import { listFiles } from "./testing.js";
+/**
+ * What an agent is told up front about its folder and this machine, beside its walls - what agents otherwise go looking
+ * for, a command at a time: whether there is anything above their folder, its git history, the toolchains' versions,
+ * where the build's dependencies come from. On the hycu runs a wandering model spent a third of its calls on these.
+ */
+/** The commands that say a toolchain's version, by the toolchain's name as `stackOf` gives it. */
+const VERSION_COMMANDS = {
+    Python: ["python3"],
+    Node: ["node", "npm"],
+    Java: ["java", "mvn", "gradle"],
+    Go: ["go"],
+    Rust: ["cargo"],
+    "C/C++": ["cc"],
+    Zig: ["zig"],
+    Odin: ["odin"],
+    Ruby: ["ruby"],
+    PHP: ["php"],
+    Elixir: ["elixir"],
+};
+/** How each command is asked its version. */
+const VERSION_ARGS = { java: ["-version"], go: ["version"], zig: ["version"], odin: ["version"], ruby: ["-v"], php: ["-v"], mvn: ["-v"] };
+const probed = new Map();
+/** The first line a command gives for its version on this machine - asked once - or nothing when it is not here. */
+function probeVersion(command) {
+    if (probed.has(command))
+        return probed.get(command);
+    const run = spawnSync(command, VERSION_ARGS[command] ?? ["--version"], { encoding: "utf8", timeout: 10_000, env: { ...process.env, JAVA_TOOL_OPTIONS: "" } });
+    const first = run.status === 0 || (run.status !== null && (run.stdout || run.stderr))
+        ? `${run.stdout ?? ""}\n${run.stderr ?? ""}`
+            .split("\n")
+            .map((line) => line.trim())
+            .find((line) => line !== "" && !line.startsWith("Picked up"))
+        : undefined;
+    const version = run.error === undefined ? first : undefined;
+    probed.set(command, version);
+    return version;
+}
+/** What the build tools of a toolchain fetch from, and where it is kept - said without a path. */
+const DEPENDENCIES = {
+    Java: "Maven's local repository is set for you, a cache shared by the project's modules: you need not look for it - and if " +
+        "you set `MAVEN_OPTS`, keep `-Dmaven.repo.local` from it. Gradle's home is set the same way. `JAVA_TOOL_OPTIONS` gives " +
+        'every JVM its temporary folder and home: leave it set; each JVM printing "Picked up JAVA_TOOL_OPTIONS" is expected.',
+    Node: "npm's cache is set for you, shared by the project's modules; packages install into the project's `node_modules`.",
+    Python: "pip's and uv's caches are set for you; packages install into the project's own virtual environment.",
+    Go: "Go's module cache and build cache are set for you, shared by the project's modules.",
+    Rust: "Cargo's home is set for you, shared by the project's modules.",
+};
+/** The implementation reqs of the module a folder is part of - `plain_modules/<module>/...` - from its spec, imports in. */
+function reqsOfModule(dir) {
+    const parts = resolve(dir).split(sep);
+    const index = parts.lastIndexOf(MODULES_DIR);
+    if (index < 0 || parts.length <= index + 1)
+        return [];
+    const module = parts[index + 1];
+    return projectImplementationReqs(projectRootOf(dir)).find((entry) => entry.module === module)?.reqs ?? [];
+}
+/** The block, for the agent's system prompt beside its walls. */
+export function workspaceBlock(input) {
+    const probe = input.probe ?? probeVersion;
+    const files = listFiles(input.dir);
+    const folder = files.length === 0
+        ? `- Your folder, \`${input.dir}\`, is empty: nothing is built yet, and there is nothing above it to find.`
+        : existsSync(join(input.dir, RECORD_FILE))
+            ? `- Your folder, \`${input.dir}\`, holds the code built so far, and its unit tests passed when it was committed: you need not run them before you change anything.`
+            : `- Your folder, \`${input.dir}\`, holds what was written so far, ${files.length} file${files.length === 1 ? "" : "s"}.`;
+    const lines = [
+        "<your folder and this machine>",
+        folder,
+        input.hasMyDiff
+            ? "- It is not a git repository, and none above it is yours: `my_diff` shows what you have changed in this pulse."
+            : "- It is not a git repository, and none above it is yours.",
+    ];
+    const needs = stackOf((input.implementationReqs ?? reqsOfModule(input.dir)).join("\n"));
+    for (const need of needs) {
+        const commands = VERSION_COMMANDS[need.toolchain] ?? need.commands;
+        // A bare number says nothing on its own: `npm 11.19.1`, not `11.19.1`.
+        const versions = commands
+            .map((command) => {
+            const version = probe(command);
+            return version === undefined ? undefined : /^v?\d/.test(version) ? `${command} ${version}` : version;
+        })
+            .filter((version) => version !== undefined);
+        lines.push(versions.length > 0
+            ? `- ${need.toolchain}: ${versions.join("; ")}.`
+            : `- ${need.toolchain}: not on this machine - report it with report_environment_error if the work needs it.`);
+        const dependencies = DEPENDENCIES[need.toolchain];
+        if (dependencies !== undefined && versions.length > 0)
+            lines.push(`  ${dependencies}`);
+    }
+    lines.push("- The network is open: the build tools fetch what the manifest declares.", "</your folder and this machine>");
+    return lines.join("\n");
+}

package/dist/regenerate-cli.js

@@ -0,0 +1,68 @@
+import { CONFIG_FILE, readProjectConfig } from "./config.js";
+import { c } from "./module-report.js";
+import { parseArgs, runLoop } from "./loop-cli.js";
+const USAGE = `usage: turri regenerate [file.plain] [frid ...] [options]
+
+Regenerates the module's code from its spec as it is now, and everything it requires, bottom first, as
+the chat does: what is left to regenerate - from what each module's code was regenerated from to its
+spec now - is planned into jobs, and they run one after the other until the code is regenerated from
+the spec, each followed by the conformance tests of what it regenerated when they are on. Then it says
+how each went. With functional specs named, those are regenerated though their spec did not change - as regenerate
+does in the chat with functionalities named: their code rewritten or started over, doing what the spec says.
+
+The project's config.turri.yaml, in the current directory, gives the defaults: module (the file to
+build when none is given), coding-model (the agents that build), harness-model (the planner), and
+conformance-tests.
+
+  --dry-run                plan the work and print the prompt of the first job, and run nothing (turri glimpse)
+  --start-over             start over, without asking, a codebase regenerated without a module it now requires
+  --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
+  --build-dir <dir>        default: plain_modules/<module>/code
+  --model <provider/id>    model for the agents
+
+  PLAIN_TEMPLATE_DIRS      colon-separated template directories`;
+/** Options of the build this replaced, and what to do instead. */
+const GONE = {
+    force: "to regenerate a functionality again, name it: turri regenerate <file.plain> <frid>",
+    only: "every module the spec requires is built, bottom first",
+    to: "the whole spec is built: stop the jobs to stop partway",
+    from: "every functionality not built is queued; built ones are skipped",
+    "conformance-root": "conformance tests are in plain_modules/<module>/tests",
+    "max-regression-rounds": "each conformance job runs the whole suite",
+    "try-it": "run turri release to try what is regenerated",
+    conformance: `set conformance-tests: in ${CONFIG_FILE}, or turri conform`,
+    "no-conformance": `set conformance-tests: false in ${CONFIG_FILE}`,
+    "template-dir": "set PLAIN_TEMPLATE_DIRS",
+};
+const { positional, options } = parseArgs(process.argv.slice(2), ["--only", "--force", "--conformance", "--no-conformance", "--try-it", "--dry-run", "--start-over", "--from-scratch"], USAGE);
+for (const [name, instead] of Object.entries(GONE)) {
+    if (options[name] !== undefined)
+        console.log(c.dim(`--${name} is no longer an option: ${instead}.`));
+}
+const named = positional[0] ?? readProjectConfig(process.cwd()).module;
+// Functional specs named after the file: regenerated again though their spec did not change.
+const again = positional.slice(1);
+if (!named) {
+    console.error(`${USAGE}\n\nNo file given, and ${CONFIG_FILE} names no module.`);
+    process.exit(1);
+}
+// A dry run starts nothing, and from scratch deletes before it plans: the two do not go together.
+if (options["from-scratch"] !== undefined && options["dry-run"] !== undefined) {
+    console.error("--from-scratch deletes the module's code before anything is planned: it cannot be a dry run.");
+    process.exit(1);
+}
+runLoop({
+    plainFile: named,
+    ...(options.model !== undefined ? { model: options.model } : {}),
+    ...(options["build-dir"] !== undefined ? { buildDir: options["build-dir"] } : {}),
+    dryRun: options["dry-run"] !== undefined,
+    startOver: options["start-over"] !== undefined,
+    ask: (loop) => again.length > 0
+        ? loop.regenerateAgain(named, again, options.model !== undefined ? { model: options.model } : {})
+        : options["from-scratch"] !== undefined
+            ? loop.fromScratch(named, options.model !== undefined ? { model: options.model } : {})
+            : loop.bringUp(named, options.model !== undefined ? { model: options.model } : {}),
+}).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/release-agent.js

@@ -0,0 +1,114 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from "@earendil-works/pi-coding-agent";
+import { createDeployTools, DEPLOY_TOOLS } from "./release-tools.js";
+import { hostDirOf, shortPath } from "./regenerate/release.js";
+import { projectDirOf } from "./regenerate/paths.js";
+import { ask, BEGIN, createExecutor } from "./pi.js";
+/** The person's own shell, in the deployed folder: it installs and runs what the release needs. */
+function hostBash(dir) {
+    const bash = createBashToolDefinition(dir);
+    return {
+        ...bash,
+        description: `${bash.description}\n\nIt runs on the person's own machine, in ${shortPath(dir)}. Never start a server here: activate does.`,
+    };
+}
+/** A file tool that writes, refused inside plain_modules: the built code is the spec's to change, never a release's. */
+function outsideBuiltCode(tool, dir) {
+    return {
+        ...tool,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            const path = resolve(dir, String(params.path ?? ""));
+            if (relative(dir, path).split(sep).includes("plain_modules")) {
+                throw new Error(`Not written: ${shortPath(path)} is built code. A release never changes it - a fix belongs in the spec.`);
+            }
+            return tool.execute(toolCallId, params, signal, onUpdate, ctx);
+        },
+    };
+}
+function shown(file, max = 40_000) {
+    const text = readFileSync(file, "utf8");
+    const body = text.length > max ? `${text.slice(0, max)}\n… [the rest of ${shortPath(file)} is not shown]` : text;
+    return `<file path="${shortPath(file)}">\n${body.trimEnd()}\n</file>`;
+}
+/**
+ * What the project says of itself, for the agent to find release guidance in: its AGENTS.md and its skills
+ * (`.agents/skills`, `.pi/skills`, `.claude/skills`), where turri runs and in the host codebase - once each, whole.
+ */
+export function projectNotes(dirs) {
+    const roots = [...new Set(dirs.map((dir) => resolve(dir)))];
+    const files = new Set();
+    for (const root of roots) {
+        const agents = join(root, "AGENTS.md");
+        if (existsSync(agents))
+            files.add(agents);
+        for (const skills of [".agents/skills", ".pi/skills", ".claude/skills"].map((folder) => join(root, folder))) {
+            if (!existsSync(skills))
+                continue;
+            for (const name of readdirSync(skills)) {
+                const skill = join(skills, name, "SKILL.md");
+                if (existsSync(skill))
+                    files.add(skill);
+            }
+        }
+    }
+    return [...files].map((file) => shown(file));
+}
+/** Run the release agent to its end; its last reply. */
+export async function runReleaseAgent(input) {
+    const { plainFile } = input;
+    const tools = createDeployTools({ cwd: input.cwd, state: input.state, defaultPlainFile: () => plainFile });
+    // It releases from the host codebase, which holds dist too.
+    const dir = hostDirOf(plainFile, input.cwd);
+    const notes = projectNotes([input.cwd, dir, projectDirOf(plainFile)]);
+    const said = input.guidance ?? input.state.guidance.get(input.afterPulse?.moduleName ?? "");
+    const fileTools = [
+        createReadToolDefinition(dir),
+        createLsToolDefinition(dir),
+        createGrepToolDefinition(dir),
+        createFindToolDefinition(dir),
+        // A guided release may say to change the host - a registration, an import.
+        outsideBuiltCode(createEditToolDefinition(dir), dir),
+        outsideBuiltCode(createWriteToolDefinition(dir), dir),
+    ];
+    const executor = await createExecutor({
+        // Its sessions are kept in the project, not in the folder it deploys.
+        cwd: projectDirOf(plainFile),
+        customTools: [...fileTools, hostBash(dir), ...tools],
+        tools: [...fileTools.map((tool) => tool.name), "bash", ...DEPLOY_TOOLS],
+        ...(input.model !== undefined ? { model: input.model } : {}),
+        role: "release",
+        system: [
+            "You get software that was just built running on the person's own machine, so they can try it. You ask no one: do it.",
+            `Your file tools and your shell start in ${dir}. Your shell is the person's own - not a sandbox.`,
+        ].join("\n"),
+        task: [
+            input.afterPulse !== undefined
+                ? `A pulse of module ${input.afterPulse.moduleName} just landed: ${input.afterPulse.subject}. You release it now, before the module's next pulse starts - if the project's release guidance says to release after a build or a pulse.`
+                : `Release ${shortPath(plainFile)} for the person to try, with the release tool, then do what it says.`,
+            "",
+            "First ask yourself: is there guidance for how this project releases it - what the person said below, the project's",
+            "notes and skills below, or anything else you find? If there is, call release with it as guidance, in full: the code is",
+            "put in dist/<module>, and the guidance takes it on from there. If there is none, call release without guidance: the",
+            "code is put in dist/<module> and started from there, as best it can be.",
+            ...(input.afterPulse !== undefined
+                ? [
+                    "",
+                    "Released after a pulse: when nothing in the guidance says to release after a build, call nothing and say so in a line.",
+                    "When release says it is already released, leave it at that.",
+                ]
+                : []),
+            ...(input.inModule !== undefined ? ["", `Release the codebase of module ${input.inModule}: pass in_module.`] : []),
+            ...(said !== undefined ? ["", "What the person said of how to release it:", said] : []),
+            ...(notes.length > 0 ? ["", "The project's notes and skills:", ...notes] : []),
+            "",
+            "End with what you did, in a line or two: where it runs, or why nothing was released.",
+        ].join("\n"),
+    });
+    try {
+        return await ask(executor, BEGIN, input.onDelta);
+    }
+    finally {
+        executor.dispose();
+    }
+}

package/dist/release-cli.js

@@ -0,0 +1,131 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { configForSpec, modelSpec, projectModels, readProjectConfig } from "./config.js";
+import { createDeployState } from "./release-tools.js";
+import { runReleaseAgent } from "./release-agent.js";
+import { listDeployed, runningDeployed, stopDeployed } from "./regenerate/release.js";
+const USAGE = `usage: turri release [file.plain] [options]
+
+Releases the module on top of the spec's requires chain, which holds the code of the ones below, and
+has an agent start it here, on this machine. The module's code, as its last commit has it, always
+goes in dist/<module> first. The agent looks for guidance on how this project releases it - what
+--guidance says, the project's AGENTS.md - and follows it from there when there is some: an
+integration its host application takes with the host's own scripts, say. When there is none, it
+reads how the code in dist runs, installs what it needs, and starts what serves. Either way it asks
+nothing, and stays in the foreground with the servers' output; Ctrl-C stops them.
+
+The project's config.turri.yaml gives the defaults: module (the file when none is given) and
+harness-model (the agent's model).
+
+  --in-module <module>     the codebase to take, when modules built on this one branch
+  --guidance <text>        how this project releases it: the scripts to run, in order
+  --model <provider/id>    the agent's model (default: harness-model)`;
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+const PROBLEMS = "If you are having problems, use chat mode to deploy: run turri and ask to try it.";
+function parseArgs(argv) {
+    const positional = [];
+    let model;
+    let inModule;
+    let guidance;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            console.log(USAGE);
+            process.exit(0);
+        }
+        else if (arg === "--model" || arg === "--harness-model")
+            model = argv[++i];
+        else if (arg === "--in-module")
+            inModule = argv[++i];
+        else if (arg === "--guidance")
+            guidance = argv[++i];
+        else if (arg.startsWith("-")) {
+            console.error(`unknown option: ${arg}\n\n${USAGE}`);
+            process.exit(1);
+        }
+        else
+            positional.push(arg);
+    }
+    return { plainFile: positional[0], model, inModule, guidance };
+}
+/** Follow every running server's output, prefixed with its name, until Ctrl-C or they have all ended. */
+function followLogs() {
+    const offsets = new Map();
+    return new Promise((done) => {
+        const tick = () => {
+            const running = runningDeployed();
+            for (const item of listDeployed()) {
+                let size = 0;
+                try {
+                    size = statSync(item.log).size;
+                }
+                catch {
+                    continue;
+                }
+                const from = offsets.get(item.log) ?? 0;
+                if (size <= from)
+                    continue;
+                const buffer = Buffer.alloc(size - from);
+                const fd = openSync(item.log, "r");
+                readSync(fd, buffer, 0, buffer.length, from);
+                closeSync(fd);
+                offsets.set(item.log, size);
+                for (const line of buffer.toString("utf8").split("\n").filter((l) => l !== ""))
+                    console.log(`${c.cyan(`[${item.name}]`)} ${line}`);
+            }
+            if (running.length === 0) {
+                clearInterval(timer);
+                console.log(c.dim("Everything it started has ended."));
+                done();
+            }
+        };
+        const timer = setInterval(tick, 500);
+    });
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const named = args.plainFile ?? readProjectConfig(process.cwd()).module;
+    if (named === undefined) {
+        console.error(`${USAGE}\n\nNo file given, and config.turri.yaml names no module.`);
+        process.exit(1);
+    }
+    const plainFile = resolve(named);
+    // A release follows steps - a script, a start command: the coding model does that well, thinking low.
+    const model = args.model ?? modelSpec(projectModels(configForSpec(plainFile)).coding);
+    const state = createDeployState();
+    const stopAll = async () => {
+        const stopped = await stopDeployed();
+        if (stopped.length > 0)
+            console.log(c.dim(`\nStopped ${stopped.join(", ")}.`));
+    };
+    process.on("SIGINT", () => {
+        void stopAll().then(() => process.exit(0));
+    });
+    console.log(c.dim(`\nworking out how to start it${model !== undefined ? ` (${model})` : ""}…\n`));
+    await runReleaseAgent({
+        plainFile,
+        cwd: process.cwd(),
+        state,
+        ...(model !== undefined ? { model } : {}),
+        ...(args.inModule !== undefined ? { inModule: args.inModule } : {}),
+        ...(args.guidance !== undefined ? { guidance: args.guidance } : {}),
+        onDelta: (delta) => process.stdout.write(delta),
+    });
+    console.log(`\n\n${c.dim(PROBLEMS)}`);
+    if (runningDeployed().length === 0)
+        process.exit(0);
+    console.log(c.green(c.bold("\nRunning - Ctrl-C stops it.")) + c.dim(" Its output follows.\n"));
+    await followLogs();
+    process.exit(0);
+}
+main().catch(async (error) => {
+    await stopDeployed();
+    console.error(error instanceof Error ? error.message : error);
+    console.error(`\n${PROBLEMS}`);
+    process.exit(1);
+});

package/dist/release-tools.js

@@ -0,0 +1,148 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { deployLogDir, deployTarget, describeDeployment, exportModule, hostDirOf, shortPath, startDeployed, stopDeployed, } from "./regenerate/release.js";
+import { projectDirOf } from "./regenerate/paths.js";
+import { haltTool } from "./loop-tools.js";
+export function createDeployState() {
+    return { released: new Map(), guidance: new Map() };
+}
+/** What the agent is to do once the code is in dist - in the deploy tool's answer, and the CLI agent's prompt. */
+export function deployGuide(dir) {
+    const where = shortPath(dir);
+    return [
+        `What to do now, to have the person try it - it runs on this machine, outside the sandbox, from ${where}:`,
+        `1. Find out how it runs: its README, its manifests (package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, pom.xml, build.gradle, docker-compose.yml) and entry points, in ${where}.`,
+        "2. Check the toolchains it needs are on this machine (`command -v node`, `python3 --version`, `go version`, ...). One missing: install it with this machine's package manager (brew on macOS, apt or dnf on Linux), then go on.",
+        "3. Install what it needs yourself, in your shell - dependencies into a virtual environment or node_modules, a build that fetches packages, an image pull. Do not ask the person: do it, and fix what fails.",
+        "4. Start anything that keeps running - a backend, a frontend's dev server - with activate, with the URL it serves at: never in the shell with & or nohup. An app with a backend and a frontend: start both, the backend first.",
+        "5. Then tell the person, briefly. Something that serves: only where to open it - the frontend's URL, and the API's in one line when there is one. A CLI or a library: a few commands to paste, run from the folder, with what they print. A port that is taken: say which and by what, and do not move the app to another.",
+        `Do not change the code in ${where} - it is a copy of what was built, and a fix belongs in the spec. A config file it needs made from its example (a .env from .env.example) is fine.`,
+    ].join("\n");
+}
+/**
+ * What the agent is to do on a guided release: the code is in dist, as on any release, and the guidance takes it on from
+ * there. The rules of a release to dist hold here too: what keeps running started with activate, and the built code never
+ * edited - and nothing put to the person.
+ */
+export function guidedGuide(deployment, guidance) {
+    const host = shortPath(deployment.hostDir ?? deployment.dir);
+    const dist = shortPath(deployment.dir);
+    const built = shortPath(deployment.buildDir);
+    return [
+        "The guidance for releasing it - follow it:",
+        guidance.trim(),
+        "",
+        `What to do now - on this machine, outside the sandbox, from ${host}:`,
+        `1. The code to release is in ${dist}: the last commit that landed whole. Take it from there, never from ${built}, where a pulse may be writing. Where the guidance's own tooling reads ${built}, point it at ${dist} if it can take another source; if it cannot, do by hand, from ${dist}, what it does.`,
+        `2. Read what the guidance leaves open - the scripts, files and commands it names, in ${host} - then do what it says, in its order. Where it says to change the host - a registration, an import, a config entry - change it. Never change ${built} or ${dist}: a fix to the code belongs in the spec.`,
+        "3. Run the project's scripts and install what it needs yourself, in your shell. Do not ask the person: do it, and fix what fails.",
+        "4. Start what keeps running - a start script, a dev server - with activate, with the URL it serves at - never in the shell with & or nohup.",
+        `5. Then tell the person briefly: what was done, what you changed in ${host} if anything, and where to open it or how to try it. Where the guidance does not fit what you find, say so, and do not guess past it.`,
+    ].join("\n");
+}
+function text(value, details = {}) {
+    return { content: [{ type: "text", text: value }], details };
+}
+/** The folder a command runs in: dist's, or - guided - the host codebase's, or one inside either. */
+function inside(current, dir) {
+    const base = current.hostDir ?? current.dir;
+    const target = resolve(base, dir ?? ".");
+    const within = (root) => {
+        const rel = relative(root, target);
+        return !rel.startsWith("..") && !isAbsolute(rel);
+    };
+    if (!within(base) && !within(current.dir))
+        throw new Error(`${dir} is outside ${shortPath(base)}: what release starts runs from there.`);
+    return target;
+}
+export function createDeployTools(options) {
+    const { state } = options;
+    const needsDeploy = () => {
+        if (state.current === undefined)
+            throw new Error("Nothing is released yet: call release first.");
+        return state.current;
+    };
+    const deploy = defineTool({
+        name: "release",
+        label: "Release",
+        description: "Release a module's code for the person to try - the module on top of the spec's requires chain, which holds the " +
+            "code of the ones below - stopping whatever an earlier release of it started. Before you call it, ask yourself: is " +
+            "there guidance for releasing this project - in what the person said, the project's AGENTS.md, a skill, or anything " +
+            "else you were given? An integration a host application loads, say, released with the host's own scripts. If there " +
+            "is, pass it as guidance, in full. Either way its last commit - what last landed whole - is exported to dist/<module> " +
+            "first; with guidance it is taken on from there as the guidance says, in the host codebase; without, it is started " +
+            "from there, as best it can be. Call it when the " +
+            "person wants to try, run, see or use what was built, and whenever guidance says to release after a pulse: when " +
+            "the module's last commit is already released it does nothing and says so, so never decide that yourself. It says " +
+            "what to do next.",
+        promptSnippet: "release the regenerated code for the person to try - as the project's release guidance says, or to dist/<module> - then activate it",
+        parameters: Type.Object({
+            plain_file: Type.Optional(Type.String({ description: "A .plain file of the module. Default: the project's module from config.turri.yaml." })),
+            in_module: Type.Optional(Type.String({ description: "The codebase to take, when modules built on this one branch" })),
+            again: Type.Optional(Type.Boolean({ description: "Release even when the module's last commit is already released - only when what the last release said to do was not done." })),
+            guidance: Type.Optional(Type.String({ description: "The guidance for releasing this project, whole, from wherever it is - the person, AGENTS.md, a skill: the scripts to run and in which order, where the code goes. Omit when there is none." })),
+        }),
+        async execute(_id, params) {
+            const named = params.plain_file ?? options.defaultPlainFile();
+            if (named === undefined)
+                throw new Error("Which spec? config.turri.yaml names no module: pass plain_file.");
+            const plainFile = resolve(options.cwd, named);
+            const target = deployTarget(plainFile, params.in_module);
+            const guidance = params.guidance?.trim() || undefined;
+            // Released already: the module's last commit is what the last release shipped. Nothing is exported or stopped -
+            // releasing it again would only restart what runs - so it is safe to call after every pulse.
+            const last = state.released.get(target.entry.moduleName);
+            if (last !== undefined && !params.again && target.commit.startsWith(last.commit) && last.way === (guidance === undefined ? "dist" : "guided")) {
+                state.current = last;
+                return text(`Already released: ${target.entry.moduleName}'s last commit, ${last.commit} (${last.subject}), is what the last release shipped, and what that release said to do was done then. Nothing to do - what runs is left running. Say so in a line.`, { module: last.moduleName, commit: last.commit, already: true });
+            }
+            // What the last release started runs from what is about to be replaced.
+            const stopped = await stopDeployed({ moduleName: target.entry.moduleName });
+            // Always the last commit, clean, in dist first; guidance takes it on from there.
+            const exported = exportModule(plainFile, params.in_module);
+            const deployment = guidance === undefined ? exported : { ...exported, way: "guided", hostDir: hostDirOf(plainFile, options.cwd) };
+            state.current = deployment;
+            state.released.set(deployment.moduleName, deployment);
+            if (guidance !== undefined)
+                state.guidance.set(deployment.moduleName, guidance);
+            return text([
+                describeDeployment(deployment),
+                ...(stopped.length > 0 ? [`Stopped what the last release started: ${stopped.join(", ")}.`] : []),
+                "",
+                guidance === undefined ? deployGuide(deployment.dir) : guidedGuide(deployment, guidance),
+            ].join("\n"), { module: deployment.moduleName, way: deployment.way, dir: deployment.dir, ...(deployment.hostDir !== undefined ? { host: deployment.hostDir } : {}), commit: deployment.commit });
+        },
+    });
+    const startTool = defineTool({
+        name: "activate",
+        label: "Activate",
+        description: "Start something that keeps running - a backend, a frontend's dev server - from the deployed folder, on this " +
+            "machine: in the background, its output kept, stopped on the next release, on /halt and when turri exits. " +
+            "With `url`, waits until something answers there and says so, or shows the end of its output. A port something " +
+            "else holds is said, and nothing is started.",
+        promptSnippet: "start a server of the deployed code, and wait for it to answer",
+        parameters: Type.Object({
+            name: Type.String({ description: "A short name for it: backend, frontend, app" }),
+            command: Type.String({ description: "The command that starts it, as run from its folder" }),
+            url: Type.Optional(Type.String({ description: "Where it serves, e.g. http://localhost:5173 - it is ready once this answers" })),
+            dir: Type.Optional(Type.String({ description: "A folder inside the deployed one to run it in, e.g. frontend. Default: the deployed folder." })),
+        }),
+        async execute(_id, params) {
+            const current = needsDeploy();
+            const started = await startDeployed({
+                name: params.name,
+                command: params.command,
+                dir: inside(current, params.dir),
+                moduleName: current.moduleName,
+                logDir: deployLogDir(projectDirOf(current.plainFile)),
+                ...(params.url !== undefined ? { url: params.url } : {}),
+            });
+            return text(started.text, { ok: started.ok, ...(started.process !== undefined ? { pid: started.process.pid, log: started.process.log } : {}) });
+        },
+    });
+    // The one halt: with the pulses in the conversation, and without them for the release agent.
+    const stopTool = haltTool(options.jobs !== undefined ? { jobs: options.jobs } : {});
+    return [deploy, startTool, stopTool];
+}
+export const DEPLOY_TOOLS = ["release", "activate", "halt"];