@mastra/factory 0.21.1-alpha.3 → 0.22.0-alpha.4

package/dist/environment/build-workflow.js

@@ -0,0 +1,149 @@
+import { ENVIRONMENT_BUILD_TRIGGERS, environmentBuildContext, errorReason, redactCredentials, runEnvironmentBuild } from "./build.js";
+import { resolveProjectEnvironment } from "../workspace.js";
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+//#region src/environment/build-workflow.ts
+/**
+* The `factory-environment-build` workflow: step one decides and starts a
+* build (`runEnvironmentBuild`), step two polls the provider until the build
+* settles and pins the active template on the project row. Registered by
+* `MastraFactory.prepare()` only when the sandbox has `builds`, and driven by
+* the Build now route, the per-project cron schedule and the GitHub push
+* hand-off. Saving settings never starts it.
+*/
+const ENVIRONMENT_BUILD_WORKFLOW_ID = "factory-environment-build";
+const DEFAULT_BUILD_POLL_MS = 15e3;
+const MAX_BUILD_WAIT_MS = 30 * 6e4;
+const environmentBuildInputSchema = z.object({
+	projectId: z.string().min(1),
+	trigger: z.enum(ENVIRONMENT_BUILD_TRIGGERS)
+});
+const startOutputSchema = z.object({
+	projectId: z.string(),
+	outcome: z.enum([
+		"started",
+		"skipped",
+		"unavailable",
+		"failed"
+	]),
+	buildId: z.string().optional(),
+	templateId: z.string().optional(),
+	reason: z.string().optional(),
+	heads: z.record(z.string(), z.string()).optional()
+});
+const environmentBuildOutputSchema = z.object({
+	outcome: z.enum([
+		"started",
+		"skipped",
+		"unavailable",
+		"failed"
+	]),
+	buildId: z.string().optional(),
+	templateId: z.string().optional(),
+	reason: z.string().optional(),
+	/** Where the started build ended: `ready`, `failed`, or `unknown` when the provider lost it or the wait ran out. */
+	status: z.enum([
+		"ready",
+		"failed",
+		"unknown"
+	]).optional()
+});
+function createEnvironmentBuildWorkflow(deps, options = {}) {
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const pollMs = options.pollMs ?? 15e3;
+	const maxWaitMs = options.maxWaitMs ?? 18e5;
+	const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+	const start = createStep({
+		id: "start",
+		inputSchema: environmentBuildInputSchema,
+		outputSchema: startOutputSchema,
+		execute: async ({ inputData, runId }) => {
+			const outcome = await runEnvironmentBuild(deps, inputData);
+			options.onStart?.(runId, outcome);
+			return {
+				projectId: inputData.projectId,
+				...outcome
+			};
+		}
+	});
+	const awaitBuild = createStep({
+		id: "await-build",
+		inputSchema: startOutputSchema,
+		outputSchema: environmentBuildOutputSchema,
+		execute: async ({ inputData }) => {
+			const { projectId, heads, ...result } = inputData;
+			if (result.outcome !== "started" || !result.buildId || !heads) return result;
+			const builds = deps.sandbox?.builds;
+			const project = await deps.projects.getById({ id: projectId });
+			if (!builds || !deps.sourceControl || !project) return {
+				...result,
+				status: "unknown"
+			};
+			const environment = await resolveProjectEnvironment(deps.sourceControl.storage, project);
+			const ctx = environmentBuildContext(project, environment, heads, deps.sourceControl.versionControl);
+			const startedAt = now().getTime();
+			try {
+				for (;;) {
+					const build = await builds.get(ctx, environment.settings, result.buildId);
+					if (build.status === "ready") {
+						const templateId = build.templateId ?? result.templateId ?? result.buildId;
+						const pinned = await deps.projects.pinActiveTemplate({
+							id: project.id,
+							buildId: result.buildId,
+							templateId,
+							heads
+						});
+						deps.logger?.info(pinned ? "environment build ready" : "environment build ready but superseded", {
+							factoryProjectId: project.id,
+							templateId
+						});
+						return {
+							...result,
+							templateId,
+							status: "ready"
+						};
+					}
+					if (build.status === "failed" || build.status === "unknown") {
+						deps.logger?.info("environment build did not complete", {
+							factoryProjectId: project.id,
+							buildId: result.buildId,
+							status: build.status,
+							...build.error ? { reason: redactCredentials(build.error) } : {}
+						});
+						return {
+							...result,
+							status: build.status,
+							...build.error ? { reason: redactCredentials(build.error) } : {}
+						};
+					}
+					if (now().getTime() - startedAt >= maxWaitMs) return {
+						...result,
+						status: "unknown",
+						reason: "Build wait timed out."
+					};
+					await sleep(pollMs);
+				}
+			} catch (error) {
+				const reason = errorReason(error);
+				deps.logger?.info("environment build status read failed", {
+					factoryProjectId: project.id,
+					reason
+				});
+				return {
+					...result,
+					status: "unknown",
+					reason
+				};
+			}
+		}
+	});
+	return createWorkflow({
+		id: ENVIRONMENT_BUILD_WORKFLOW_ID,
+		inputSchema: environmentBuildInputSchema,
+		outputSchema: environmentBuildOutputSchema
+	}).then(start).then(awaitBuild).commit();
+}
+//#endregion
+export { DEFAULT_BUILD_POLL_MS, ENVIRONMENT_BUILD_WORKFLOW_ID, MAX_BUILD_WAIT_MS, createEnvironmentBuildWorkflow, environmentBuildInputSchema, environmentBuildOutputSchema };
+
+//# sourceMappingURL=build-workflow.js.map

package/dist/environment/build-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-workflow.js","names":[],"sources":["../../src/environment/build-workflow.ts"],"sourcesContent":["/**\n * The `factory-environment-build` workflow: step one decides and starts a\n * build (`runEnvironmentBuild`), step two polls the provider until the build\n * settles and pins the active template on the project row. Registered by\n * `MastraFactory.prepare()` only when the sandbox has `builds`, and driven by\n * the Build now route, the per-project cron schedule and the GitHub push\n * hand-off. Saving settings never starts it.\n */\n\nimport { createStep, createWorkflow } from '@mastra/core/workflows';\nimport { z } from 'zod';\nimport { resolveProjectEnvironment } from '../workspace.js';\nimport {\n  ENVIRONMENT_BUILD_TRIGGERS,\n  environmentBuildContext,\n  errorReason,\n  redactCredentials,\n  runEnvironmentBuild,\n} from './build.js';\nimport type { EnvironmentBuildDeps, EnvironmentBuildOutcome } from './build.js';\n\nexport const ENVIRONMENT_BUILD_WORKFLOW_ID = 'factory-environment-build';\nexport const DEFAULT_BUILD_POLL_MS = 15_000;\nexport const MAX_BUILD_WAIT_MS = 30 * 60_000;\n\nexport const environmentBuildInputSchema = z.object({\n  projectId: z.string().min(1),\n  trigger: z.enum(ENVIRONMENT_BUILD_TRIGGERS),\n});\n\nconst startOutputSchema = z.object({\n  projectId: z.string(),\n  outcome: z.enum(['started', 'skipped', 'unavailable', 'failed']),\n  buildId: z.string().optional(),\n  templateId: z.string().optional(),\n  reason: z.string().optional(),\n  heads: z.record(z.string(), z.string()).optional(),\n});\n\nexport const environmentBuildOutputSchema = z.object({\n  outcome: z.enum(['started', 'skipped', 'unavailable', 'failed']),\n  buildId: z.string().optional(),\n  templateId: z.string().optional(),\n  reason: z.string().optional(),\n  /** Where the started build ended: `ready`, `failed`, or `unknown` when the provider lost it or the wait ran out. */\n  status: z.enum(['ready', 'failed', 'unknown']).optional(),\n});\n\nexport type EnvironmentBuildWorkflowResult = z.infer<typeof environmentBuildOutputSchema>;\n\nexport interface EnvironmentBuildWorkflowOptions {\n  sleep?: (ms: number) => Promise<void>;\n  pollMs?: number;\n  maxWaitMs?: number;\n  /** Called with the first step's answer so a caller can return it without waiting for the poll. */\n  onStart?: (runId: string, outcome: EnvironmentBuildOutcome) => void;\n}\n\nexport function createEnvironmentBuildWorkflow(\n  deps: EnvironmentBuildDeps,\n  options: EnvironmentBuildWorkflowOptions = {},\n) {\n  const sleep = options.sleep ?? (ms => new Promise<void>(resolve => setTimeout(resolve, ms)));\n  const pollMs = options.pollMs ?? DEFAULT_BUILD_POLL_MS;\n  const maxWaitMs = options.maxWaitMs ?? MAX_BUILD_WAIT_MS;\n  const now = deps.now ?? (() => new Date());\n\n  const start = createStep({\n    id: 'start',\n    inputSchema: environmentBuildInputSchema,\n    outputSchema: startOutputSchema,\n    execute: async ({ inputData, runId }) => {\n      const outcome = await runEnvironmentBuild(deps, inputData);\n      options.onStart?.(runId, outcome);\n      return { projectId: inputData.projectId, ...outcome };\n    },\n  });\n\n  const awaitBuild = createStep({\n    id: 'await-build',\n    inputSchema: startOutputSchema,\n    outputSchema: environmentBuildOutputSchema,\n    execute: async ({ inputData }): Promise<EnvironmentBuildWorkflowResult> => {\n      const { projectId, heads, ...result } = inputData;\n      if (result.outcome !== 'started' || !result.buildId || !heads) return result;\n      const builds = deps.sandbox?.builds;\n      const project = await deps.projects.getById({ id: projectId });\n      if (!builds || !deps.sourceControl || !project) return { ...result, status: 'unknown' };\n      const environment = await resolveProjectEnvironment(deps.sourceControl.storage, project);\n      const ctx = environmentBuildContext(project, environment, heads, deps.sourceControl.versionControl);\n      const startedAt = now().getTime();\n      try {\n        for (;;) {\n          const build = await builds.get(ctx, environment.settings, result.buildId);\n          if (build.status === 'ready') {\n            const templateId = build.templateId ?? result.templateId ?? result.buildId;\n            // A newer run may have replaced `last_build_id` while this one\n            // polled; the pin is skipped then so the stale image never wins.\n            const pinned = await deps.projects.pinActiveTemplate({\n              id: project.id,\n              buildId: result.buildId,\n              templateId,\n              heads,\n            });\n            deps.logger?.info(pinned ? 'environment build ready' : 'environment build ready but superseded', {\n              factoryProjectId: project.id,\n              templateId,\n            });\n            return { ...result, templateId, status: 'ready' };\n          }\n          if (build.status === 'failed' || build.status === 'unknown') {\n            deps.logger?.info('environment build did not complete', {\n              factoryProjectId: project.id,\n              buildId: result.buildId,\n              status: build.status,\n              ...(build.error ? { reason: redactCredentials(build.error) } : {}),\n            });\n            return {\n              ...result,\n              status: build.status,\n              ...(build.error ? { reason: redactCredentials(build.error) } : {}),\n            };\n          }\n          if (now().getTime() - startedAt >= maxWaitMs) {\n            return { ...result, status: 'unknown', reason: 'Build wait timed out.' };\n          }\n          await sleep(pollMs);\n        }\n      } catch (error) {\n        const reason = errorReason(error);\n        deps.logger?.info('environment build status read failed', { factoryProjectId: project.id, reason });\n        return { ...result, status: 'unknown', reason };\n      }\n    },\n  });\n\n  return createWorkflow({\n    id: ENVIRONMENT_BUILD_WORKFLOW_ID,\n    inputSchema: environmentBuildInputSchema,\n    outputSchema: environmentBuildOutputSchema,\n  })\n    .then(start)\n    .then(awaitBuild)\n    .commit();\n}\n"],"mappings":"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"}

package/dist/environment/build.d.ts

@@ -0,0 +1,111 @@
+/**
+ * One proactive environment build: decide whether a trigger should build,
+ * hand the sandbox's `builds` capability a context identical to a session's,
+ * and record the started build on the project row. Polling the build to its
+ * end and pinning the active template is the workflow's second step
+ * (`build-workflow.ts`), so a request that only needs the start answer never
+ * waits on the provider.
+ */
+import type { FactorySandbox, FactorySandboxContext } from '@mastra/core/workspace';
+import type { VersionControl } from '../capabilities/version-control.js';
+import type { FactoryProject, FactoryProjectsStorage } from '../storage/domains/projects/base.js';
+import type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js';
+import type { SessionEnvironment } from '../workspace.js';
+import type { EnvironmentHeads } from './heads.js';
+export declare const ENVIRONMENT_BUILD_TRIGGERS: readonly ["manual", "schedule", "push"];
+export type EnvironmentBuildTrigger = (typeof ENVIRONMENT_BUILD_TRIGGERS)[number];
+export interface EnvironmentBuildSourceControl {
+    storage: Pick<SourceControlStorageHandle, 'projectRepositories' | 'repositories'>;
+    versionControl: Pick<VersionControl, 'getRepositoryAccess'>;
+}
+export interface EnvironmentBuildDeps {
+    /** The factory's normalized sandbox; builds are unavailable without its `builds`. */
+    sandbox: FactorySandbox | undefined;
+    projects: Pick<FactoryProjectsStorage, 'getById' | 'claimBuildAttempt' | 'claimBuildStart' | 'renewBuildStart' | 'releaseBuildStart' | 'pinActiveTemplate'>;
+    /** Absent when the factory has no source-control integration to resolve heads with. */
+    sourceControl: EnvironmentBuildSourceControl | undefined;
+    logger?: {
+        info: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    now?: () => Date;
+    /** How often a run renews its build-start lease; a third of `BUILD_START_LEASE_MS` by default. */
+    leaseRenewMs?: number;
+    /** Waits between tries at recording a started build. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface EnvironmentBuildOutcome {
+    outcome: 'started' | 'skipped' | 'unavailable' | 'failed';
+    buildId?: string;
+    templateId?: string;
+    /** Why nothing started: `debounced`, `starting` (another run is starting a build), `in_progress`, `unchanged`, `unresolved` (a lapsed run may have started a build the provider cannot list), `no_environment`, `no_builds`, `no_source_control`; why a run failed: `not_recorded`, `superseded`, or an error. */
+    reason?: string;
+    /** The heads the started build pins; the workflow stores them once the build is ready. */
+    heads?: EnvironmentHeads;
+}
+/** The synthetic session id a project's build runs under; never a session. */
+export declare function environmentBuildSessionId(projectId: string): string;
+/**
+ * A build or setup error may echo a clone URL or a token; strip URL userinfo
+ * and GitHub token shapes before the message is stored, logged or shown.
+ */
+export declare function redactCredentials(message: string): string;
+/** An error's message with credentials redacted, safe to log, store or return. */
+export declare function errorReason(error: unknown): string;
+/**
+ * The context an environment build (or a read of its status) hands the
+ * provider: the same list form a session boots with, under the build's own
+ * session id, with heads served from `heads` so the provider never resolves
+ * them itself.
+ */
+export declare function environmentBuildContext(project: Pick<FactoryProject, 'id' | 'orgId'>, environment: SessionEnvironment, heads: EnvironmentHeads, versionControl: Pick<VersionControl, 'getRepositoryAccess'>): FactorySandboxContext;
+/**
+ * Fingerprint of everything a build bakes into the template besides the
+ * repository heads: provider settings, the repositories and their order,
+ * their setup commands, the workspace setup command and the working
+ * directory. A schedule or push skips a ready build only while this matches.
+ */
+export declare function environmentBuildInputs(environment: SessionEnvironment): string;
+/**
+ * The current head of every environment repository's template branch, keyed
+ * by slug. The template clones the repository default branch (a link's own
+ * branch is the session's base, checked out after boot), so that is the
+ * branch a build pins; sessions let the provider resolve the same head.
+ */
+export declare function resolveEnvironmentHeads(sourceControl: EnvironmentBuildSourceControl, project: Pick<FactoryProject, 'orgId'>, environment: SessionEnvironment): Promise<EnvironmentHeads>;
+/**
+ * How long a build-start lease lasts without renewal. The run holding it
+ * renews it every third of that while it works, so a lease lapses only when
+ * its run died or stalled.
+ */
+export declare const BUILD_START_LEASE_MS: number;
+/**
+ * Start a build for `projectId` when `trigger` calls for one. Every trigger
+ * takes the project's build-start lease before reading build state and renews
+ * it until the started build is recorded, so overlapping manual, scheduled and
+ * push runs never both start a build, however long the provider takes; a run
+ * that finds the lease held skips as `starting`. Every trigger skips while the
+ * last build is still running; `schedule` and `push` also skip when the last
+ * build is ready and neither a head nor any other template input changed;
+ * `manual` otherwise always builds. A `push` that would build then takes the
+ * leading-edge debounce claim, so only a push that starts a build opens the
+ * window. Saving settings never builds.
+ *
+ * Taking over a lapsed lease leaves the start uncertain: the lapsed run may
+ * have started a build it never recorded. The mark persists until resolved.
+ * While it stands, a provider that lists builds is asked for a running one
+ * (and every trigger skips as `in_progress` on it); with a provider that
+ * cannot list, every trigger skips as `unresolved`.
+ *
+ * The result is written as the lease is released, and only while this run
+ * still holds it. A failed `builds.start` clears the last build id, so a later
+ * `schedule` or `push` cannot mistake the previous ready build for the current
+ * template; any other error keeps a running build's id. A started build whose
+ * recording keeps failing yields `failed` (`not_recorded`) with the lease left
+ * to lapse rather than released, and a run that lost its lease while the
+ * provider started yields `failed` (`superseded`); neither is polled or pinned.
+ */
+export declare function runEnvironmentBuild(deps: EnvironmentBuildDeps, input: {
+    projectId: string;
+    trigger: EnvironmentBuildTrigger;
+}): Promise<EnvironmentBuildOutcome>;
+//# sourceMappingURL=build.d.ts.map

package/dist/environment/build.d.ts.map

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

package/dist/environment/build.js

@@ -0,0 +1,344 @@
+import { headsChanged, recordedHeadResolver, resolveCurrentHeads } from "./heads.js";
+import { environmentSandboxContext, resolveProjectEnvironment } from "../workspace.js";
+import { createHash, randomUUID } from "crypto";
+//#region src/environment/build.ts
+/**
+* One proactive environment build: decide whether a trigger should build,
+* hand the sandbox's `builds` capability a context identical to a session's,
+* and record the started build on the project row. Polling the build to its
+* end and pinning the active template is the workflow's second step
+* (`build-workflow.ts`), so a request that only needs the start answer never
+* waits on the provider.
+*/
+const ENVIRONMENT_BUILD_TRIGGERS = [
+	"manual",
+	"schedule",
+	"push"
+];
+/** The synthetic session id a project's build runs under; never a session. */
+function environmentBuildSessionId(projectId) {
+	return `environment-build:${projectId}`;
+}
+/**
+* A build or setup error may echo a clone URL or a token; strip URL userinfo
+* and GitHub token shapes before the message is stored, logged or shown.
+*/
+function redactCredentials(message) {
+	return message.replace(/\/\/[^/\s@]+@/g, "//***@").replace(/\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]+/g, "***");
+}
+/** An error's message with credentials redacted, safe to log, store or return. */
+function errorReason(error) {
+	return redactCredentials(error instanceof Error ? error.message : String(error));
+}
+/**
+* The context an environment build (or a read of its status) hands the
+* provider: the same list form a session boots with, under the build's own
+* session id, with heads served from `heads` so the provider never resolves
+* them itself.
+*/
+function environmentBuildContext(project, environment, heads, versionControl) {
+	return {
+		sessionId: environmentBuildSessionId(project.id),
+		...environmentSandboxContext(environment, {
+			orgId: project.orgId,
+			getRepositoryAccess: (args) => versionControl.getRepositoryAccess(args),
+			resolveHead: recordedHeadResolver(heads)
+		})
+	};
+}
+/**
+* Fingerprint of everything a build bakes into the template besides the
+* repository heads: provider settings, the repositories and their order,
+* their setup commands, the workspace setup command and the working
+* directory. A schedule or push skips a ready build only while this matches.
+*/
+function environmentBuildInputs(environment) {
+	const inputs = {
+		settings: environment.settings,
+		workspaceSetupCommand: environment.workspaceSetupCommand ?? null,
+		workingDirectory: environment.workingDirectory ?? null,
+		repos: environment.repos.map((repo) => ({
+			repositoryId: repo.repositoryId,
+			templateBranch: repo.templateBranch,
+			setupCommand: repo.setupCommand ?? null
+		}))
+	};
+	return createHash("sha256").update(JSON.stringify(inputs)).digest("hex");
+}
+/**
+* The current head of every environment repository's template branch, keyed
+* by slug. The template clones the repository default branch (a link's own
+* branch is the session's base, checked out after boot), so that is the
+* branch a build pins; sessions let the provider resolve the same head.
+*/
+async function resolveEnvironmentHeads(sourceControl, project, environment) {
+	return resolveCurrentHeads(sourceControl, {
+		orgId: project.orgId,
+		repositories: environment.repos.map((repo) => ({
+			id: repo.repositoryId,
+			slug: repo.slug,
+			branch: repo.templateBranch
+		}))
+	});
+}
+/**
+* How long a build-start lease lasts without renewal. The run holding it
+* renews it every third of that while it works, so a lease lapses only when
+* its run died or stalled.
+*/
+const BUILD_START_LEASE_MS = 10 * 6e4;
+/** Tries at recording a started build before the run leaves its lease to lapse. */
+const RECORD_ATTEMPTS = 5;
+/**
+* Start a build for `projectId` when `trigger` calls for one. Every trigger
+* takes the project's build-start lease before reading build state and renews
+* it until the started build is recorded, so overlapping manual, scheduled and
+* push runs never both start a build, however long the provider takes; a run
+* that finds the lease held skips as `starting`. Every trigger skips while the
+* last build is still running; `schedule` and `push` also skip when the last
+* build is ready and neither a head nor any other template input changed;
+* `manual` otherwise always builds. A `push` that would build then takes the
+* leading-edge debounce claim, so only a push that starts a build opens the
+* window. Saving settings never builds.
+*
+* Taking over a lapsed lease leaves the start uncertain: the lapsed run may
+* have started a build it never recorded. The mark persists until resolved.
+* While it stands, a provider that lists builds is asked for a running one
+* (and every trigger skips as `in_progress` on it); with a provider that
+* cannot list, every trigger skips as `unresolved`.
+*
+* The result is written as the lease is released, and only while this run
+* still holds it. A failed `builds.start` clears the last build id, so a later
+* `schedule` or `push` cannot mistake the previous ready build for the current
+* template; any other error keeps a running build's id. A started build whose
+* recording keeps failing yields `failed` (`not_recorded`) with the lease left
+* to lapse rather than released, and a run that lost its lease while the
+* provider started yields `failed` (`superseded`); neither is polled or pinned.
+*/
+async function runEnvironmentBuild(deps, input) {
+	const builds = deps.sandbox?.builds;
+	if (!builds) return {
+		outcome: "unavailable",
+		reason: "no_builds"
+	};
+	if (!deps.sourceControl) return {
+		outcome: "unavailable",
+		reason: "no_source_control"
+	};
+	const sourceControl = deps.sourceControl;
+	const initial = await deps.projects.getById({ id: input.projectId });
+	if (!initial) return {
+		outcome: "skipped",
+		reason: "no_environment"
+	};
+	const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+	const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const pushDebounced = (project, at) => project.lastPushBuildAt !== null && at.getTime() - project.lastPushBuildAt.getTime() < project.buildPushDebounceMinutes * 6e4;
+	if (input.trigger === "push" && pushDebounced(initial, now())) return {
+		outcome: "skipped",
+		reason: "debounced"
+	};
+	const token = randomUUID();
+	const lease = {
+		id: initial.id,
+		token,
+		leaseMs: BUILD_START_LEASE_MS
+	};
+	const claim = await deps.projects.claimBuildStart({
+		...lease,
+		now: now()
+	});
+	if (!claim.claimed) return {
+		outcome: "skipped",
+		reason: "starting"
+	};
+	let held = true;
+	const renewal = setInterval(() => {
+		deps.projects.renewBuildStart({
+			...lease,
+			now: now()
+		}).then((renewed) => {
+			if (!renewed) held = false;
+		}, () => {});
+	}, deps.leaseRenewMs ?? 6e5 / 3);
+	renewal.unref?.();
+	const attempted = { lastBuildAttemptedAt: now() };
+	let resolved = false;
+	const release = (changes = {}) => deps.projects.releaseBuildStart({
+		id: initial.id,
+		token,
+		changes,
+		resolved,
+		now: now()
+	});
+	const failed = async (error, changes) => {
+		const reason = errorReason(error);
+		await release(changes);
+		deps.logger?.info("environment build failed", {
+			factoryProjectId: initial.id,
+			trigger: input.trigger,
+			reason
+		});
+		return {
+			outcome: "failed",
+			reason
+		};
+	};
+	try {
+		let project;
+		let environment;
+		let heads;
+		let ctx;
+		let buildInputs;
+		try {
+			project = await deps.projects.getById({ id: initial.id }) ?? initial;
+			environment = await resolveProjectEnvironment(sourceControl.storage, project);
+			if (environment.repos.length === 0) {
+				await release();
+				return {
+					outcome: "skipped",
+					reason: "no_environment"
+				};
+			}
+			heads = await resolveEnvironmentHeads(sourceControl, project, environment);
+			ctx = environmentBuildContext(project, environment, heads, sourceControl.versionControl);
+			buildInputs = environmentBuildInputs(environment);
+			if (claim.uncertain) if (builds.list) {
+				const running = (await builds.list(ctx, environment.settings)).find((build) => build.status === "pending" || build.status === "building");
+				if (running) {
+					await release();
+					return {
+						outcome: "skipped",
+						reason: "in_progress",
+						buildId: running.buildId
+					};
+				}
+				resolved = true;
+			} else {
+				await release();
+				return {
+					outcome: "skipped",
+					reason: "unresolved"
+				};
+			}
+			if (project.lastBuildId) {
+				const last = await builds.get(ctx, environment.settings, project.lastBuildId);
+				if (last.status === "pending" || last.status === "building") {
+					await release();
+					return {
+						outcome: "skipped",
+						reason: "in_progress",
+						buildId: project.lastBuildId
+					};
+				}
+				let pinnedHeads = project.activeTemplateHeads;
+				const lastTemplateId = last.templateId ?? project.lastBuildId;
+				if (last.status === "ready" && project.lastBuildHeads && project.activeTemplateId !== lastTemplateId) {
+					if (await deps.projects.pinActiveTemplate({
+						id: project.id,
+						buildId: project.lastBuildId,
+						templateId: lastTemplateId,
+						heads: project.lastBuildHeads
+					})) pinnedHeads = project.lastBuildHeads;
+				}
+				if ((input.trigger === "schedule" || input.trigger === "push") && last.status === "ready" && !headsChanged(pinnedHeads, heads) && project.lastBuildInputs === buildInputs) {
+					await release();
+					return {
+						outcome: "skipped",
+						reason: "unchanged"
+					};
+				}
+			}
+		} catch (error) {
+			return await failed(error, attempted);
+		}
+		if (!held) return {
+			outcome: "skipped",
+			reason: "starting"
+		};
+		if (input.trigger === "push") {
+			let claimed;
+			try {
+				claimed = await deps.projects.claimBuildAttempt({
+					id: project.id,
+					debounceMinutes: project.buildPushDebounceMinutes,
+					now: now()
+				});
+			} catch (error) {
+				return await failed(error, {});
+			}
+			if (!claimed) {
+				await release();
+				return {
+					outcome: "skipped",
+					reason: "debounced"
+				};
+			}
+		}
+		let started;
+		try {
+			started = await builds.start(ctx, environment.settings);
+		} catch (error) {
+			return await failed(error, {
+				lastBuildId: null,
+				lastBuildHeads: null,
+				lastBuildInputs: null,
+				...attempted
+			});
+		}
+		const log = {
+			factoryProjectId: project.id,
+			trigger: input.trigger,
+			buildId: started.buildId
+		};
+		const changes = {
+			lastBuildId: started.buildId,
+			lastBuildHeads: heads,
+			lastBuildInputs: buildInputs,
+			...attempted
+		};
+		let recorded;
+		for (let attempt = 1; recorded === void 0; attempt++) try {
+			recorded = await release(changes);
+		} catch (error) {
+			if (attempt >= RECORD_ATTEMPTS) {
+				deps.logger?.info("environment build started but not recorded", {
+					...log,
+					reason: errorReason(error)
+				});
+				return {
+					outcome: "failed",
+					reason: "not_recorded",
+					buildId: started.buildId
+				};
+			}
+			await sleep(1e3 * 2 ** (attempt - 1));
+		}
+		if (!recorded) {
+			deps.logger?.info("environment build superseded", log);
+			return {
+				outcome: "failed",
+				reason: "superseded",
+				buildId: started.buildId
+			};
+		}
+		try {
+			deps.logger?.info("environment build started", {
+				...log,
+				templateId: started.templateId
+			});
+		} catch {}
+		return {
+			outcome: "started",
+			buildId: started.buildId,
+			...started.templateId ? { templateId: started.templateId } : {},
+			heads
+		};
+	} finally {
+		clearInterval(renewal);
+	}
+}
+//#endregion
+export { BUILD_START_LEASE_MS, ENVIRONMENT_BUILD_TRIGGERS, environmentBuildContext, environmentBuildInputs, environmentBuildSessionId, errorReason, redactCredentials, resolveEnvironmentHeads, runEnvironmentBuild };
+
+//# sourceMappingURL=build.js.map