@alecrust/workbox 0.4.1

package/src/core/path.ts

@@ -0,0 +1,103 @@
+import { lstat, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+
+export const isSubpath = (candidatePath: string, basePath: string): boolean => {
+  const base = resolve(basePath);
+  const candidate = resolve(candidatePath);
+  if (candidate === base) {
+    return true;
+  }
+  const baseWithSep = base.endsWith(sep) ? base : `${base}${sep}`;
+  return candidate.startsWith(baseWithSep);
+};
+
+const realpathOrResolve = async (path: string): Promise<string> => {
+  try {
+    return await realpath(path);
+  } catch {
+    return resolve(path);
+  }
+};
+
+const checkSegmentsWithinRoot = async (
+  rootResolved: string,
+  rootReal: string,
+  rel: string,
+  label: string
+): Promise<{ ok: true } | { ok: false; reason: string }> => {
+  let cursor = rootResolved;
+  const segments = rel.split(sep).filter((segment) => segment.length > 0);
+
+  for (const segment of segments) {
+    cursor = join(cursor, segment);
+    try {
+      const stat = await lstat(cursor);
+      if (stat.isSymbolicLink()) {
+        const linkTarget = await realpathOrResolve(cursor);
+        if (!isSubpath(linkTarget, rootReal)) {
+          return {
+            ok: false,
+            reason: `${label} escapes repo root via symlink (${cursor} -> ${linkTarget}).`,
+          };
+        }
+      }
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR")
+      )
+        return { ok: true };
+      throw error;
+    }
+  }
+
+  return { ok: true };
+};
+
+export const checkPathWithinRoot = async (input: {
+  rootDir: string;
+  candidatePath: string;
+  label: string;
+}): Promise<{ ok: true } | { ok: false; reason: string }> => {
+  const rootResolved = resolve(input.rootDir);
+  const rootReal = await realpathOrResolve(rootResolved);
+  const candidateResolved = resolve(input.candidatePath);
+
+  if (!isSubpath(candidateResolved, rootResolved)) {
+    return {
+      ok: false,
+      reason: `${input.label} must be within repo root (${rootResolved}): ${input.candidatePath}`,
+    };
+  }
+
+  const rel = relative(rootResolved, candidateResolved);
+  if (!rel || rel === ".") {
+    return { ok: true };
+  }
+
+  const segmentCheck = await checkSegmentsWithinRoot(rootResolved, rootReal, rel, input.label);
+  if (!segmentCheck.ok) {
+    return segmentCheck;
+  }
+
+  try {
+    const candidateReal = await realpath(candidateResolved);
+    if (!isSubpath(candidateReal, rootReal)) {
+      return {
+        ok: false,
+        reason: `${input.label} must resolve within repo root (${rootReal}): ${input.candidatePath}`,
+      };
+    }
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    )
+      return { ok: true };
+    throw error;
+  }
+
+  return { ok: true };
+};

package/src/core/paths.ts

@@ -0,0 +1,23 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const CONFIG_PRIMARY = join(".workbox", "config.toml");
+export const CONFIG_SECONDARY = "workbox.toml";
+export const GLOBAL_CONFIG_XDG = join("workbox", "config.toml");
+export const GLOBAL_CONFIG_FALLBACK = join(".workbox", "config.toml");
+
+export const getGlobalConfigPath = (
+  env: NodeJS.ProcessEnv = process.env,
+  homeDir = homedir()
+): string =>
+  env.XDG_CONFIG_HOME
+    ? join(env.XDG_CONFIG_HOME, GLOBAL_CONFIG_XDG)
+    : join(homeDir, GLOBAL_CONFIG_FALLBACK);
+
+export const getProjectConfigCandidatePaths = (repoRoot: string): string[] => [
+  join(repoRoot, CONFIG_PRIMARY),
+  join(repoRoot, CONFIG_SECONDARY),
+];
+
+export const resolveWorktreesDir = (worktreesDir: string, repoRoot: string): string =>
+  resolve(repoRoot, worktreesDir);

package/src/core/process.ts

@@ -0,0 +1,52 @@
+type RunMode = "inherit" | "capture";
+
+type RunResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+const readStream = async (
+  stream: ReadableStream<Uint8Array> | null | undefined
+): Promise<string> => {
+  if (!stream) {
+    return "";
+  }
+  return new Response(stream).text();
+};
+
+export const runCommand = async (input: {
+  cmd: string[];
+  cwd: string;
+  mode: RunMode;
+  env?: Record<string, string>;
+}): Promise<RunResult> => {
+  const proc = Bun.spawn({
+    cmd: input.cmd,
+    cwd: input.cwd,
+    env: input.env ? { ...process.env, ...input.env } : process.env,
+    stdout: input.mode === "inherit" ? "inherit" : "pipe",
+    stderr: input.mode === "inherit" ? "inherit" : "pipe",
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    input.mode === "capture" ? readStream(proc.stdout) : Promise.resolve(""),
+    input.mode === "capture" ? readStream(proc.stderr) : Promise.resolve(""),
+    proc.exited,
+  ]);
+
+  return { exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
+};
+
+export const runShellCommand = async (input: {
+  command: string;
+  cwd: string;
+  mode: RunMode;
+  env?: Record<string, string>;
+}): Promise<RunResult> => {
+  const isWindows = process.platform === "win32";
+  const cmd = isWindows
+    ? ["cmd.exe", "/d", "/s", "/c", input.command]
+    : ["sh", "-c", input.command];
+  return runCommand({ cmd, cwd: input.cwd, mode: input.mode, env: input.env });
+};

package/src/core/repo.ts

@@ -0,0 +1,44 @@
+import { dirname, resolve } from "node:path";
+
+import { CliError } from "../ui/errors";
+import { runCommand } from "./process";
+
+const runGit = async (args: string[], cwd: string): Promise<string> => {
+  const { stdout, stderr, exitCode } = await runCommand({
+    cmd: ["git", ...args],
+    cwd,
+    mode: "capture",
+  });
+
+  if (exitCode !== 0) {
+    const message = stderr.trim() || stdout.trim() || "Unknown git error.";
+    throw new CliError(`Git command failed (git ${args.join(" ")}): ${message}`);
+  }
+
+  return stdout.trim();
+};
+
+export const getRepoInfo = async (
+  cwd: string
+): Promise<{ repoRoot: string; worktreeRoot: string; gitCommonDir: string }> => {
+  const worktreeRoot = await runGit(["rev-parse", "--show-toplevel"], cwd);
+  if (!worktreeRoot) {
+    throw new CliError("Unable to resolve Git worktree root.");
+  }
+
+  const commonDirRaw = await runGit(["rev-parse", "--git-common-dir"], cwd);
+  if (!commonDirRaw) {
+    throw new CliError("Unable to resolve Git common directory.");
+  }
+
+  // `--git-common-dir` is typically relative to the current working directory,
+  // not the worktree root. Resolving it relative to `cwd` ensures this works
+  // from nested subdirectories.
+  const gitCommonDir = resolve(cwd, commonDirRaw);
+  const repoRoot = dirname(gitCommonDir);
+  if (!repoRoot) {
+    throw new CliError("Unable to resolve Git repository root.");
+  }
+
+  return { repoRoot, worktreeRoot, gitCommonDir };
+};

package/src/provision/runner.ts

@@ -0,0 +1,204 @@
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import { checkPathWithinRoot } from "../core/path";
+import { runShellCommand } from "../core/process";
+import { CliError } from "../ui/errors";
+
+type ProvisionCopy = {
+  from: string;
+  to: string;
+  required: boolean;
+};
+
+type ProvisionStep = {
+  name: string;
+  run: string;
+  cwd?: string;
+  env?: Record<string, string>;
+};
+
+type ProvisionCopyResult = {
+  from: string;
+  to: string;
+  required: boolean;
+  source: string;
+  destination: string;
+  status: "copied" | "skipped" | "failed";
+  reason?: string;
+};
+
+type ProvisionStepResult = {
+  name: string;
+  command: string;
+  cwd: string;
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+};
+
+type ProvisionResult = {
+  status: "ok" | "failed";
+  message: string;
+  copies: ProvisionCopyResult[];
+  steps: ProvisionStepResult[];
+  exitCode: number;
+};
+
+type OutputMode = "inherit" | "capture";
+
+const isMissingPathError = (error: unknown): boolean =>
+  error instanceof Error && "code" in error && error.code === "ENOENT";
+
+const getErrorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const resolveWithinRoot = async (rootDir: string, path: string, label: string): Promise<string> => {
+  const resolved = resolve(rootDir, path);
+  const within = await checkPathWithinRoot({
+    rootDir,
+    candidatePath: resolved,
+    label,
+  });
+  if (!within.ok) {
+    throw new CliError(within.reason, { exitCode: 2 });
+  }
+  return resolved;
+};
+
+const buildFailedResult = (
+  message: string,
+  copies: ProvisionCopyResult[],
+  steps: ProvisionStepResult[],
+  exitCode: number
+): ProvisionResult => ({
+  status: "failed",
+  message,
+  copies,
+  steps,
+  exitCode,
+});
+
+export const runProvision = async (
+  provision: { copy: ProvisionCopy[]; steps: ProvisionStep[] },
+  options: {
+    sourceRoot: string;
+    targetRoot: string;
+    worktreeName: string;
+    mode: OutputMode;
+  }
+): Promise<ProvisionResult> => {
+  const copies: ProvisionCopyResult[] = [];
+  const steps: ProvisionStepResult[] = [];
+
+  if (provision.copy.length === 0 && provision.steps.length === 0) {
+    return {
+      status: "ok",
+      message: "no provision actions configured.",
+      copies,
+      steps,
+      exitCode: 0,
+    };
+  }
+
+  for (const item of provision.copy) {
+    const source = await resolveWithinRoot(options.sourceRoot, item.from, "provision copy source");
+    const destination = await resolveWithinRoot(
+      options.targetRoot,
+      item.to,
+      "provision copy destination"
+    );
+
+    let sourceStat: Awaited<ReturnType<typeof stat>>;
+    try {
+      sourceStat = await stat(source);
+    } catch (error) {
+      if (!isMissingPathError(error)) {
+        const reason = getErrorMessage(error);
+        copies.push({ ...item, source, destination, status: "failed", reason });
+        return buildFailedResult(
+          `provision copy "${item.from}" failed: ${reason}`,
+          copies,
+          steps,
+          1
+        );
+      }
+      if (!item.required) {
+        copies.push({ ...item, source, destination, status: "skipped", reason: "missing source" });
+        continue;
+      }
+      const reason = "missing required source";
+      copies.push({ ...item, source, destination, status: "failed", reason });
+      return buildFailedResult(
+        `provision copy "${item.from}" failed: ${reason}.`,
+        copies,
+        steps,
+        1
+      );
+    }
+
+    if (sourceStat.isDirectory()) {
+      const reason = "source is a directory";
+      copies.push({ ...item, source, destination, status: "failed", reason });
+      return buildFailedResult(
+        `provision copy "${item.from}" failed: ${reason}.`,
+        copies,
+        steps,
+        1
+      );
+    }
+
+    try {
+      await mkdir(dirname(destination), { recursive: true });
+      await copyFile(source, destination);
+    } catch (error) {
+      const reason = getErrorMessage(error);
+      copies.push({ ...item, source, destination, status: "failed", reason });
+      return buildFailedResult(`provision copy "${item.from}" failed: ${reason}`, copies, steps, 1);
+    }
+
+    copies.push({ ...item, source, destination, status: "copied" });
+  }
+
+  for (const step of provision.steps) {
+    const cwd = await resolveWithinRoot(options.targetRoot, step.cwd ?? ".", "provision step cwd");
+    const result = await runShellCommand({
+      command: step.run,
+      cwd,
+      mode: options.mode,
+      env: {
+        WORKBOX_SOURCE: options.sourceRoot,
+        WORKBOX_WORKTREE: options.targetRoot,
+        WORKBOX_NAME: options.worktreeName,
+        ...step.env,
+      },
+    });
+
+    steps.push({
+      name: step.name,
+      command: step.run,
+      cwd,
+      exitCode: result.exitCode,
+      ...(options.mode === "capture"
+        ? { stdout: result.stdout.trim(), stderr: result.stderr.trim() }
+        : {}),
+    });
+
+    if (result.exitCode !== 0) {
+      return buildFailedResult(
+        `provision step "${step.name}" failed (exit ${result.exitCode}).`,
+        copies,
+        steps,
+        result.exitCode
+      );
+    }
+  }
+
+  return {
+    status: "ok",
+    message: "provision completed.",
+    copies,
+    steps,
+    exitCode: 0,
+  };
+};

package/src/ui/errors.ts

@@ -0,0 +1,23 @@
+export class CliError extends Error {
+  readonly exitCode: number;
+
+  constructor(message: string, options?: { exitCode?: number; cause?: unknown }) {
+    super(message, options);
+    this.name = "CliError";
+    this.exitCode = options?.exitCode ?? 1;
+  }
+}
+
+export class UsageError extends CliError {
+  constructor(message: string) {
+    super(message, { exitCode: 2 });
+    this.name = "UsageError";
+  }
+}
+
+export class ConfigError extends CliError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, { exitCode: 1, cause: options?.cause });
+    this.name = "ConfigError";
+  }
+}

package/src/ui/log.ts

@@ -0,0 +1,32 @@
+type OutputMode = "text" | "json";
+
+type CliPayload = {
+  ok: boolean;
+  command?: string;
+  message?: string;
+  data?: unknown;
+  help?: string;
+  errors?: string[];
+};
+
+export const formatOutput = (payload: CliPayload, mode: OutputMode): string => {
+  if (mode === "json") {
+    return JSON.stringify(payload, null, 2);
+  }
+
+  const lines: string[] = [];
+  if (payload.message) {
+    lines.push(payload.message);
+  }
+  if (payload.help) {
+    lines.push(payload.help);
+  }
+  if (payload.errors && payload.errors.length > 0) {
+    lines.push("Errors:");
+    for (const error of payload.errors) {
+      lines.push(`- ${error}`);
+    }
+  }
+
+  return lines.join("\n");
+};