@mastra/docker 0.9.3 → 0.10.0-alpha.1

package/README.md

@@ -169,6 +169,8 @@ const sandbox = new DockerSandbox({
 });
 ```
 
+If `baseImage` runs as a non-root `USER`, set `owner` to that user (for example `owner: 'node'` or `owner: '1000:1000'`). The checkout is then copied with `COPY --chown`, so git and setup commands can write to it. Without `owner`, the checkout is owned by root.
+
 ## Documentation
 
 - [Docker Sandbox integration guide](https://mastra.ai/integrations/sandboxes/docker)

package/dist/index.cjs

@@ -1600,6 +1600,11 @@ function renderSecretRun(command, secrets) {
 	const prefix = names.length > 0 ? [`export ${exports.join(" ")}`] : [];
 	return `RUN ${[...mounts, ""].join(" ")}${[...prefix, ...toCommandList(command)].join(" && ")}`;
 }
+const OWNER_PATTERN = /^[A-Za-z0-9_.-]+(:[A-Za-z0-9_.-]+)?$/;
+/** Throws unless `owner` is a `user[:group]` or `uid[:gid]` usable in `COPY --chown`. */
+function assertValidOwner(owner) {
+	if (typeof owner !== "string" || !OWNER_PATTERN.test(owner)) throw new TypeError(`owner must be user[:group] or uid[:gid], got ${JSON.stringify(owner)}`);
+}
 function synthesizeDockerfile(definition) {
 	const lines = [];
 	let mainIndex = 0;
@@ -1621,13 +1626,14 @@ function synthesizeDockerfile(definition) {
 				lines.push(`RUN ${toCommandList(operation.args[0]).join(" && ")}`);
 				break;
 			case "runWithSecrets": {
-				const [command, { secrets, output }] = operation.args;
+				const [command, { secrets, output, owner }] = operation.args;
+				if (owner !== void 0) assertValidOwner(owner);
 				const snapshot = mainStageName(mainIndex);
 				const stage = secretStageName(index);
 				lines.push(`FROM ${snapshot} AS ${stage}`, renderSecretRun(command, secrets));
 				mainIndex += 1;
 				openMain(snapshot);
-				lines.push(`COPY --from=${stage} ${output} ${output}`);
+				lines.push(`COPY ${owner !== void 0 ? `--chown=${owner} ` : ""}--from=${stage} ${output} ${output}`);
 				break;
 			}
 			case "aptInstall":
@@ -1658,12 +1664,13 @@ function canonicalOperation(operation) {
 			args: [sortedEntries(operation.args[0])]
 		};
 		case "runWithSecrets": {
-			const [command, { secrets, output }] = operation.args;
+			const [command, { secrets, output, owner }] = operation.args;
 			return {
 				method: "runWithSecrets",
 				args: [command, {
 					secrets: [...secrets].sort(),
-					output
+					output,
+					...owner !== void 0 ? { owner } : {}
 				}]
 			};
 		}
@@ -1809,11 +1816,17 @@ var DockerTemplate = class DockerTemplate {
 		});
 		const output = validateString(options.output, "output");
 		if (!output.startsWith("/")) throw new TypeError("output must be an absolute path");
+		let owner;
+		if (options.owner !== void 0) {
+			owner = validateString(options.owner, "owner");
+			assertValidOwner(owner);
+		}
 		return this.#append({
 			method: "runWithSecrets",
 			args: [validateStringOrStrings(command, "command"), {
 				secrets,
-				output
+				output,
+				...owner !== void 0 ? { owner } : {}
 			}]
 		});
 	}
@@ -2161,6 +2174,8 @@ function isImageNotFoundError(error) {
 }
 //#endregion
 //#region ../../packages/_internals/workspace/dist/index.js
+/** Directory, relative to the template's build cwd, that holds every marker below. */
+const SETUP_MARKER_DIR = ".mastra-sandbox";
 /**
 * Setup completion marker shared by repo templates and their consumers.
 *
@@ -2170,8 +2185,29 @@ function isImageNotFoundError(error) {
 * booted from the image tell whether the setup it is about to run already
 * happened. Relative to the template's build cwd, which is also the runtime
 * working directory the repo was cloned into.
+*
+* This is the single-repository marker. Templates built from a repository
+* list write one marker per repository instead ({@link repoSetupMarkerPath}).
 */
 const SETUP_MARKER_PATH = ".mastra-sandbox/setup";
+/**
+* Marker for the workspace-level setup of a multi-repository template: the
+* commands that ran at the working directory after every repository was set
+* up. Written even when there were no such commands, so a consumer can tell
+* "ran nothing" from "never built".
+*/
+const WORKSPACE_SETUP_MARKER_PATH = ".mastra-sandbox/workspace-setup";
+/**
+* One line per repository directory whose setup failed while the build was
+* told to continue. Absent when nothing failed. Consumers check this before
+* trusting a per-repository marker: that marker means every step ran, not
+* that every step succeeded.
+*/
+const SETUP_FAILED_MARKER_PATH = ".mastra-sandbox/setup-failed";
+/** Per-repository marker of a multi-repository template, keyed by the clone directory name. */
+function repoSetupMarkerPath(repoDir) {
+	return `${SETUP_MARKER_DIR}/repos/${repoDir}`;
+}
 /** Blank entries never become build steps, so they never count toward the digest either. */
 function normalizeSetupCommands(setupCommand) {
 	return (setupCommand === void 0 ? [] : Array.isArray(setupCommand) ? setupCommand : [setupCommand]).filter((command) => command.trim() !== "");
@@ -2181,8 +2217,26 @@ function setupMarkerContent(setupCommand) {
 	return `sha256:${(0, crypto.createHash)("sha256").update(normalizeSetupCommands(setupCommand).join("\n")).digest("hex")}`;
 }
 /** Shell step that writes the marker relative to the cwd. `content` is a digest, so it is shell-safe. */
-function setupMarkerCommand(content) {
-	return `mkdir -p "$(dirname "${SETUP_MARKER_PATH}")" && printf '%s' '${content}' > "${SETUP_MARKER_PATH}"`;
+function setupMarkerCommand(content, markerPath = SETUP_MARKER_PATH) {
+	return `mkdir -p "$(dirname "${markerPath}")" && printf '%s' '${content}' > "${markerPath}"`;
+}
+/** A clone directory name is one path segment of word characters, dots and dashes, so it never needs quoting. */
+const REPO_DIR_PATTERN = /^[\w.-]+$/;
+/**
+* Shell step that runs one setup command inside a repository clone.
+*
+* Without the guard this is the plain `cd "<dir>" && <cmd>` step. With it,
+* the `cd` sits inside the parenthesized group so that the failure branch
+* runs back at the build cwd and the failure list lands at the workspace
+* level, never inside the repository.
+*/
+function guardedSetupCommand({ repoDir, command, continueOnFailure }) {
+	if (!REPO_DIR_PATTERN.test(repoDir)) throw new TypeError(`Repository directory "${repoDir}" must match ${REPO_DIR_PATTERN}.`);
+	if (!continueOnFailure) return `cd "${repoDir}" && ${command}`;
+	return `( cd "${repoDir}" && sh -c ${shellQuote$1(command)} ) || { mkdir -p "${SETUP_MARKER_DIR}" && grep -qxF -- '${repoDir}' "${SETUP_FAILED_MARKER_PATH}" 2>/dev/null || printf '%s\\n' '${repoDir}' >> "${SETUP_FAILED_MARKER_PATH}"; }`;
+}
+function shellQuote$1(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 //#endregion
 //#region src/template/repo-template.ts
@@ -2198,7 +2252,11 @@ function setupMarkerCommand(content) {
 * the template identity. A moved branch therefore yields a fresh image on the
 * next new sandbox, and an unmoved one reuses the cached image. When the head
 * cannot be resolved the resolver rejects: an unpinned clone cached under a
-* stable tag would otherwise serve stale repository state forever.
+* stable tag would otherwise serve stale repository state forever. This holds
+* for every entry of the `repos` form too, where the platform and E2B
+* templates clone such a repository unpinned instead: those use a shallow
+* clone whose tip the session fetches past, while this template clones full
+* history and pins by `checkout`, so there is no cheap unpinned mode here.
 *
 * The clone runs in a throwaway build stage; the credential is passed by value
 * to that stage only and never enters the template identity or the image.
@@ -2214,38 +2272,67 @@ function setupMarkerCommand(content) {
 * ```
 */
 const execFileAsync = (0, util.promisify)(child_process.execFile);
-/** Env var the build's clone reads the credential from (see `cloneFull`). */
+/** Env var the build's clone reads the credential from (see `cloneAndPin`). */
 const BUILD_TOKEN_ENV = "GH_TOKEN";
 const DEFAULT_BASE_IMAGE = "node:22-slim";
 const DEFAULT_WORKING_DIRECTORY = "/workspace";
 const FULL_SHA_PATTERN = /^[0-9a-f]{40}$/i;
-const SHA_PATTERN = /^[0-9a-f]{40}$/i;
 const CLONE_URL_ALLOWED_CHARS = /^[a-z0-9:/._-]+$/i;
 const CLONE_URL_HOST_PATTERN = /^[a-z0-9.-]+$/i;
 const CLONE_URL_SEGMENT_PATTERN = /^[\w.-]+$/;
 /** Refs interpolate into shell too; git ref names are already restricted, so allowlist tightly. */
 const REF_PATTERN = /^[\w./-]+$/;
 function createDockerRepoTemplate(options) {
-	if (!options.getRepositoryAccess) return void 0;
-	if (options.ref !== void 0 && !REF_PATTERN.test(options.ref)) throw new Error(`Invalid ref '${options.ref}': expected a git ref name`);
+	if (options.getRepositoryAccess && options.repos) throw new TypeError("createDockerRepoTemplate: pass either getRepositoryAccess or repos, not both");
+	if (!options.repos && (options.workspaceSetupCommand !== void 0 || options.continueOnSetupFailure !== void 0)) throw new TypeError("createDockerRepoTemplate: workspaceSetupCommand and continueOnSetupFailure require repos");
+	if (!options.getRepositoryAccess && !options.repos?.length) return void 0;
+	const entries = options.repos ?? [{
+		getRepositoryAccess: options.getRepositoryAccess,
+		ref: options.ref,
+		setupCommand: options.setupCommand
+	}];
+	for (const entry of entries) {
+		if (entry.ref !== void 0 && !REF_PATTERN.test(entry.ref)) throw new Error(`Invalid ref '${entry.ref}': expected a git ref name`);
+		assertSingleLineCommands(entry.setupCommand, "setupCommand");
+	}
+	assertSingleLineCommands(options.workspaceSetupCommand, "workspaceSetupCommand");
 	const workingDirectory = trimTrailingSlashes(options.workingDirectory ?? DEFAULT_WORKING_DIRECTORY);
 	if (!workingDirectory.startsWith("/")) throw new Error(`workingDirectory must be an absolute path, got '${options.workingDirectory}'`);
-	return (resolveOptions) => resolveRepoTemplate(options, workingDirectory, resolveOptions);
+	return (resolveOptions) => resolveRepoTemplate(options, entries, workingDirectory, resolveOptions);
 }
-async function resolveRepoTemplate(options, workingDirectory, resolveOptions = {}) {
+async function resolveRepoTemplate(options, entries, workingDirectory, resolveOptions = {}) {
 	const { abortSignal } = resolveOptions;
+	const isList = options.repos !== void 0;
 	throwIfAborted(abortSignal, "resolve Docker repository template");
-	let access;
-	try {
-		access = await options.getRepositoryAccess(resolveOptions);
-	} catch (error) {
-		throw normalizeAbortError(error, "resolve Docker repository template");
+	const repos = [];
+	const seenDirs = /* @__PURE__ */ new Map();
+	for (const [index, entry] of entries.entries()) {
+		let access;
+		try {
+			access = await entry.getRepositoryAccess(resolveOptions);
+		} catch (error) {
+			throw normalizeAbortError(error, "resolve Docker repository template");
+		}
+		throwIfAborted(abortSignal, "resolve Docker repository template");
+		const cloneUrl = access?.cloneUrl;
+		if (!cloneUrl) throw new Error(`Repo template has no clone URL: repository access returned none${isList ? ` (repos[${index}])` : ""}.`);
+		assertCloneUrl(cloneUrl);
+		const repoDir = repoDirName(cloneUrl);
+		const previous = seenDirs.get(repoDir);
+		if (previous) throw new Error(`createDockerRepoTemplate: repositories ${previous} and ${cloneUrl} would both clone into "${repoDir}"`);
+		seenDirs.set(repoDir, cloneUrl);
+		const token = access?.authorization?.token;
+		const sha = await resolveHead(cloneUrl, entry.ref, token, abortSignal);
+		throwIfAborted(abortSignal, "resolve Docker repository template");
+		if (!sha) throw new Error(`Could not resolve ${entry.ref ?? "HEAD"} of ${cloneUrl} with git ls-remote; check the ref, the credential and network access`);
+		repos.push({
+			cloneUrl,
+			sha,
+			token,
+			tokenEnv: token ? isList ? `${BUILD_TOKEN_ENV}_${index}` : BUILD_TOKEN_ENV : void 0,
+			setupCommand: entry.setupCommand
+		});
 	}
-	throwIfAborted(abortSignal, "resolve Docker repository template");
-	const cloneUrl = access?.cloneUrl;
-	if (!cloneUrl) throw new Error("Repo template has no clone URL: repository access returned none.");
-	assertCloneUrl(cloneUrl);
-	const token = access?.authorization?.token;
 	let buildEnv;
 	try {
 		buildEnv = typeof options.buildEnv === "function" ? await options.buildEnv(resolveOptions) : options.buildEnv;
@@ -2253,18 +2340,28 @@ async function resolveRepoTemplate(options, workingDirectory, resolveOptions = {
 		throw normalizeAbortError(error, "resolve Docker repository template");
 	}
 	throwIfAborted(abortSignal, "resolve Docker repository template");
-	const sha = await resolveHead(cloneUrl, options.ref, token, abortSignal);
-	throwIfAborted(abortSignal, "resolve Docker repository template");
-	if (!sha) throw new Error(`Could not resolve ${options.ref ?? "HEAD"} of ${cloneUrl} with git ls-remote; check the ref, the credential and network access`);
-	return buildRepoTemplate({
-		cloneUrl,
-		sha,
-		token,
+	const shared = {
 		buildEnv,
-		setupCommand: options.setupCommand,
 		workingDirectory,
 		baseImage: options.baseImage,
+		owner: options.owner,
 		dockerOptions: options.dockerOptions
+	};
+	if (!isList) {
+		const [repo] = repos;
+		return buildRepoTemplate({
+			...shared,
+			cloneUrl: repo.cloneUrl,
+			sha: repo.sha,
+			token: repo.token,
+			setupCommand: repo.setupCommand
+		});
+	}
+	return buildMultiRepoTemplate({
+		...shared,
+		repos,
+		workspaceSetupCommand: options.workspaceSetupCommand,
+		continueOnSetupFailure: options.continueOnSetupFailure ?? false
 	});
 }
 /**
@@ -2283,14 +2380,15 @@ function buildRepoTemplate(inputs) {
 	if (inputs.baseImage === void 0) template = template.aptInstall(["git", "ca-certificates"]);
 	if (buildEnv && Object.keys(buildEnv).length > 0) template = template.setEnvs(buildEnv);
 	const tokenEnv = token ? BUILD_TOKEN_ENV : void 0;
-	const clone = [cloneFull({
+	template = template.runWithSecrets(cloneAndPin({
 		cloneUrl,
 		destination,
-		tokenEnv
-	}), `git -C ${shellQuote(destination)} checkout --detach ${shellQuote(sha)}`];
-	template = template.runWithSecrets(clone, {
+		tokenEnv,
+		sha
+	}), {
 		secrets: tokenEnv ? [tokenEnv] : [],
-		output: destination
+		output: destination,
+		...inputs.owner !== void 0 ? { owner: inputs.owner } : {}
 	}).setWorkdir(destination);
 	const setupCommands = normalizeSetupCommands(inputs.setupCommand);
 	for (const command of setupCommands) template = template.runCmd(command);
@@ -2298,6 +2396,60 @@ function buildRepoTemplate(inputs) {
 	return template;
 }
 /**
+* List-form assembly: the working directory is the cwd, every repository is
+* laid out under it (public first) around its own pin, then the workspace
+* steps and marker. Exported for tests.
+* @internal
+*/
+function buildMultiRepoTemplate(inputs) {
+	const { repos, buildEnv, continueOnSetupFailure } = inputs;
+	const workingDirectory = trimTrailingSlashes(inputs.workingDirectory);
+	const secretValues = {};
+	for (const repo of repos) if (repo.tokenEnv && repo.token) secretValues[repo.tokenEnv] = repo.token;
+	let template = new DockerTemplate({
+		baseImage: inputs.baseImage ?? DEFAULT_BASE_IMAGE,
+		dockerOptions: inputs.dockerOptions,
+		...Object.keys(secretValues).length > 0 ? { secrets: secretValues } : {}
+	});
+	if (inputs.baseImage === void 0) template = template.aptInstall(["git", "ca-certificates"]);
+	if (buildEnv && Object.keys(buildEnv).length > 0) template = template.setEnvs(buildEnv);
+	template = template.setWorkdir(workingDirectory);
+	const ordered = [...repos.filter((repo) => !repo.token), ...repos.filter((repo) => repo.token)];
+	for (const repo of ordered) {
+		const repoDir = repoDirName(repo.cloneUrl);
+		const destination = `${workingDirectory}/${repoDir}`;
+		const secrets = repo.tokenEnv ? [repo.tokenEnv] : [];
+		const setupCommands = normalizeSetupCommands(repo.setupCommand);
+		template = template.runWithSecrets(cloneAndPin({
+			cloneUrl: repo.cloneUrl,
+			destination,
+			tokenEnv: repo.tokenEnv,
+			sha: repo.sha
+		}), {
+			secrets,
+			output: destination,
+			...inputs.owner !== void 0 ? { owner: inputs.owner } : {}
+		});
+		for (const command of setupCommands) template = template.runCmd(guardedSetupCommand({
+			repoDir,
+			command,
+			continueOnFailure: continueOnSetupFailure
+		}));
+		template = template.runCmd(setupMarkerCommand(setupMarkerContent(setupCommands), repoSetupMarkerPath(repoDir)));
+	}
+	const workspaceCommands = normalizeSetupCommands(inputs.workspaceSetupCommand);
+	for (const command of workspaceCommands) template = template.runCmd(command);
+	template = template.runCmd(setupMarkerCommand(setupMarkerContent(workspaceCommands), WORKSPACE_SETUP_MARKER_PATH));
+	return template;
+}
+/**
+* A Dockerfile `RUN` only spans lines through `\\` continuation, which the
+* parser folds away; a bare newline would start a new instruction.
+*/
+function assertSingleLineCommands(commands, option) {
+	for (const command of normalizeSetupCommands(commands)) if (/(?<!\\)\n|\r/.test(command)) throw new Error(`createDockerRepoTemplate: ${option} entries cannot contain a bare newline; end the line with \\ or pass separate commands`);
+}
+/**
 * Resolve `ref` (or the default branch) to a commit sha with `git ls-remote`
 * on the host, without cloning. A full sha is returned as is. Any failure
 * yields undefined; the caller decides how to surface it.
@@ -2328,14 +2480,14 @@ async function resolveHead(cloneUrl, ref, token, abortSignal) {
 		});
 		const lines = stdout.split("\n").filter(Boolean).map((line) => line.split("	"));
 		const sha = (lines.find(([, name]) => name?.endsWith("^{}")) ?? lines[0])?.[0]?.trim();
-		return sha && SHA_PATTERN.test(sha) ? sha.toLowerCase() : void 0;
+		return sha && FULL_SHA_PATTERN.test(sha) ? sha.toLowerCase() : void 0;
 	} catch (error) {
 		if (abortSignal?.aborted) throw normalizeAbortError(error, "resolve Docker repository template");
 		return;
 	}
 }
-function cloneFull({ cloneUrl, destination, tokenEnv }) {
-	return `git ${tokenEnv ? `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${tokenEnv}" | base64 -w0)" ` : ""}clone ${shellQuote(cloneUrl)} ${shellQuote(destination)}`;
+function cloneAndPin({ cloneUrl, destination, tokenEnv, sha }) {
+	return [`git ${tokenEnv ? `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${tokenEnv}" | base64 -w0)" ` : ""}clone ${shellQuote(cloneUrl)} ${shellQuote(destination)}`, `git -C ${shellQuote(destination)} checkout --detach ${shellQuote(sha)}`];
 }
 function assertCloneUrl(cloneUrl) {
 	if (cloneUrl.length > 2048 || !CLONE_URL_ALLOWED_CHARS.test(cloneUrl)) throw new Error(`Invalid cloneUrl '${cloneUrl}': expected an https URL with a plain host and path`);