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

package/dist/cli.js

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+/**
+ * @file Command line entry point of agent-cloud-kit: wires `setup`, `session`, `docker`, `doctor`,
+ * `init`, `manual` and `prepare` to their modules, relaunching or delegating to the version each
+ * repo pins.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import { readConfig } from "./config.js";
+import { CONFIG_FILE, DOCKERD_LOG, OUTPUT_PREFIX, RUNNING_PACKAGE_ROOT, homeDir, toolsDir } from "./constants.js";
+import { doctor } from "./doctor.js";
+import { dockerResponds, realDocker } from "./docker.js";
+import { init } from "./init.js";
+import { findRepos, packageBin, planSetup, relaunch } from "./launcher.js";
+import { MANUAL_FILE, writeManual } from "./manual.js";
+import { EXIT_INTERRUPTED, InterruptedError, branchDay, prepare } from "./prepare/index.js";
+import { captureProcess, runProcess } from "./run.js";
+import { session } from "./session.js";
+import { setupRepo } from "./setup.js";
+/** Help text shown by `--help`. */
+const HELP = `${OUTPUT_PREFIX}prepares Claude Code cloud sessions.
+
+Usage: agent-cloud-kit <command>
+
+Commands:
+  setup [--repo <path>]  prepare the machine for every repo in the home dir (or only <path>)
+  session                report the machine state and wire the tools into the session
+  docker                 start the Docker daemon and wait until it answers
+  doctor                 check the network allowlist, tools, Docker and the machine state
+  init                   create .claude/cloud.json and register the SessionStart hook
+  manual                 write docs/agent-cloud.md from .claude/cloud.json
+  prepare [--resume]     run locally: set the repo up for the cloud on a new branch and verify it in a cloud session
+
+Options:
+  --help                 show this help
+  --version              print the package version
+`;
+/** Environment variable with the project dir that Claude Code passes to hooks. */
+const PROJECT_DIR_VAR = "CLAUDE_PROJECT_DIR";
+/** Environment marker set on a delegated `session`, so it never delegates again. */
+export const DELEGATED_ENV = "AGENT_CLOUD_KIT_DELEGATED";
+/** Value of `DELEGATED_ENV` that marks a delegated run. */
+const DELEGATED_VALUE = "1";
+/** Option that limits setup to one repo. */
+const REPO_OPTION = "--repo";
+/** Timeout of the git call that finds the repo root, in milliseconds. */
+const GIT_TIMEOUT_MS = 10_000;
+/** Option of `prepare` that continues in an existing prepare worktree. */
+const RESUME_OPTION = "--resume";
+/** Exit code for success. */
+const EXIT_OK = 0;
+/** Exit code for failure or wrong usage. */
+const EXIT_FAIL = 1;
+/**
+ * Reads the package version from the package.json next to `src/` or `dist/`.
+ *
+ * @returns The version string.
+ * @throws When package.json cannot be read or parsed.
+ */
+function readVersion() {
+    const file = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(file, "utf8"));
+    return pkg.version;
+}
+/**
+ * Turns an unknown error into its message.
+ *
+ * @param err - Anything thrown.
+ * @returns The message.
+ */
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Runs setup for one repo with this version and prints its summary.
+ *
+ * @param repo - Repo root.
+ * @param deps - CLI dependencies.
+ */
+async function runOne(repo, deps) {
+    const { config, errors } = readConfig(repo);
+    for (const error of errors)
+        deps.print(`${OUTPUT_PREFIX}${repo}: ${error}`);
+    if (config && config.version !== deps.packageVersion) {
+        deps.print(`${OUTPUT_PREFIX}running ${deps.packageVersion} although ${CONFIG_FILE} asks for ${config.version}`);
+    }
+    const state = await setupRepo(repo, {
+        toolsDir: toolsDir(deps.env),
+        run: deps.run,
+        packageVersion: deps.packageVersion,
+        env: deps.env,
+        docker: deps.docker,
+        packageRoot: deps.packageRoot,
+    });
+    const failed = state.steps.filter((s) => !s.ok).map((s) => s.name);
+    const detail = failed.length ? ` (${failed.join(", ")})` : "";
+    deps.print(`${OUTPUT_PREFIX}setup ${repo}: ${state.steps.length} steps, ${failed.length} failed${detail}`);
+}
+/**
+ * Carries out one item of the setup plan; may throw, the caller reports it and moves on.
+ *
+ * @param item - Plan item.
+ * @param deps - CLI dependencies.
+ */
+async function runPlanItem(item, deps) {
+    if (item.action === "skip") {
+        deps.print(`${OUTPUT_PREFIX}skipping ${item.repo}: ${item.reason ?? ""}`);
+        return;
+    }
+    if (item.action === "run" || !item.version) {
+        await runOne(item.repo, deps);
+        return;
+    }
+    deps.print(`${OUTPUT_PREFIX}relaunching with ${item.version} for ${item.repo}`);
+    try {
+        await relaunch(item.repo, item.version, deps.run, deps.env);
+    }
+    catch (err) {
+        deps.print(`${OUTPUT_PREFIX}relaunch with ${item.version} for ${item.repo} failed: ${message(err)}`);
+    }
+}
+/**
+ * Runs `setup`: one repo with `--repo`, otherwise every repo of the home dir in series (apt
+ * cannot run twice at once). Always exits 0: a failure is reported, never fatal.
+ *
+ * @param args - Arguments after `setup`.
+ * @param deps - CLI dependencies.
+ * @returns Exit code 0.
+ */
+async function setupCommand(args, deps) {
+    try {
+        const at = args.indexOf(REPO_OPTION);
+        if (at >= 0) {
+            const value = args[at + 1];
+            if (!value || value.startsWith("-"))
+                deps.print(`${OUTPUT_PREFIX}${REPO_OPTION} needs a path`);
+            else
+                await runOne(resolve(deps.cwd, value), deps);
+            return EXIT_OK;
+        }
+        const repos = findRepos(homeDir(deps.env));
+        if (!repos.length)
+            deps.print(`${OUTPUT_PREFIX}no repos found in ${homeDir(deps.env)}`);
+        for (const item of planSetup(repos, deps.packageVersion, readConfig)) {
+            try {
+                await runPlanItem(item, deps);
+            }
+            catch (err) {
+                deps.print(`${OUTPUT_PREFIX}setup error for ${item.repo}: ${message(err)}`);
+            }
+        }
+    }
+    catch (err) {
+        deps.print(`${OUTPUT_PREFIX}setup error: ${message(err)}`);
+    }
+    return EXIT_OK;
+}
+/**
+ * Finds the repo of the session: `CLAUDE_PROJECT_DIR`, else the git toplevel, else the cwd.
+ *
+ * @param deps - CLI dependencies.
+ * @returns The repo root.
+ */
+function sessionRepo(deps) {
+    const fromEnv = deps.env[PROJECT_DIR_VAR];
+    if (fromEnv)
+        return fromEnv;
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: deps.cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: GIT_TIMEOUT_MS,
+        }).trim();
+    }
+    catch {
+        return deps.cwd;
+    }
+}
+/**
+ * Runs `session`, delegating to the installed version the repo pins when it differs from this
+ * one. A delegated run carries `DELEGATED_ENV` and never delegates again, so two versions can
+ * not bounce between each other. Always exits 0 so the session start is never blocked.
+ *
+ * @param deps - CLI dependencies.
+ * @returns Exit code 0.
+ */
+async function sessionCommand(deps) {
+    const repo = sessionRepo(deps);
+    const tools = toolsDir(deps.env);
+    const wanted = readConfig(repo).config?.version;
+    const delegated = deps.env[DELEGATED_ENV] === DELEGATED_VALUE;
+    if (!delegated && wanted && wanted !== deps.packageVersion && existsSync(packageBin(tools, wanted))) {
+        try {
+            await deps.run(packageBin(tools, wanted), ["session"], { env: { ...deps.env, [DELEGATED_ENV]: DELEGATED_VALUE } });
+        }
+        catch (err) {
+            deps.print(`${OUTPUT_PREFIX}session ${wanted} failed: ${message(err)}`);
+        }
+        return EXIT_OK;
+    }
+    const lines = await session(repo, { env: deps.env, toolsDir: tools, run: deps.run, packageVersion: deps.packageVersion, docker: deps.docker });
+    for (const line of lines)
+        deps.print(line);
+    return EXIT_OK;
+}
+/**
+ * Runs `docker`: starts the daemon and waits for it.
+ *
+ * @param deps - CLI dependencies.
+ * @returns 0 when Docker answers, 1 otherwise.
+ */
+async function dockerCommand(deps) {
+    if (await deps.docker.ensure().catch(() => false))
+        return EXIT_OK;
+    deps.print(`${OUTPUT_PREFIX}dockerd did not start; see ${DOCKERD_LOG}`);
+    return EXIT_FAIL;
+}
+/**
+ * Runs `doctor` for the session repo.
+ *
+ * @param deps - CLI dependencies.
+ * @returns 0 when every check passes, 1 otherwise.
+ */
+async function doctorCommand(deps) {
+    const result = await doctor(sessionRepo(deps), {
+        capture: deps.capture ?? captureProcess,
+        toolsDir: toolsDir(deps.env),
+        packageVersion: deps.packageVersion,
+        dockerInfo: deps.dockerInfo ?? dockerResponds,
+    });
+    for (const line of result.lines)
+        deps.print(line);
+    return result.ok ? EXIT_OK : EXIT_FAIL;
+}
+/**
+ * Runs `init` for the session repo, copying the skill from `deps.packageRoot`.
+ *
+ * @param deps - CLI dependencies.
+ * @returns 0, or 1 when settings.json is not valid JSON or the skill cannot be copied.
+ */
+function initCommand(deps) {
+    let result;
+    try {
+        result = init(sessionRepo(deps), deps.packageVersion, deps.packageRoot ?? RUNNING_PACKAGE_ROOT);
+    }
+    catch (err) {
+        deps.print(`${OUTPUT_PREFIX}${message(err)}`);
+        return EXIT_FAIL;
+    }
+    for (const line of result.lines)
+        deps.print(line);
+    return result.ok ? EXIT_OK : EXIT_FAIL;
+}
+/**
+ * Runs `manual`: writes `docs/agent-cloud.md` for the session repo.
+ *
+ * @param deps - CLI dependencies.
+ * @returns 0 on success, 1 when there is no usable config.
+ */
+function manualCommand(deps) {
+    try {
+        writeManual(sessionRepo(deps), deps.packageVersion);
+    }
+    catch (err) {
+        deps.print(`${OUTPUT_PREFIX}${message(err)}`);
+        return EXIT_FAIL;
+    }
+    deps.print(`${OUTPUT_PREFIX}wrote ${MANUAL_FILE}`);
+    return EXIT_OK;
+}
+/**
+ * Asks one question on the terminal, showing the suggestion in brackets. The interface is closed
+ * after each answer so child processes (claude) get stdin back. Ctrl+C (which readline catches,
+ * so no process SIGINT arrives) rejects with `InterruptedError`.
+ *
+ * @param question - Question text.
+ * @param suggestion - Suggested answer, shown when not empty.
+ * @returns The raw answer.
+ * @throws InterruptedError on Ctrl+C.
+ * @example
+ * await askTerminal("Include these changes in the commit? [y/N]", ""); // "y"
+ */
+const askTerminal = async (question, suggestion) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await new Promise((resolveAnswer, reject) => {
+            rl.on("SIGINT", () => reject(new InterruptedError()));
+            rl.question(`${question}${suggestion ? ` [${suggestion}]` : ""}: `).then(resolveAnswer, reject);
+        });
+    }
+    finally {
+        rl.close();
+    }
+};
+/**
+ * Registers a process SIGINT listener (Ctrl+C while a child runs). Being registered, it replaces
+ * Node's default exit for every Ctrl+C; it exits 130 only when the handler says so, so a Ctrl+C
+ * meant for an interactive `claude` (same process group) does not end `prepare`.
+ *
+ * @param handler - Prints where the worktree is and says whether to exit.
+ * @returns Removes the listener.
+ * @example
+ * const stop = onProcessInterrupt(() => true); stop();
+ */
+function onProcessInterrupt(handler) {
+    const listener = () => {
+        if (handler())
+            process.exit(EXIT_INTERRUPTED);
+    };
+    process.on("SIGINT", listener);
+    return () => process.off("SIGINT", listener);
+}
+/**
+ * Shows a text on the terminal and waits for Enter.
+ *
+ * @param text - Text to show.
+ * @example
+ * await waitTerminal("Press Enter");
+ */
+async function waitTerminal(text) {
+    await askTerminal(text, "");
+}
+/**
+ * Runs `prepare` in the working directory.
+ *
+ * @param args - Arguments after `prepare`.
+ * @param deps - CLI dependencies.
+ * @returns 0 when the cloud session was started, 130 after Ctrl+C, 1 otherwise.
+ */
+async function prepareCommand(args, deps) {
+    const unknown = args.filter((arg) => arg !== RESUME_OPTION);
+    if (unknown.length) {
+        deps.print(`${OUTPUT_PREFIX}unknown option for prepare: ${unknown.join(" ")}`);
+        return EXIT_FAIL;
+    }
+    return prepare(deps.cwd, {
+        run: deps.run,
+        capture: deps.capture ?? captureProcess,
+        ask: deps.ask ?? askTerminal,
+        waitEnter: deps.waitEnter ?? waitTerminal,
+        print: deps.print,
+        packageVersion: deps.packageVersion,
+        packageRoot: deps.packageRoot ?? RUNNING_PACKAGE_ROOT,
+        today: deps.today ?? branchDay(new Date()),
+        isTty: deps.isTty ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
+        onInterrupt: deps.onInterrupt ?? onProcessInterrupt,
+    }, { resume: args.includes(RESUME_OPTION) });
+}
+/**
+ * Runs the CLI.
+ *
+ * @param argv - Arguments after the executable name.
+ * @param deps - Dependencies; tests inject fakes.
+ * @returns The process exit code.
+ * @example
+ * process.exitCode = await main(["setup"], realDeps());
+ */
+export async function main(argv, deps) {
+    const [command, ...rest] = argv;
+    if (command === "setup")
+        return setupCommand(rest, deps);
+    if (command === "session")
+        return sessionCommand(deps);
+    if (command === "docker")
+        return dockerCommand(deps);
+    if (command === "doctor")
+        return doctorCommand(deps);
+    if (command === "init")
+        return initCommand(deps);
+    if (command === "manual")
+        return manualCommand(deps);
+    if (command === "prepare")
+        return prepareCommand(rest, deps);
+    if (command === "--version") {
+        deps.print(deps.packageVersion);
+        return EXIT_OK;
+    }
+    deps.print(HELP);
+    return command === undefined || command === "--help" ? EXIT_OK : EXIT_FAIL;
+}
+/**
+ * Builds the real dependencies of the CLI.
+ *
+ * @returns Dependencies backed by the process, the real runner and the real Docker.
+ */
+function realDeps() {
+    return {
+        env: process.env,
+        run: runProcess,
+        docker: realDocker,
+        packageVersion: readVersion(),
+        print: (line) => console.log(line),
+        cwd: process.cwd(),
+    };
+}
+/**
+ * Tells whether this module is the process entry point (also when started through a symlink).
+ *
+ * @returns True when run as the CLI rather than imported.
+ */
+function isEntryPoint() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint()) {
+    process.exitCode = await main(process.argv.slice(2), realDeps());
+}

package/dist/config.js

@@ -0,0 +1,197 @@
+/**
+ * @file Reader and validator for `<repo>/.claude/cloud.json`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_FILE } from "./constants.js";
+/** Top-level key that editors use to point at the JSON schema; allowed but not part of the config. */
+const SCHEMA_KEY = "$schema";
+/** Exact semver: no ranges, no prefixes. */
+const EXACT_SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+/** Top-level keys of `CloudConfig`; must match `schema.json#/properties` (minus `$schema`). */
+export const CONFIG_KEYS = [
+    "version",
+    "aptRepos",
+    "apt",
+    "docker",
+    "setup",
+    "session",
+    "requiredEnv",
+    "notes",
+    "domains",
+];
+/** Keys accepted inside the `docker` object. */
+const DOCKER_KEYS = ["pull"];
+/** Keys that hold a list of strings. */
+const LIST_KEYS = ["aptRepos", "apt", "setup", "session", "requiredEnv"];
+/** A DNS host name: dot-separated labels, no scheme, port or path. */
+const HOST_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+/**
+ * Tells whether a string is a plain DNS host name, the rule `domains` entries follow.
+ *
+ * @param host - Candidate host.
+ * @returns True for names like `api.example.com`; false with a scheme, port, path or one label.
+ * @example
+ * isHostName("api.example.com"); // true
+ * isHostName("https://api.example.com"); // false
+ */
+export function isHostName(host) {
+    return HOST_NAME.test(host);
+}
+/** Value of `docker.pull` that asks for image auto-detection. */
+const PULL_AUTO = "auto";
+/**
+ * Builds an error message prefixed with the config file name.
+ *
+ * @param message - What went wrong.
+ * @returns The prefixed message.
+ */
+function fail(message) {
+    return `${CONFIG_FILE}: ${message}`;
+}
+/**
+ * Tells whether a value is a plain JSON object.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True for non-null, non-array objects.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Tells whether a value is an array of strings.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True when every element is a string.
+ */
+function isStringList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+ * Validates `docker`, falling back to the default when it is invalid.
+ *
+ * @param value - Raw `docker` value, possibly undefined.
+ * @param errors - Collector that receives any problem found.
+ * @returns A valid docker section.
+ */
+function parseDocker(value, errors) {
+    if (value === undefined)
+        return { pull: PULL_AUTO };
+    if (!isRecord(value)) {
+        errors.push(fail('"docker" must be an object'));
+        return { pull: PULL_AUTO };
+    }
+    for (const key of Object.keys(value)) {
+        if (!DOCKER_KEYS.includes(key)) {
+            errors.push(fail(`unknown field "docker.${key}"`));
+        }
+    }
+    const pull = value.pull;
+    if (pull === undefined || pull === PULL_AUTO)
+        return { pull: PULL_AUTO };
+    if (pull === false || isStringList(pull))
+        return { pull };
+    errors.push(fail('"docker.pull" must be "auto", false or an array of strings'));
+    return { pull: PULL_AUTO };
+}
+/**
+ * Validates a list-of-strings field, using `[]` when it is invalid or missing.
+ *
+ * @param raw - The whole parsed object.
+ * @param key - Field to read.
+ * @param errors - Collector that receives any problem found.
+ * @returns The list, or an empty list.
+ */
+function parseList(raw, key, errors) {
+    const value = raw[key];
+    if (value === undefined)
+        return [];
+    if (isStringList(value))
+        return value;
+    errors.push(fail(`"${key}" must be an array of strings`));
+    return [];
+}
+/**
+ * Validates `domains`, dropping (and reporting) every entry that is not a plain host name.
+ *
+ * @param value - Raw `domains` value, possibly undefined.
+ * @param errors - Collector that receives any problem found.
+ * @returns The valid hosts.
+ * @example
+ * parseDomains(["api.example.com", "https://x"], errors); // ["api.example.com"], one error
+ */
+function parseDomains(value, errors) {
+    if (value === undefined)
+        return [];
+    if (!isStringList(value)) {
+        errors.push(fail('"domains" must be an array of strings'));
+        return [];
+    }
+    return value.filter((host) => {
+        const valid = isHostName(host);
+        if (!valid)
+            errors.push(fail(`"domains" has an invalid host: ${JSON.stringify(host)}`));
+        return valid;
+    });
+}
+/**
+ * Validates the parsed object and builds a normalized config.
+ *
+ * @param raw - Parsed JSON object.
+ * @param errors - Collector that receives any problem found.
+ * @returns The config, or undefined when `version` is missing or invalid.
+ */
+function parseConfig(raw, errors) {
+    const known = [...CONFIG_KEYS, SCHEMA_KEY];
+    for (const key of Object.keys(raw)) {
+        if (!known.includes(key))
+            errors.push(fail(`unknown field "${key}"`));
+    }
+    const version = raw.version;
+    if (typeof version !== "string" || !EXACT_SEMVER.test(version)) {
+        errors.push(fail('"version" must be an exact semver string such as "1.0.0"'));
+        return undefined;
+    }
+    const lists = Object.fromEntries(LIST_KEYS.map((key) => [key, parseList(raw, key, errors)]));
+    const config = {
+        version,
+        aptRepos: lists.aptRepos ?? [],
+        apt: lists.apt ?? [],
+        docker: parseDocker(raw.docker, errors),
+        setup: lists.setup ?? [],
+        session: lists.session ?? [],
+        requiredEnv: lists.requiredEnv ?? [],
+        domains: parseDomains(raw.domains, errors),
+    };
+    if (typeof raw.notes === "string")
+        config.notes = raw.notes;
+    else if (raw.notes !== undefined)
+        errors.push(fail('"notes" must be a string'));
+    return config;
+}
+/**
+ * Reads and validates a repo's cloud config without ever throwing.
+ *
+ * @param repo - Path of the repo root.
+ * @returns The config (absent when the file is missing or `version` is invalid) and the list of errors.
+ * @example
+ * readConfig("/home/user/my-repo"); // { config: { version: "1.0.0", ... }, errors: [] }
+ */
+export function readConfig(repo) {
+    const file = join(repo, CONFIG_FILE);
+    if (!existsSync(file))
+        return { errors: [] };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { errors: [fail(`cannot read file: ${reason}`)] };
+    }
+    if (!isRecord(raw))
+        return { errors: [fail("must contain a JSON object")] };
+    const errors = [];
+    const config = parseConfig(raw, errors);
+    return config ? { config, errors } : { errors };
+}

package/dist/constants.js

@@ -0,0 +1,77 @@
+/**
+ * @file Fixed values shared by the agent-cloud-kit modules, each in a documented constant.
+ */
+import { fileURLToPath } from "node:url";
+/** Prefix of every line the CLI prints. */
+export const OUTPUT_PREFIX = "agent-cloud-kit: ";
+/** Path of the repo config file, relative to the repo root. */
+export const CONFIG_FILE = ".claude/cloud.json";
+/** Root of the running package: the folder above `dist/` (or `src/` in tests), which holds `skills/`. */
+export const RUNNING_PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+/** Name of this package on npm. */
+export const PACKAGE = "agent-cloud-kit";
+/**
+ * The npm spec the setup script installs: the major (`agent-cloud-kit@1`) for a stable version,
+ * the exact version for a prerelease, which a major range does not match.
+ *
+ * @param packageVersion - Version of the running package.
+ * @returns The spec.
+ * @example
+ * packageSpec("1.2.0"); // "agent-cloud-kit@1"
+ * packageSpec("1.0.0-rc.1"); // "agent-cloud-kit@1.0.0-rc.1"
+ */
+export function packageSpec(packageVersion) {
+    if (packageVersion.includes("-"))
+        return `${PACKAGE}@${packageVersion}`;
+    return `${PACKAGE}@${packageVersion.split(".")[0]}`;
+}
+/** Default root directory that holds the installed tools and the state files. */
+export const TOOLS_DIR = "/opt/agent-cloud-kit";
+/** Environment variable that overrides `TOOLS_DIR` (used by tests). */
+export const TOOLS_DIR_ENV = "AGENT_CLOUD_KIT_DIR";
+/** Default directory whose first-level folders are the cloned repos. */
+export const HOME_DIR = "/home/user";
+/** Environment variable that overrides `HOME_DIR` (used by tests). */
+export const HOME_DIR_ENV = "AGENT_CLOUD_KIT_HOME";
+/** Number of Docker images pulled at the same time. */
+export const PULL_JOBS = 4;
+/** Log file of the detached Docker daemon. */
+export const DOCKERD_LOG = "/var/log/agent-cloud-kit-dockerd.log";
+/** Seconds to wait for the Docker daemon to answer. */
+export const DOCKER_WAIT_SECONDS = 60;
+/** Total step time, in milliseconds, above which setup is reported as slow. */
+export const SETUP_SLOW_MS = 240_000;
+/** Time limit of one tool install step (a download or an install), in milliseconds. */
+export const TOOL_INSTALL_TIMEOUT_MS = 120_000;
+/** Time limit of one apt step (repo script, update or install), in milliseconds. */
+export const APT_STEP_TIMEOUT_MS = 180_000;
+/** Time limit of one `docker pull`, in milliseconds. */
+export const DOCKER_PULL_TIMEOUT_MS = 180_000;
+/** Time limit of one repo setup command, in milliseconds. */
+export const SETUP_STEP_TIMEOUT_MS = 180_000;
+/** Time limit of one `git fetch` at session start, in milliseconds. */
+export const GIT_FETCH_TIMEOUT_MS = 60_000;
+/** Default location of the cloud proxy CA bundle. */
+export const PROXY_CA_DEFAULT = "/root/.ccr/ca-bundle.crt";
+/**
+ * Resolves the tools directory, honoring the `AGENT_CLOUD_KIT_DIR` override.
+ *
+ * @param env - Process environment.
+ * @returns The override when set and non-empty, otherwise `TOOLS_DIR`.
+ * @example
+ * toolsDir({ AGENT_CLOUD_KIT_DIR: "/tmp/x" }); // "/tmp/x"
+ */
+export function toolsDir(env) {
+    return env[TOOLS_DIR_ENV] || TOOLS_DIR;
+}
+/**
+ * Resolves the directory that holds the cloned repos, honoring the `AGENT_CLOUD_KIT_HOME` override.
+ *
+ * @param env - Process environment.
+ * @returns The override when set and non-empty, otherwise `HOME_DIR`.
+ * @example
+ * homeDir({ AGENT_CLOUD_KIT_HOME: "/tmp/home" }); // "/tmp/home"
+ */
+export function homeDir(env) {
+    return env[HOME_DIR_ENV] || HOME_DIR;
+}