@alecrust/workbox 0.4.1

package/src/core/config.ts

@@ -0,0 +1,317 @@
+import { z } from "zod";
+
+import { ConfigError } from "../ui/errors";
+import { checkPathWithinRoot } from "./path";
+import {
+  CONFIG_PRIMARY,
+  CONFIG_SECONDARY,
+  GLOBAL_CONFIG_FALLBACK,
+  GLOBAL_CONFIG_XDG,
+  getGlobalConfigPath,
+  getProjectConfigCandidatePaths,
+  resolveWorktreesDir,
+} from "./paths";
+
+const BootstrapStepSchema = z
+  .object({
+    name: z.string().min(1, "Step name is required."),
+    run: z.string().min(1, "Step command is required."),
+    cwd: z.string().min(1).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+  })
+  .strict();
+
+const BootstrapObjectSchema = z
+  .object({
+    enabled: z.boolean(),
+    steps: z.array(BootstrapStepSchema),
+  })
+  .strict();
+
+const ProvisionCopySchema = z
+  .object({
+    from: z.string().min(1, "Provision copy source is required."),
+    to: z.string().min(1, "Provision copy destination is required."),
+    required: z.boolean().default(false),
+  })
+  .strict();
+
+const PartialProvisionCopySchema = ProvisionCopySchema.omit({ required: true })
+  .extend({
+    required: z.boolean().optional(),
+  })
+  .strict();
+
+const ProvisionObjectSchema = z
+  .object({
+    enabled: z.boolean(),
+    copy: z.array(ProvisionCopySchema).default([]),
+    steps: z.array(BootstrapStepSchema).default([]),
+  })
+  .strict();
+
+const validateBootstrapSteps = (
+  steps: Array<z.infer<typeof BootstrapStepSchema>>,
+  ctx: z.RefinementCtx
+) => {
+  const seen = new Set<string>();
+  steps.forEach((step, index) => {
+    if (seen.has(step.name)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["steps", index, "name"],
+        message: `Duplicate bootstrap step name "${step.name}".`,
+      });
+    }
+    seen.add(step.name);
+  });
+};
+
+const BootstrapSchema = BootstrapObjectSchema.superRefine((value, ctx) => {
+  validateBootstrapSteps(value.steps, ctx);
+});
+
+const validateProvisionSteps = (
+  steps: Array<z.infer<typeof BootstrapStepSchema>>,
+  ctx: z.RefinementCtx
+) => {
+  const seen = new Set<string>();
+  steps.forEach((step, index) => {
+    if (seen.has(step.name)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["steps", index, "name"],
+        message: `Duplicate provision step name "${step.name}".`,
+      });
+    }
+    seen.add(step.name);
+  });
+};
+
+const ProvisionSchema = ProvisionObjectSchema.superRefine((value, ctx) => {
+  validateProvisionSteps(value.steps, ctx);
+});
+
+const WorktreesSchema = z
+  .object({
+    directory: z.string().min(1, "Worktree directory is required."),
+    branch_prefix: z.string().min(1, "Worktree branch prefix is required."),
+    base_ref: z.string().min(1, "Worktree base ref must be non-empty.").optional(),
+  })
+  .strict();
+
+const WorkboxConfigSchema = z
+  .object({
+    worktrees: WorktreesSchema,
+    bootstrap: BootstrapSchema,
+    provision: ProvisionSchema.default({ enabled: false, copy: [], steps: [] }),
+    dev: z
+      .object({
+        command: z.string().min(1, "Dev command is required."),
+        open: z.string().min(1, "Dev open command must be non-empty.").optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+type WorkboxConfig = z.infer<typeof WorkboxConfigSchema>;
+
+const PartialWorkboxConfigSchema = z
+  .object({
+    worktrees: WorktreesSchema.partial().optional(),
+    bootstrap: BootstrapObjectSchema.partial()
+      .superRefine((value, ctx) => {
+        if (value.steps) {
+          validateBootstrapSteps(value.steps, ctx);
+        }
+      })
+      .optional(),
+    provision: z
+      .object({
+        enabled: z.boolean().optional(),
+        copy: z.array(PartialProvisionCopySchema).optional(),
+        steps: z.array(BootstrapStepSchema).optional(),
+      })
+      .strict()
+      .superRefine((value, ctx) => {
+        if (value.steps) {
+          validateProvisionSteps(value.steps, ctx);
+        }
+      })
+      .optional(),
+    dev: z
+      .object({
+        command: z.string().min(1, "Dev command is required.").optional(),
+        open: z.string().min(1, "Dev open command must be non-empty.").optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+type PartialWorkboxConfig = z.infer<typeof PartialWorkboxConfigSchema>;
+
+export type ResolvedWorkboxConfig = WorkboxConfig & {
+  worktrees: WorkboxConfig["worktrees"] & { directory: string };
+};
+
+type LoadedConfig = {
+  config: ResolvedWorkboxConfig;
+  path: string;
+};
+
+type LoadConfigOptions = {
+  env?: NodeJS.ProcessEnv;
+  homeDir?: string;
+};
+
+const formatZodError = (error: z.ZodError, filePath: string): string => {
+  const issues = error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    return `${path}: ${issue.message}`;
+  });
+
+  return `Invalid workbox config in ${filePath}:\n${issues.map((item) => `- ${item}`).join("\n")}`;
+};
+
+const parseConfig = (source: string, filePath: string): PartialWorkboxConfig => {
+  let parsed: unknown;
+  try {
+    parsed = Bun.TOML.parse(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ConfigError(`Invalid TOML in ${filePath}: ${message}`, { cause: error });
+  }
+
+  const result = PartialWorkboxConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new ConfigError(formatZodError(result.error, filePath));
+  }
+
+  return result.data;
+};
+
+const mergeConfig = (configs: PartialWorkboxConfig[]): PartialWorkboxConfig =>
+  configs.reduce<PartialWorkboxConfig>((merged, config) => {
+    if (config.worktrees) {
+      merged.worktrees = {
+        ...merged.worktrees,
+        ...config.worktrees,
+      };
+    }
+
+    if (config.bootstrap) {
+      merged.bootstrap = {
+        ...merged.bootstrap,
+        ...config.bootstrap,
+      };
+    }
+
+    if (config.provision) {
+      merged.provision = {
+        ...merged.provision,
+        ...config.provision,
+      };
+    }
+
+    if (config.dev) {
+      merged.dev = {
+        ...merged.dev,
+        ...config.dev,
+      };
+    }
+
+    return merged;
+  }, {});
+
+const validateMergedConfig = (
+  config: PartialWorkboxConfig,
+  sourceDescription: string
+): WorkboxConfig => {
+  const result = WorkboxConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new ConfigError(formatZodError(result.error, sourceDescription));
+  }
+
+  return result.data;
+};
+
+const resolveConfig = async (
+  config: WorkboxConfig,
+  repoRoot: string
+): Promise<ResolvedWorkboxConfig> => {
+  const resolved = resolveWorktreesDir(config.worktrees.directory, repoRoot);
+  const within = await checkPathWithinRoot({
+    rootDir: repoRoot,
+    candidatePath: resolved,
+    label: "worktrees.directory",
+  });
+  if (!within.ok) {
+    throw new ConfigError(within.reason);
+  }
+
+  return {
+    ...config,
+    worktrees: {
+      ...config.worktrees,
+      directory: resolved,
+    },
+  };
+};
+
+const describeConfigSources = (paths: string[]): string =>
+  paths.length === 1 ? (paths[0] ?? "workbox config") : `merged config from ${paths.join(" and ")}`;
+
+const readConfigIfExists = async (
+  configPath: string
+): Promise<{ config: PartialWorkboxConfig; path: string } | undefined> => {
+  const file = Bun.file(configPath);
+  if (!(await file.exists())) {
+    return undefined;
+  }
+
+  const contents = await file.text();
+  return {
+    config: parseConfig(contents, configPath),
+    path: configPath,
+  };
+};
+
+export const loadConfig = async (
+  repoRoot: string,
+  options: LoadConfigOptions = {}
+): Promise<LoadedConfig> => {
+  const globalPath = getGlobalConfigPath(options.env, options.homeDir);
+  const projectCandidates = getProjectConfigCandidatePaths(repoRoot);
+  const loadedConfigs: Array<{ config: PartialWorkboxConfig; path: string }> = [];
+
+  const globalConfig = await readConfigIfExists(globalPath);
+  if (globalConfig) {
+    loadedConfigs.push(globalConfig);
+  }
+
+  for (const configPath of projectCandidates) {
+    const projectConfig = await readConfigIfExists(configPath);
+    if (projectConfig) {
+      loadedConfigs.push(projectConfig);
+      break;
+    }
+  }
+
+  if (loadedConfigs.length > 0) {
+    const paths = loadedConfigs.map((item) => item.path);
+    const merged = mergeConfig(loadedConfigs.map((item) => item.config));
+    const config = validateMergedConfig(merged, describeConfigSources(paths));
+    return {
+      config: await resolveConfig(config, repoRoot),
+      path: paths.at(-1) ?? globalPath,
+    };
+  }
+
+  throw new ConfigError(
+    `No workbox config found. Expected ${GLOBAL_CONFIG_XDG} under $XDG_CONFIG_HOME, ` +
+      `${GLOBAL_CONFIG_FALLBACK} under your home directory, or ${CONFIG_PRIMARY} or ` +
+      `${CONFIG_SECONDARY} in ${repoRoot}.`
+  );
+};

package/src/core/git.ts

@@ -0,0 +1,352 @@
+import { access, mkdir, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+
+import { CliError } from "../ui/errors";
+import { checkPathWithinRoot, isSubpath } from "./path";
+import { runCommand } from "./process";
+
+type WorktreeInfo = {
+  name: string;
+  path: string;
+  branch: string | null;
+  managedBranch: string;
+  managed: boolean;
+};
+
+type WorktreeStatus = WorktreeInfo & {
+  clean: boolean;
+};
+
+type PorcelainWorktree = {
+  path: string;
+  branch: string | null;
+  detached: boolean;
+};
+
+type RunResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+const runCmd = async (cmd: string[], cwd: string): Promise<RunResult> => {
+  return runCommand({ cmd, cwd, mode: "capture" });
+};
+
+const runGit = async (args: string[], cwd: string): Promise<string> => {
+  const result = await runCmd(["git", ...args], cwd);
+  if (result.exitCode !== 0) {
+    const message = result.stderr || result.stdout || "Unknown git error.";
+    throw new CliError(`Git command failed (git ${args.join(" ")}): ${message}`);
+  }
+  return result.stdout.trim();
+};
+
+const gitSucceeds = async (args: string[], cwd: string): Promise<boolean> => {
+  const result = await runCmd(["git", ...args], cwd);
+  return result.exitCode === 0;
+};
+
+const assertValidBranchName = async (branch: string, repoRoot: string): Promise<void> => {
+  const valid = await gitSucceeds(["check-ref-format", "--branch", branch], repoRoot);
+  if (!valid) {
+    throw new CliError(
+      `Invalid branch name "${branch}". Check worktrees.branch_prefix and the sandbox name.`
+    );
+  }
+};
+
+const normalizePath = async (path: string): Promise<string> => {
+  try {
+    return await realpath(path);
+  } catch {
+    return resolve(path);
+  }
+};
+
+const pathExists = async (path: string): Promise<boolean> => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const assertWorktreesDirSafe = async (repoRoot: string, worktreesDir: string): Promise<void> => {
+  const within = await checkPathWithinRoot({
+    rootDir: repoRoot,
+    candidatePath: worktreesDir,
+    label: "worktrees.directory",
+  });
+  if (!within.ok) {
+    throw new CliError(within.reason);
+  }
+};
+
+const parseWorktreeListPorcelain = (output: string): PorcelainWorktree[] => {
+  const lines = output.split("\n");
+  const items: PorcelainWorktree[] = [];
+  let current: PorcelainWorktree | null = null;
+
+  for (const line of lines) {
+    if (line.startsWith("worktree ")) {
+      if (current) {
+        items.push(current);
+      }
+      current = {
+        path: line.slice("worktree ".length).trim(),
+        branch: null,
+        detached: false,
+      };
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    if (line === "detached") {
+      current.detached = true;
+      current.branch = null;
+      continue;
+    }
+
+    if (line.startsWith("branch ")) {
+      const ref = line.slice("branch ".length).trim();
+      current.branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+    }
+  }
+
+  if (current) {
+    items.push(current);
+  }
+
+  return items;
+};
+
+const validateWorktreeName = (name: string): void => {
+  if (!name || name.trim().length === 0) {
+    throw new CliError("Worktree name must be non-empty.", { exitCode: 2 });
+  }
+  if (name === "." || name === "..") {
+    throw new CliError(`Invalid worktree name "${name}".`, { exitCode: 2 });
+  }
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+    throw new CliError(`Invalid worktree name "${name}".`, { exitCode: 2 });
+  }
+  if (name.includes("..")) {
+    throw new CliError(`Invalid worktree name "${name}".`, { exitCode: 2 });
+  }
+};
+
+const listWorktreesPorcelain = async (repoRoot: string): Promise<PorcelainWorktree[]> => {
+  const output = await runGit(["worktree", "list", "--porcelain"], repoRoot);
+  return parseWorktreeListPorcelain(output);
+};
+
+export const getWorkboxWorktrees = async (input: {
+  repoRoot: string;
+  worktreesDir: string;
+  branchPrefix: string;
+}): Promise<WorktreeInfo[]> => {
+  await assertWorktreesDirSafe(input.repoRoot, input.worktreesDir);
+  const worktrees = await listWorktreesPorcelain(input.repoRoot);
+  const normalizedWorktreesDir = await normalizePath(input.worktreesDir);
+
+  const items: WorktreeInfo[] = [];
+  for (const worktree of worktrees) {
+    const resolvedPath = resolve(input.repoRoot, worktree.path);
+    const normalizedPath = await normalizePath(resolvedPath);
+
+    if (!isSubpath(normalizedPath, normalizedWorktreesDir)) {
+      continue;
+    }
+
+    const relativePath = relative(normalizedWorktreesDir, normalizedPath);
+    if (!relativePath || relativePath === "." || relativePath.includes(sep)) {
+      continue;
+    }
+
+    validateWorktreeName(relativePath);
+    const name = relativePath;
+    const expectedPath = await normalizePath(join(input.worktreesDir, name));
+
+    if (expectedPath !== normalizedPath) {
+      continue;
+    }
+
+    const managedBranch = `${input.branchPrefix}${name}`;
+    items.push({
+      name,
+      path: normalizedPath,
+      branch: worktree.branch,
+      managedBranch,
+      managed: worktree.branch === managedBranch,
+    });
+  }
+
+  items.sort((a, b) => a.name.localeCompare(b.name));
+  return items;
+};
+
+export const getManagedWorktrees = async (input: {
+  repoRoot: string;
+  worktreesDir: string;
+  branchPrefix: string;
+}): Promise<WorktreeInfo[]> => {
+  const items = await getWorkboxWorktrees(input);
+  return items.filter((item) => item.managed);
+};
+
+export const getWorkboxWorktree = async (input: {
+  repoRoot: string;
+  worktreesDir: string;
+  branchPrefix: string;
+  name: string;
+}): Promise<WorktreeInfo> => {
+  await assertWorktreesDirSafe(input.repoRoot, input.worktreesDir);
+  validateWorktreeName(input.name);
+  const expectedPath = await normalizePath(join(input.worktreesDir, input.name));
+
+  const candidates = await getWorkboxWorktrees({
+    repoRoot: input.repoRoot,
+    worktreesDir: input.worktreesDir,
+    branchPrefix: input.branchPrefix,
+  });
+
+  const match = candidates.find((candidate) => candidate.name === input.name);
+  if (!match) {
+    throw new CliError(`No workbox worktree found for "${input.name}".`);
+  }
+
+  if ((await normalizePath(match.path)) !== expectedPath) {
+    throw new CliError(
+      `Refusing to operate on "${input.name}": path mismatch (expected ${expectedPath}, got ${match.path}).`
+    );
+  }
+
+  return match;
+};
+
+export const createWorktree = async (input: {
+  repoRoot: string;
+  worktreesDir: string;
+  branchPrefix: string;
+  baseRef: string;
+  name: string;
+}): Promise<WorktreeInfo> => {
+  await assertWorktreesDirSafe(input.repoRoot, input.worktreesDir);
+  validateWorktreeName(input.name);
+  const managedBranch = `${input.branchPrefix}${input.name}`;
+  const worktreePath = join(input.worktreesDir, input.name);
+
+  await mkdir(input.worktreesDir, { recursive: true });
+  await assertValidBranchName(managedBranch, input.repoRoot);
+
+  const baseExists = await gitSucceeds(["rev-parse", "--verify", input.baseRef], input.repoRoot);
+  if (!baseExists) {
+    throw new CliError(`Base ref "${input.baseRef}" does not exist.`);
+  }
+
+  const branchExists = await gitSucceeds(
+    ["show-ref", "--verify", `refs/heads/${managedBranch}`],
+    input.repoRoot
+  );
+  if (branchExists) {
+    throw new CliError(
+      `Branch "${managedBranch}" already exists. Refusing to create a new sandbox.`
+    );
+  }
+
+  await runGit(
+    ["worktree", "add", "-b", managedBranch, worktreePath, input.baseRef],
+    input.repoRoot
+  );
+
+  if (await pathExists(join(worktreePath, ".gitmodules"))) {
+    await runGit(["submodule", "update", "--init", "--recursive"], worktreePath);
+  }
+
+  return {
+    name: input.name,
+    path: await normalizePath(worktreePath),
+    branch: managedBranch,
+    managedBranch,
+    managed: true,
+  };
+};
+
+export const removeWorktree = async (input: {
+  repoRoot: string;
+  worktreesDir: string;
+  branchPrefix: string;
+  name: string;
+  force: boolean;
+  deleteBranch: boolean;
+}): Promise<WorktreeInfo> => {
+  await assertWorktreesDirSafe(input.repoRoot, input.worktreesDir);
+  const worktree = await getWorkboxWorktree({
+    repoRoot: input.repoRoot,
+    worktreesDir: input.worktreesDir,
+    branchPrefix: input.branchPrefix,
+    name: input.name,
+  });
+
+  if (input.deleteBranch && !worktree.managed) {
+    throw new CliError(`Refusing to delete a branch for unmanaged worktree "${input.name}".`);
+  }
+
+  await runGit(
+    ["worktree", "remove", ...(input.force ? ["--force"] : []), "--", worktree.path],
+    input.repoRoot
+  );
+
+  if (input.deleteBranch) {
+    await runGit(["branch", input.force ? "-D" : "-d", worktree.managedBranch], input.repoRoot);
+  }
+
+  return worktree;
+};
+
+export const pruneWorktrees = async (repoRoot: string): Promise<{ stdout: string }> => {
+  const stdout = await runGit(["worktree", "prune"], repoRoot);
+  return { stdout };
+};
+
+const isCleanWorktree = async (path: string): Promise<boolean> => {
+  const status = await runGit(["status", "--porcelain"], path);
+  return status.trim().length === 0;
+};
+
+export const getWorktreeStatus = async (input: {
+  repoRoot: string;
+  worktreesDir: string;
+  branchPrefix: string;
+  name?: string;
+}): Promise<WorktreeStatus[]> => {
+  await assertWorktreesDirSafe(input.repoRoot, input.worktreesDir);
+  const worktrees = input.name
+    ? [
+        await getWorkboxWorktree({
+          repoRoot: input.repoRoot,
+          worktreesDir: input.worktreesDir,
+          branchPrefix: input.branchPrefix,
+          name: input.name,
+        }),
+      ]
+    : await getWorkboxWorktrees({
+        repoRoot: input.repoRoot,
+        worktreesDir: input.worktreesDir,
+        branchPrefix: input.branchPrefix,
+      });
+
+  const results: WorktreeStatus[] = [];
+  for (const worktree of worktrees) {
+    results.push({
+      ...worktree,
+      clean: await isCleanWorktree(worktree.path),
+    });
+  }
+  return results;
+};