agent-cloud-kit 0.0.0-stage → 1.0.0-rc.0

package/dist/run.js

@@ -0,0 +1,113 @@
+/**
+ * @file Process runner: the single place where child processes are spawned.
+ * Modules that execute processes receive a `Run` (or a `Capture`) so tests can inject a fake.
+ */
+import { spawn } from "node:child_process";
+/** Signal sent to a process group that ran past its time limit. */
+const KILL_SIGNAL = "SIGKILL";
+/** File descriptor of the parent's stderr, reused as the child's stdout and stderr. */
+const PARENT_STDERR = 2;
+/** Error thrown when a child is killed because it ran past its time limit. */
+export class RunTimeoutError extends Error {
+    /**
+     * Builds the error.
+     *
+     * @param cmd - Executable that timed out.
+     * @param ms - Time limit, in milliseconds.
+     */
+    constructor(cmd, ms) {
+        super(`${cmd} timed out after ${ms}ms`);
+        this.name = "RunTimeoutError";
+    }
+}
+/**
+ * Maps an output mode to the spawn stdio setting.
+ *
+ * @param mode - Output mode.
+ * @returns `"inherit"`, or stdin ignored and stdout plus stderr on the parent's stderr.
+ */
+function stdioFor(mode) {
+    return mode === "stderr" ? ["ignore", PARENT_STDERR, PARENT_STDERR] : "inherit";
+}
+/**
+ * Kills a detached child together with its process group; never throws.
+ *
+ * @param pid - Process id of the group leader.
+ */
+function killGroup(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, KILL_SIGNAL);
+    }
+    catch {
+        try {
+            process.kill(pid, KILL_SIGNAL);
+        }
+        catch {
+            // NOTE: the process already exited.
+        }
+    }
+}
+/**
+ * Spawns a process and settles when it exits, or when it runs past its time limit.
+ *
+ * @param cmd - Executable to run.
+ * @param args - Arguments passed to the executable.
+ * @param opts - Options.
+ * @param stdio - Spawn stdio setting.
+ * @param onStdout - Receives stdout chunks when stdout is piped.
+ * @returns Resolves on exit code 0.
+ * @throws When the process cannot be spawned, exits non-zero, is killed by a signal or times out.
+ */
+function spawnAndWait(cmd, args, opts, stdio, onStdout) {
+    return new Promise((resolve, reject) => {
+        const limited = opts.timeoutMs !== undefined;
+        const child = spawn(cmd, args, { stdio, cwd: opts.cwd, env: opts.env, detached: limited });
+        if (onStdout)
+            child.stdout?.on("data", onStdout);
+        let timer;
+        if (limited) {
+            const ms = opts.timeoutMs ?? 0;
+            timer = setTimeout(() => {
+                killGroup(child.pid);
+                reject(new RunTimeoutError(cmd, ms));
+            }, ms);
+        }
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0)
+                return resolve();
+            reject(new Error(`${cmd} exited with ${code === null ? `signal ${signal}` : `code ${code}`}`));
+        });
+    });
+}
+/**
+ * Spawns a process with inherited stdio, or with its output sent to stderr.
+ *
+ * @param cmd - Executable to run.
+ * @param args - Arguments passed to the executable.
+ * @param opts - Optional working directory, environment, output mode and timeout.
+ * @returns Resolves on exit code 0; rejects with the exit code in the message otherwise.
+ * @throws When the process cannot be spawned, exits with a non-zero code or signal, or times out
+ *   (`RunTimeoutError`).
+ */
+export const runProcess = (cmd, args, opts = {}) => spawnAndWait(cmd, args, opts, stdioFor(opts.stdio ?? "inherit"));
+/**
+ * Spawns a process and collects its stdout; stdin and stderr are ignored.
+ *
+ * @param cmd - Executable to run.
+ * @param args - Arguments passed to the executable.
+ * @param opts - Optional working directory, environment and timeout.
+ * @returns The stdout text.
+ * @throws When the process cannot be spawned, exits with a non-zero code or signal, or times out.
+ */
+export const captureProcess = async (cmd, args, opts = {}) => {
+    const chunks = [];
+    await spawnAndWait(cmd, args, opts, ["ignore", "pipe", "ignore"], (chunk) => chunks.push(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+};

package/dist/session.js

@@ -0,0 +1,245 @@
+/**
+ * @file The `session` phase: runs from the SessionStart hook of a cloud session, reports the
+ * state of the machine, wires the pinned tools into the session and runs the repo's session steps.
+ */
+import { appendFileSync, existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { findProxyCa, shellQuote } from "./ca.js";
+import { readConfig } from "./config.js";
+import { CONFIG_FILE, GIT_FETCH_TIMEOUT_MS, OUTPUT_PREFIX, PACKAGE, SETUP_SLOW_MS } from "./constants.js";
+import { configImages, defaultBranch, readToolVersions } from "./detect.js";
+import { realDocker } from "./docker.js";
+import { pathLine, toolBinDirs } from "./installers.js";
+import { linkDir } from "./launcher.js";
+import { resolveNotes } from "./manual.js";
+import { RunTimeoutError } from "./run.js";
+import { fingerprint, readState } from "./state.js";
+/** Generic note shown in every cloud session. */
+const GENERIC_NOTE = "you are in a Claude Code cloud session. There are no open ports or previews: test against localhost. gh pr and gh issue fail (the GitHub proxy blocks GraphQL): use gh api (REST).";
+/** Milliseconds in a second. */
+const MS_PER_SECOND = 1000;
+/** Seconds in a minute. */
+const SECONDS_PER_MINUTE = 60;
+/** Environment variable holding the file where the session reads extra exports from. */
+const ENV_FILE_VAR = "CLAUDE_ENV_FILE";
+/** Environment variable that exposes the proxy CA path to the session. */
+const PROXY_CA_VAR = "CLOUD_PROXY_CA";
+/** Path of the shallow marker inside a git directory. */
+const SHALLOW_MARKER = join(".git", "shallow");
+/** Environment that keeps git from ever prompting. */
+const GIT_NON_INTERACTIVE = { GIT_TERMINAL_PROMPT: "0" };
+/** Time limit of each repo session step, in milliseconds. */
+export const SESSION_STEP_TIMEOUT_MS = 120_000;
+/**
+ * Lists the directories to put first on PATH: the pinned tools' bin dirs, then the folder of the
+ * `agent-cloud-kit` link, so `agent-cloud-kit doctor` resolves in the session.
+ *
+ * @param versions - Requested versions by tool.
+ * @param toolsDir - Tools directory.
+ * @param resolved - Versions setup installed (`MachineState.resolved`).
+ * @returns The directories, tools first.
+ * @example
+ * pathDirs({ node: "22" }, "/opt/agent-cloud-kit", { node: "22.12.0" }); // ["/opt/agent-cloud-kit/node-22.12.0/bin", "/opt/agent-cloud-kit/bin"]
+ */
+export function pathDirs(versions, toolsDir, resolved) {
+    return [...toolBinDirs(versions, toolsDir, resolved), linkDir(toolsDir)];
+}
+/**
+ * Builds the environment for repo commands: some directories first on PATH, plus the CA.
+ *
+ * @param dirs - Directories to put first on PATH (`pathDirs`).
+ * @param baseEnv - Environment to extend; it is not modified.
+ * @param ca - Proxy CA path, when found.
+ * @returns A new environment.
+ * @example
+ * toolsEnv(["/opt/agent-cloud-kit/node-24.14.1/bin"], process.env, "/root/.ccr/ca-bundle.crt");
+ */
+export function toolsEnv(dirs, baseEnv, ca) {
+    const path = [...dirs, ...(baseEnv.PATH ? [baseEnv.PATH] : [])].join(":");
+    const env = { ...baseEnv, PATH: path };
+    if (ca)
+        env[PROXY_CA_VAR] = ca;
+    return env;
+}
+/**
+ * Formats a duration in milliseconds as `<m>m<s>s`.
+ *
+ * @param ms - Milliseconds.
+ * @returns For example `4m10s`.
+ */
+function minutesSeconds(ms) {
+    const total = Math.round(ms / MS_PER_SECOND);
+    return `${Math.floor(total / SECONDS_PER_MINUTE)}m${total % SECONDS_PER_MINUTE}s`;
+}
+/**
+ * Computes the fingerprint the machine should have, using the package version stored in the state
+ * so a package upgrade alone is not reported here (setup's relaunch handles versions).
+ *
+ * @param repo - Repo root.
+ * @param config - Repo config.
+ * @param state - Recorded state.
+ * @returns The expected fingerprint.
+ * @example
+ * expectedFingerprint("/home/user/app", config, state) === state.fingerprint;
+ */
+export function expectedFingerprint(repo, config, state) {
+    return fingerprint(config, readToolVersions(repo), configImages(config, repo), state.packageVersion);
+}
+/**
+ * Describes what is wrong with the machine, from the recorded state.
+ *
+ * @param repo - Repo root.
+ * @param config - Repo config.
+ * @param state - Recorded state, if any.
+ * @returns Warning messages, without prefix.
+ */
+function machineWarnings(repo, config, state) {
+    if (!state) {
+        return [
+            `the environment setup did not run for ${basename(repo)}. Set the setup script of the environment in claude.ai to: npx -y ${PACKAGE}@1 setup`,
+        ];
+    }
+    const out = [];
+    const failed = state.steps.filter((s) => !s.ok).map((s) => s.name);
+    if (failed.length)
+        out.push(`setup failed: ${failed.join(", ")}. Run agent-cloud-kit doctor.`);
+    if (expectedFingerprint(repo, config, state) !== state.fingerprint) {
+        out.push("the machine was prepared with another configuration. Edit the setup script field in claude.ai (any change) so it is rebuilt.");
+    }
+    const total = state.steps.reduce((sum, s) => sum + s.ms, 0);
+    if (total > SETUP_SLOW_MS)
+        out.push(`setup took ${minutesSeconds(total)}, close to the ~5 minute limit.`);
+    return out;
+}
+/**
+ * Appends the PATH line and the CA export to `$CLAUDE_ENV_FILE`, when it is set; never throws.
+ *
+ * @param env - Process environment.
+ * @param lines - Lines to write; empty ones are dropped.
+ * @returns An error line when the file could not be written; undefined otherwise.
+ */
+function writeEnvFile(env, lines) {
+    const file = env[ENV_FILE_VAR];
+    const body = lines.filter(Boolean);
+    if (!file || !body.length)
+        return undefined;
+    try {
+        appendFileSync(file, `${body.join("\n")}\n`);
+        return undefined;
+    }
+    catch (err) {
+        return `could not write ${ENV_FILE_VAR} (${file}): ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+/**
+ * Makes the clone complete and brings the default branch, so `git diff main...` works.
+ * Each git call is an argv array; the branch is validated before it is used in a refspec.
+ *
+ * @param repo - Repo root.
+ * @param run - Process runner.
+ * @param env - Environment for git.
+ */
+async function syncGit(repo, run, env) {
+    const opts = { cwd: repo, env: { ...env, ...GIT_NON_INTERACTIVE }, stdio: "stderr" };
+    const fetchOpts = { ...opts, timeoutMs: GIT_FETCH_TIMEOUT_MS };
+    if (existsSync(join(repo, SHALLOW_MARKER))) {
+        await run("git", ["fetch", "-q", "--unshallow", "origin"], fetchOpts).catch(() => undefined);
+    }
+    const branch = defaultBranch(repo);
+    const valid = await run("git", ["check-ref-format", "--branch", branch], opts).then(() => !branch.startsWith("-"), () => false);
+    if (!valid)
+        return;
+    await run("git", ["fetch", "-q", "origin", `${branch}:refs/remotes/origin/${branch}`], fetchOpts).catch(() => undefined);
+}
+/**
+ * Runs the repo's session commands in order; a failure is reported and does not stop the rest.
+ * Their output goes to stderr, so it never lands in Claude's context, and each one is killed
+ * after `SESSION_STEP_TIMEOUT_MS`.
+ *
+ * @param repo - Repo root.
+ * @param commands - Shell commands from the config (repo-owned by design).
+ * @param run - Process runner.
+ * @param env - Environment for the commands.
+ * @returns One line per failed or timed out command.
+ */
+async function runSessionSteps(repo, commands, run, env) {
+    const problems = [];
+    for (const command of commands) {
+        try {
+            await run("bash", ["-c", command], { cwd: repo, env, stdio: "stderr", timeoutMs: SESSION_STEP_TIMEOUT_MS });
+        }
+        catch (err) {
+            problems.push(`${err instanceof RunTimeoutError ? "session step timed out" : "session step failed"}: ${command}`);
+        }
+    }
+    return problems;
+}
+/**
+ * Starts Docker without ever throwing, even when the injected operation does.
+ *
+ * @param docker - Docker operations.
+ * @returns An error message, or undefined on success.
+ */
+function startDocker(docker) {
+    try {
+        return docker.start();
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+}
+/**
+ * Does the work of `session`; may throw, the caller turns that into a line.
+ *
+ * @param repo - Repo root.
+ * @param ctx - Dependencies.
+ * @param out - Output lines, filled in order.
+ */
+async function sessionBody(repo, ctx, out) {
+    out.push(GENERIC_NOTE);
+    if (!existsSync(join(repo, CONFIG_FILE)))
+        return;
+    const { config, errors } = readConfig(repo);
+    out.push(...errors);
+    const versions = readToolVersions(repo);
+    const state = readState(ctx.toolsDir, repo);
+    const dirs = pathDirs(versions, ctx.toolsDir, state?.resolved ?? {});
+    const ca = findProxyCa(ctx.env, existsSync);
+    const envFileProblem = writeEnvFile(ctx.env, [pathLine(dirs), ca ? `export ${PROXY_CA_VAR}=${shellQuote(ca)}` : ""]);
+    if (envFileProblem)
+        out.push(envFileProblem);
+    if (config)
+        out.push(...machineWarnings(repo, config, state));
+    const missing = (config?.requiredEnv ?? []).filter((name) => !ctx.env[name]);
+    if (missing.length)
+        out.push(`missing environment variables: ${missing.join(", ")}`);
+    const notes = resolveNotes(repo, config?.notes)?.trim();
+    if (notes)
+        out.push(notes);
+    const dockerProblem = startDocker(ctx.docker ?? realDocker);
+    if (dockerProblem)
+        out.push(`could not start dockerd: ${dockerProblem}`);
+    const env = toolsEnv(dirs, ctx.env, ca);
+    await syncGit(repo, ctx.run, env);
+    out.push(...(await runSessionSteps(repo, config?.session ?? [], ctx.run, env)));
+}
+/**
+ * Runs the session phase for a repo.
+ *
+ * @param repo - Repo root.
+ * @param ctx - Dependencies (environment, tools dir, runner, package version, Docker).
+ * @returns The lines to print on stdout, each with the output prefix; never rejects.
+ * @example
+ * (await session("/home/user/app", { env: process.env, toolsDir, run: runProcess, packageVersion: "1.0.0" }))
+ *   .forEach((line) => console.log(line));
+ */
+export async function session(repo, ctx) {
+    const out = [];
+    try {
+        await sessionBody(repo, ctx, out);
+    }
+    catch (err) {
+        out.push(`session error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return out.map((line) => OUTPUT_PREFIX + line);
+}

package/dist/setup.js

@@ -0,0 +1,277 @@
+/**
+ * @file The `setup` phase for one repo: runs as root before Claude starts, installs the pinned
+ * tools, apt packages and Docker images and copies this package into the tools dir, then runs the
+ * repo's setup steps and records the result. Values from the repo config are untrusted: they are
+ * validated and always passed as argv, never interpolated into a shell string.
+ */
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { findProxyCa } from "./ca.js";
+import { readConfig } from "./config.js";
+import { APT_STEP_TIMEOUT_MS, DOCKERD_LOG, DOCKER_PULL_TIMEOUT_MS, PULL_JOBS, RUNNING_PACKAGE_ROOT, SETUP_STEP_TIMEOUT_MS } from "./constants.js";
+import { configImages, readToolVersions } from "./detect.js";
+import { realDocker } from "./docker.js";
+import { curlNodeIndex, installTools, resolveVersions } from "./installers.js";
+import { linkPath, packageBin, packageInstallDir } from "./launcher.js";
+import { pathDirs, toolsEnv } from "./session.js";
+import { fingerprint, writeState } from "./state.js";
+import { lanes, step } from "./steps.js";
+/** Strict Debian package name; anything else is never handed to apt-get. */
+const DEBIAN_PACKAGE_NAME = /^[a-z0-9][a-z0-9+.-]+$/;
+/** Only scheme accepted for apt repo setup scripts. */
+const HTTPS_PREFIX = "https://";
+/** Script that downloads an apt repo setup script (`$1`) and runs it; fails if curl fails. */
+const APT_REPO_SCRIPT = 'set -o pipefail; curl -1sLf -- "$1" | bash';
+/** Placeholder for `$0` in inline bash scripts. */
+const SCRIPT_NAME = "_";
+/** Environment that keeps apt from asking questions. */
+const APT_ENV = { DEBIAN_FRONTEND: "noninteractive" };
+/** Characters that make an image reference unsafe to pass on: any whitespace. */
+const WHITESPACE = /\s/;
+/** Prefix of the name of each repo setup step. */
+const SETUP_STEP_PREFIX = "setup: ";
+/** Manifest file of this package. */
+const MANIFEST = "package.json";
+/** Compiled code of this package, copied together with the manifest. */
+const DIST_DIR = "dist";
+/** Entry point of the CLI, relative to the package root. */
+const CLI_ENTRY = join(DIST_DIR, "cli.js");
+/** Mode of the CLI entry point: executable by everyone. */
+const EXECUTABLE_MODE = 0o755;
+/**
+ * Builds a step that always fails with a message, for input that is refused without running it.
+ *
+ * @param name - Step name.
+ * @param message - Why it was refused.
+ * @returns The failed result.
+ */
+function refused(name, message) {
+    return step(name, async () => {
+        throw new Error(message);
+    });
+}
+/**
+ * Runs the apt work in series: repo scripts, then `apt-get update`, then `apt-get install`.
+ *
+ * @param config - Repo config.
+ * @param deps - Shared dependencies.
+ * @returns One result per apt repo and refused package, plus update (when there is a repo or a
+ *   valid package) and install (when there is a valid package).
+ */
+async function aptLane(config, deps) {
+    if (!config.aptRepos.length && !config.apt.length)
+        return [];
+    const env = { ...deps.env, ...APT_ENV };
+    const results = [];
+    for (const url of config.aptRepos) {
+        const name = `apt repo ${url}`;
+        if (!url.startsWith(HTTPS_PREFIX)) {
+            results.push(await refused(name, `apt repo must be an ${HTTPS_PREFIX} URL`));
+            continue;
+        }
+        results.push(await step(name, () => deps.run("bash", ["-c", APT_REPO_SCRIPT, SCRIPT_NAME, url], { env, timeoutMs: APT_STEP_TIMEOUT_MS })));
+    }
+    const valid = config.apt.filter((pkg) => DEBIAN_PACKAGE_NAME.test(pkg));
+    for (const pkg of config.apt.filter((p) => !valid.includes(p))) {
+        results.push(await refused(`apt package ${pkg}`, "invalid Debian package name"));
+    }
+    if (!valid.length && !config.aptRepos.length)
+        return results;
+    results.push(await step("apt-get update", () => deps.run("apt-get", ["update", "-q"], { env, timeoutMs: APT_STEP_TIMEOUT_MS })));
+    if (valid.length) {
+        results.push(await step("apt-get install", () => deps.run("apt-get", ["install", "-y", "-q", "--", ...valid], { env, timeoutMs: APT_STEP_TIMEOUT_MS })));
+    }
+    return results;
+}
+/**
+ * Pulls images with at most `PULL_JOBS` pulls at a time, keeping the input order in the results.
+ *
+ * @param images - Validated image references.
+ * @param deps - Shared dependencies.
+ * @returns One result per image.
+ */
+async function pullAll(images, deps) {
+    const results = new Array(images.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < images.length) {
+            const index = next++;
+            const image = images[index];
+            results[index] = await step(`docker pull ${image}`, () => deps.run("docker", ["pull", "-q", image], { env: deps.env, timeoutMs: DOCKER_PULL_TIMEOUT_MS }));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(PULL_JOBS, images.length) }, worker));
+    return results;
+}
+/**
+ * Starts Docker and pulls the images. Docker is started even with no images, because setup
+ * steps may use it (`docker build`); only `docker.pull: false` leaves it alone.
+ *
+ * @param config - Repo config.
+ * @param images - Image references from the config or detection (untrusted).
+ * @param docker - Docker operations.
+ * @param deps - Shared dependencies.
+ * @returns A failed `docker` step when the daemon does not answer, otherwise one result per image.
+ */
+async function dockerLane(config, images, docker, deps) {
+    if (config.docker.pull === false)
+        return [];
+    const results = [];
+    const valid = images.filter((image) => !WHITESPACE.test(image) && !image.startsWith("-") && image !== "");
+    for (const image of images.filter((i) => !valid.includes(i))) {
+        results.push(await refused(`docker pull ${image}`, "invalid image reference"));
+    }
+    const up = await docker.ensure().catch(() => false);
+    if (!up)
+        return [...results, await refused("docker", `dockerd did not start; see ${DOCKERD_LOG}`)];
+    return [...results, ...(await pullAll(valid, deps))];
+}
+/**
+ * Runs the repo's setup commands in series, in the repo, with the pinned tools on PATH.
+ *
+ * @param commands - Shell commands from the config (repo-owned by design).
+ * @param deps - Shared dependencies; `env` already carries the tools PATH.
+ * @returns One result per command.
+ */
+async function setupSteps(commands, deps) {
+    const results = [];
+    for (const command of commands) {
+        results.push(await step(SETUP_STEP_PREFIX + command, () => deps.run("bash", ["-c", command], { cwd: deps.repo, env: deps.env, timeoutMs: SETUP_STEP_TIMEOUT_MS })));
+    }
+    return results;
+}
+/**
+ * Points a link at a target, replacing any old link atomically.
+ *
+ * @param link - Link path.
+ * @param target - Link target.
+ * @throws When the link cannot be created.
+ */
+function replaceLink(link, target) {
+    mkdirSync(dirname(link), { recursive: true });
+    const temp = `${link}.${process.pid}.tmp`;
+    rmSync(temp, { force: true });
+    symlinkSync(target, temp);
+    renameSync(temp, link);
+}
+/**
+ * Reads the version from a package manifest; never throws.
+ *
+ * @param root - Package root.
+ * @returns The version, or undefined when the manifest is missing or invalid.
+ */
+function manifestVersion(root) {
+    try {
+        const version = JSON.parse(readFileSync(join(root, MANIFEST), "utf8")).version;
+        return typeof version === "string" ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Copies the package manifest and `dist/` into a target folder, through a temp folder renamed
+ * into place, and leaves the CLI entry point executable.
+ *
+ * @param source - Root of the running package.
+ * @param target - Destination package root.
+ * @param version - Version expected in the source manifest.
+ * @throws When the source is another version or the copy fails.
+ */
+function copyPackage(source, target, version) {
+    const found = manifestVersion(source);
+    if (found !== version)
+        throw new Error(`the package at ${source} is ${found ?? "unknown"}, not ${version}`);
+    const temp = `${target}.${process.pid}.tmp`;
+    rmSync(temp, { recursive: true, force: true });
+    mkdirSync(temp, { recursive: true });
+    cpSync(join(source, MANIFEST), join(temp, MANIFEST));
+    cpSync(join(source, DIST_DIR), join(temp, DIST_DIR), { recursive: true });
+    chmodSync(join(temp, CLI_ENTRY), EXECUTABLE_MODE);
+    rmSync(target, { recursive: true, force: true });
+    renameSync(temp, target);
+}
+/**
+ * Copies the running package into `<toolsDir>/pkg/<version>` (unless that version is already
+ * there) and links its binary, without npm or network, so it works before anything else runs.
+ *
+ * @param version - Version of this package.
+ * @param toolsDir - Tools directory.
+ * @param source - Root of the running package.
+ * @returns The self install result.
+ */
+function selfInstall(version, toolsDir, source) {
+    return step(`self install ${version}`, async () => {
+        const target = packageInstallDir(toolsDir, version);
+        if (manifestVersion(target) !== version)
+            copyPackage(source, target, version);
+        const bin = packageBin(toolsDir, version);
+        replaceLink(bin, relative(dirname(bin), join(target, CLI_ENTRY)));
+        replaceLink(linkPath(toolsDir), bin);
+    });
+}
+/**
+ * Runs the phases and writes the state; may throw, the caller turns that into a step. Phase 1
+ * runs the tools, apt, Docker and the self install in parallel lanes; phase 2 runs the repo's
+ * setup steps. The fingerprint reads versions and images again after the setup steps, because
+ * those steps may generate the files they come from and `session` reads them later.
+ *
+ * @param repo - Repo root.
+ * @param config - Valid repo config.
+ * @param ctx - Dependencies.
+ * @returns The recorded state.
+ */
+async function runPhases(repo, config, ctx) {
+    const env = ctx.env ?? process.env;
+    const versions = readToolVersions(repo);
+    const images = configImages(config, repo);
+    const base = { repo, toolsDir: ctx.toolsDir, run: ctx.run, env };
+    let resolved = {};
+    const toolsLane = async () => {
+        const resolution = await resolveVersions(versions, curlNodeIndex(ctx.run, env));
+        resolved = resolution.resolved;
+        return [...resolution.results, ...(await installTools(resolved, ctx.toolsDir, ctx.run, env))];
+    };
+    const steps = await lanes(toolsLane, () => aptLane(config, base), () => dockerLane(config, images, ctx.docker ?? realDocker, base), async () => [await selfInstall(ctx.packageVersion, ctx.toolsDir, ctx.packageRoot ?? RUNNING_PACKAGE_ROOT)]);
+    const dirs = pathDirs(versions, ctx.toolsDir, resolved);
+    const toolsDeps = { ...base, env: toolsEnv(dirs, env, findProxyCa(env, existsSync)) };
+    steps.push(...(await setupSteps(config.setup, toolsDeps)));
+    const state = {
+        fingerprint: fingerprint(config, readToolVersions(repo), configImages(config, repo), ctx.packageVersion),
+        packageVersion: ctx.packageVersion,
+        finishedAt: new Date().toISOString(),
+        steps,
+        resolved,
+    };
+    const saved = await step("write state", async () => writeState(ctx.toolsDir, repo, state));
+    return saved.ok ? state : { ...state, steps: [...steps, saved] };
+}
+/**
+ * Prepares the machine for one repo: tools, apt, Docker and the self install in parallel lanes
+ * (apt work in series inside its lane), then the repo's setup steps; writes the state.
+ *
+ * @param repo - Repo root.
+ * @param ctx - Dependencies (tools dir, runner, package version, optional env and Docker).
+ * @returns The state; when the config is missing or invalid, a state with one failed `config`
+ *   step that is not written. Never rejects.
+ * @example
+ * const state = await setupRepo("/home/user/app", { toolsDir: "/opt/agent-cloud-kit", run: runProcess, packageVersion: "1.0.0" });
+ */
+export async function setupRepo(repo, ctx) {
+    const failed = (name, error) => ({
+        fingerprint: "",
+        packageVersion: ctx.packageVersion,
+        finishedAt: new Date().toISOString(),
+        steps: [{ name, ok: false, ms: 0, error }],
+        resolved: {},
+    });
+    const { config, errors } = readConfig(repo);
+    if (!config)
+        return failed("config", errors.join("; ") || "no config");
+    try {
+        return await runPhases(repo, config, ctx);
+    }
+    catch (err) {
+        return failed("setup", err instanceof Error ? err.message : String(err));
+    }
+}