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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramón Soto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,233 @@
-# Temporary Holding Version
+# agent-cloud-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A zero-dependency CLI that prepares [Claude Code on the web](https://claude.ai/code) cloud
+sessions. It installs the tool versions a repo pins, starts Docker, completes the partial
+clone, and tells you when the saved machine is not what the repo asks for, working around the
+limits of the cloud sandbox that the platform does not document.
+
+> Not affiliated with or endorsed by Anthropic. Works with Claude Code on the web.
+>
+> Continues `@ramon-sg/claude-cloud` (its 1.0.0), with no automatic migration: install this package
+> and run `init` again.
+
+- Written in TypeScript, published compiled, **no runtime dependencies**, Node `>=20` (the cloud
+  image ships Node 22, so it runs before any tool of your repo is installed).
+- The **repo decides the version**: `.claude/cloud.json` pins the exact version of this package,
+  so updating it is a commit.
+
+## What it solves
+
+Installing Node and starting Docker takes a few lines of shell. The expensive part is what the
+platform does not tell you:
+
+- The egress proxy blocks GitHub releases and GitHub's GraphQL API, so tools that download from
+  GitHub fail. `agent-cloud-kit` installs Node from nodejs.org; Bun, Deno, pnpm and Yarn from npm;
+  and uv from PyPI.
+- The setup script runs from `/home/user`, not from the repo, and a failure is silent.
+- A setup that takes more than about 5 minutes does not leave a saved machine.
+- Two `apt` runs at the same time collide on the dpkg lock, so apt work runs in series.
+- `dockerd` is off and the clone is partial (shallow, without `origin/<default branch>`).
+- There is no IPv6.
+- The proxy replaces TLS, and `docker build` does not trust its CA.
+- A resumed session does not run the setup again, and changing the setup does not rebuild the
+  saved machine.
+
+## The flow
+
+1. **Install your agent tooling** with agent-kitchen (config, hook and skill arrive in the repo).
+2. **Run `npx agent-cloud-kit prepare`** in a local terminal. It asks nothing up front: it
+   creates a worktree on a dated branch, runs `init`, and opens
+   Claude locally with the `cloud-ready` skill so it can write the cloud preparation with you. Then
+   it writes the manual, commits, pushes and opens a draft PR.
+3. **Configure the environment in claude.ai** following `docs/agent-cloud.md`, which `prepare`
+   generated from your `.claude/cloud.json`. The document keeps growing: when the skill, locally
+   or in the cloud, finds that a domain or an environment variable is missing, it adds it to
+   `.claude/cloud.json`, regenerates the document and tells you in the session what to add in
+   claude.ai.
+4. **Verification in the cloud:** `prepare` launches `claude --cloud` on that branch, so a real
+   cloud session runs `cloud-ready verify`, fixes what fails and reports in the PR.
+
+`claude --cloud` uses the environment chosen with `/remote-env` in `claude`, and the Claude GitHub
+App must be installed on the repo (without it the session cannot push). Inside the cloud, `gh api`
+(REST) works; GraphQL (`gh pr list`, `gh pr create`) is blocked. If `prepare` is interrupted,
+`npx agent-cloud-kit prepare --resume` continues in the existing worktree.
+
+## No opinion about tests
+
+This package does not impose any way of testing, and a repo may have no tests at all (then the
+cloud only needs a prepared machine). The `cloud-ready` skill finds the tests your repo already
+has, tells you which would run in the cloud as they are, and proposes adapting the cloud
+preparation or, only if needed, a cloud variant of them. Nothing changes without your approval.
+
+### The `cloud-ready` skill
+
+`init` copies it to `.agents/skills/cloud-ready` and links it from `.claude/skills/cloud-ready`,
+because Claude Code does not discover `.agents/skills`. Commit both. `cloud-ready configure` runs
+locally with you; `cloud-ready verify` runs inside the cloud session. The skill and the generated
+manual are written in Spanish.
+
+## Set up claude.ai
+
+In the environment form at `https://claude.ai/code`:
+
+1. **Network access:** choose *Custom* and keep **Also include default list of common package
+   managers** checked. Add any extra domains your `apt` repos or setup steps need, one per line.
+   Run `agent-cloud-kit doctor` in a session to see which hosts are blocked (it probes with `curl`,
+   so it goes through the proxy like the setup does). If the setup never ran, use
+   `npx agent-cloud-kit doctor`.
+2. **Setup script:** the cloud runs it as root from `/home/user`, before Claude starts:
+
+   ```bash
+   #!/bin/bash
+   npx -y agent-cloud-kit@1 setup
+   ```
+
+   The `@1` only pins the launcher. Each repo then relaunches the exact version it asks for, so a
+   new launcher major is adopted by editing this field on purpose. To force the saved machine to
+   be rebuilt, change anything in this field (a comment with the date works).
+
+3. In each repo run `npx agent-cloud-kit init`, then commit `.claude/cloud.json`,
+   `.claude/settings.json`, `.agents/skills/cloud-ready` and the `.claude/skills/cloud-ready` link.
+
+Environment changes are read when a session is created: start a new session to test them. A
+resumed session does not run the setup again.
+
+## `.claude/cloud.json`
+
+It lives in `.claude/` rather than in `package.json` so repos without Node can use it. A JSON
+schema ships with the package (`schema.json`). Unknown fields are reported and ignored, and a
+broken file never stops a session.
+
+```json
+{
+  "$schema": "https://unpkg.com/agent-cloud-kit@1.0.0/schema.json",
+  "version": "1.0.0",
+  "aptRepos": ["https://example.com/setup.deb.sh"],
+  "apt": ["direnv", "jq"],
+  "domains": ["registry.example.com"],
+  "docker": { "pull": "auto" },
+  "setup": ["scripts/cloud-setup-extra.sh"],
+  "session": ["scripts/worktree-setup.sh"],
+  "requiredEnv": ["API_TOKEN"],
+  "notes": ".claude/cloud-notes.md"
+}
+```
+
+| Field         | Required | Meaning                                                                                                                                              |
+| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`     | yes      | Exact version of this package to run (no ranges). If `setup` runs a different one it relaunches with this one.                                       |
+| `aptRepos`    | no       | HTTPS URLs of setup scripts that add APT repositories; each is downloaded and piped to `bash` before installing packages.                            |
+| `apt`         | no       | Debian packages to install. Names are validated and passed as arguments, never to a shell.                                                           |
+| `domains`     | no       | Extra hosts the environment must allow; `doctor` probes them and the manual lists them.                                                              |
+| `docker.pull` | no       | `"auto"` (default) pulls the images found in compose files and in `FROM` lines pinned with `@sha256`; a list of image names pulls those; `false` leaves Docker alone during `setup`. |
+| `setup`       | no       | Shell commands run once during `setup`, in the repo, with the pinned tools first on `PATH`. A failing command is recorded and the rest still run.    |
+| `session`     | no       | Shell commands run at the start of every session, in the repo. Their output goes to stderr (not into Claude's context), each one is stopped after 2 minutes, and a failing command is reported while the rest still run. |
+| `requiredEnv` | no       | Environment variables that must be set; the session warns about the missing ones.                                                                    |
+| `notes`       | no       | What does and does not run in the cloud: free text, or a path, relative to the repo, of a text file inside it (then its contents are used). Printed at the start of every session and shown in the manual. `prepare` expects the file the `cloud-ready` skill writes. |
+
+Tool versions are deduced, in order, from `.tool-versions`, `mise.toml`, `.nvmrc` and
+`package.json#packageManager`. The default branch comes from `origin/HEAD`. Each tool is installed
+under `/opt/agent-cloud-kit/<tool>-<version>`, so versions coexist and the repos of one environment
+share the folder. A tool with no installer produces a warning and is skipped.
+
+A Node version that is not exact (`22`, `22.1`, `lts/iron`, `lts/*` or `node`) is resolved during
+`setup` to the newest matching release in `https://nodejs.org/dist/index.json` and installed under
+`/opt/agent-cloud-kit/node-<exact version>`. The resolved version is recorded in the machine state, so
+`session` puts the same folder on `PATH`.
+
+## Commands
+
+| Command                       | What it does                                                                                                                                                                                                                       |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-cloud-kit setup [--repo <path>]` | Runs as root before Claude starts. For every git repo in the home dir (`/home/user`) with a `.claude/cloud.json` (or only `<path>`): installs tools, apt packages and images and copies itself (no npm, no network) to `/opt/agent-cloud-kit/bin/agent-cloud-kit`, then runs the `setup` steps and records the result. Repos without the file are skipped with a notice. It always exits 0: failures are recorded, never fatal. |
+| `agent-cloud-kit session`        | Runs from the `SessionStart` hook, in seconds and without network (except to complete the clone). Warns when setup did not run, failed steps, or the machine was prepared with another configuration; writes the `PATH` line (the pinned tools, then `/opt/agent-cloud-kit/bin`, so `agent-cloud-kit` itself resolves) to `$CLAUDE_ENV_FILE`; starts Docker; fetches the full history and `origin/<default branch>`; runs the `session` steps. It never fails the session start. |
+| `agent-cloud-kit docker`         | Starts `dockerd` detached and waits up to 60 seconds for it to answer. Exits 1 if it does not, at once when `dockerd` is not installed.                                                                                             |
+| `agent-cloud-kit doctor`         | Checks that the proxy lets the needed hosts through, that the pinned tools are installed, that Docker answers, and the recorded state (fingerprint and each step). Exits 1 if any check fails.                                       |
+| `agent-cloud-kit init`           | Creates `.claude/cloud.json` if missing, adds the `SessionStart` hook to `.claude/settings.json` (keeping the hooks already there), copies the `cloud-ready` skill to `.agents/skills/cloud-ready` when its version differs, and links it from `.claude/skills/cloud-ready`. Safe to run again.                                                                           |
+| `agent-cloud-kit manual`         | Writes `docs/agent-cloud.md` from `.claude/cloud.json`, deterministically: the exact setup script (`agent-cloud-kit@<major>`, or the exact version for a release candidate), domains, variable names, how to verify the environment. |
+| `agent-cloud-kit prepare [--resume]` | Local only, needs an interactive terminal: sets the repo up for the cloud on a new branch in a worktree, opens the PR and verifies it in a real cloud session (see "The flow"). `--resume` continues in the existing worktree. |
+
+Environment variables: `AGENT_CLOUD_KIT_DIR` overrides `/opt/agent-cloud-kit` and `AGENT_CLOUD_KIT_HOME`
+overrides `/home/user`; both exist mainly for tests.
+
+### The `SessionStart` hook
+
+`init` adds this hook. Outside a cloud session it does nothing, and it calls the copy of the
+package that `setup` left on the saved machine, so it needs no network and no `node_modules`:
+
+```json
+{
+  "type": "command",
+  "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'",
+  "timeout": 600
+}
+```
+
+When the repo pins another version than the one that is running and that version is installed,
+`session` hands over to it.
+
+### Machine fingerprint
+
+`setup` stores a fingerprint of the config, the pinned versions, the images and the package
+version. If the repo changes afterwards, `session` warns that "the machine was prepared with
+another configuration". The saved machine is rebuilt by claude.ai about every 7 days, or when you
+edit the setup script field.
+
+## The proxy CA and `docker build`
+
+The cloud proxy replaces TLS, so `docker build` does not trust it. `session` finds the CA bundle
+(`SSL_CERT_FILE`, then `NODE_EXTRA_CA_CERTS`, then `/root/.ccr/ca-bundle.crt`) and exports its
+path as `CLOUD_PROXY_CA`. Pass it to the build as a secret, only when it is set:
+
+```bash
+docker build ${CLOUD_PROXY_CA:+--secret id=proxy_ca,src="$CLOUD_PROXY_CA"} -t app .
+```
+
+```dockerfile
+RUN --mount=type=secret,id=proxy_ca \
+    if [ -f /run/secrets/proxy_ca ]; then \
+      export SSL_CERT_FILE=/run/secrets/proxy_ca NODE_EXTRA_CA_CERTS=/run/secrets/proxy_ca; \
+    fi; \
+    npm ci
+```
+
+## What it does not do
+
+- It does not make the platform's limits go away: no open ports or previews, and `gh pr` and
+  `gh issue` fail (GitHub's GraphQL is blocked; use `gh api`). `gh pr ready` fails too; the 403
+  names a REST route for it (`POST /repos/{owner}/{repo}/pulls/{n}/ccr/ready_for_review`), not
+  yet verified.
+- It does not configure claude.ai for you: the environment is yours to set, following the manual.
+- It does not download skills in the cloud; they live in the repo.
+- It does not impose a way of testing.
+- It does not install plugins, or run the hooks of plugins, from your machine.
+- It does not install tools from GitHub releases; the proxy blocks them.
+- It does not run Docker inside Docker, and it does not start a Docker daemon in local sessions
+  (the hook exits when `CLAUDE_CODE_REMOTE` is not `true`).
+- It does not keep secrets safe: environment variables of a cloud environment are readable by
+  anyone who uses it.
+- It does not run your `setup` steps on a resumed session; only a new session does.
+- `setup` runs code fetched from npm as root. The version is pinned in the repo and the relaunch
+  uses exactly that version.
+
+## Releasing
+
+For maintainers. Releases are published by `.github/workflows/publish.yml` when a GitHub release is
+published; the workflow fails if the release tag, without its leading `v`, differs from the
+`version` in `package.json`.
+
+The first publish of a new package cannot use npm trusted publishing, because trusted publishing
+is configured on a package that already exists. Publish the first version by hand:
+
+1. Either run `npm ci && npm run build && npm publish --provenance=false` from a machine logged in
+   to npm (`npm login`) with publish rights on the `agent-cloud-kit` package (provenance needs a CI, and
+   `package.json` asks for it), or run the workflow once with an `NPM_TOKEN` secret
+   (`NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` on the publish step).
+2. On npmjs.com, open the package settings and add a trusted publisher: this GitHub repository and
+   the `publish.yml` workflow.
+3. Remove the `NPM_TOKEN` secret if you created one. From then on, bump `version` in
+   `package.json`, update `CHANGELOG.md`, and publish a GitHub release tagged `v<version>`. A version with a prerelease suffix (`1.0.0-rc.1`) is published under the `next` tag once a stable version is `latest`; before that it also becomes `latest`, so tools that read `latest` (agent-kitchen) see it. Mark its GitHub release as a pre-release.
+
+## License
+
+MIT

package/dist/ca.js

@@ -0,0 +1,30 @@
+/**
+ * @file Discovery of the cloud proxy CA bundle and safe shell quoting for the lines written to the env file.
+ */
+import { PROXY_CA_DEFAULT } from "./constants.js";
+/** Environment variables that may point at the CA bundle, in priority order. */
+const CA_ENV_VARS = ["SSL_CERT_FILE", "NODE_EXTRA_CA_CERTS"];
+/**
+ * Finds the proxy CA bundle: `SSL_CERT_FILE`, then `NODE_EXTRA_CA_CERTS`, then the default path.
+ *
+ * @param env - Process environment.
+ * @param exists - Tells whether a file exists.
+ * @returns The first candidate that exists, or undefined.
+ * @example
+ * findProxyCa({ SSL_CERT_FILE: "/etc/ca.crt" }, () => true); // "/etc/ca.crt"
+ */
+export function findProxyCa(env, exists) {
+    const candidates = [...CA_ENV_VARS.map((name) => env[name]), PROXY_CA_DEFAULT];
+    return candidates.find((path) => Boolean(path) && exists(path));
+}
+/**
+ * Quotes a value for a POSIX shell using single quotes, so nothing in it is interpreted.
+ *
+ * @param value - Any string.
+ * @returns The value wrapped in single quotes, with embedded quotes escaped as `'\''`.
+ * @example
+ * shellQuote("it's"); // 'it'\''s'
+ */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}