Sandcastle Review

Reusable CLI for the Sandcastle/Codex PR review workflow prototyped in the conakry workspace.

Develop This CLI

pnpm install
pnpm build
pnpm test
pnpm dev -- init
pnpm dev -- doctor
pnpm dev -- build-image --dry-run
pnpm dev -- run --base origin/main --no-pr

Run In A New Project

Install the package once in the project that should use Sandcastle review:

pnpm add -D @ppucc/sandcastle-review

Initialize the project. This creates .sandcastle/, sandcastle.config.mjs, and clean package scripts:

pnpm exec sandcastle-review init

Build the local review image:

pnpm review:build

Run a review against the base branch:

pnpm review --base origin/main

For the first smoke test, avoid creating a PR:

pnpm review --base origin/main --no-pr

Cleanup stays available through the generated script:

pnpm review:clean --prune-ledgers

The same setup works with npm:

npm install -D @ppucc/sandcastle-review
npm exec -- sandcastle-review init
npm run review:build
npm run review -- --base origin/main

bun add -d @ppucc/sandcastle-review
bunx sandcastle-review init
bun run review:build
bun run review --base origin/main

After init, each package manager can use the same generated scripts:

{
  "review": "sandcastle-review run",
  "review:build": "sandcastle-review build-image",
  "review:clean": "sandcastle-review cleanup"
}

sandcastle-review init detects the package manager from the lockfile, writes the review configuration, then offers an interactive wizard. If you choose to build the image, it can also launch the first review and ask for the base branch/ref. Use --no-wizard for CI or fully non-interactive setup:

pnpm exec sandcastle-review init --no-wizard --base origin/main

Configuration

sandcastle-review init writes sandcastle.config.mjs. Without a config file, run keeps the default review settings, including origin/main, sandcastle:kathmandu, the pnpm install command, Codex model defaults, prompt paths under .sandcastle, and PR creation enabled.

Project config can override:

export default {
  imageName: "sandcastle:review",
  packageManager: "pnpm",
  installCommand:
    "pnpm install --frozen-lockfile --ignore-scripts --prefer-offline --store-dir /.pnpm-store",
  createPr: true,
  model: "gpt-5.5",
  fastModel: "gpt-5.5",
  fastServiceTier: "fast",
  promptDir: ".sandcastle",
  dockerfilePath: ".sandcastle/Dockerfile",
  dockerBuildContext: ".sandcastle",
  codexCliVersion: "0.130.0",
};