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

package/dist/session.js

@@ -0,0 +1,246 @@
+/**
+ * @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, packageSpec, 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.
+ * @param packageVersion - Version of the running package, for the setup command.
+ * @returns Warning messages, without prefix.
+ */
+function machineWarnings(repo, config, state, packageVersion) {
+    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 ${packageSpec(packageVersion)} 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, ctx.packageVersion));
+    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));
+    }
+}

package/dist/skill.js

@@ -0,0 +1,148 @@
+/**
+ * @file The `cloud-ready` skill that `init` copies into the repo, and the link Claude Code needs
+ * to discover it.
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Repo-relative directory of the `cloud-ready` skill. */
+export const SKILL_DIR = ".agents/skills/cloud-ready";
+/** Directory of the skill inside this package. */
+const PACKAGE_SKILL_DIR = "skills/cloud-ready";
+/** Repo-relative folder of the skills that Claude Code discovers. */
+const CLAUDE_SKILLS_DIR = ".claude/skills";
+/** Repo-relative folder of the skills that skills-manager installs. */
+const AGENTS_SKILLS_DIR = ".agents/skills";
+/** Repo-relative path of the link to the skill that Claude Code discovers. */
+const SKILL_LINK = `${CLAUDE_SKILLS_DIR}/cloud-ready`;
+/** Target of `SKILL_LINK`, relative to the folder that holds it. */
+const SKILL_LINK_TARGET = `../../${SKILL_DIR}`;
+/** Matches the frontmatter at the start of a skill file; group 1 is its body. */
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+/** Matches the `metadata:` block of the frontmatter, up to the next top-level key or the end. */
+const METADATA_BLOCK = /^metadata:[ \t]*\n((?:[ \t]+.*(?:\n|$))*)/m;
+/** Matches an indented `version:` line inside the metadata block; the value may be quoted. */
+const VERSION_LINE = /^\s+version:\s*"?([^"\n]+)"?$/m;
+/**
+ * Reads `metadata.version` from the frontmatter of the installed skill.
+ *
+ * @param repo - Repo root.
+ * @returns The version, or undefined when the skill or its version is missing.
+ * @example
+ * skillVersion("/home/user/app"); // "1.0.0"
+ */
+export function skillVersion(repo) {
+    const file = join(repo, SKILL_DIR, "SKILL.md");
+    if (!existsSync(file))
+        return undefined;
+    const frontmatter = FRONTMATTER.exec(readFileSync(file, "utf8"))?.[1] ?? "";
+    const block = METADATA_BLOCK.exec(frontmatter)?.[1] ?? "";
+    return VERSION_LINE.exec(block)?.[1]?.trim();
+}
+/**
+ * Sets `metadata.version` in the frontmatter of a skill file, adding the block when it is missing.
+ *
+ * @param text - Content of SKILL.md.
+ * @param version - Version to write.
+ * @returns The new content; unchanged when the file has no frontmatter.
+ * @example
+ * withVersion('---\nname: x\nmetadata:\n  version: "0.0.0"\n---\n', "1.0.0"); // version "1.0.0"
+ */
+function withVersion(text, version) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return text;
+    const frontmatter = match[1] ?? "";
+    const line = `  version: "${version}"`;
+    const block = METADATA_BLOCK.exec(frontmatter);
+    let updated;
+    if (!block) {
+        updated = `${frontmatter}\nmetadata:\n${line}`;
+    }
+    else {
+        const body = block[1] ?? "";
+        const newBody = VERSION_LINE.test(body) ? body.replace(VERSION_LINE, line) : `${line}\n${body}`;
+        const head = block[0].slice(0, block[0].length - body.length);
+        updated = frontmatter.slice(0, block.index) + head + newBody + frontmatter.slice(block.index + block[0].length);
+    }
+    return `---\n${updated}\n---${text.slice(match[0].length)}`;
+}
+/**
+ * Copies the `cloud-ready` skill of this package into the repo, with `metadata.version` set to the
+ * package version. Leaves it untouched when it is already at that version; otherwise replaces the
+ * whole folder atomically (copy to a temp folder, then rename).
+ *
+ * @param repo - Repo root.
+ * @param packageRoot - Root of this package, which holds `skills/cloud-ready`.
+ * @param packageVersion - Version of this package.
+ * @returns A line describing the outcome.
+ * @throws When the package has no skill or the copy fails (the installed skill is kept).
+ * @example
+ * installSkill("/home/user/app", "/usr/lib/node_modules/agent-cloud-kit", "1.0.0");
+ * // "installed .agents/skills/cloud-ready 1.0.0"
+ */
+export function installSkill(repo, packageRoot, packageVersion) {
+    const current = skillVersion(repo);
+    if (current === packageVersion)
+        return `${SKILL_DIR} already at ${packageVersion}`;
+    const source = join(packageRoot, PACKAGE_SKILL_DIR);
+    if (!existsSync(join(source, "SKILL.md")))
+        throw new Error(`${PACKAGE_SKILL_DIR}/SKILL.md not found in ${packageRoot}`);
+    const target = join(repo, SKILL_DIR);
+    const temp = `${target}.${process.pid}.tmp`;
+    const old = `${target}.${process.pid}.old`;
+    mkdirSync(dirname(target), { recursive: true });
+    try {
+        rmSync(temp, { recursive: true, force: true });
+        cpSync(source, temp, { recursive: true });
+        const skillFile = join(temp, "SKILL.md");
+        writeFileSync(skillFile, withVersion(readFileSync(skillFile, "utf8"), packageVersion));
+        if (existsSync(target))
+            renameSync(target, old);
+        renameSync(temp, target);
+    }
+    catch (err) {
+        rmSync(temp, { recursive: true, force: true });
+        if (existsSync(old) && !existsSync(target))
+            renameSync(old, target);
+        throw err;
+    }
+    rmSync(old, { recursive: true, force: true });
+    return current === undefined ? `installed ${SKILL_DIR} ${packageVersion}` : `updated ${SKILL_DIR} from ${current} to ${packageVersion}`;
+}
+/**
+ * Tells whether a path exists, counting a broken symlink as existing.
+ *
+ * @param path - Absolute path.
+ * @returns True when something is there.
+ */
+function present(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Links the skill where Claude Code discovers it: Claude Code does not read `.agents/skills/`, so
+ * this creates the relative symlink `.claude/skills/cloud-ready -> ../../.agents/skills/cloud-ready`.
+ * Does nothing when `.claude/skills` already resolves to `.agents/skills` or the entry exists.
+ *
+ * @param repo - Repo root.
+ * @returns A line describing what was done, or undefined when nothing was needed.
+ * @example
+ * linkSkill("/home/user/app"); // "linked .claude/skills/cloud-ready to .agents/skills/cloud-ready"
+ */
+export function linkSkill(repo) {
+    const claudeSkills = join(repo, CLAUDE_SKILLS_DIR);
+    const agentsSkills = join(repo, AGENTS_SKILLS_DIR);
+    if (existsSync(claudeSkills) && existsSync(agentsSkills) && realpathSync(claudeSkills) === realpathSync(agentsSkills))
+        return undefined;
+    const link = join(repo, SKILL_LINK);
+    if (present(link))
+        return undefined;
+    mkdirSync(claudeSkills, { recursive: true });
+    symlinkSync(SKILL_LINK_TARGET, link);
+    return `linked ${SKILL_LINK} to ${SKILL_DIR}`;
+}