@betterborg/cli 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Betterborg
+
+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/NOTICE

@@ -0,0 +1,7 @@
+Betterborg CLI
+Copyright 2026 Betterborg
+
+This product includes software developed by Betterborg
+(https://github.com/betterborg).
+
+Betterborg CLI is distributed under the MIT License. See LICENSE.

package/README.md

@@ -1,11 +1,76 @@
 # @betterborg/cli
 
-Placeholder reserving this package name. It contains no code.
+Betterborg is an AI engineering team for substantial software projects, not a chat window that makes an isolated edit. You give it a task or a PRD; agents investigate your real code, write a reviewed technical plan, decompose it into a dependency graph of tasks, and implement them, each in its own isolated Git worktree. You approve the plan before anything is decomposed, and the estimate before anything runs. It works locally, on your own Claude Code or Codex subscription.
 
-The first published release is `0.1.0`. Install that instead:
+> [!NOTE]
+> Pre-alpha. Interfaces may change between releases.
+
+This package is a launcher, not the CLI itself. It resolves a `betterborg` matching its own version, then forwards your arguments, stdio, and signals to it. Nothing is downloaded at install time.
+
+## Try it
+
+```bash
+npx --yes @betterborg/cli version
+```
+
+## Install
+
+```bash
+npm install --global @betterborg/cli
+```
+
+Then activate the agent-host integrations, which need a persistent install rather than `npx`:
+
+```bash
+betterborg plugins install --all
+```
+
+Run `/reload-plugins` in any open Claude Code session, and start a new Codex session when prompted.
+
+From inside a Git repository, run the loop:
 
 ```bash
-npx --yes @betterborg/cli
+betterborg trust                     # trust this worktree (machine-local)
+betterborg init                      # register and analyze the repository
+betterborg create my-feature         # or: betterborg create my-feature --prd spec.md
+betterborg plan start my-feature     # agents plan, review, and iterate
+betterborg plan approve my-feature   # your gate: nothing is decomposed before this
+betterborg task estimate my-feature  # P50/P80 work and cost
+betterborg execute my-feature        # approve the estimate, then run
 ```
 
-See [betterborg/betterborg-cli](https://github.com/betterborg/betterborg-cli).
+`betterborg execute` hands off reviewed local branches. Add `--push` or `--pr` to publish them. `betterborg --help` is the full command index.
+
+## How the launcher finds the CLI
+
+On each run, in order:
+
+1. **An installed `betterborg` on `PATH`**, if `betterborg version` reports this package's exact version. A `pip install betterborg` or the standalone installer takes over from here, and the launcher adds nothing.
+2. **The standalone release binary** for macOS and Linux on arm64 or x86_64. It is fetched from the matching GitHub release, verified against the published SHA-256 digest, and cached under `$XDG_CACHE_HOME/betterborg/cli/<version>`, or `~/.cache/betterborg/cli/<version>`, so later runs reuse it. A binary that fails verification is discarded, never executed.
+3. **`uvx --from betterborg==<version> betterborg`**, if [uv](https://docs.astral.sh/uv/) is on `PATH`.
+
+If none of those resolve, the launcher exits with what it tried and how to fix it.
+
+## Requirements
+
+- Node.js 18+ to run the launcher.
+- macOS or Linux. On Windows, use a WSL2 shell.
+- One agent transport: a `claude` or `codex` CLI on `PATH` and **already logged in**, or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` exported in your shell.
+
+Step 3 additionally needs Python 3.11+, which `uv` will provide.
+
+Keep provider keys in your shell or a secret manager, never in `.betterborg/config.toml` or any tracked file.
+
+## Documentation
+
+- [Installation guide](https://github.com/betterborg/betterborg-cli/blob/main/docs/installation.md): version pinning, WSL2, providers, recovery
+- [Command guide](https://github.com/betterborg/betterborg-cli/blob/main/docs/commands.md): bootstrap and initialization
+- [Repository](https://github.com/betterborg/betterborg-cli)
+
+## Reporting bugs
+
+File a [GitHub issue](https://github.com/betterborg/betterborg-cli/issues).
+
+## License
+
+Copyright 2026 Betterborg. Licensed under the [MIT License](https://github.com/betterborg/betterborg-cli/blob/main/LICENSE). See [NOTICE](https://github.com/betterborg/betterborg-cli/blob/main/NOTICE) for attribution.

package/bin/betterborg.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const metadata = require("../package.json");
+const { main, reportFailure } = require("../lib/launcher");
+
+main(process.argv.slice(2), { version: metadata.version }).catch(reportFailure);

package/lib/launcher.js

@@ -0,0 +1,421 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+
+const REPOSITORY = "betterborg/betterborg-cli";
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const SIGNAL_EXIT_CODES = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 };
+
+function targetFor(platform, architecture) {
+  const operatingSystems = { darwin: "darwin", linux: "linux" };
+  const architectures = { arm64: "arm64", x64: "x86_64" };
+  const operatingSystem = operatingSystems[platform];
+  const targetArchitecture = architectures[architecture];
+  if (!operatingSystem || !targetArchitecture) {
+    return null;
+  }
+  return `betterborg-${operatingSystem}-${targetArchitecture}`;
+}
+
+function translateVersionArguments(arguments_) {
+  if (
+    arguments_.length === 1 &&
+    (arguments_[0] === "--version" || arguments_[0] === "-V")
+  ) {
+    return ["version"];
+  }
+  return [...arguments_];
+}
+
+function executableNames(name, platform, environment) {
+  if (platform !== "win32") {
+    return [name];
+  }
+  const extensions = (environment.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+    .split(";")
+    .filter(Boolean);
+  return [name, ...extensions.map((extension) => `${name}${extension}`)];
+}
+
+function samePath(left, right, platform) {
+  if (platform === "win32") {
+    return left.toLowerCase() === right.toLowerCase();
+  }
+  return left === right;
+}
+
+function isWindowsCommandScript(command, platform) {
+  return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}
+
+const WINDOWS_SHELL_META_CHARACTERS = /([()\][%!^"`<>&|;, *?])/g;
+
+function escapeWindowsCommand(command) {
+  return command.replace(WINDOWS_SHELL_META_CHARACTERS, "^$1");
+}
+
+function escapeWindowsArgument(argument) {
+  let escaped = String(argument)
+    .replace(/(\\*)"/g, '$1$1\\"')
+    .replace(/(\\*)$/, "$1$1");
+  escaped = `"${escaped}"`;
+  return escaped.replace(WINDOWS_SHELL_META_CHARACTERS, "^$1");
+}
+
+function commandInvocation(command, arguments_, options, dependencies) {
+  if (!isWindowsCommandScript(command, dependencies.platform)) {
+    return { command, arguments: arguments_, options };
+  }
+  if ([command, ...arguments_].some((value) => /[\r\n]/.test(value))) {
+    throw new Error(
+      "Windows command shims cannot safely forward paths or arguments containing line breaks",
+    );
+  }
+
+  const shell =
+    dependencies.environment.ComSpec ||
+    dependencies.environment.COMSPEC ||
+    "cmd.exe";
+  const shellCommand = [
+    escapeWindowsCommand(command),
+    ...arguments_.map(escapeWindowsArgument),
+  ].join(" ");
+  return {
+    command: shell,
+    arguments: ["/d", "/s", "/v:off", "/c", `"${shellCommand}"`],
+    options: { ...options, windowsVerbatimArguments: true },
+  };
+}
+
+function launcherExecutables(dependencies) {
+  if (!dependencies.launcherPath) {
+    return [];
+  }
+  const executables = [dependencies.launcherPath];
+  let directory = dependencies.pathModule.dirname(dependencies.launcherPath);
+  while (dependencies.pathModule.dirname(directory) !== directory) {
+    if (
+      dependencies.pathModule.basename(directory).toLowerCase() ===
+      "node_modules"
+    ) {
+      const shimDirectories = [
+        dependencies.pathModule.join(directory, ".bin"),
+      ];
+      if (dependencies.platform === "win32") {
+        shimDirectories.push(dependencies.pathModule.dirname(directory));
+      }
+      const names =
+        dependencies.platform === "win32"
+          ? ["betterborg", "betterborg.cmd", "betterborg.ps1"]
+          : ["betterborg"];
+      for (const shimDirectory of shimDirectories) {
+        for (const name of names) {
+          executables.push(dependencies.pathModule.resolve(shimDirectory, name));
+        }
+      }
+    }
+    directory = dependencies.pathModule.dirname(directory);
+  }
+  return executables;
+}
+
+function executableOnPath(name, dependencies, excludedPaths = []) {
+  const {
+    environment,
+    fileSystem,
+    pathModule,
+    platform,
+    pathDelimiter,
+  } = dependencies;
+  const pathValue = environment.PATH || environment.Path || "";
+  for (const directory of pathValue.split(pathDelimiter)) {
+    if (!directory) {
+      continue;
+    }
+    for (const executableName of executableNames(name, platform, environment)) {
+      const candidate = pathModule.resolve(directory, executableName);
+      try {
+        fileSystem.accessSync(candidate, fileSystem.constants.X_OK);
+        const resolvedCandidate = fileSystem.realpathSync(candidate);
+        if (
+          !excludedPaths.some((excludedPath) =>
+            samePath(resolvedCandidate, excludedPath, platform),
+          )
+        ) {
+          return candidate;
+        }
+      } catch {
+        // A PATH entry that is missing or not executable is not a candidate.
+      }
+    }
+  }
+  return null;
+}
+
+function installedCli(version, dependencies) {
+  const candidate = executableOnPath(
+    "betterborg",
+    dependencies,
+    launcherExecutables(dependencies),
+  );
+  if (!candidate) {
+    return null;
+  }
+  const invocation = commandInvocation(
+    candidate,
+    ["version"],
+    {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    },
+    dependencies,
+  );
+  const completed = dependencies.spawnSync(
+    invocation.command,
+    invocation.arguments,
+    invocation.options,
+  );
+  if (
+    completed.status === 0 &&
+    completed.stdout.trim() === `betterborg ${version}`
+  ) {
+    return candidate;
+  }
+  return null;
+}
+
+function digest(pathname, fileSystem = fs) {
+  return crypto
+    .createHash("sha256")
+    .update(fileSystem.readFileSync(pathname))
+    .digest("hex");
+}
+
+function verifiedBinary(binaryPath, checksumPath, target, fileSystem = fs) {
+  try {
+    const checksum = fileSystem.readFileSync(checksumPath, "utf8");
+    const match = checksum.match(/^([a-f0-9]{64})  ([^\r\n]+)\n$/);
+    return Boolean(
+      match &&
+        match[2] === target &&
+        digest(binaryPath, fileSystem) === match[1],
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function downloadToFile(url, destination) {
+  const response = await fetch(url, { redirect: "follow" });
+  if (!response.ok) {
+    throw new Error(`download returned HTTP ${response.status} for ${url}`);
+  }
+  const content = Buffer.from(await response.arrayBuffer());
+  fs.writeFileSync(destination, content, { flag: "wx" });
+}
+
+function defaultCacheDirectory(version, dependencies) {
+  const root = dependencies.environment.XDG_CACHE_HOME
+    ? dependencies.pathModule.resolve(dependencies.environment.XDG_CACHE_HOME)
+    : dependencies.pathModule.join(dependencies.homeDirectory, ".cache");
+  return dependencies.pathModule.join(root, "betterborg", "cli", version);
+}
+
+async function cachedRelease(version, target, dependencies) {
+  const directory =
+    dependencies.cacheDirectory || defaultCacheDirectory(version, dependencies);
+  const binaryPath = dependencies.pathModule.join(directory, target);
+  const checksumPath = dependencies.pathModule.join(directory, `${target}.sha256`);
+  if (
+    verifiedBinary(binaryPath, checksumPath, target, dependencies.fileSystem)
+  ) {
+    dependencies.fileSystem.chmodSync(binaryPath, 0o755);
+    return binaryPath;
+  }
+
+  dependencies.fileSystem.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const nonce = dependencies.randomBytes(8).toString("hex");
+  const temporaryBinary = `${binaryPath}.${nonce}.tmp`;
+  const temporaryChecksum = `${checksumPath}.${nonce}.tmp`;
+  const releaseRoot = `https://github.com/${REPOSITORY}/releases/download/v${version}`;
+  try {
+    await dependencies.download(`${releaseRoot}/${target}`, temporaryBinary);
+    await dependencies.download(
+      `${releaseRoot}/${target}.sha256`,
+      temporaryChecksum,
+    );
+    if (
+      !verifiedBinary(
+        temporaryBinary,
+        temporaryChecksum,
+        target,
+        dependencies.fileSystem,
+      )
+    ) {
+      throw new Error(`downloaded ${target} failed SHA-256 verification`);
+    }
+    dependencies.fileSystem.chmodSync(temporaryBinary, 0o755);
+    dependencies.fileSystem.renameSync(temporaryBinary, binaryPath);
+    dependencies.fileSystem.renameSync(temporaryChecksum, checksumPath);
+    return binaryPath;
+  } finally {
+    dependencies.fileSystem.rmSync(temporaryBinary, { force: true });
+    dependencies.fileSystem.rmSync(temporaryChecksum, { force: true });
+  }
+}
+
+function withDefaults(overrides = {}) {
+  let launcherPath = null;
+  try {
+    launcherPath = fs.realpathSync(process.argv[1]);
+  } catch {
+    // Tests and unusual embeddings may not have a filesystem entry in argv[1].
+  }
+  return {
+    cacheDirectory: null,
+    download: downloadToFile,
+    environment: process.env,
+    fileSystem: fs,
+    homeDirectory: os.homedir(),
+    launcherPath,
+    pathDelimiter: path.delimiter,
+    pathModule: path,
+    platform: process.platform,
+    architecture: process.arch,
+    process,
+    randomBytes: crypto.randomBytes,
+    spawn,
+    spawnSync,
+    ...overrides,
+  };
+}
+
+async function resolveCli(version, overrides = {}) {
+  const dependencies = withDefaults(overrides);
+  const installed = installedCli(version, dependencies);
+  if (installed) {
+    return { command: installed, argumentsPrefix: [], source: "installed" };
+  }
+
+  const target = targetFor(dependencies.platform, dependencies.architecture);
+  let releaseFailure = null;
+  if (target) {
+    try {
+      const binary = await cachedRelease(version, target, dependencies);
+      return { command: binary, argumentsPrefix: [], source: "release" };
+    } catch (error) {
+      releaseFailure = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  const uvx = executableOnPath("uvx", dependencies);
+  if (uvx) {
+    return {
+      command: uvx,
+      argumentsPrefix: ["--from", `betterborg==${version}`, "betterborg"],
+      source: "uvx",
+    };
+  }
+
+  const targetDescription = target
+    ? `could not install the ${target} release${releaseFailure ? ` (${releaseFailure})` : ""}`
+    : `no standalone release supports ${dependencies.platform}/${dependencies.architecture}`;
+  throw new Error(
+    `${targetDescription}, and uvx is not on PATH. Install uv from https://docs.astral.sh/uv/ or install betterborg==${version} so betterborg is on PATH.`,
+  );
+}
+
+function launch(resolved, arguments_, overrides = {}) {
+  const dependencies = withDefaults(overrides);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let child;
+    try {
+      const invocation = commandInvocation(
+        resolved.command,
+        [...resolved.argumentsPrefix, ...arguments_],
+        { stdio: "inherit" },
+        dependencies,
+      );
+      child = dependencies.spawn(
+        invocation.command,
+        invocation.arguments,
+        invocation.options,
+      );
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    const handlers = new Map(
+      FORWARDED_SIGNALS.map((signal) => [
+        signal,
+        () => {
+          child.kill(signal);
+        },
+      ]),
+    );
+    for (const [signal, handler] of handlers) {
+      dependencies.process.on(signal, handler);
+    }
+    const cleanup = () => {
+      for (const [signal, handler] of handlers) {
+        dependencies.process.removeListener(signal, handler);
+      }
+    };
+
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new Error(`could not start Betterborg CLI: ${error.message}`));
+    });
+    child.once("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (signal) {
+        if (typeof dependencies.process.kill === "function") {
+          dependencies.process.kill(dependencies.process.pid, signal);
+        } else {
+          dependencies.process.exitCode = SIGNAL_EXIT_CODES[signal] || 1;
+        }
+      } else {
+        dependencies.process.exitCode = code === null ? 1 : code;
+      }
+      resolve();
+    });
+  });
+}
+
+async function main(arguments_, overrides = {}) {
+  if (!overrides.version) {
+    throw new Error("npm package version metadata is missing");
+  }
+  const resolved = await resolveCli(overrides.version, overrides);
+  await launch(resolved, translateVersionArguments(arguments_), overrides);
+}
+
+function reportFailure(error, dependencies = {}) {
+  const logger = dependencies.console || console;
+  const processLike = dependencies.process || process;
+  const message = error instanceof Error ? error.message : String(error);
+  logger.error(`betterborg: ${message}`);
+  processLike.exitCode = 1;
+}
+
+module.exports = {
+  cachedRelease,
+  launch,
+  main,
+  reportFailure,
+  resolveCli,
+  targetFor,
+  translateVersionArguments,
+  verifiedBinary,
+};

package/package.json

@@ -1,14 +1,34 @@
 {
   "name": "@betterborg/cli",
-  "version": "0.0.1",
-  "description": "Placeholder reserving @betterborg/cli. The first real release is 0.1.0.",
+  "version": "0.1.1",
+  "description": "Installer and launcher for the Betterborg CLI",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/betterborg/betterborg-cli.git",
     "directory": "npm"
   },
-  "homepage": "https://github.com/betterborg/betterborg-cli",
-  "publishConfig": { "access": "public" },
-  "files": ["README.md"]
+  "homepage": "https://github.com/betterborg/betterborg-cli#readme",
+  "bugs": "https://github.com/betterborg/betterborg-cli/issues",
+  "type": "commonjs",
+  "bin": {
+    "betterborg": "bin/betterborg.js"
+  },
+  "files": [
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "node --check bin/betterborg.js && node --check lib/launcher.js && node --check test/launcher.test.js",
+    "test": "node --test test/launcher.test.js"
+  }
 }