@mastra/factory 0.0.0 → 0.1.0-alpha.3

package/dist/integrations/github/sandbox.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Repo materialization for GitHub-backed repositories.
+ *
+ * A GitHub repo is never cloned onto the server host. Instead each project gets
+ * its own isolated sandbox (provisioned by the fleet in `../sandbox/fleet`) and
+ * the repo is cloned *inside* that sandbox. The agent's file tools and command
+ * tools then operate entirely against the remote checkout.
+ *
+ * - `ensureProjectSandbox(row)` / `teardownProjectSandbox(row)` bind the fleet's
+ *   provision/reattach/teardown lifecycle to the per-(project,user) sandbox row.
+ * - `materializeRepo(row, token)` runs `git clone` (first open) or `git pull`
+ *   (re-open) inside the sandbox, using a short-lived installation token that is
+ *   scrubbed from the git remote afterwards so it never persists in the VM.
+ *
+ * This module owns everything git/GitHub: clone/pull, commit/push, worktrees,
+ * and `gh pr create`. Sandbox provisioning, budgets, and workdir layout live in
+ * the fleet module.
+ */
+import type { MaterializationSandbox, ProgressFn, SandboxFleet } from '../../sandbox/fleet.js';
+import type { ProjectRepositorySandbox, SourceControlStorageHandle } from '../../storage/domains/source-control/base.js';
+type SourceControlSandboxStorage = SourceControlStorageHandle['sandboxes'];
+type MaterializationStore = Pick<SourceControlSandboxStorage, 'markMaterialized'>;
+interface RepoMaterializationBinding {
+    id: string;
+    sandboxWorkdir: string;
+    materializedAt: Date | null;
+}
+/**
+ * Provision a new sandbox (persisting its provider id on first open) or
+ * reattach to the stored one. Returns a started, live sandbox.
+ */
+export declare function ensureProjectSandbox(options: {
+    fleet: SandboxFleet;
+    row: ProjectRepositorySandbox;
+    storage: SourceControlSandboxStorage;
+    onProgress?: ProgressFn;
+}): Promise<MaterializationSandbox>;
+/**
+ * Tear down a user's sandbox for a project: stop the live VM (best-effort) and
+ * clear the persisted `sandboxId`/`materializedAt` on the per-(project,user)
+ * binding row so the next open re-provisions cleanly.
+ *
+ * @param row     the per-(project,user) sandbox binding to tear down
+ * @param sandbox an already-reattached live sandbox to stop, when available
+ */
+export declare function teardownProjectSandbox(options: {
+    fleet: SandboxFleet;
+    row: ProjectRepositorySandbox;
+    storage: SourceControlSandboxStorage;
+    sandbox?: MaterializationSandbox;
+}): Promise<void>;
+/**
+ * Single-quote a string for safe POSIX shell interpolation. Wraps the value in
+ * single quotes and escapes any embedded single quote using the canonical
+ * close-quote / escaped-quote / reopen-quote sequence (`'\''`). This is the
+ * standard POSIX-safe construction and prevents the quoted string from being
+ * terminated early.
+ */
+export declare function shellQuote(value: string): string;
+/** Error raised when the sandbox cannot materialize the repo (actionable). */
+export declare class MaterializeError extends Error {
+    readonly code: 'git-missing' | 'egress-blocked' | 'clone-failed' | 'pull-failed' | 'push-failed' | 'commit-failed' | 'gh-missing' | 'pr-failed';
+    constructor(message: string, code: 'git-missing' | 'egress-blocked' | 'clone-failed' | 'pull-failed' | 'push-failed' | 'commit-failed' | 'gh-missing' | 'pr-failed');
+}
+/** Repo metadata needed to materialize, read from the org-owned project row. */
+export interface RepoMaterializeInfo {
+    repoFullName: string;
+    defaultBranch: string;
+}
+/**
+ * Materialize the repo inside the user's sandbox. Clones on first open, pulls on
+ * re-open. Always scrubs the install token from the remote afterwards and sets
+ * `materialized_at` on the per-user sandbox binding row.
+ *
+ */
+export declare function materializeRepo(options: {
+    /** The per-(project,user) sandbox binding (provisioned via `ensureProjectSandbox`). */
+    row: RepoMaterializationBinding;
+    /** Repo metadata from the org-owned project row. */
+    repoInfo: RepoMaterializeInfo;
+    /** The live sandbox to run git inside. */
+    sandbox: MaterializationSandbox;
+    /** A freshly minted, short-lived installation access token. */
+    token: string;
+    storage: MaterializationStore;
+    onProgress?: ProgressFn;
+}): Promise<void>;
+/** Check out a session's branch inside its isolated repository clone. */
+export declare function checkoutSessionBranch(sandbox: MaterializationSandbox, workdir: string, { branch, baseBranch, token, repoFullName, }: {
+    branch: string;
+    baseBranch: string;
+    token: string;
+    repoFullName: string;
+}): Promise<void>;
+/**
+ * Validate a git ref (branch) name. Server-side defense-in-depth: only allow a
+ * conservative character set so a branch can never be built into a shell
+ * command in a way that escapes quoting. Mirrors the route-layer check.
+ */
+export declare function isValidGitRef(value: unknown): value is string;
+/** Identity used to author commits inside the sandbox. */
+export interface GitIdentity {
+    name?: string | null;
+    email?: string | null;
+    /** GitHub login, used to derive a stable noreply identity when name/email are absent. */
+    login?: string | null;
+}
+/**
+ * Resolve a concrete `{ name, email }` for git authorship from a possibly-sparse
+ * identity. Falls back to a GitHub-style noreply identity so commits are never
+ * authored with an empty or host-derived identity.
+ */
+export declare function resolveGitIdentity(identity: GitIdentity): {
+    name: string;
+    email: string;
+};
+/**
+ * Configure `user.name` / `user.email` for the given repo working tree inside
+ * the sandbox so commits are authored correctly. Values are shell-quoted.
+ */
+export declare function configureGitIdentity(sandbox: MaterializationSandbox, workdir: string, identity: GitIdentity): Promise<void>;
+/**
+ * Temporarily rewrite `origin` to a tokenized URL, run `fn` (e.g. a push), and
+ * **always** scrub the remote back to the tokenless URL in a `finally`. The
+ * token therefore only ever lives in the remote URL for the duration of the
+ * operation and is never left in the VM's git config.
+ *
+ * On the success path the scrub must succeed (a leaked token is a hard error);
+ * if it fails we surface it. On the failure path the scrub is best-effort but
+ * still attempted, and the original operation error is rethrown.
+ */
+export declare function withInstallToken<T>(sandbox: MaterializationSandbox, workdir: string, repoFullName: string, token: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Push a branch back to GitHub from inside the sandbox using a short-lived
+ * installation token. The branch is ref-validated, the token is injected only
+ * into the remote URL via `withInstallToken`, and egress failures are
+ * classified into actionable errors.
+ */
+export declare function pushBranch(sandbox: MaterializationSandbox, workdir: string, branch: string, token: string, repoFullName: string): Promise<void>;
+export interface CommitResult {
+    /** True when a commit was created; false when there was nothing to commit. */
+    committed: boolean;
+}
+/**
+ * Stage every change in the working tree and create a commit inside the
+ * sandbox. The git identity is configured first so authorship is correct. When
+ * there is nothing to commit this is a no-op (`committed: false`) rather than an
+ * error, so callers can safely commit-then-push without first diffing.
+ *
+ * @param sandbox  the live sandbox containing the checkout
+ * @param workdir  the worktree (or repo) path to commit in
+ * @param message  the commit message (quoted; arbitrary text is safe)
+ * @param identity authorship identity for the commit
+ */
+export declare function commitAll(sandbox: MaterializationSandbox, workdir: string, message: string, identity: GitIdentity): Promise<CommitResult>;
+/** Error raised when a worktree cannot be created/reused inside the sandbox. */
+export declare class WorktreeError extends Error {
+    readonly code: 'invalid-branch' | 'worktree-failed' | 'setup-failed';
+    constructor(message: string, code: 'invalid-branch' | 'worktree-failed' | 'setup-failed');
+}
+/**
+ * Reduce a (already ref-validated) branch name to a filesystem-safe directory
+ * segment for the worktree path: slashes/dots/unsafe chars collapsed to `-`.
+ * This only affects the *directory name*, never the git branch itself.
+ *
+ * Sanitization is lossy (e.g. `feat/a` and `feat-a` both reduce to `feat-a`),
+ * so an 8-char hash of the original branch is appended whenever the sanitized
+ * form differs from the input. That keeps clean names (`main`) readable while
+ * guaranteeing distinct branches never share a worktree directory.
+ */
+export declare function safeBranchDir(branch: string): string;
+/**
+ * Compute the absolute worktree path for a branch, server-side only. Worktrees
+ * live alongside the repo checkout under a sibling `worktrees/` directory so the
+ * repo's `.git` is shared. Never derived from client-supplied paths.
+ */
+export declare function computeWorktreePath(repoWorkdir: string, branch: string): string;
+export interface EnsureWorktreeResult {
+    worktreePath: string;
+    branch: string;
+    baseBranch: string;
+    /** True when an existing worktree was reused rather than freshly created. */
+    reused: boolean;
+}
+/**
+ * Create (or reuse) a git worktree + branch inside the sandbox for a unit of
+ * work. Idempotent: if a worktree already exists at the computed path it is
+ * reused. The branch is created from the freshly fetched `origin/<baseBranch>`
+ * — never the sandbox's possibly stale local ref — so new worktrees always
+ * start from the latest remote state.
+ *
+ * @param sandbox       live sandbox containing the base checkout
+ * @param repoWorkdir   the base repo checkout path inside the sandbox
+ * @param branch        the feature branch (ref-validated server-side)
+ * @param baseBranch    the branch to fork from (ref-validated; defaults to the repo's default branch)
+ * @param token         short-lived installation token used only for the base-branch fetch
+ * @param repoFullName  `owner/repo` used to build the tokenized remote URL
+ */
+export declare function ensureWorktree(sandbox: MaterializationSandbox, repoWorkdir: string, { branch, baseBranch, token, repoFullName, }: {
+    branch: string;
+    baseBranch: string;
+    token: string;
+    repoFullName: string;
+}): Promise<EnsureWorktreeResult>;
+/**
+ * Run the project's setup command (e.g. `pnpm i && pnpm build`) inside a
+ * freshly created worktree. Called before the worktree is handed to any agent
+ * run so the checkout is ready to build/test. A non-zero exit is a hard error —
+ * starting agent work in a half-set-up tree is worse than failing the request.
+ *
+ * Security model: the command is intentionally arbitrary shell — that is the
+ * feature (install deps, build, seed fixtures). It is only configurable by
+ * authenticated org members (the settings route is gated by
+ * `resolveOrgTenant` + org-scoped project lookup, with length and
+ * control-character validation), and it executes exclusively inside the
+ * project's isolated sandbox — the same environment where org members already
+ * run arbitrary shell via the agent's command tool. It never runs on the web
+ * server host, so it grants no privilege beyond what sandbox access already
+ * provides.
+ *
+ * @param sandbox       live sandbox containing the worktree
+ * @param worktreePath  the server-computed worktree path the command runs in
+ * @param command       the org-configured setup shell command
+ */
+export declare function runWorktreeSetup(sandbox: MaterializationSandbox, worktreePath: string, command: string): Promise<void>;
+/**
+ * Remove a worktree (and its local feature branch) from the sandbox. The
+ * checkout is removed with `--force` — the caller owns confirming that any
+ * uncommitted work in it can be discarded. Idempotent: a worktree whose
+ * directory is already gone only has its metadata pruned.
+ *
+ * @param sandbox       live sandbox containing the base checkout
+ * @param repoWorkdir   the base repo checkout path inside the sandbox
+ * @param branch        the worktree's feature branch (ref-validated)
+ * @param worktreePath  the persisted, server-computed worktree path
+ */
+export declare function removeWorktree(sandbox: MaterializationSandbox, repoWorkdir: string, { branch, worktreePath }: {
+    branch: string;
+    worktreePath: string;
+}): Promise<void>;
+export interface CreatePullRequestArgs {
+    /** Short-lived installation token, injected only into the `gh` process env. */
+    token: string;
+    /** Base branch the PR merges into. Ref-validated. */
+    base: string;
+    /** Head branch the PR is opened from. Ref-validated. */
+    head: string;
+    /** PR title. */
+    title: string;
+    /** PR body (optional). */
+    body?: string;
+}
+export interface CreatePullRequestResult {
+    /** The PR URL parsed from `gh pr create` stdout. */
+    url: string;
+}
+/**
+ * Open a pull request from inside the sandbox via `gh pr create`. The token is
+ * passed only through a per-invocation `GH_TOKEN` env scoped to the single `gh`
+ * process (never persisted), all arguments are shell-quoted, and the resulting
+ * PR URL is parsed from stdout.
+ *
+ * @param sandbox live sandbox containing the checkout
+ * @param workdir the worktree (or repo) path the PR head branch is checked out in
+ */
+export declare function createPullRequest(sandbox: MaterializationSandbox, workdir: string, { token, base, head, title, body }: CreatePullRequestArgs): Promise<CreatePullRequestResult>;
+export {};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/integrations/github/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/integrations/github/sandbox.ts"],"names":[],"mappings":"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"}

package/dist/integrations/github/sandbox.js

@@ -0,0 +1,381 @@
+// src/integrations/github/sandbox.ts
+import { createHash } from "crypto";
+
+// src/sandbox/fleet.ts
+import path from "path";
+function reportProgress(onProgress, event) {
+  if (!onProgress) return;
+  try {
+    onProgress(event);
+  } catch {
+  }
+}
+
+// src/integrations/github/sandbox.ts
+function bindingStore(row, storage) {
+  return {
+    sandboxId: row.sandboxId,
+    setSandboxId: (id) => id === null ? storage.clearBinding({ id: row.id }) : storage.setSandboxId({ id: row.id, sandboxId: id }),
+    clear: () => storage.clearBinding({ id: row.id })
+  };
+}
+async function ensureProjectSandbox(options) {
+  const { fleet, row, storage, onProgress } = options;
+  return fleet.ensureSandbox(bindingStore(row, storage), onProgress);
+}
+async function teardownProjectSandbox(options) {
+  const { fleet, row, storage, sandbox } = options;
+  return fleet.teardownSandbox(bindingStore(row, storage), sandbox);
+}
+function shellQuote(value) {
+  return `'` + value.split(`'`).join(`'\\''`) + `'`;
+}
+async function sh(sandbox, script) {
+  return sandbox.executeCommand("sh", ["-c", script]);
+}
+var MaterializeError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "MaterializeError";
+  }
+  code;
+};
+function tokenUrl(repoFullName, token) {
+  return `https://x-access-token:${token}@github.com/${repoFullName}.git`;
+}
+function cleanUrl(repoFullName) {
+  return `https://github.com/${repoFullName}.git`;
+}
+async function materializeRepo(options) {
+  const { row: sandboxRow, repoInfo, sandbox, token, storage, onProgress } = options;
+  const workdir = sandboxRow.sandboxWorkdir;
+  const repo = repoInfo.repoFullName;
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+    throw new MaterializeError(`Refusing to materialize: invalid repo full name '${repo}'.`, "clone-failed");
+  }
+  if (!/^[A-Za-z0-9_./-]+$/.test(repoInfo.defaultBranch)) {
+    throw new MaterializeError(
+      `Refusing to materialize: invalid default branch '${repoInfo.defaultBranch}'.`,
+      "clone-failed"
+    );
+  }
+  const gitVersion = await sh(sandbox, "git --version");
+  if (gitVersion.exitCode !== 0) {
+    throw new MaterializeError(
+      "git is not installed in the sandbox. The sandbox template must include git.",
+      "git-missing"
+    );
+  }
+  const authUrl = tokenUrl(repo, token);
+  const alreadyMaterialized = Boolean(sandboxRow.materializedAt) || await hasExistingCheckout(sandbox, workdir, repo);
+  try {
+    if (!alreadyMaterialized) {
+      reportProgress(onProgress, {
+        phase: "cloning",
+        message: `Cloning ${repo} (first open can take a minute)\u2026`
+      });
+      const clone = await sh(
+        sandbox,
+        `git clone --depth=1 --single-branch --branch ${shellQuote(repoInfo.defaultBranch)} ${shellQuote(authUrl)} ${shellQuote(workdir)}`
+      );
+      if (clone.exitCode !== 0) {
+        throw classifyGitFailure(clone, "clone-failed");
+      }
+    } else {
+      reportProgress(onProgress, { phase: "pulling", message: `Updating ${repo} to the latest changes\u2026` });
+      const setUrl = await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(authUrl)}`);
+      if (setUrl.exitCode !== 0) {
+        throw new MaterializeError(`Failed to set git remote: ${setUrl.stderr}`, "pull-failed");
+      }
+      const pull = await sh(sandbox, `git -C ${shellQuote(workdir)} pull --ff-only`);
+      if (pull.exitCode !== 0) {
+        throw classifyGitFailure(pull, "pull-failed");
+      }
+    }
+  } finally {
+    await scrubRemote(sandbox, workdir, repo, alreadyMaterialized);
+  }
+  reportProgress(onProgress, { phase: "finalizing", message: "Finalizing workspace\u2026" });
+  await storage.markMaterialized({ id: sandboxRow.id });
+}
+async function checkoutSessionBranch(sandbox, workdir, {
+  branch,
+  baseBranch,
+  token,
+  repoFullName
+}) {
+  if (!isValidGitRef(branch) || !isValidGitRef(baseBranch)) {
+    throw new MaterializeError("Refusing to create a session from an invalid branch name.", "clone-failed");
+  }
+  const current = await sh(sandbox, `git -C ${shellQuote(workdir)} branch --show-current`);
+  if (current.exitCode === 0 && current.stdout.trim() === branch) return;
+  const local = await sh(
+    sandbox,
+    `git -C ${shellQuote(workdir)} show-ref --verify --quiet refs/heads/${shellQuote(branch)}`
+  );
+  if (local.exitCode === 0) {
+    const checkout = await sh(sandbox, `git -C ${shellQuote(workdir)} checkout ${shellQuote(branch)}`);
+    if (checkout.exitCode !== 0) throw classifyGitFailure(checkout, "clone-failed");
+    return;
+  }
+  const authUrl = tokenUrl(repoFullName, token);
+  try {
+    const setUrl = await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(authUrl)}`);
+    if (setUrl.exitCode !== 0) throw classifyGitFailure(setUrl, "pull-failed");
+    const fetch = await sh(
+      sandbox,
+      `git -C ${shellQuote(workdir)} fetch origin ${shellQuote(baseBranch)} && git -C ${shellQuote(workdir)} checkout -b ${shellQuote(branch)} FETCH_HEAD`
+    );
+    if (fetch.exitCode !== 0) throw classifyGitFailure(fetch, "clone-failed");
+  } finally {
+    await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`);
+  }
+}
+async function hasExistingCheckout(sandbox, workdir, repoFullName) {
+  const result = await sh(sandbox, `git -C ${shellQuote(workdir)} remote get-url origin`);
+  if (result.exitCode !== 0) return false;
+  const url = result.stdout.trim().toLowerCase();
+  const suffix = `github.com/${repoFullName.toLowerCase()}`;
+  return url.endsWith(`${suffix}.git`) || url.endsWith(suffix);
+}
+async function scrubRemote(sandbox, workdir, repoFullName, expectGitDir) {
+  const result = await sh(
+    sandbox,
+    `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`
+  );
+  if (result.exitCode !== 0 && expectGitDir) {
+    throw new MaterializeError(
+      `Failed to scrub installation token from git remote: ${result.stderr.trim() || result.stdout.trim()}`,
+      "pull-failed"
+    );
+  }
+}
+function classifyGitFailure(result, fallback) {
+  const stderr = result.stderr || "";
+  if (/could not resolve host|failed to connect|network is unreachable|Connection timed out/i.test(stderr)) {
+    return new MaterializeError(
+      "The sandbox could not reach github.com. The sandbox network must allow outbound egress to github.com.",
+      "egress-blocked"
+    );
+  }
+  const verb = fallback === "clone-failed" ? "clone" : fallback === "pull-failed" ? "pull" : "push";
+  return new MaterializeError(`git ${verb} failed: ${stderr}`, fallback);
+}
+function isValidGitRef(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 255 && // Reject leading-dash refs (e.g. `--mirror`) so the value can never be
+  // parsed as a git option when interpolated into a command.
+  !value.startsWith("-") && /^[A-Za-z0-9_./-]+$/.test(value);
+}
+function resolveGitIdentity(identity) {
+  const login = (identity.login || "").trim();
+  const name = (identity.name || "").trim() || login || "Mastra Code";
+  const email = (identity.email || "").trim() || (login ? `${login}@users.noreply.github.com` : "mastra-code@users.noreply.github.com");
+  return { name, email };
+}
+async function configureGitIdentity(sandbox, workdir, identity) {
+  const { name, email } = resolveGitIdentity(identity);
+  const setName = await sh(sandbox, `git -C ${shellQuote(workdir)} config user.name ${shellQuote(name)}`);
+  if (setName.exitCode !== 0) {
+    throw new MaterializeError(`Failed to set git user.name: ${setName.stderr.trim()}`, "commit-failed");
+  }
+  const setEmail = await sh(sandbox, `git -C ${shellQuote(workdir)} config user.email ${shellQuote(email)}`);
+  if (setEmail.exitCode !== 0) {
+    throw new MaterializeError(`Failed to set git user.email: ${setEmail.stderr.trim()}`, "commit-failed");
+  }
+}
+async function withInstallToken(sandbox, workdir, repoFullName, token, fn) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repoFullName)) {
+    throw new MaterializeError(`Refusing to push: invalid repo full name '${repoFullName}'.`, "push-failed");
+  }
+  const setUrl = await sh(
+    sandbox,
+    `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(tokenUrl(repoFullName, token))}`
+  );
+  if (setUrl.exitCode !== 0) {
+    await scrubRemote(sandbox, workdir, repoFullName, false);
+    throw new MaterializeError(`Failed to set git remote: ${setUrl.stderr.trim()}`, "push-failed");
+  }
+  try {
+    return await fn();
+  } finally {
+    await scrubRemote(sandbox, workdir, repoFullName, true);
+  }
+}
+async function pushBranch(sandbox, workdir, branch, token, repoFullName) {
+  if (!isValidGitRef(branch)) {
+    throw new MaterializeError(`Refusing to push: invalid branch name '${branch}'.`, "push-failed");
+  }
+  await withInstallToken(sandbox, workdir, repoFullName, token, async () => {
+    const push = await sh(sandbox, `git -C ${shellQuote(workdir)} push -u origin ${shellQuote(branch)}`);
+    if (push.exitCode !== 0) {
+      throw classifyGitFailure(push, "push-failed");
+    }
+  });
+}
+async function commitAll(sandbox, workdir, message, identity) {
+  await configureGitIdentity(sandbox, workdir, identity);
+  const add = await sh(sandbox, `git -C ${shellQuote(workdir)} add -A`);
+  if (add.exitCode !== 0) {
+    throw new MaterializeError(`git add failed: ${add.stderr.trim() || add.stdout.trim()}`, "commit-failed");
+  }
+  const staged = await sh(sandbox, `git -C ${shellQuote(workdir)} diff --cached --quiet`);
+  if (staged.exitCode === 0) {
+    return { committed: false };
+  }
+  const commit = await sh(sandbox, `git -C ${shellQuote(workdir)} commit -m ${shellQuote(message)}`);
+  if (commit.exitCode !== 0) {
+    throw new MaterializeError(`git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`, "commit-failed");
+  }
+  return { committed: true };
+}
+var WorktreeError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "WorktreeError";
+  }
+  code;
+};
+function safeBranchDir(branch) {
+  const sanitized = branch.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/\/+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 100) || "work";
+  if (sanitized === branch) return sanitized;
+  const hash = createHash("sha256").update(branch).digest("hex").slice(0, 8);
+  return `${sanitized}-${hash}`;
+}
+function computeWorktreePath(repoWorkdir, branch) {
+  const parent = repoWorkdir.replace(/\/+$/, "").split("/").slice(0, -1).join("/") || "";
+  return `${parent}/worktrees/${safeBranchDir(branch)}`;
+}
+async function ensureWorktree(sandbox, repoWorkdir, {
+  branch,
+  baseBranch,
+  token,
+  repoFullName
+}) {
+  if (!isValidGitRef(branch)) {
+    throw new WorktreeError(`Invalid branch name '${branch}'.`, "invalid-branch");
+  }
+  if (!isValidGitRef(baseBranch)) {
+    throw new WorktreeError(`Invalid base branch name '${baseBranch}'.`, "invalid-branch");
+  }
+  const worktreePath = computeWorktreePath(repoWorkdir, branch);
+  const exists = await sh(sandbox, `test -e ${shellQuote(`${worktreePath}/.git`)}`);
+  if (exists.exitCode === 0) {
+    return { worktreePath, branch, baseBranch, reused: true };
+  }
+  const baseRef = `origin/${baseBranch}`;
+  await withInstallToken(sandbox, repoWorkdir, repoFullName, token, async () => {
+    const fetch = await sh(
+      sandbox,
+      `git -C ${shellQuote(repoWorkdir)} fetch origin ${shellQuote(`+refs/heads/${baseBranch}:refs/remotes/${baseRef}`)}`
+    );
+    if (fetch.exitCode !== 0) {
+      throw classifyGitFailure(fetch, "pull-failed");
+    }
+  });
+  const add = await sh(
+    sandbox,
+    `git -C ${shellQuote(repoWorkdir)} worktree add --no-track -B ${shellQuote(branch)} ${shellQuote(worktreePath)} ${shellQuote(baseRef)}`
+  );
+  if (add.exitCode !== 0) {
+    throw new WorktreeError(`git worktree add failed: ${add.stderr.trim() || add.stdout.trim()}`, "worktree-failed");
+  }
+  return { worktreePath, branch, baseBranch, reused: false };
+}
+async function runWorktreeSetup(sandbox, worktreePath, command) {
+  const result = await sh(sandbox, `cd ${shellQuote(worktreePath)} && { ${command}
+}`);
+  if (result.exitCode !== 0) {
+    const detail = (result.stderr.trim() || result.stdout.trim()).slice(-2e3);
+    throw new WorktreeError(`Setup command failed (exit ${result.exitCode}): ${detail}`, "setup-failed");
+  }
+}
+async function removeWorktree(sandbox, repoWorkdir, { branch, worktreePath }) {
+  if (!isValidGitRef(branch)) {
+    throw new WorktreeError(`Invalid branch name '${branch}'.`, "invalid-branch");
+  }
+  const remove = await sh(
+    sandbox,
+    `git -C ${shellQuote(repoWorkdir)} worktree remove --force ${shellQuote(worktreePath)}`
+  );
+  if (remove.exitCode !== 0) {
+    await sh(sandbox, `git -C ${shellQuote(repoWorkdir)} worktree prune`);
+    const exists = await sh(sandbox, `test -e ${shellQuote(worktreePath)}`);
+    if (exists.exitCode === 0) {
+      throw new WorktreeError(
+        `git worktree remove failed: ${remove.stderr.trim() || remove.stdout.trim()}`,
+        "worktree-failed"
+      );
+    }
+  }
+  await sh(sandbox, `git -C ${shellQuote(repoWorkdir)} branch -D ${shellQuote(branch)}`);
+}
+async function assertGhAvailable(sandbox) {
+  const version = await sh(sandbox, "gh --version");
+  if (version.exitCode !== 0) {
+    throw new MaterializeError(
+      "The GitHub CLI (gh) is not installed in the sandbox. The sandbox template must include gh to open pull requests.",
+      "gh-missing"
+    );
+  }
+}
+function parsePullRequestUrl(stdout) {
+  const match = stdout.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/);
+  return match?.[0];
+}
+async function createPullRequest(sandbox, workdir, { token, base, head, title, body }) {
+  if (!isValidGitRef(base)) {
+    throw new MaterializeError(`Refusing to open PR: invalid base branch '${base}'.`, "pr-failed");
+  }
+  if (!isValidGitRef(head)) {
+    throw new MaterializeError(`Refusing to open PR: invalid head branch '${head}'.`, "pr-failed");
+  }
+  await assertGhAvailable(sandbox);
+  const ghCommand = [
+    `GH_TOKEN=${shellQuote(token)} gh pr create`,
+    `--base ${shellQuote(base)}`,
+    `--head ${shellQuote(head)}`,
+    `--title ${shellQuote(title)}`,
+    `--body ${shellQuote(body ?? "")}`
+  ].join(" ");
+  const script = `cd ${shellQuote(workdir)} && ${ghCommand}`;
+  const result = await sh(sandbox, script);
+  if (result.exitCode !== 0) {
+    const classified = classifyGitFailure(result, "push-failed");
+    if (classified.code === "egress-blocked") {
+      throw classified;
+    }
+    throw new MaterializeError(`gh pr create failed: ${result.stderr.trim() || result.stdout.trim()}`, "pr-failed");
+  }
+  const url = parsePullRequestUrl(result.stdout);
+  if (!url) {
+    throw new MaterializeError(
+      `gh pr create succeeded but no PR URL was found in its output: ${result.stdout.trim()}`,
+      "pr-failed"
+    );
+  }
+  return { url };
+}
+export {
+  MaterializeError,
+  WorktreeError,
+  checkoutSessionBranch,
+  commitAll,
+  computeWorktreePath,
+  configureGitIdentity,
+  createPullRequest,
+  ensureProjectSandbox,
+  ensureWorktree,
+  isValidGitRef,
+  materializeRepo,
+  pushBranch,
+  removeWorktree,
+  resolveGitIdentity,
+  runWorktreeSetup,
+  safeBranchDir,
+  shellQuote,
+  teardownProjectSandbox,
+  withInstallToken
+};
+//# sourceMappingURL=sandbox.js.map