Runcastle

Dependency Upgrade & Fix Loop

MIT0 downloads

by runcastle

v1.0.0

A single Claude Code agent brings your dependencies up to date in safe batches — patches, then minors, then one major at a time — fixing any breakage it introduces, gated by a hard build + test check every round until everything is current and green.

Topology

Disclosures

Disclosures — declared side-effect surface

Everything below runs on your machine or inside the sandbox when you use this workflow. Mismatches between these declarations and the actual code block publishing.

Host hooks

Commands executed on YOUR host machine by Sandcastle lifecycle hooks.

None declared.

Sandbox hooks

Commands executed inside the sandbox container.

  • npm install

Network access

None beyond your package registry. The agent reads and writes only the local repository inside the sandbox; the `npm install` sandbox hook and the agent's reinstall step fetch packages from your declared registry.

Shell expansion

No shell-expansion blocks in prompt files.

Files

Diff vs the stock Sandcastle 0.12.0 template Dockerfile — green lines were added by the author, red lines were removed from stock.

+# Sandbox image for the Dependency Upgrade & Fix Loop workflow.
+# Node 22 + git + the Claude Code CLI, running as a non-root `agent` user.
+# Add your project's toolchain (python, go, ...) here if your build or suite
+# needs it.
FROM node:22-bookworm
-# System dependencies.
RUN apt-get update && apt-get install -y --no-install-recommends \
git \
curl \
jq \
ca-certificates \
&& rm -rf /var/lib/apt/lists/*
# Claude Code CLI (the agent runtime).
RUN npm install -g @anthropic-ai/claude-code
# Non-root agent user. `sandcastle docker build-image` aligns AGENT_UID/GID to
# the host user via --build-arg to avoid permission errors on bind mounts.
ARG AGENT_UID=1000
ARG AGENT_GID=1000
RUN groupadd --gid ${AGENT_GID} agent \
&& useradd --uid ${AGENT_UID} --gid ${AGENT_GID} --create-home --shell /bin/bash agent
USER agent
WORKDIR /workspace
Show full Dockerfile (highlighted)
# Sandbox image for the Dependency Upgrade & Fix Loop workflow.
# Node 22 + git + the Claude Code CLI, running as a non-root `agent` user.
# Add your project's toolchain (python, go, ...) here if your build or suite
# needs it.
FROM node:22-bookworm

RUN apt-get update && apt-get install -y --no-install-recommends \
      git \
      curl \
      jq \
      ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# Claude Code CLI (the agent runtime).
RUN npm install -g @anthropic-ai/claude-code

# Non-root agent user. `sandcastle docker build-image` aligns AGENT_UID/GID to
# the host user via --build-arg to avoid permission errors on bind mounts.
ARG AGENT_UID=1000
ARG AGENT_GID=1000
RUN groupadd --gid ${AGENT_GID} agent \
 && useradd --uid ${AGENT_UID} --gid ${AGENT_GID} --create-home --shell /bin/bash agent

USER agent
WORKDIR /workspace

README

Dependency Upgrade & Fix Loop

Stale dependencies rot quietly — until a security advisory or a blocked feature forces a painful, all-at-once upgrade. This workflow keeps that debt from piling up by letting a single Claude Code agent do the tedious part: bump your dependencies in safe batches and repair whatever the bumps break, all behind a hard build-and-test gate.

What it does

On each round the agent surveys what is outdated and bumps a conservative batch in priority order — all safe patches together, then minors, then a single major at a time. It reinstalls, then works through the fallout: renamed APIs, moved exports, changed defaults, type errors. It follows each package's migration notes and makes the smallest change that adapts your code to the new version. If a major upgrade is genuinely too risky, it skips it, leaves a // TODO(deps): note explaining why, and keeps the tree green rather than leaving it broken. When everything is current and passing, it emits <promise>ALL_GREEN</promise> and stops.

How it works

main.ts creates one warm Docker sandbox with createSandbox() and installs dependencies once via an onSandboxReady hook. It then loops up to five rounds. Every round is an agent pass followed by a hard gate that runs npm run build and then npm test through sandbox.exec(). If either is red, the failure is handed back so the next round can fix it — the loop never stacks broken upgrades. Because the container stays warm, the base install is paid for once, not per round.

The topology is a tight loop: install → bump deps + fix breakage → verify (build + test) → back to bump.

Requirements

Set CLAUDE_CODE_OAUTH_TOKEN in .sandcastle/.env (run claude setup-token on your host). Your repo should expose a working npm run build and npm test; adjust the prompt if your stack uses a different package manager or scripts. Build the image once with npx @ai-hero/sandcastle docker build-image, then run it with npx tsx .sandcastle/main.ts. Work lands on the agent/deps branch for review before you merge.