@olhapi/maestro 0.1.5-rc.12 → 0.1.5-rc.14

package/README.md

@@ -29,7 +29,7 @@ The docs site is organized around the same operator flow the product uses:
 
 ### npm
 
-Current public npm install on supported platforms:
+Install the launcher package:
 
 ```bash
 npm install -g @olhapi/maestro
@@ -43,19 +43,47 @@ npm install -g @olhapi/maestro@next
 
 The installed command name is still `maestro`.
 
-Official npm builds currently cover:
+This package no longer ships native platform binaries. It installs a thin host
+launcher that runs Maestro from the published Docker image, so Docker is now a
+first-party runtime requirement for normal CLI use.
 
-| Platform | Arch | Notes |
-| --- | --- | --- |
-| macOS | arm64 | native package |
-| macOS | x64 | native package |
-| Linux | x64 | glibc only |
-| Linux | arm64 | glibc only |
-| Windows | x64 | native package |
+The npm launcher requires Node 24 or newer because it uses the built-in
+`node:sqlite` module to inspect the Maestro database before Docker starts.
 
-Linux npm packages currently target glibc only. Alpine and other musl-based distros should build from source or use Docker.
+The launcher resolves its runtime image in this order:
 
-### Docker
+- `MAESTRO_IMAGE`
+- the locally pinned image from `~/.maestro/launcher/runtime.json`
+- the npm package version you installed
+
+Pull and pin the latest runtime image explicitly:
+
+```bash
+maestro self-update
+```
+
+Pin a specific image version:
+
+```bash
+maestro self-update --version 0.117.0
+```
+
+Validate the local launcher install, Docker access, and runtime pin:
+
+```bash
+maestro doctor install
+```
+
+### Curl Installer
+
+If you want the same launcher without npm, install it with the repository
+script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/olhapi/maestro/main/scripts/install_maestro.sh | sh
+```
+
+### Docker Runtime
 
 Published image:
 
@@ -77,7 +105,8 @@ docker run --rm -v ./repo:/repo -v ./data:/data ghcr.io/olhapi/maestro:latest ru
 
 ### Build From Source
 
-For local development or unsupported platforms:
+For local development, contributor workflows, or environments where Docker is
+not the right runtime:
 
 ```bash
 go build -o maestro ./cmd/maestro
@@ -89,7 +118,7 @@ development package for the standard `make build` / `make test` flow.
 Local contributor Docker build:
 
 ```bash
-docker build -t maestro-local .
+docker build -t maestro-local --build-arg CODEX_VERSION="$(./scripts/codex_supported_version.sh)" .
 ```
 
 ## Quick Start
@@ -132,6 +161,12 @@ When `--db` is omitted, Maestro uses `~/.maestro/maestro.db` by default. When `-
 
 Running `maestro run` without `repo_path` starts the shared daemon for the current database. It does not infer the repo from your shell working directory.
 
+Before Docker starts, `maestro run` performs a one-time preflight pass. When a
+database file exists, the launcher reads the discovered workflow files, resolves
+their `workspace.root` values, and mounts the repo and workspace directories up
+front. If the database file does not exist yet, it skips discovery so fresh
+bootstrap flows still work.
+
 Issue images are stored next to the active database under `assets/images`. With the default database path, that means `~/.maestro/assets/images`. If you run with `--db /custom/path/maestro.db`, image assets move to `/custom/path/assets/images`.
 
 The preview warning on `run` is intentional. Pass `--i-understand-that-this-will-be-running-without-the-usual-guardrails` only when unattended Codex execution is actually what you want.
@@ -382,9 +417,10 @@ Repo-managed Git hooks stay targeted:
 - staged website changes run Astro checks and website tests
 - staged workspace and hook changes run the full `pnpm verify` suite
 - `pnpm verify` runs the JS lint/test/check/smoke flow, npm packaging unit test, and Go build/test/coverage/race gates
-- `pnpm run verify:pre-push` adds current-host npm packaging smoke, the shared retry stress test, and the full retry-safety harness on top of `pnpm verify`
+- `pnpm run verify:pre-push` adds real Docker image build smoke, tarball install smoke, local-registry install smoke, curl-installer smoke, the shared retry stress test, and the full retry-safety harness on top of `pnpm verify`
+- `pnpm run verify:ci` is the lean GitHub Actions gate: web verification, launcher packaging tests, and `go test ./...`
 - package-scoped root commands such as `pnpm run frontend:test` and `pnpm run website:build` now go through `turbo --filter=...` so they benefit from task caching too
-- `pre-push` now runs `pnpm run verify:pre-push`, leaving GitHub Actions with the cross-platform packaging matrix and registry smoke coverage
+- `pre-push` now runs `pnpm run verify:pre-push`, while GitHub Actions stays on the smaller `pnpm run verify:ci` gate
 
 ## License
 

package/bin/maestro

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+
+set -eu
+
+SCRIPT_PATH="$0"
+while [ -L "$SCRIPT_PATH" ]; do
+  LINK_TARGET=$(readlink "$SCRIPT_PATH")
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *) SCRIPT_PATH=$(dirname "$SCRIPT_PATH")/$LINK_TARGET ;;
+  esac
+done
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname "$SCRIPT_PATH")" && pwd)
+NODE_BIN="${MAESTRO_NODE_BIN:-node}"
+exec "$NODE_BIN" "$SCRIPT_DIR/maestro.js" "$@"

package/bin/maestro.cmd

@@ -0,0 +1,8 @@
+@ECHO OFF
+SETLOCAL
+SET SCRIPT_DIR=%~dp0
+IF DEFINED MAESTRO_NODE_BIN (
+  "%MAESTRO_NODE_BIN%" "%SCRIPT_DIR%maestro.js" %*
+) ELSE (
+  node "%SCRIPT_DIR%maestro.js" %*
+)

package/bin/maestro.js

@@ -1,26 +1,15 @@
 #!/usr/bin/env node
 
-const { spawnSync } = require("node:child_process");
-const { getExePath } = require("../lib/get-exe-path");
-
-let exePath;
-try {
-  exePath = getExePath();
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  process.stderr.write(`${message}\n`);
+const nodeMajor = Number.parseInt(process.versions.node.split(".")[0], 10);
+if (!Number.isInteger(nodeMajor) || nodeMajor < 24) {
+  process.stderr.write(`Maestro's npm launcher requires Node 24 or newer; found ${process.versions.node}\n`);
   process.exit(1);
 }
 
-const result = spawnSync(exePath, process.argv.slice(2), { stdio: "inherit" });
-if (result.error) {
-  process.stderr.write(`${result.error.message}\n`);
+const { main } = require("../lib/cli");
+
+main(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
   process.exit(1);
-}
-if (typeof result.status === "number") {
-  process.exit(result.status);
-}
-if (result.signal) {
-  process.stderr.write(`maestro terminated with signal ${result.signal}\n`);
-}
-process.exit(1);
+});

package/bin/maestro.ps1

@@ -0,0 +1,4 @@
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$NodeBin = if ($env:MAESTRO_NODE_BIN) { $env:MAESTRO_NODE_BIN } else { "node" }
+& $NodeBin (Join-Path $ScriptDir "maestro.js") @args
+exit $LASTEXITCODE

package/lib/browser.js

@@ -0,0 +1,79 @@
+const { spawn } = require("node:child_process");
+
+const DEFAULT_BROWSER_TIMEOUT_MS = 3000;
+const DEFAULT_BROWSER_POLL_INTERVAL_MS = 50;
+
+function terminalsInteractive(streams = process) {
+  return Boolean(streams.stdout && streams.stdout.isTTY && streams.stderr && streams.stderr.isTTY);
+}
+
+function browserOpenDisabled(env = process.env) {
+  const value = env && env.MAESTRO_DISABLE_BROWSER_OPEN;
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function browserCommandFor(platform, url) {
+  switch (platform) {
+    case "darwin":
+      return ["open", [url]];
+    case "linux":
+    case "freebsd":
+    case "openbsd":
+    case "netbsd":
+      return ["xdg-open", [url]];
+    case "win32":
+      return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+    default:
+      throw new Error(`unsupported platform ${platform}`);
+  }
+}
+
+async function waitForHealthy(url, options = {}) {
+  const timeoutMs = options.timeoutMs || DEFAULT_BROWSER_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs || DEFAULT_BROWSER_POLL_INTERVAL_MS;
+  const fetchImpl = options.fetchImpl || fetch;
+  const deadline = Date.now() + timeoutMs;
+  let lastError = null;
+
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetchImpl(url);
+      if (response.ok) {
+        await response.arrayBuffer();
+        return;
+      }
+      lastError = new Error(`health returned ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+
+  if (lastError) {
+    throw lastError;
+  }
+  throw new Error(`timed out waiting for ${url}`);
+}
+
+async function openDashboardWhenReady(baseURL, options = {}) {
+  if (!baseURL || browserOpenDisabled(options.env || process.env) || !terminalsInteractive(options.streams || process)) {
+    return;
+  }
+
+  const normalizedBaseURL = String(baseURL).replace(/\/+$/, "");
+  await waitForHealthy(`${normalizedBaseURL}/health`, options);
+  const [command, args] = browserCommandFor(options.platform || process.platform, normalizedBaseURL);
+  const child = spawn(command, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+module.exports = {
+  browserOpenDisabled,
+  browserCommandFor,
+  openDashboardWhenReady,
+  terminalsInteractive,
+  waitForHealthy,
+};

package/lib/cli.js

@@ -0,0 +1,306 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+
+const { browserOpenDisabled, openDashboardWhenReady } = require("./browser");
+const { planDockerInvocation } = require("./docker-plan");
+const { installBundledSkills } = require("./install-skills");
+const {
+  DEFAULT_IMAGE_REPOSITORY,
+  imageRefForVersion,
+  resolveImageRef,
+  sanitizeVersion,
+  writeRuntimeState,
+} = require("./runtime-state");
+
+const MINIMUM_LAUNCHER_NODE_MAJOR = 24;
+
+function packageVersion() {
+  const packageJSON = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+  return packageJSON.version;
+}
+
+function ensureSupportedNodeVersion(nodeVersion = process.versions.node) {
+  const major = Number.parseInt(String(nodeVersion || "").split(".")[0], 10);
+  if (!Number.isInteger(major) || major < MINIMUM_LAUNCHER_NODE_MAJOR) {
+    throw new Error(`Maestro's npm launcher requires Node ${MINIMUM_LAUNCHER_NODE_MAJOR} or newer; found ${nodeVersion}`);
+  }
+}
+
+async function main(argv = process.argv.slice(2), options = {}) {
+  ensureSupportedNodeVersion();
+  const deps = createDeps(options);
+  if (argv[0] === "self-update") {
+    return handleSelfUpdate(argv.slice(1), deps);
+  }
+  if (argv[0] === "doctor" && argv[1] === "install") {
+    return handleDoctorInstall(argv.slice(2), deps);
+  }
+  if (argv[0] === "install" && argv.includes("--skills") && !argv.includes("--help") && !argv.includes("-h")) {
+    return handleInstallSkills(deps);
+  }
+  return runContainerized(argv, deps);
+}
+
+function createDeps(options) {
+  return {
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    fs: options.fs || fs,
+    gid: options.gid ?? (typeof process.getgid === "function" ? process.getgid() : undefined),
+    baseDir: options.baseDir || path.join(__dirname, ".."),
+    homeDir: options.homeDir || os.homedir(),
+    packageVersion: options.packageVersion || packageVersion(),
+    platform: options.platform || process.platform,
+    spawn: options.spawn || spawn,
+    spawnSync: options.spawnSync || spawnSync,
+    stdout: options.stdout || process.stdout,
+    stderr: options.stderr || process.stderr,
+    uid: options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined),
+    exit: options.exit || ((code) => process.exit(code)),
+    openDashboardWhenReady: options.openDashboardWhenReady || openDashboardWhenReady,
+    planDockerInvocation: options.planDockerInvocation || planDockerInvocation,
+  };
+}
+
+function dockerBinary(env) {
+  if (typeof env.MAESTRO_DOCKER_BIN === "string" && env.MAESTRO_DOCKER_BIN.trim() !== "") {
+    return env.MAESTRO_DOCKER_BIN.trim();
+  }
+  return "docker";
+}
+
+function ensureDockerAvailable(deps) {
+  const result = deps.spawnSync(dockerBinary(deps.env), ["version", "--format", "{{.Server.Version}}"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.error) {
+    throw new Error(`failed to start docker: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || "").trim();
+    throw new Error(stderr || "docker is required to run the Maestro launcher");
+  }
+}
+
+function ensureImageAvailable(imageRef, deps) {
+  const inspect = deps.spawnSync(dockerBinary(deps.env), ["image", "inspect", imageRef], {
+    encoding: "utf8",
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  if (inspect.error) {
+    throw new Error(`failed to inspect docker image ${imageRef}: ${inspect.error.message}`);
+  }
+  if (inspect.status === 0) {
+    return;
+  }
+
+  const pull = deps.spawnSync(dockerBinary(deps.env), ["pull", imageRef], {
+    encoding: "utf8",
+    stdio: "inherit",
+  });
+  if (pull.error) {
+    throw new Error(`failed to pull docker image ${imageRef}: ${pull.error.message}`);
+  }
+  if (pull.status !== 0) {
+    throw new Error(`docker pull ${imageRef} failed`);
+  }
+}
+
+async function runContainerized(argv, deps) {
+  ensureDockerAvailable(deps);
+  const imageRef = resolveImageRef({
+    env: deps.env,
+    homeDir: deps.homeDir,
+    packageVersion: deps.packageVersion,
+  });
+  ensureImageAvailable(imageRef, deps);
+
+  const plan = await deps.planDockerInvocation(argv, {
+    cwd: deps.cwd,
+    env: deps.env,
+    fs: deps.fs,
+    gid: deps.gid,
+    homeDir: deps.homeDir,
+    imageRef,
+    platform: deps.platform,
+    uid: deps.uid,
+  });
+
+  const child = deps.spawn(dockerBinary(deps.env), plan.dockerArgs, {
+    cwd: deps.cwd,
+    stdio: "inherit",
+  });
+
+  let browserPromise = Promise.resolve();
+  if (plan.commandPath[0] === "run" && plan.hostBaseURL && !browserOpenDisabled(deps.env)) {
+    browserPromise = deps.openDashboardWhenReady(plan.hostBaseURL, {
+      env: deps.env,
+      streams: { stdout: deps.stdout, stderr: deps.stderr },
+      platform: deps.platform,
+    }).catch(() => {});
+  }
+
+  const signalHandlers = [];
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    const handler = () => {
+      if (!child.killed) {
+        child.kill(signal);
+      }
+    };
+    process.on(signal, handler);
+    signalHandlers.push([signal, handler]);
+  }
+
+  const exitCode = await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        deps.stderr.write(`maestro terminated with signal ${signal}\n`);
+        resolve(1);
+        return;
+      }
+      resolve(typeof code === "number" ? code : 1);
+    });
+  });
+
+  for (const [signal, handler] of signalHandlers) {
+    process.off(signal, handler);
+  }
+  await browserPromise;
+  deps.exit(exitCode);
+}
+
+function printInstalledTargets(targets, stdout) {
+  stdout.write("Installed Maestro skill bundle:\n");
+  for (const target of targets) {
+    stdout.write(` - ${target}\n`);
+  }
+}
+
+function handleInstallSkills(deps) {
+  const targets = installBundledSkills({
+    baseDir: deps.baseDir,
+    fs: deps.fs,
+    homeDir: deps.homeDir,
+  });
+  printInstalledTargets(targets, deps.stdout);
+}
+
+function parseSelfUpdateArgs(argv) {
+  let version = "";
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--help" || token === "-h") {
+      return { help: true, version: "" };
+    }
+    if (token === "--version" && typeof argv[i + 1] === "string") {
+      version = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (token.startsWith("--version=")) {
+      version = token.slice("--version=".length);
+      continue;
+    }
+    throw new Error(`unknown argument for self-update: ${token}`);
+  }
+  return { help: false, version };
+}
+
+function handleSelfUpdate(argv, deps) {
+  const parsed = parseSelfUpdateArgs(argv);
+  if (parsed.help) {
+    deps.stdout.write("Usage: maestro self-update [--version <tag>]\n");
+    return;
+  }
+
+  ensureDockerAvailable(deps);
+  const selectedRef = parsed.version
+    ? imageRefForVersion(parsed.version, DEFAULT_IMAGE_REPOSITORY)
+    : `${DEFAULT_IMAGE_REPOSITORY}:latest`;
+  const pull = deps.spawnSync(dockerBinary(deps.env), ["pull", selectedRef], {
+    encoding: "utf8",
+    stdio: "inherit",
+  });
+  if (pull.error) {
+    throw new Error(`failed to pull docker image ${selectedRef}: ${pull.error.message}`);
+  }
+  if (pull.status !== 0) {
+    throw new Error(`docker pull ${selectedRef} failed`);
+  }
+  writeRuntimeState(selectedRef, {
+    fs: deps.fs,
+    homeDir: deps.homeDir,
+  });
+  deps.stdout.write(`Pinned Maestro runtime image to ${selectedRef}\n`);
+}
+
+function handleDoctorInstall(argv, deps) {
+  if (argv.some((arg) => arg === "--help" || arg === "-h")) {
+    deps.stdout.write("Usage: maestro doctor install [--json]\n");
+    return;
+  }
+  const jsonMode = argv.includes("--json");
+  const checks = [];
+
+  try {
+    ensureDockerAvailable(deps);
+    checks.push({ name: "docker", status: "ok" });
+  } catch (error) {
+    checks.push({ name: "docker", status: "fail", detail: error.message });
+  }
+
+  const homeDir = deps.homeDir;
+  const runtimeImage = resolveImageRef({
+    env: deps.env,
+    homeDir,
+    packageVersion: deps.packageVersion,
+  });
+  checks.push({ name: "runtime_image", status: "ok", detail: runtimeImage });
+
+  const codexConfigDir = path.join(homeDir, ".codex");
+  checks.push({
+    name: "codex_config",
+    status: deps.fs.existsSync(codexConfigDir) ? "ok" : "warn",
+    detail: codexConfigDir,
+  });
+
+  const daemonRegistryDir = path.join(homeDir, ".maestro", "launcher", "daemons");
+  checks.push({
+    name: "daemon_registry",
+    status: "ok",
+    detail: daemonRegistryDir,
+  });
+
+  if (jsonMode) {
+    deps.stdout.write(`${JSON.stringify({ checks }, null, 2)}\n`);
+    return;
+  }
+
+  deps.stdout.write("INSTALL DOCTOR\n");
+  for (const check of checks) {
+    deps.stdout.write(`${check.name}:\t${check.status}`);
+    if (check.detail) {
+      deps.stdout.write(`\t${check.detail}`);
+    }
+    deps.stdout.write("\n");
+  }
+}
+
+module.exports = {
+  createDeps,
+  dockerBinary,
+  ensureDockerAvailable,
+  ensureImageAvailable,
+  ensureSupportedNodeVersion,
+  handleDoctorInstall,
+  handleInstallSkills,
+  handleSelfUpdate,
+  main,
+  parseSelfUpdateArgs,
+  printInstalledTargets,
+  runContainerized,
+};