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

package/dist/detect.js

@@ -0,0 +1,265 @@
+/**
+ * @file Deduces tool versions, Docker images and the default branch from a repo's files.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Tools whose versions can be pinned. */
+export const TOOLS = ["node", "bun", "deno", "pnpm", "yarn", "uv"];
+/** Branch name used when nothing else can be determined. */
+const FALLBACK_BRANCH = "main";
+/** Maximum directory depth (root is 0) searched for Dockerfiles. */
+const DOCKERFILE_MAX_DEPTH = 3;
+/** Directories never searched for Dockerfiles. */
+const SKIPPED_DIRS = ["node_modules", ".git"];
+/** Alternative names that map to a supported tool. */
+const TOOL_ALIASES = { nodejs: "node" };
+/** Matches `docker-compose*.yml|yaml` and `compose*.yml|yaml`. */
+const COMPOSE_FILE = /^(docker-)?compose([.-][^/]*)?\.ya?ml$/;
+/** Matches an `image:` line in a compose file. */
+const IMAGE_LINE = /^\s*(?:-\s+)?image:\s*(\S+)/;
+/** Matches a pinned `FROM` line in a Dockerfile. */
+const FROM_LINE = /^FROM\s+(?:--\S+\s+)*(\S+@sha256:\S+)/i;
+/** Milliseconds after which a git call is abandoned, so session start never stalls. */
+const GIT_TIMEOUT_MS = 10_000;
+/** Environment that keeps git non-interactive and its output in English. */
+const GIT_ENV = { GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" };
+/** Matches the `HEAD branch:` line of `git remote show`. */
+const HEAD_BRANCH_LINE = /^\s*HEAD branch:\s*(\S+)/m;
+/**
+ * Reads a file as text.
+ *
+ * @param path - File to read.
+ * @returns Its contents, or undefined when missing or unreadable.
+ */
+function readText(path) {
+    try {
+        return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves a name to a supported tool.
+ *
+ * @param name - Name as written in the source file.
+ * @returns The tool, or undefined when unsupported.
+ */
+function toTool(name) {
+    const mapped = TOOL_ALIASES[name] ?? name;
+    return TOOLS.includes(mapped) ? mapped : undefined;
+}
+/**
+ * Parses `.tool-versions` lines (`name version`).
+ *
+ * @param text - File contents.
+ * @returns Detected versions.
+ */
+function parseToolVersions(text) {
+    const found = {};
+    for (const line of text.split("\n")) {
+        const [name, version] = line.replace(/#.*/, "").trim().split(/\s+/);
+        const tool = name ? toTool(name) : undefined;
+        if (tool && version)
+            found[tool] ??= version;
+    }
+    return found;
+}
+/**
+ * Parses the `[tools]` section of `mise.toml` (`name = "version"`).
+ *
+ * @param text - File contents.
+ * @returns Detected versions.
+ */
+function parseMise(text) {
+    const found = {};
+    let inTools = false;
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (line.startsWith("["))
+            inTools = line === "[tools]";
+        const match = inTools ? /^"?([\w.-]+)"?\s*=\s*["']([^"']+)["']/.exec(line) : null;
+        const tool = match?.[1] ? toTool(match[1]) : undefined;
+        if (tool && match?.[2])
+            found[tool] ??= match[2];
+    }
+    return found;
+}
+/**
+ * Parses `.nvmrc`.
+ *
+ * @param text - File contents.
+ * @returns The node version, if any.
+ */
+function parseNvmrc(text) {
+    const version = text.trim().replace(/^v/, "");
+    return version ? { node: version } : {};
+}
+/**
+ * Parses `package.json#packageManager` (`name@version+hash`).
+ *
+ * @param text - File contents.
+ * @returns Detected versions.
+ */
+function parsePackageManager(text) {
+    try {
+        const value = JSON.parse(text).packageManager;
+        const match = typeof value === "string" ? /^([^@]+)@([^+]+)/.exec(value) : null;
+        const tool = match?.[1] ? toTool(match[1]) : undefined;
+        return tool && match?.[2] ? { [tool]: match[2] } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Reads pinned tool versions; the first source that defines a tool wins.
+ *
+ * @param repo - Path of the repo root.
+ * @returns Versions by tool; unsupported tools are ignored.
+ * @example
+ * readToolVersions("/home/user/repo"); // { node: "24.14.1", bun: "1.4.2" }
+ */
+export function readToolVersions(repo) {
+    const sources = [
+        [".tool-versions", parseToolVersions],
+        ["mise.toml", parseMise],
+        [".nvmrc", parseNvmrc],
+        ["package.json", parsePackageManager],
+    ];
+    const result = {};
+    for (const [file, parse] of sources) {
+        const text = readText(join(repo, file));
+        if (text !== undefined)
+            Object.assign(result, { ...parse(text), ...result });
+    }
+    return result;
+}
+/**
+ * Extracts `image:` values from compose files in the repo root.
+ *
+ * @param repo - Path of the repo root.
+ * @returns Image references, unfiltered.
+ */
+function composeImages(repo) {
+    const images = [];
+    let entries = [];
+    try {
+        entries = readdirSync(repo);
+    }
+    catch {
+        return images;
+    }
+    for (const entry of entries) {
+        if (!COMPOSE_FILE.test(entry))
+            continue;
+        for (const line of (readText(join(repo, entry)) ?? "").split("\n")) {
+            const match = IMAGE_LINE.exec(line);
+            if (match?.[1])
+                images.push(match[1].replace(/^["']|["']$/g, ""));
+        }
+    }
+    return images;
+}
+/**
+ * Extracts digest-pinned `FROM` images from Dockerfiles up to a depth.
+ *
+ * @param dir - Directory to walk.
+ * @param depth - Depth of `dir` (root is 0).
+ * @returns Image references, unfiltered.
+ */
+function dockerfileImages(dir, depth) {
+    const images = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return images;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const deeper = depth < DOCKERFILE_MAX_DEPTH && !SKIPPED_DIRS.includes(entry.name);
+            if (deeper)
+                images.push(...dockerfileImages(join(dir, entry.name), depth + 1));
+        }
+        else if (entry.name === "Dockerfile" || entry.name.startsWith("Dockerfile.")) {
+            for (const line of (readText(join(dir, entry.name)) ?? "").split("\n")) {
+                const match = FROM_LINE.exec(line.trim());
+                if (match?.[1])
+                    images.push(match[1]);
+            }
+        }
+    }
+    return images;
+}
+/**
+ * Finds Docker images referenced by compose files and pinned in Dockerfiles.
+ *
+ * @param repo - Path of the repo root.
+ * @returns Sorted, unique image references without variables (`$`).
+ * @example
+ * detectImages("/home/user/repo"); // ["oven/bun:1@sha256:abc", "postgres:16"]
+ */
+export function detectImages(repo) {
+    try {
+        const all = [...composeImages(repo), ...dockerfileImages(repo, 0)];
+        return [...new Set(all.filter((image) => !image.includes("$")))].sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Chooses the images a config asks to pull; setup and session share it so their fingerprints agree.
+ *
+ * @param config - Repo config.
+ * @param repo - Path of the repo root.
+ * @returns `detectImages(repo)` for `"auto"`, the explicit list, or `[]` for `false`.
+ * @example
+ * configImages({ ...config, docker: { pull: ["postgres:16"] } }, "/home/user/repo"); // ["postgres:16"]
+ */
+export function configImages(config, repo) {
+    const pull = config.docker.pull;
+    if (pull === "auto")
+        return detectImages(repo);
+    return pull === false ? [] : pull;
+}
+/**
+ * Runs git synchronously and returns trimmed stdout.
+ *
+ * @param repo - Working directory.
+ * @param args - Git arguments.
+ * @returns Output, or undefined when git fails.
+ */
+function gitOutput(repo, args) {
+    try {
+        return execFileSync("git", args, {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: GIT_TIMEOUT_MS,
+            env: { ...process.env, ...GIT_ENV },
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Finds the repo's default branch; never throws.
+ *
+ * @param repo - Path of the repo root.
+ * @returns The branch from `origin/HEAD`, else from `git remote show origin`, else `main`.
+ * @example
+ * defaultBranch("/home/user/repo"); // "main"
+ */
+export function defaultBranch(repo) {
+    const ref = gitOutput(repo, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+    const fromRef = ref?.replace(/^refs\/remotes\/origin\//, "");
+    if (fromRef)
+        return fromRef;
+    const fromRemote = HEAD_BRANCH_LINE.exec(gitOutput(repo, ["remote", "show", "origin"]) ?? "")?.[1];
+    return fromRemote && fromRemote !== "(unknown)" ? fromRemote : FALLBACK_BRANCH;
+}

package/dist/docker.js

@@ -0,0 +1,95 @@
+/**
+ * @file Starts the Docker daemon detached (cloud sessions have no init system) and waits for it.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { DOCKERD_LOG, DOCKER_WAIT_SECONDS } from "./constants.js";
+/** Timeout of each probe command, in milliseconds. */
+const PROBE_TIMEOUT_MS = 10_000;
+/** Delay between readiness checks, in milliseconds. */
+const POLL_MS = 1000;
+/** Milliseconds in a second. */
+const MS_PER_SECOND = 1000;
+/** Message returned when there is no `dockerd` executable on PATH. */
+export const DOCKERD_MISSING = "dockerd not installed";
+/**
+ * Tells whether a command exits with code 0.
+ *
+ * @param cmd - Executable.
+ * @param args - Arguments.
+ * @returns True on exit code 0; false on any failure, including a missing executable.
+ */
+function succeeds(cmd, args) {
+    try {
+        execFileSync(cmd, args, { stdio: "ignore", timeout: PROBE_TIMEOUT_MS });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Tells whether the daemon already answers.
+ *
+ * @returns True when `docker info` succeeds.
+ * @example
+ * if (!dockerResponds()) console.log("docker is down");
+ */
+export function dockerResponds() {
+    return succeeds("docker", ["info"]);
+}
+/**
+ * Starts `dockerd` detached, logging to `DOCKERD_LOG`. Does nothing when Docker already
+ * answers or when one is already running. Never throws.
+ *
+ * @param probe - Command probe; the real one when omitted (tests inject a fake).
+ * @returns `DOCKERD_MISSING` when there is no `dockerd` on PATH, another error message when the
+ *   daemon could not be started, undefined otherwise.
+ * @example
+ * const problem = startDockerDetached();
+ */
+export function startDockerDetached(probe = succeeds) {
+    if (probe("docker", ["info"]))
+        return undefined;
+    if (!probe("sh", ["-c", "command -v dockerd"]))
+        return DOCKERD_MISSING;
+    if (probe("pgrep", ["-x", "dockerd"]))
+        return undefined;
+    try {
+        const log = openSync(DOCKERD_LOG, "a");
+        try {
+            const child = spawn("dockerd", [], { detached: true, stdio: ["ignore", log, log] });
+            child.on("error", () => { });
+            child.unref();
+        }
+        finally {
+            closeSync(log);
+        }
+        return undefined;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+}
+/**
+ * Starts the daemon and waits for it to answer, up to `DOCKER_WAIT_SECONDS`. Returns false at
+ * once when the daemon cannot be started at all (for example, no `dockerd` installed).
+ *
+ * @param probe - Command probe; the real one when omitted (tests inject a fake).
+ * @returns True when Docker answers in time; false when it never does or cannot start.
+ * @example
+ * if (await ensureDocker()) console.log("docker is up");
+ */
+export async function ensureDocker(probe = succeeds) {
+    if (startDockerDetached(probe))
+        return false;
+    const deadline = Date.now() + DOCKER_WAIT_SECONDS * MS_PER_SECOND;
+    while (Date.now() < deadline) {
+        if (probe("docker", ["info"]))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+    return probe("docker", ["info"]);
+}
+/** The real Docker operations. */
+export const realDocker = { start: () => startDockerDetached(), ensure: () => ensureDocker() };

package/dist/doctor.js

@@ -0,0 +1,200 @@
+/**
+ * @file The `doctor` command: checks the network allowlist, the pinned tools, Docker and the
+ * recorded machine state, and reports one line per check.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readConfig } from "./config.js";
+import { CONFIG_FILE, OUTPUT_PREFIX } from "./constants.js";
+import { TOOLS, readToolVersions } from "./detect.js";
+import { isValidRequest, toolExecutable } from "./installers.js";
+import { expectedFingerprint } from "./session.js";
+import { SKILL_DIR, skillVersion } from "./skill.js";
+import { readState } from "./state.js";
+/** Hosts the setup needs to reach through the cloud proxy. */
+export const DOMAINS = ["registry.npmjs.org", "nodejs.org", "registry-1.docker.io", "pypi.org", "api.github.com"];
+/** Time limit of each HEAD request, in seconds, as a curl argument. */
+const PROBE_TIMEOUT_SECONDS = "5";
+/** HTTP status the proxy answers with when a host is not on the allowlist. */
+const BLOCKED_STATUS = "403";
+/** Status curl prints when it got no HTTP answer at all. */
+const NO_ANSWER_STATUS = "000";
+/** Milliseconds in a second. */
+const MS_PER_SECOND = 1000;
+/** Decimals shown in step durations. */
+const DURATION_DECIMALS = 1;
+/** Repo-relative Claude Code project settings. */
+const SETTINGS_FILE = ".claude/settings.json";
+/**
+ * Maps a pass/fail boolean to a check level.
+ *
+ * @param passed - Whether the check passed.
+ * @returns `"ok"` or `"fail"`.
+ * @example
+ * verdict(false); // "fail"
+ */
+function verdict(passed) {
+    return passed ? "ok" : "fail";
+}
+/**
+ * Checks that a host answers through the proxy with a curl HEAD request: a 403 or a curl failure
+ * counts as blocked, any other status as reachable.
+ *
+ * @param host - Host name.
+ * @param capture - Runs curl and returns its stdout.
+ * @returns The check outcome.
+ */
+async function checkDomain(host, capture) {
+    const args = ["-sS", "-o", "/dev/null", "-w", "%{http_code}", "-I", "--max-time", PROBE_TIMEOUT_SECONDS, `https://${host}/`];
+    try {
+        const status = (await capture("curl", args)).trim();
+        const ok = status !== BLOCKED_STATUS && status !== NO_ANSWER_STATUS;
+        return { text: `network ${host}: ${ok ? "ok" : "blocked"}`, level: verdict(ok) };
+    }
+    catch {
+        return { text: `network ${host}: blocked`, level: "fail" };
+    }
+}
+/**
+ * Lists the hosts to probe: the fixed ones, then the configured ones that are not repeated.
+ *
+ * @param repo - Repo root.
+ * @returns Host names without duplicates.
+ * @example
+ * domainsToProbe("/home/user/app"); // ["registry.npmjs.org", ..., "api.example.com"]
+ */
+function domainsToProbe(repo) {
+    return [...new Set([...DOMAINS, ...(readConfig(repo).config?.domains ?? [])])];
+}
+/**
+ * Checks that every pinned tool has its executable installed; an invalid version or a node
+ * version setup never resolved is a failed check, not an exception.
+ *
+ * @param repo - Repo root.
+ * @param toolsDir - Tools directory.
+ * @param state - Recorded state, for the versions setup resolved.
+ * @returns One check per pinned tool.
+ */
+function checkTools(repo, toolsDir, state) {
+    const versions = readToolVersions(repo);
+    return TOOLS.flatMap((tool) => {
+        const version = versions[tool];
+        if (!version)
+            return [];
+        if (!isValidRequest(tool, version))
+            return [{ text: `tool ${tool} ${version}: invalid version`, level: "fail" }];
+        const executable = toolExecutable(tool, version, toolsDir, state?.resolved ?? {});
+        if (!executable)
+            return [{ text: `tool ${tool} ${version}: not resolved (setup did not install it)`, level: "fail" }];
+        const present = existsSync(executable);
+        return [{ text: `tool ${tool} ${version}: ${present ? "ok" : "missing"}`, level: verdict(present) }];
+    });
+}
+/**
+ * Checks the repo config, the recorded state, its fingerprint and the step durations.
+ *
+ * @param repo - Repo root.
+ * @param ctx - Dependencies.
+ * @returns The checks, in order.
+ */
+function checkState(repo, ctx) {
+    if (!existsSync(join(repo, CONFIG_FILE)))
+        return [{ text: `${CONFIG_FILE}: missing`, level: "fail" }];
+    const { config, errors } = readConfig(repo);
+    const out = errors.map((text) => ({ text: `${CONFIG_FILE}: ${text}`, level: "fail" }));
+    if (!config)
+        return out;
+    const state = readState(ctx.toolsDir, repo);
+    if (!state)
+        return [...out, { text: "state: missing (setup did not run)", level: "fail" }];
+    const same = expectedFingerprint(repo, config, state) === state.fingerprint;
+    out.push({ text: `fingerprint: ${same ? "ok" : "mismatch"}`, level: verdict(same) });
+    for (const s of state.steps) {
+        const seconds = (s.ms / MS_PER_SECOND).toFixed(DURATION_DECIMALS);
+        out.push({ text: `step ${s.name}: ${s.ok ? "ok" : "failed"} (${seconds}s)`, level: verdict(s.ok) });
+    }
+    return out;
+}
+/**
+ * Warns about each plugin enabled in the project settings: plugins do not reach cloud sessions.
+ * Missing or malformed settings give no warnings.
+ *
+ * @param repo - Repo root.
+ * @returns One warning per enabled plugin.
+ * @example
+ * checkPlugins("/home/user/app"); // [{ text: "plugin x@m is enabled but ...", level: "warn" }]
+ */
+function checkPlugins(repo) {
+    try {
+        const settings = JSON.parse(readFileSync(join(repo, SETTINGS_FILE), "utf8"));
+        const plugins = settings?.enabledPlugins;
+        if (typeof plugins !== "object" || plugins === null)
+            return [];
+        return Object.entries(plugins)
+            .filter(([, enabled]) => enabled === true)
+            .map(([name]) => ({
+            text: `warn: plugin ${name} is enabled but is not in the repo; it will not reach the cloud (copy its skills with skills-manager)`,
+            level: "warn",
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Warns when the installed `cloud-ready` skill is of another version than the package.
+ *
+ * @param repo - Repo root.
+ * @param packageVersion - Version of this package.
+ * @returns A warning, or nothing when there is no skill or the versions match.
+ * @example
+ * checkSkill("/home/user/app", "1.0.0"); // [{ text: "warn: .agents/skills/cloud-ready is 0.9.0, ...", level: "warn" }]
+ */
+function checkSkill(repo, packageVersion) {
+    const installed = skillVersion(repo);
+    if (installed === undefined || installed === packageVersion)
+        return [];
+    return [
+        {
+            text: `warn: ${SKILL_DIR} is ${installed}, the package is ${packageVersion}; run npx agent-cloud-kit@${packageVersion} init`,
+            level: "warn",
+        },
+    ];
+}
+/**
+ * Runs one group of checks, turning anything it throws into a failed check.
+ *
+ * @param name - Group name, for the failed line.
+ * @param fn - Produces the checks.
+ * @returns The checks, or one failed check with the error.
+ */
+async function guarded(name, fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        return [{ text: `${name}: error: ${err instanceof Error ? err.message : String(err)}`, level: "fail" }];
+    }
+}
+/**
+ * Runs every diagnostic for a repo; never throws.
+ *
+ * @param repo - Repo root.
+ * @param ctx - Dependencies (curl capture, tools dir, package version, Docker probe).
+ * @returns The report lines and whether everything passed.
+ * @example
+ * const { lines, ok } = await doctor("/home/user/app", { capture: captureProcess, toolsDir, packageVersion: "1.0.0", dockerInfo });
+ */
+export async function doctor(repo, ctx) {
+    const checks = [];
+    checks.push(...(await guarded("network", async () => Promise.all(domainsToProbe(repo).map((host) => checkDomain(host, ctx.capture))))));
+    checks.push(...(await guarded("tools", () => checkTools(repo, ctx.toolsDir, readState(ctx.toolsDir, repo)))));
+    checks.push(...(await guarded("docker", () => {
+        const docker = ctx.dockerInfo();
+        return [{ text: `docker: ${docker ? "ok" : "missing"}`, level: verdict(docker) }];
+    })));
+    checks.push(...(await guarded("state", () => checkState(repo, ctx))));
+    checks.push(...(await guarded("plugins", () => checkPlugins(repo))));
+    checks.push(...(await guarded("skill", () => checkSkill(repo, ctx.packageVersion))));
+    return { lines: checks.map((c) => OUTPUT_PREFIX + c.text), ok: checks.every((c) => c.level !== "fail") };
+}

package/dist/init.js

@@ -0,0 +1,136 @@
+/**
+ * @file The `init` command: scaffolds `.claude/cloud.json`, registers the SessionStart hook in
+ * `.claude/settings.json` without touching anything else, and installs the `cloud-ready` skill.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_FILE, OUTPUT_PREFIX, PACKAGE } from "./constants.js";
+import { installSkill, linkSkill } from "./skill.js";
+/** Path of the Claude Code settings file, relative to the repo root. */
+const SETTINGS_FILE = ".claude/settings.json";
+/** Text that marks a SessionStart hook as ours. */
+const HOOK_MARKER = "agent-cloud-kit session";
+/** Timeout of the hook, in seconds. */
+const HOOK_TIMEOUT_SECONDS = 600;
+/** Indentation of the files written. */
+const JSON_INDENT = 2;
+/** Command of the SessionStart hook: does nothing outside cloud sessions. */
+const HOOK_COMMAND = "[ \"$CLAUDE_CODE_REMOTE\" = true ] || exit 0; /opt/agent-cloud-kit/bin/agent-cloud-kit session || echo 'agent-cloud-kit: the environment setup did not run; see npx agent-cloud-kit doctor'";
+/** The hook `init` registers. */
+const HOOK = { type: "command", command: HOOK_COMMAND, timeout: HOOK_TIMEOUT_SECONDS };
+/**
+ * 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);
+}
+/**
+ * Builds the outcome for a settings file that cannot be updated safely: it is left untouched and
+ * the user gets the hook to add by hand.
+ *
+ * @param reason - What is wrong with the file.
+ * @returns The failed outcome.
+ */
+function addByHand(reason) {
+    const entry = JSON.stringify({ hooks: [HOOK] });
+    return { line: `${SETTINGS_FILE} ${reason}, left untouched; add this entry to hooks.SessionStart by hand: ${entry}`, ok: false };
+}
+/**
+ * Writes a JSON file with a trailing newline, creating its folder.
+ *
+ * @param file - Absolute path.
+ * @param value - Value to serialize.
+ */
+function writeJson(file, value) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(value, null, JSON_INDENT)}\n`);
+}
+/**
+ * Tells whether some SessionStart entry already runs `agent-cloud-kit session`.
+ *
+ * @param entries - The `hooks.SessionStart` array.
+ * @returns True when any hook command contains the marker.
+ */
+function hasHook(entries) {
+    return entries.some((entry) => {
+        const hooks = entry?.hooks;
+        return Array.isArray(hooks) && hooks.some((h) => String(h?.command ?? "").includes(HOOK_MARKER));
+    });
+}
+/**
+ * Creates `.claude/cloud.json` unless it exists.
+ *
+ * @param repo - Repo root.
+ * @param packageVersion - Version of this package.
+ * @returns A line describing the outcome.
+ */
+function scaffoldConfig(repo, packageVersion) {
+    const file = join(repo, CONFIG_FILE);
+    if (existsSync(file))
+        return `${CONFIG_FILE} already exists, left as is`;
+    writeJson(file, {
+        $schema: `https://unpkg.com/${PACKAGE}@${packageVersion}/schema.json`,
+        version: packageVersion,
+        aptRepos: [],
+        apt: [],
+        docker: { pull: "auto" },
+        setup: [],
+        session: [],
+        requiredEnv: [],
+        domains: [],
+    });
+    return `created ${CONFIG_FILE}`;
+}
+/**
+ * Adds the SessionStart hook to `.claude/settings.json`, keeping everything else.
+ *
+ * @param repo - Repo root.
+ * @returns The outcome line and whether it succeeded.
+ */
+function registerHook(repo) {
+    const file = join(repo, SETTINGS_FILE);
+    let settings = {};
+    if (existsSync(file)) {
+        try {
+            settings = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            return addByHand("is not valid JSON");
+        }
+    }
+    if (!isRecord(settings))
+        return addByHand("is not a JSON object");
+    const hooks = settings.hooks ?? {};
+    if (!isRecord(hooks))
+        return addByHand('has a "hooks" that is not an object');
+    const entries = hooks.SessionStart ?? [];
+    if (!Array.isArray(entries))
+        return addByHand('has a "hooks.SessionStart" that is not an array');
+    if (hasHook(entries))
+        return { line: `${SETTINGS_FILE} already has the SessionStart hook`, ok: true };
+    writeJson(file, { ...settings, hooks: { ...hooks, SessionStart: [...entries, { hooks: [HOOK] }] } });
+    return { line: `added the SessionStart hook to ${SETTINGS_FILE}`, ok: true };
+}
+/**
+ * Sets a repo up for agent-cloud-kit; safe to run again. It is the only place that copies the
+ * `cloud-ready` skill into the repo (and links it for Claude Code).
+ *
+ * @param repo - Repo root.
+ * @param packageVersion - Version of this package, written into the config and the skill.
+ * @param packageRoot - Root of this package, which holds `skills/cloud-ready`.
+ * @returns What it did, and whether settings.json could be updated.
+ * @throws When the skill cannot be copied.
+ * @example
+ * init("/home/user/app", "1.0.0", "/usr/lib/node_modules/agent-cloud-kit").lines.forEach((l) => console.log(l));
+ */
+export function init(repo, packageVersion, packageRoot) {
+    const config = scaffoldConfig(repo, packageVersion);
+    const hook = registerHook(repo);
+    const skill = installSkill(repo, packageRoot, packageVersion);
+    const link = linkSkill(repo);
+    const lines = [config, hook.line, skill, ...(link ? [link] : [])];
+    return { lines: lines.map((l) => OUTPUT_PREFIX + l), ok: hook.ok };
+}