@alecrust/workbox 0.4.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+## [0.4.1] - 2026-05-19

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alec Rust
+
+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/README.md

@@ -0,0 +1,105 @@
+# workbox (wkb) [![CI](https://github.com/AlecRust/workbox/actions/workflows/ci.yml/badge.svg)](https://github.com/AlecRust/workbox/actions/workflows/ci.yml)
+
+Minimal Bun-first CLI for Git worktrees. Creates a worktree per sandbox and removes it cleanly.
+
+## Install
+
+Requires Bun `1.3.13` or newer.
+
+```sh
+bun add -g @alecrust/workbox
+```
+
+Verify the install:
+
+```sh
+wkb --version
+```
+
+## Use
+
+```sh
+wkb new <name> [--from <ref>]         # create and provision sandbox worktree
+wkb rm <name> [--force] [--unmanaged] [--delete-branch] # remove worktree
+wkb list                              # list workbox worktrees
+wkb prune                             # prune stale git worktree metadata
+wkb status [name]                     # show repo/worktree info and cleanliness
+wkb setup                             # run configured bootstrap steps (in current worktree)
+wkb dev <name>                        # run configured dev command in a sandbox
+wkb exec <name> -- <cmd...>           # run a command in a sandbox
+```
+
+`workbox` and `wkb` are equivalent.
+
+## Config
+
+Looks for global config in:
+
+1. `$XDG_CONFIG_HOME/workbox/config.toml`
+2. `~/.workbox/config.toml` when `$XDG_CONFIG_HOME` is not set
+
+Then looks for project config in:
+
+1. `.workbox/config.toml`
+2. `workbox.toml`
+
+Config is required from at least one global or project location. Global config provides defaults;
+project config overrides only the settings it defines. Paths are resolved relative to the repo root.
+`worktrees.directory` must resolve within the repo root.
+
+Example:
+
+```toml
+[worktrees]
+directory = ".workbox/worktrees"
+branch_prefix = "wkb/"
+base_ref = "main"
+
+[bootstrap]
+enabled = true
+steps = [
+  { name = "install", run = "bun install" },
+  { name = "build", run = "bun run build" }
+]
+
+[provision]
+enabled = true
+
+[[provision.copy]]
+from = ".env"
+to = ".env"
+
+[[provision.copy]]
+from = ".env.local"
+to = ".env.local"
+required = false
+
+[[provision.steps]]
+name = "generate"
+run = "bun run generate"
+
+[dev]
+command = "bun run dev"
+# Optional (explicit opt-in): open an editor when running `wkb dev`.
+# open = "code ."
+```
+
+Provision runs automatically after `wkb new` creates a worktree. Copy sources resolve from the
+current worktree where `wkb new` is run, copy destinations and steps run inside the new worktree,
+and missing copied files are skipped unless `required = true`.
+
+Bootstrap is separate: `wkb setup` runs bootstrap in the current worktree, and `wkb dev <name>`
+runs bootstrap in the named sandbox before the dev command.
+
+## Development
+
+```sh
+bun install
+bun test
+bun run check
+bun run format
+```
+
+## Commit conventions
+
+Conventional Commits are enforced. See `cog.toml`.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@alecrust/workbox",
+  "version": "0.4.1",
+  "description": "Bun-first CLI for managing Git worktree sandboxes.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "bun@1.3.13",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlecRust/workbox.git"
+  },
+  "homepage": "https://github.com/AlecRust/workbox#readme",
+  "bugs": {
+    "url": "https://github.com/AlecRust/workbox/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "workbox": "./src/cli.ts",
+    "wkb": "./src/cli.ts"
+  },
+  "engines": {
+    "bun": "1.3.13"
+  },
+  "scripts": {
+    "prepare": "bun scripts/prepare.ts",
+    "test": "bun test",
+    "lint": "biome lint .",
+    "check:types": "tsc --noEmit",
+    "check:unused": "knip",
+    "check": "bun run lint && bun run check:types && bun run check:unused",
+    "format": "biome check --write ."
+  },
+  "dependencies": {
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "@tsconfig/bun": "^1.0.10",
+    "@types/bun": "^1.3.13",
+    "knip": "^6.9.0",
+    "lefthook": "^2.1.6",
+    "typescript": "^6.0.3"
+  },
+  "keywords": [
+    "git",
+    "worktree",
+    "cli",
+    "bun"
+  ]
+}

package/src/bootstrap/runner.ts

@@ -0,0 +1,89 @@
+import { resolve } from "node:path";
+
+import { checkPathWithinRoot } from "../core/path";
+import { runShellCommand } from "../core/process";
+import { CliError } from "../ui/errors";
+import type { BootstrapStep } from "./steps";
+
+type BootstrapStepResult = {
+  name: string;
+  command: string;
+  cwd: string;
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+};
+
+type BootstrapResult = {
+  status: "ok" | "failed";
+  message: string;
+  steps: BootstrapStepResult[];
+  exitCode: number;
+};
+
+type OutputMode = "inherit" | "capture";
+
+const resolveStepCwd = async (repoRoot: string, stepCwd?: string): Promise<string> => {
+  if (!stepCwd) {
+    return repoRoot;
+  }
+  const resolved = resolve(repoRoot, stepCwd);
+  const within = await checkPathWithinRoot({
+    rootDir: repoRoot,
+    candidatePath: resolved,
+    label: "bootstrap step cwd",
+  });
+  if (!within.ok) {
+    throw new CliError(within.reason, { exitCode: 2 });
+  }
+  return resolved;
+};
+
+export const runBootstrap = async (
+  steps: BootstrapStep[],
+  options: { repoRoot: string; mode: OutputMode }
+): Promise<BootstrapResult> => {
+  if (steps.length === 0) {
+    return {
+      status: "ok",
+      message: "no bootstrap steps configured.",
+      steps: [],
+      exitCode: 0,
+    };
+  }
+
+  const results: BootstrapStepResult[] = [];
+  for (const step of steps) {
+    const cwd = await resolveStepCwd(options.repoRoot, step.cwd);
+    const { stdout, stderr, exitCode } = await runShellCommand({
+      command: step.run,
+      cwd,
+      mode: options.mode,
+      env: step.env,
+    });
+
+    results.push({
+      name: step.name,
+      command: step.run,
+      cwd,
+      exitCode,
+      ...(options.mode === "capture" ? { stdout: stdout.trim(), stderr: stderr.trim() } : {}),
+    });
+
+    if (exitCode !== 0) {
+      return {
+        status: "failed",
+        message: `bootstrap step "${step.name}" failed (exit ${exitCode}).`,
+        steps: results,
+        exitCode,
+      };
+    }
+  }
+
+  return {
+    status: "ok",
+    message: "bootstrap completed.",
+    steps: results,
+    exitCode: 0,
+  };
+};

package/src/bootstrap/steps/index.ts

@@ -0,0 +1,6 @@
+export type BootstrapStep = {
+  name: string;
+  run: string;
+  cwd?: string;
+  env?: Record<string, string>;
+};

package/src/cli/args.ts

@@ -0,0 +1,144 @@
+import { parseArgs } from "node:util";
+
+type CliFlags = {
+  help: boolean;
+  json: boolean;
+  nonInteractive: boolean;
+  version: boolean;
+};
+
+type ParsedArgs = {
+  command: string | null;
+  commandArgs: string[];
+  flags: CliFlags;
+  errors: string[];
+};
+
+const GLOBAL_OPTIONS = {
+  help: { type: "boolean", short: "h" },
+  json: { type: "boolean" },
+  "non-interactive": { type: "boolean" },
+  version: { type: "boolean" },
+} as const;
+
+type ParsedToken =
+  | {
+      kind: "option";
+      index: number;
+      name: string;
+      rawName?: string;
+      value?: string;
+      inlineValue?: boolean;
+    }
+  | {
+      kind: "positional";
+      index: number;
+      value: string;
+    }
+  | {
+      kind: "option-terminator";
+      index: number;
+    };
+
+const flagFromOption = (name: string): keyof CliFlags | null => {
+  switch (name) {
+    case "help":
+      return "help";
+    case "json":
+      return "json";
+    case "non-interactive":
+      return "nonInteractive";
+    case "version":
+      return "version";
+    default:
+      return null;
+  }
+};
+
+const pushOptionArgs = (token: ParsedToken, argv: string[], commandArgs: string[]): void => {
+  if (token.kind !== "option") {
+    return;
+  }
+
+  const optionArg = argv[token.index];
+  if (optionArg !== undefined) {
+    commandArgs.push(optionArg);
+  }
+
+  if ("value" in token && token.value !== undefined && token.inlineValue === false) {
+    const valueArg = argv[token.index + 1];
+    if (valueArg !== undefined) {
+      commandArgs.push(valueArg);
+    }
+  }
+};
+
+export const parseCliArgs = (argv: string[]): ParsedArgs => {
+  const flags: CliFlags = {
+    help: false,
+    json: false,
+    nonInteractive: false,
+    version: false,
+  };
+  const errors: string[] = [];
+  const commandArgs: string[] = [];
+  let command: string | null = null;
+  let passthrough = false;
+
+  const parsed = parseArgs({
+    args: argv,
+    options: GLOBAL_OPTIONS,
+    strict: false,
+    allowPositionals: true,
+    tokens: true,
+  });
+  const tokens = parsed.tokens as ParsedToken[] | undefined;
+
+  for (const token of tokens ?? []) {
+    if (token.kind === "option-terminator") {
+      passthrough = true;
+      commandArgs.push("--");
+      continue;
+    }
+
+    if (token.kind === "option" && !passthrough) {
+      const flag = flagFromOption(token.name);
+      if (flag) {
+        flags[flag] = true;
+        continue;
+      }
+      if (!command) {
+        const rawName = "rawName" in token ? token.rawName : argv[token.index];
+        errors.push(`Unknown flag "${rawName ?? token.name}".`);
+        continue;
+      }
+      pushOptionArgs(token, argv, commandArgs);
+      continue;
+    }
+
+    if (!command && token.kind === "positional") {
+      command = token.value;
+      continue;
+    }
+
+    if (!command && passthrough && token.kind === "option") {
+      command = argv[token.index] ?? token.name;
+      continue;
+    }
+
+    if (token.kind === "positional") {
+      const value = argv[token.index] ?? token.value;
+      commandArgs.push(value);
+      continue;
+    }
+
+    pushOptionArgs(token, argv, commandArgs);
+  }
+
+  return {
+    command,
+    commandArgs,
+    flags,
+    errors,
+  };
+};

package/src/cli/help.ts

@@ -0,0 +1,42 @@
+import { commands } from "../commands";
+import type { CommandDefinition } from "../commands/types";
+
+const TOOL_DESCRIPTION = "workbox manages fast Git worktree sandboxes with optional bootstraps.";
+
+export const renderGlobalHelp = (toolName: string, alias: string): string => {
+  const commandLines = commands.map((command) => `  ${command.name.padEnd(8)} ${command.summary}`);
+
+  return [
+    `${toolName} - ${TOOL_DESCRIPTION}`,
+    `Alias: ${alias}`,
+    "",
+    "Usage:",
+    `  ${toolName} <command> [options]`,
+    "",
+    "Commands:",
+    ...commandLines,
+    "",
+    "Global options:",
+    "  --help            Show help for a command",
+    "  --json            Output machine-readable JSON",
+    "  --non-interactive Disable prompts and fail fast",
+    "  --version         Show the current version",
+  ].join("\n");
+};
+
+export const renderCommandHelp = (toolName: string, command: CommandDefinition): string =>
+  [
+    `${toolName} ${command.name} - ${command.summary}`,
+    "",
+    "Usage:",
+    `  ${command.usage}`,
+    "",
+    "Description:",
+    `  ${command.description}`,
+    "",
+    "Global options:",
+    "  --help            Show help for this command",
+    "  --json            Output machine-readable JSON",
+    "  --non-interactive Disable prompts and fail fast",
+    "  --version         Show the current version",
+  ].join("\n");

package/src/cli.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+import { parseCliArgs } from "./cli/args";
+import { renderCommandHelp, renderGlobalHelp } from "./cli/help";
+import { getCommand } from "./commands";
+import { loadConfig } from "./core/config";
+import { getRepoInfo } from "./core/repo";
+import { CliError, UsageError } from "./ui/errors";
+import { formatOutput } from "./ui/log";
+
+const TOOL_NAME = "workbox";
+const TOOL_ALIAS = "wkb";
+
+type OutputTarget = NodeJS.WritableStream;
+
+const loadPackageVersion = async (): Promise<string> => {
+  const packageJson = (await Bun.file(new URL("../package.json", import.meta.url)).json()) as {
+    version?: unknown;
+  };
+  return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+};
+
+const writeOutput = (output: string, stream: OutputTarget): void => {
+  if (output.trim().length === 0) {
+    return;
+  }
+  stream.write(`${output}\n`);
+};
+
+export const runCli = async (argv: string[], cwd = process.cwd()): Promise<number> => {
+  const parsed = parseCliArgs(argv);
+  const outputMode = parsed.flags.json ? "json" : "text";
+
+  if (parsed.errors.length > 0) {
+    throw new UsageError(`${parsed.errors.join(" ")} Run '${TOOL_NAME} --help' for usage.`);
+  }
+
+  if (parsed.flags.version) {
+    const version = await loadPackageVersion();
+    writeOutput(
+      formatOutput(
+        {
+          ok: true,
+          message: `${TOOL_NAME} ${version}`,
+          data: { version },
+        },
+        outputMode
+      ),
+      process.stdout
+    );
+    return 0;
+  }
+
+  if (parsed.flags.nonInteractive) {
+    process.env.CI ??= "1";
+    process.env.GIT_TERMINAL_PROMPT ??= "0";
+    process.env.GCM_INTERACTIVE ??= "Never";
+  }
+
+  const command = parsed.command ? getCommand(parsed.command) : undefined;
+
+  if (!parsed.command || parsed.flags.help) {
+    if (parsed.command && !command) {
+      throw new UsageError(`Unknown command "${parsed.command}".`);
+    }
+
+    const helpText = command
+      ? renderCommandHelp(TOOL_NAME, command)
+      : renderGlobalHelp(TOOL_NAME, TOOL_ALIAS);
+
+    writeOutput(
+      formatOutput(
+        {
+          ok: true,
+          command: command?.name,
+          help: helpText,
+        },
+        outputMode
+      ),
+      process.stdout
+    );
+    return 0;
+  }
+
+  if (!command) {
+    throw new UsageError(`Unknown command "${parsed.command}".`);
+  }
+
+  const { repoRoot, worktreeRoot } = await getRepoInfo(cwd);
+  const { config, path } = await loadConfig(repoRoot);
+  const result = await command.run(
+    {
+      cwd,
+      repoRoot,
+      worktreeRoot,
+      config,
+      configPath: path,
+      flags: parsed.flags,
+    },
+    parsed.commandArgs
+  );
+
+  const exitCode = result.exitCode ?? 0;
+  writeOutput(
+    formatOutput(
+      {
+        ok: exitCode === 0,
+        command: command.name,
+        message: result.message,
+        data: result.data,
+      },
+      outputMode
+    ),
+    process.stdout
+  );
+
+  return exitCode;
+};
+
+const main = async () => {
+  const outputMode = parseCliArgs(Bun.argv.slice(2)).flags.json ? "json" : "text";
+  try {
+    const exitCode = await runCli(Bun.argv.slice(2));
+    process.exitCode = exitCode;
+  } catch (error) {
+    const exitCode = error instanceof CliError ? error.exitCode : 1;
+    const message = error instanceof Error ? error.message : String(error);
+
+    writeOutput(
+      formatOutput(
+        {
+          ok: false,
+          message: `Error: ${message}`,
+          ...(outputMode === "json" ? { errors: [message] } : {}),
+        },
+        outputMode
+      ),
+      process.stderr
+    );
+    process.exitCode = exitCode;
+  }
+};
+
+if (import.meta.main) {
+  await main();
+}

package/src/commands/dev.ts

@@ -0,0 +1,90 @@
+import { runBootstrap } from "../bootstrap/runner";
+import { getWorkboxWorktree } from "../core/git";
+import { runShellCommand } from "../core/process";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+export const devCommand: CommandDefinition = {
+  name: "dev",
+  summary: "Start a dev session in a sandbox",
+  description: "Start a development session inside a workbox sandbox.",
+  usage: "workbox dev <name>",
+  run: async (context, args) => {
+    const { positionals } = parseArgsOrUsage({
+      args,
+      allowPositionals: true,
+      strict: true,
+    });
+    const [name, ...rest] = positionals;
+    if (!name) {
+      const message = context.flags.nonInteractive
+        ? "Missing worktree name in non-interactive mode."
+        : "Missing worktree name.";
+      throw new UsageError(message);
+    }
+    if (rest.length > 0) {
+      throw new UsageError(`Unexpected arguments: ${rest.join(" ")}`);
+    }
+
+    if (!context.config.dev) {
+      throw new UsageError('Dev is not configured. Add a [dev] section with a "command".');
+    }
+
+    const worktree = await getWorkboxWorktree({
+      repoRoot: context.repoRoot,
+      worktreesDir: context.config.worktrees.directory,
+      branchPrefix: context.config.worktrees.branch_prefix,
+      name,
+    });
+
+    const mode = context.flags.json ? "capture" : "inherit";
+
+    let bootstrapResult: unknown;
+    if (context.config.bootstrap.enabled) {
+      const result = await runBootstrap(context.config.bootstrap.steps, {
+        repoRoot: worktree.path,
+        mode,
+      });
+      bootstrapResult = result;
+      if (result.exitCode !== 0) {
+        return {
+          message: result.message,
+          data: { worktree, bootstrap: result },
+          exitCode: result.exitCode,
+        };
+      }
+    }
+
+    let openResult: Awaited<ReturnType<typeof runShellCommand>> | undefined;
+    if (context.config.dev.open) {
+      openResult = await runShellCommand({
+        command: context.config.dev.open,
+        cwd: worktree.path,
+        mode,
+      });
+      if (openResult.exitCode !== 0)
+        return {
+          message: `dev open command failed (exit ${openResult.exitCode}).`,
+          data: { worktree, bootstrap: bootstrapResult, open: openResult },
+          exitCode: openResult.exitCode,
+        };
+    }
+
+    const devResult = await runShellCommand({
+      command: context.config.dev.command,
+      cwd: worktree.path,
+      mode,
+    });
+    return {
+      message: devResult.exitCode === 0 ? "" : `dev command exited with ${devResult.exitCode}.`,
+      data: {
+        worktree,
+        bootstrap: bootstrapResult,
+        open: openResult,
+        dev: devResult,
+      },
+      exitCode: devResult.exitCode,
+    };
+  },
+};