@alecrust/workbox 0.4.1

package/src/commands/exec.ts

@@ -0,0 +1,67 @@
+import { getWorkboxWorktree } from "../core/git";
+import { runCommand } from "../core/process";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+const splitExecArgs = (args: string[]): { name: string; command: string[] } => {
+  const { tokens } = parseArgsOrUsage({
+    args,
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  const separator = tokens?.find((token) => token.kind === "option-terminator");
+  if (!separator) {
+    throw new UsageError(
+      "Missing command separator '--'. Usage: workbox exec <name> -- <command>."
+    );
+  }
+
+  const before = args.slice(0, separator.index);
+  if (before.length !== 1) {
+    throw new UsageError("Usage: workbox exec <name> -- <command>.");
+  }
+
+  const [name] = before;
+  const command = args.slice(separator.index + 1);
+  if (!name) {
+    throw new UsageError("Missing worktree name.");
+  }
+  if (command.length === 0) {
+    throw new UsageError("Missing command to execute after '--'.");
+  }
+
+  return { name, command };
+};
+
+export const execCommand: CommandDefinition = {
+  name: "exec",
+  summary: "Run a command inside a sandbox",
+  description: "Execute a command inside a workbox sandbox worktree.",
+  usage: "workbox exec <name> -- <command>",
+  run: async (context, args) => {
+    const { name, command } = splitExecArgs(args);
+
+    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";
+    const result = await runCommand({ cmd: command, cwd: worktree.path, mode });
+
+    return {
+      message: "",
+      data: {
+        worktree,
+        command,
+        result,
+      },
+      exitCode: result.exitCode,
+    };
+  },
+};

package/src/commands/index.ts

@@ -0,0 +1,23 @@
+import { devCommand } from "./dev";
+import { execCommand } from "./exec";
+import { listCommand } from "./list";
+import { newCommand } from "./new";
+import { pruneCommand } from "./prune";
+import { rmCommand } from "./rm";
+import { setupCommand } from "./setup";
+import { statusCommand } from "./status";
+import type { CommandDefinition } from "./types";
+
+export const commands: CommandDefinition[] = [
+  newCommand,
+  rmCommand,
+  listCommand,
+  pruneCommand,
+  statusCommand,
+  setupCommand,
+  devCommand,
+  execCommand,
+];
+
+export const getCommand = (name: string): CommandDefinition | undefined =>
+  commands.find((command) => command.name === name);

package/src/commands/list.ts

@@ -0,0 +1,42 @@
+import { getWorkboxWorktrees } from "../core/git";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+export const listCommand: CommandDefinition = {
+  name: "list",
+  summary: "List sandbox worktrees",
+  description: "List all workbox sandbox worktrees.",
+  usage: "workbox list",
+  run: async (context, args) => {
+    const { positionals } = parseArgsOrUsage({
+      args,
+      allowPositionals: true,
+      strict: true,
+    });
+    if (positionals.length > 0) {
+      throw new UsageError(`Unexpected arguments: ${positionals.join(" ")}`);
+    }
+
+    const worktrees = await getWorkboxWorktrees({
+      repoRoot: context.repoRoot,
+      worktreesDir: context.config.worktrees.directory,
+      branchPrefix: context.config.worktrees.branch_prefix,
+    });
+
+    return {
+      message:
+        worktrees.length === 0
+          ? "No workbox worktrees found."
+          : [
+              "Workbox worktrees:",
+              ...worktrees.map((w) => {
+                const branch = w.branch ?? "(detached)";
+                const status = w.managed ? "managed" : "unmanaged";
+                return `- ${w.name}\t${branch}\t${status}\t${w.path}`;
+              }),
+            ].join("\n"),
+      data: worktrees,
+    };
+  },
+};

package/src/commands/new.ts

@@ -0,0 +1,73 @@
+import { createWorktree } from "../core/git";
+import { runProvision } from "../provision/runner";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+export const newCommand: CommandDefinition = {
+  name: "new",
+  summary: "Create a new sandbox worktree",
+  description: "Create a new workbox sandbox worktree with the given name.",
+  usage: "workbox new <name> [--from <ref>]",
+  run: async (context, args) => {
+    const parsed = parseArgsOrUsage({
+      args,
+      options: {
+        from: { type: "string" },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+    const { positionals } = parsed;
+    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(" ")}`);
+    }
+
+    const fromValue = parsed.values.from;
+    const baseRef =
+      (typeof fromValue === "string" ? fromValue : undefined) ?? context.config.worktrees.base_ref;
+    if (!baseRef) {
+      throw new UsageError(
+        "Missing base ref. Provide --from <ref> or set worktrees.base_ref in config."
+      );
+    }
+
+    const worktree = await createWorktree({
+      repoRoot: context.repoRoot,
+      name,
+      worktreesDir: context.config.worktrees.directory,
+      branchPrefix: context.config.worktrees.branch_prefix,
+      baseRef,
+    });
+
+    let provisionResult: Awaited<ReturnType<typeof runProvision>> | undefined;
+    if (context.config.provision.enabled) {
+      provisionResult = await runProvision(context.config.provision, {
+        sourceRoot: context.worktreeRoot,
+        targetRoot: worktree.path,
+        worktreeName: worktree.name,
+        mode: context.flags.json ? "capture" : "inherit",
+      });
+
+      if (provisionResult.exitCode !== 0) {
+        return {
+          message: provisionResult.message,
+          data: { worktree, provision: provisionResult },
+          exitCode: provisionResult.exitCode,
+        };
+      }
+    }
+
+    return {
+      message: `Created worktree "${worktree.name}" at ${worktree.path} on branch ${worktree.managedBranch}.`,
+      data: provisionResult ? { worktree, provision: provisionResult } : worktree,
+    };
+  },
+};

package/src/commands/parse.ts

@@ -0,0 +1,14 @@
+import { parseArgs } from "node:util";
+
+import { UsageError } from "../ui/errors";
+
+type ParseArgsOptions = Parameters<typeof parseArgs>[0];
+
+export const parseArgsOrUsage = (options: ParseArgsOptions) => {
+  try {
+    return parseArgs(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new UsageError(message);
+  }
+};

package/src/commands/prune.ts

@@ -0,0 +1,30 @@
+import { pruneWorktrees } from "../core/git";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+export const pruneCommand: CommandDefinition = {
+  name: "prune",
+  summary: "Prune stale git worktree metadata",
+  description: "Prune stale git worktree metadata (does not delete branches).",
+  usage: "workbox prune",
+  run: async (context, args) => {
+    const { positionals } = parseArgsOrUsage({
+      args,
+      allowPositionals: true,
+      strict: true,
+    });
+    if (positionals.length > 0) {
+      throw new UsageError(`Unexpected arguments: ${positionals.join(" ")}`);
+    }
+
+    const result = await pruneWorktrees(context.repoRoot);
+    return {
+      message:
+        result.stdout.length > 0
+          ? `Pruned worktree metadata:\n${result.stdout}`
+          : "Pruned worktree metadata.",
+      data: result,
+    };
+  },
+};

package/src/commands/rm.ts

@@ -0,0 +1,64 @@
+import { getWorkboxWorktree, removeWorktree } from "../core/git";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+export const rmCommand: CommandDefinition = {
+  name: "rm",
+  summary: "Remove a sandbox worktree",
+  description: "Remove a workbox sandbox worktree by name.",
+  usage: "workbox rm <name> [--force] [--unmanaged] [--delete-branch]",
+  run: async (context, args) => {
+    const parsed = parseArgsOrUsage({
+      args,
+      options: {
+        force: { type: "boolean" },
+        unmanaged: { type: "boolean" },
+        "delete-branch": { type: "boolean" },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+    const { positionals } = parsed;
+    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(" ")}`);
+    }
+
+    const worktree = await getWorkboxWorktree({
+      repoRoot: context.repoRoot,
+      worktreesDir: context.config.worktrees.directory,
+      branchPrefix: context.config.worktrees.branch_prefix,
+      name,
+    });
+
+    if (!worktree.managed && parsed.values.unmanaged !== true) {
+      throw new UsageError(
+        `Refusing to remove unmanaged worktree "${name}". Re-run with --unmanaged to confirm.`
+      );
+    }
+
+    await removeWorktree({
+      repoRoot: context.repoRoot,
+      worktreesDir: context.config.worktrees.directory,
+      branchPrefix: context.config.worktrees.branch_prefix,
+      name,
+      force: parsed.values.force === true,
+      deleteBranch: parsed.values["delete-branch"] === true,
+    });
+
+    return {
+      message:
+        parsed.values["delete-branch"] === true
+          ? `Removed worktree "${worktree.name}" at ${worktree.path} and deleted branch ${worktree.managedBranch}.`
+          : `Removed worktree "${worktree.name}" at ${worktree.path}. No branches were deleted.`,
+      data: worktree,
+    };
+  },
+};

package/src/commands/setup.ts

@@ -0,0 +1,41 @@
+import { runBootstrap } from "../bootstrap/runner";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+export const setupCommand: CommandDefinition = {
+  name: "setup",
+  summary: "Run bootstrap steps",
+  description: "Run configured bootstrap steps for a workbox sandbox.",
+  usage: "workbox setup",
+  run: async (context, args) => {
+    const { positionals } = parseArgsOrUsage({
+      args,
+      allowPositionals: true,
+      strict: true,
+    });
+    if (positionals.length > 0) {
+      throw new UsageError(`Unexpected arguments: ${positionals.join(" ")}`);
+    }
+
+    if (!context.config.bootstrap.enabled) {
+      return {
+        message: "bootstrap is disabled in config.",
+        data: {
+          status: "disabled",
+          steps: context.config.bootstrap.steps.map((step) => step.name),
+        },
+      };
+    }
+
+    const result = await runBootstrap(context.config.bootstrap.steps, {
+      repoRoot: context.worktreeRoot,
+      mode: context.flags.json ? "capture" : "inherit",
+    });
+    return {
+      message: result.message,
+      data: result,
+      exitCode: result.exitCode,
+    };
+  },
+};

package/src/commands/status.ts

@@ -0,0 +1,42 @@
+import { getWorktreeStatus } from "../core/git";
+import { UsageError } from "../ui/errors";
+import { parseArgsOrUsage } from "./parse";
+import type { CommandDefinition } from "./types";
+
+export const statusCommand: CommandDefinition = {
+  name: "status",
+  summary: "Show sandbox status",
+  description: "Show status for workbox worktrees.",
+  usage: "workbox status [name]",
+  run: async (context, args) => {
+    const { positionals } = parseArgsOrUsage({
+      args,
+      allowPositionals: true,
+      strict: true,
+    });
+    if (positionals.length > 1) {
+      throw new UsageError(`Unexpected arguments: ${positionals.join(" ")}`);
+    }
+
+    const result = await getWorktreeStatus({
+      repoRoot: context.repoRoot,
+      worktreesDir: context.config.worktrees.directory,
+      branchPrefix: context.config.worktrees.branch_prefix,
+      name: positionals[0],
+    });
+    return {
+      message:
+        result.length === 0
+          ? "No workbox worktrees found."
+          : [
+              "Workbox status:",
+              ...result.map((item) => {
+                const branch = item.branch ?? "(detached)";
+                const managed = item.managed ? "managed" : "unmanaged";
+                return `- ${item.name}\t${branch}\t${managed}\t${item.clean ? "clean" : "dirty"}\t${item.path}`;
+              }),
+            ].join("\n"),
+      data: result,
+    };
+  },
+};

package/src/commands/types.ts

@@ -0,0 +1,30 @@
+import type { ResolvedWorkboxConfig } from "../core/config";
+
+type GlobalFlags = {
+  help: boolean;
+  json: boolean;
+  nonInteractive: boolean;
+};
+
+type CommandContext = {
+  cwd: string;
+  repoRoot: string;
+  worktreeRoot: string;
+  config: ResolvedWorkboxConfig;
+  configPath: string;
+  flags: GlobalFlags;
+};
+
+type CommandResult = {
+  message: string;
+  data?: unknown;
+  exitCode?: number;
+};
+
+export type CommandDefinition = {
+  name: string;
+  summary: string;
+  description: string;
+  usage: string;
+  run: (context: CommandContext, args: string[]) => Promise<CommandResult>;
+};