maesttro 0.1.2 → 0.2.0

package/docker/Dockerfile

@@ -1,10 +1,43 @@
+# git is built from source: Debian ships 2.47 and the sandbox wants a recent
+# git. Builder matches node:22-slim's Debian so the runtime libs line up.
+FROM debian:bookworm-slim AS git-build
+ARG GIT_VERSION=2.55.0
+ARG GIT_SHA256=457fdb04dc8728e007d4688695e6912e6f680727920f2a40bf11eacc17505357
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl xz-utils \
+      build-essential libcurl4-openssl-dev libexpat1-dev libssl-dev zlib1g-dev \
+    && curl -fsSL -o /tmp/git.tar.xz \
+      "https://mirrors.edge.kernel.org/pub/software/scm/git/git-${GIT_VERSION}.tar.xz" \
+    && echo "${GIT_SHA256}  /tmp/git.tar.xz" | sha256sum -c - \
+    && tar -xJf /tmp/git.tar.xz -C /tmp \
+    && cd "/tmp/git-${GIT_VERSION}" \
+    && make -j"$(nproc)" prefix=/usr/local sysconfdir=/etc NO_TCLTK=1 NO_PERL=1 NO_PYTHON=1 NO_GETTEXT=1 NO_RUST=1 \
+      DESTDIR=/out all install
+
 FROM node:22-slim
 
-RUN apt-get update && apt-get install -y \
-    git curl gh ca-certificates \
+COPY --from=git-build /out/usr/local /usr/local
+
+# gh comes from GitHub's apt repo: Debian's lags by years and predates the
+# hosts.yml / config.yml behaviour the CLI's read-only session mount relies on
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates less libcurl4 libexpat1 \
+    && install -m 0755 -d /etc/apt/keyrings \
+    && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+    && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends gh \
     && rm -rf /var/lib/apt/lists/*
 
-# Curated client CLIs — keep in sync with src/clients.js
+# System-level, not ~/.gitconfig: /home/agent is the persistent volume and
+# shadows anything baked into home for existing installs
+COPY gitconfig /etc/gitconfig
+COPY sandbox-marker /etc/maesttro/sandbox
+
+# Curated client CLIs — keep in sync with src/clients.ts
 RUN npm install -g \
     @anthropic-ai/claude-code \
     opencode-ai \
@@ -12,14 +45,18 @@ RUN npm install -g \
 
 RUN useradd -m -s /bin/bash agent
 USER agent
+# Created as agent so a fresh volume inherits them; otherwise Docker creates
+# ~/.config and ~/.claude as root when it sets up the nested read-only mounts
+RUN mkdir -p /home/agent/.config/opencode /home/agent/.claude /home/agent/.codex
 WORKDIR /workspace
 
-# Bake curated default configs into each client's config path.
-# These become each client's out-of-the-box defaults inside the sandbox;
-# `maesttro update` refreshes them by rebuilding the image.
-COPY --chown=agent:agent configs/claude/   /home/agent/.claude/
-COPY --chown=agent:agent configs/opencode/ /home/agent/.config/opencode/
-COPY --chown=agent:agent configs/codex/    /home/agent/.codex/
+# Client configs are applied at container start by `maesttro configure`
+# (mounted from the host's install): /home/agent is a persistent volume, so
+# anything baked here would only ever reach brand-new volumes.
 
-ENTRYPOINT ["/bin/bash", "-lc"]
+# Starts as root only to remap agent to the host user's uid/gid (bind mounts
+# keep host ownership on Linux), then drops to agent before running anything
+USER root
+COPY --chmod=755 entrypoint.sh /usr/local/bin/maesttro-entrypoint
+ENTRYPOINT ["/usr/local/bin/maesttro-entrypoint"]
 CMD ["claude"]

package/docker/entrypoint.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+set -e
+
+uid="${MAESTTRO_HOST_UID:-}"
+gid="${MAESTTRO_HOST_GID:-$uid}"
+
+if [ -n "$uid" ] && [ "$uid" != "$(id -u agent)" ]; then
+  groupmod --non-unique --gid "$gid" agent
+  usermod --non-unique --uid "$uid" --gid "$gid" agent
+fi
+
+owner="$(id -u agent):$(id -g agent)"
+if [ -n "$uid" ] && [ "$(stat -c %u:%g /home/agent)" != "$owner" ]; then
+  find /home/agent -xdev -exec chown -h "$owner" {} + 2>/dev/null || true
+fi
+
+export HOME=/home/agent USER=agent LOGNAME=agent
+exec setpriv --reuid=agent --regid=agent --init-groups /bin/bash -c "$*"

package/docker/gitconfig

@@ -0,0 +1,8 @@
+[url "https://github.com/"]
+	insteadOf = git@github.com:
+	insteadOf = ssh://git@github.com/
+[credential "https://github.com"]
+	helper =
+	helper = !gh auth git-credential
+[safe]
+	directory = *

package/docker/sandbox-marker

@@ -0,0 +1 @@
+maesttro sandbox

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "maesttro",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Isolated Docker sandbox for running local coding agents (claude, opencode, codex, ...) under a dedicated bot GitHub identity, with curated configs baked in per client.",
+  "type": "module",
   "bin": {
-    "maesttro": "bin/maesttro.js"
+    "maesttro": "dist/maesttro.js"
   },
   "files": [
-    "bin",
-    "src",
+    "dist",
     "docker"
   ],
+  "scripts": {
+    "build": "bun build src/cli.ts --target node --format esm --outfile dist/maesttro.js",
+    "prepack": "bun run build",
+    "test": "bun test ./tests",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "clean": "rm -rf dist node_modules"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/esatto/maesttro.git",

package/bin/maesttro.js

@@ -1,49 +0,0 @@
-#!/usr/bin/env node
-
-const { setup } = require("../src/setup")
-const { doctor } = require("../src/doctor")
-const { launch, list } = require("../src/launch")
-const { update } = require("../src/update")
-
-const [, , cmd, ...rest] = process.argv
-
-const HELP = `maesttro — isolated sandbox for local coding agents
-
-Usage:
-  maesttro                Launch the default client (claude) in the sandbox
-  maesttro <client>        Launch a specific client — see \`maesttro list\`
-  maesttro list            Show available clients
-  maesttro setup [token]   One-time: build image, create volume, authenticate bot identity
-  maesttro update          Update the package and rebuild the image with refreshed client configs
-  maesttro doctor          Health check — Docker, image, volume, bot auth, isolation, clients
-  maesttro help            Show this message
-`
-
-async function main() {
-  switch (cmd) {
-    case undefined:
-      launch([])
-      break
-    case "setup":
-      await setup(rest)
-      break
-    case "update":
-      update()
-      break
-    case "doctor":
-      doctor()
-      break
-    case "list":
-      list()
-      break
-    case "help":
-    case "--help":
-    case "-h":
-      console.log(HELP)
-      break
-    default:
-      launch([cmd, ...rest])
-  }
-}
-
-main()

package/src/clients.js

@@ -1,26 +0,0 @@
-// Curated list of supported agent clients. Adding a new one here:
-// 1. add the entry below
-// 2. add `RUN npm install -g <npmPackage>` to docker/Dockerfile
-// 3. create docker/configs/<key>/ with any default config to bake in
-// then `maesttro update` (or `agent setup` during dev) picks it up.
-
-module.exports = {
-  claude: {
-    label: "Claude Code",
-    npmPackage: "@anthropic-ai/claude-code",
-    binary: "claude",
-    configDir: "/home/agent/.claude",
-  },
-  opencode: {
-    label: "opencode",
-    npmPackage: "opencode-ai",
-    binary: "opencode",
-    configDir: "/home/agent/.config/opencode",
-  },
-  codex: {
-    label: "OpenAI Codex CLI",
-    npmPackage: "@openai/codex",
-    binary: "codex",
-    configDir: "/home/agent/.codex",
-  },
-}

package/src/doctor.js

@@ -1,78 +0,0 @@
-const { execSync } = require("child_process")
-const { IMAGE, VOLUME } = require("./paths")
-const clients = require("./clients")
-
-function check(label, fn) {
-  try {
-    const detail = fn()
-    console.log(`  [ok]   ${label}${detail ? " — " + detail : ""}`)
-    return true
-  } catch (e) {
-    console.log(`  [fail] ${label}`)
-    return false
-  }
-}
-
-function doctor() {
-  console.log("== maesttro doctor ==\n")
-  let allOk = true
-
-  allOk &= check("Docker daemon reachable", () => {
-    execSync("docker info", { stdio: "ignore" })
-  })
-
-  allOk &= check("Sandbox image built", () => {
-    const out = execSync(
-      `docker image inspect ${IMAGE} --format "{{.Created}}"`,
-    )
-      .toString()
-      .trim()
-    return `built ${out}`
-  })
-
-  allOk &= check("Persistent volume exists", () => {
-    execSync(`docker volume inspect ${VOLUME}`, { stdio: "ignore" })
-  })
-
-  allOk &= check("Bot identity authenticated", () => {
-    const out = execSync(
-      `docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "gh auth status 2>&1"`,
-    ).toString()
-    const match = out.match(/Logged in to github\.com account (\S+)/)
-    return match ? match[1] : "authenticated"
-  })
-
-  allOk &= check(
-    "Personal SSH key NOT visible inside sandbox (isolation intact)",
-    () => {
-      const out = execSync(
-        `docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "cat ~/.ssh/id_rsa 2>&1 || echo MISSING"`,
-      ).toString()
-      if (!out.includes("MISSING") && !out.includes("No such file")) {
-        throw new Error(
-          "SSH key is reachable inside the sandbox — isolation broken",
-        )
-      }
-    },
-  )
-
-  for (const [key, c] of Object.entries(clients)) {
-    allOk &= check(`Client available: ${c.label}`, () => {
-      execSync(`docker run --rm ${IMAGE} "which ${c.binary}"`, {
-        stdio: "ignore",
-      })
-    })
-  }
-
-  console.log()
-  if (allOk) {
-    console.log("All checks passed.")
-  } else {
-    console.log(
-      "Some checks failed — run `maesttro setup` or `maesttro update` to fix, or check the failing item above.",
-    )
-    process.exit(1)
-  }
-}
-
-module.exports = { doctor }

package/src/launch.js

@@ -1,68 +0,0 @@
-const { spawnSync, execSync } = require("child_process")
-const fs = require("fs")
-const path = require("path")
-const os = require("os")
-const { IMAGE, VOLUME } = require("./paths")
-const clients = require("./clients")
-
-const DEFAULT_CLIENT = "claude"
-
-function ensureReady() {
-  try {
-    execSync(`docker image inspect ${IMAGE}`, { stdio: "ignore" })
-    execSync(`docker volume inspect ${VOLUME}`, { stdio: "ignore" })
-  } catch {
-    console.error("Sandbox isn't set up yet. Run `maesttro setup` first.")
-    process.exit(1)
-  }
-}
-
-function list() {
-  console.log("Available clients:\n")
-  for (const [key, c] of Object.entries(clients)) {
-    console.log(`  ${key.padEnd(10)} ${c.label}  (${c.npmPackage})`)
-  }
-  console.log(
-    `\nDefault: ${DEFAULT_CLIENT}. Run \`maesttro <client>\` to pick one, or \`maesttro <client> -- <args>\` to pass args through.`,
-  )
-}
-
-function launch(cmdArgs) {
-  ensureReady()
-
-  const cwd = process.cwd()
-  const sharedSkills =
-    process.env.AGENT_SHARED_SKILLS ||
-    path.join(os.homedir(), "agent-shared", "skills")
-
-  let clientKey = DEFAULT_CLIENT
-  let extraArgs = []
-
-  if (cmdArgs.length > 0 && clients[cmdArgs[0]]) {
-    clientKey = cmdArgs[0]
-    extraArgs = cmdArgs.slice(1)
-  } else if (cmdArgs.length > 0) {
-    // not a known client — treat the whole thing as a raw command, e.g. `maesttro bash`
-    return runRaw(cmdArgs.join(" "), cwd, sharedSkills)
-  }
-
-  const client = clients[clientKey]
-  const command = [client.binary, ...extraArgs].join(" ")
-  runRaw(command, cwd, sharedSkills)
-}
-
-function runRaw(command, cwd, sharedSkills) {
-  const mounts = ["-v", `${VOLUME}:/home/agent`, "-v", `${cwd}:/workspace`]
-  if (fs.existsSync(sharedSkills)) {
-    mounts.push("-v", `${sharedSkills}:/home/agent/.claude/skills:ro`)
-  }
-
-  const result = spawnSync(
-    "docker",
-    ["run", "-it", "--rm", ...mounts, "-w", "/workspace", IMAGE, command],
-    { stdio: "inherit" },
-  )
-  process.exit(result.status ?? 0)
-}
-
-module.exports = { launch, list }

package/src/paths.js

@@ -1,12 +0,0 @@
-const path = require("path")
-
-// __dirname here is <install>/src — package root is one level up.
-// This works identically whether installed via `npm link`, `npm i -g .`,
-// or from the registry — npm always keeps the package's own files together.
-const PKG_ROOT = path.resolve(__dirname, "..")
-const DOCKERFILE_DIR = path.join(PKG_ROOT, "docker")
-
-const IMAGE = "maesttro-runner:latest"
-const VOLUME = "maesttro-home"
-
-module.exports = { PKG_ROOT, DOCKERFILE_DIR, IMAGE, VOLUME }

package/src/setup.js

@@ -1,101 +0,0 @@
-const { execSync, spawnSync } = require("child_process")
-const readline = require("readline")
-const fs = require("fs")
-const { DOCKERFILE_DIR, IMAGE, VOLUME } = require("./paths")
-
-function run(cmd, opts = {}) {
-  return execSync(cmd, { stdio: "inherit", ...opts })
-}
-
-function ask(question) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  })
-  return new Promise((resolve) =>
-    rl.question(question, (answer) => {
-      rl.close()
-      resolve(answer.trim())
-    }),
-  )
-}
-
-async function setup(args) {
-  console.log("== maesttro setup ==\n")
-
-  // 1. Docker present?
-  try {
-    execSync("docker info", { stdio: "ignore" })
-  } catch {
-    console.error(
-      "Docker doesn't seem to be running. Start Docker Desktop (or the docker daemon) and try again.",
-    )
-    process.exit(1)
-  }
-
-  // 2. Build image from the Dockerfile bundled inside this package
-  console.log(
-    "-> Building sandbox image (this pulls node:22-slim + installs CLIs, first run only)...",
-  )
-  run(`docker build -t ${IMAGE} "${DOCKERFILE_DIR}"`)
-
-  // 3. Create persistent volume
-  console.log("\n-> Ensuring persistent volume exists...")
-  execSync(`docker volume create ${VOLUME}`, { stdio: "ignore" })
-
-  // 4. Get bot token — file path arg, or interactive paste
-  const tokenPath = args[0]
-  let token
-  if (tokenPath && fs.existsSync(tokenPath)) {
-    token = fs.readFileSync(tokenPath, "utf8").trim()
-  } else {
-    console.log(
-      "\nPaste the bot account's fine-grained GitHub token (input hidden not supported in plain readline — clear your scrollback after):",
-    )
-    token = await ask("Token: ")
-  }
-  if (!token) {
-    console.error(
-      "No token provided. Run `maesttro setup /path/to/token.txt` or paste one when prompted.",
-    )
-    process.exit(1)
-  }
-
-  // 5. Authenticate the bot identity into the volume
-  console.log("\n-> Authenticating bot identity into the sandbox volume...")
-  const auth = spawnSync(
-    "docker",
-    [
-      "run",
-      "-i",
-      "--rm",
-      "-v",
-      `${VOLUME}:/home/agent`,
-      IMAGE,
-      "gh auth login --with-token && gh auth setup-git",
-    ],
-    { input: token, stdio: ["pipe", "inherit", "inherit"] },
-  )
-  if (auth.status !== 0) {
-    console.error(
-      "\nToken authentication failed — check the token is valid and has repo access.",
-    )
-    process.exit(1)
-  }
-
-  // 6. Verify isolation
-  console.log("\n-> Verifying isolation...")
-  console.log("   gh identity inside sandbox:")
-  run(`docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "gh auth status"`)
-  console.log("   personal SSH key should NOT be visible:")
-  run(
-    `docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "cat ~/.ssh/id_rsa 2>&1 || true"`,
-  )
-
-  console.log(
-    "\nSetup complete. Run `maesttro` from any project directory to start a session,",
-  )
-  console.log("or `maesttro list` to see available clients.")
-}
-
-module.exports = { setup }

package/src/update.js

@@ -1,22 +0,0 @@
-const { execSync } = require("child_process")
-const { DOCKERFILE_DIR, IMAGE, PKG_ROOT } = require("./paths")
-const { name: packageName } = require(`${PKG_ROOT}/package.json`)
-
-function update() {
-  console.log("== maesttro update ==\n")
-
-  console.log(`-> Updating ${packageName} package...`)
-  execSync(`npm i -g ${packageName}@latest`, { stdio: "inherit" })
-
-  console.log("\n-> Rebuilding sandbox image with refreshed client configs...")
-  execSync(`docker build -t ${IMAGE} "${DOCKERFILE_DIR}"`, { stdio: "inherit" })
-
-  console.log(
-    "\nUpdate complete. Bot identity and your project files are untouched —",
-  )
-  console.log(
-    "only the image (client versions + curated configs) was refreshed.",
-  )
-}
-
-module.exports = { update }