@samebase/alchemy-convex 0.14.1 → 0.15.0

package/lib/HubClient-C_nvjlvW.js

@@ -0,0 +1,1938 @@
+import { createRequire } from "node:module";
+import { Stack } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { access, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, posix, relative, resolve, sep, win32 } from "node:path";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import * as Result from "effect/Result";
+import { Resource } from "alchemy";
+import { AdoptPolicy, OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
+import { diffBindings, isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
+import * as Schedule from "effect/Schedule";
+import { createHash } from "node:crypto";
+import { promisify, stripVTControlCharacters } from "node:util";
+import { hashDirectory } from "alchemy/Command/Memo";
+import * as Clock from "effect/Clock";
+import * as ChildProcess from "effect/process/ChildProcess";
+import * as Stream from "effect/Stream";
+import { fileURLToPath } from "node:url";
+import * as Scope from "effect/Scope";
+import { STATE_STORE_VERSION, State, StateStoreError, encodeState, reviveState } from "alchemy/State";
+import { execFile } from "node:child_process";
+//#region src/Credentials.ts
+var Credentials = class extends Context.Service()("@samebase/alchemy-convex/Credentials") {};
+/** Environment variable for the access token, read by {@link fromConfig}. */
+const ACCESS_TOKEN_ENV = "CONVEX_ACCESS_TOKEN";
+/** Environment variable for the deploy key, read by {@link fromConfig}. The Convex CLI reads the same name. */
+const DEPLOY_KEY_ENV = "CONVEX_DEPLOY_KEY";
+/** The Convex CLI stores its device login here after `npx convex login`. */
+const convexCliConfigPath = () => join(homedir(), ".convex", "config.json");
+const CliConfig = Schema.Struct({ accessToken: Schema.String });
+var CredentialsError = class extends Schema.TaggedError()("CredentialsError", { reason: Schema.String }) {};
+/**
+* Token the Convex CLI saved on this machine. It works on the Management API
+* for the teams the logged-in user belongs to. Fails when nobody is logged in.
+*/
+const readConvexCliLogin = Effect.gen(function* () {
+	const path = convexCliConfigPath();
+	const text = yield* Effect.tryPromise({
+		try: () => readFile(path, "utf8"),
+		catch: () => new CredentialsError({ reason: `This step needs the Convex Management API. Set ${ACCESS_TOKEN_ENV} to a team access token, or run \`npx convex login\`. There is no Convex CLI login at ${path}.` })
+	});
+	const parsed = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(CliConfig))(text).pipe(Effect.mapError(() => new CredentialsError({ reason: `${path} has no accessToken` })));
+	return {
+		accessToken: Redacted.make(parsed.accessToken),
+		source: "convex-cli-login"
+	};
+});
+/**
+* Default resolution through the stack ConfigProvider (process env, `.env`,
+* stack secrets): `CONVEX_ACCESS_TOKEN`, then the Convex CLI login on this
+* machine, for the access token; `CONVEX_DEPLOY_KEY` for the deploy key. A
+* developer who ran `npx convex login` needs nothing. CI sets only the
+* deploy key when the stack pushes to deployments that exist, and the access
+* token when the stack also creates projects or deployments.
+*/
+const fromConfig = () => Layer.effect(Credentials, Effect.gen(function* () {
+	const resolved = yield* Effect.cached(Config.Redacted(ACCESS_TOKEN_ENV).pipe(Effect.map((token) => ({
+		accessToken: token,
+		source: "env"
+	})), Effect.catch(() => readConvexCliLogin), Effect.result));
+	const deployKey = yield* Effect.cached(Config.option(Config.Redacted(DEPLOY_KEY_ENV)).pipe(Effect.map(Option.getOrUndefined), Effect.orDie));
+	return {
+		accessToken: resolved.pipe(Effect.flatMap(Effect.fromResult), Effect.orDie),
+		hasAccessToken: resolved.pipe(Effect.map(Result.isSuccess)),
+		deployKey
+	};
+}));
+/** Explicit values, for tests or callers that already hold them. */
+const fromValues = (values) => Layer.succeed(Credentials, {
+	accessToken: values.accessToken === void 0 ? Effect.die(new CredentialsError({ reason: "This step needs the Convex Management API, and fromValues got no accessToken." })) : Effect.succeed({
+		accessToken: values.accessToken,
+		source: "explicit"
+	}),
+	hasAccessToken: Effect.succeed(values.accessToken !== void 0),
+	deployKey: Effect.succeed(values.deployKey)
+});
+//#endregion
+//#region src/Adoption.ts
+/** True when the resource `fqn` may take over an object that is not in state. */
+const shouldAdopt = (fqn) => Effect.gen(function* () {
+	const stack = yield* Effect.serviceOption(Stack);
+	const own = Option.isSome(stack) ? stack.value.resources[fqn]?.Adopt : void 0;
+	if (own !== void 0) return own;
+	const policy = yield* Effect.serviceOption(AdoptPolicy);
+	if (Option.isSome(policy)) return policy.value;
+	const context = yield* Effect.serviceOption(AlchemyContext);
+	return Option.isSome(context) && context.value.adopt;
+});
+//#endregion
+//#region src/ManagementApi.ts
+/**
+* One error for every control-plane and deployment call. Resources branch on
+* `status` (404 means absent for read and delete), so the class is load
+* bearing, not decorative.
+*/
+var ConvexApiError = class extends Schema.TaggedError()("ConvexApiError", {
+	operation: Schema.String,
+	status: Schema.Number,
+	code: Schema.optionalKey(Schema.String),
+	message: Schema.String
+}) {};
+const ErrorBody = Schema.Struct({
+	code: Schema.optionalKey(Schema.String),
+	message: Schema.optionalKey(Schema.String)
+});
+const toApiError = (operation, result) => {
+	const body = Schema.decodeUnknownSync(Schema.NullishOr(ErrorBody))(result.error ?? null);
+	const code = body?.code;
+	return new ConvexApiError({
+		operation,
+		status: result.response.status,
+		...code === void 0 ? {} : { code },
+		message: body?.message ?? `${operation} failed with HTTP ${result.response.status}`
+	});
+};
+/** The part of a Convex token after the first "|", or the whole value when it has none. */
+const tokenPart = (value) => value.slice(value.indexOf("|") + 1);
+var ManagementApi = class extends Context.Service()("@samebase/alchemy-convex/ManagementApi") {};
+const attempt = (operation, run) => Effect.tryPromise({
+	try: run,
+	catch: (cause) => new ConvexApiError({
+		operation,
+		status: 0,
+		message: cause instanceof Error ? cause.message : String(cause)
+	})
+});
+/** Reads `data` or fails with the HTTP status and the API's own code and message. */
+const settle = (operation, run) => attempt(operation, run).pipe(Effect.flatMap((result) => result.response.ok && result.data !== void 0 ? Effect.succeed(result.data) : Effect.fail(toApiError(operation, result))));
+/** For endpoints that answer with an empty body, such as delete calls. */
+const settleVoid = (operation, run) => attempt(operation, run).pipe(Effect.flatMap((result) => result.response.ok ? Effect.void : Effect.fail(toApiError(operation, result))));
+/**
+* True when an idempotent write can succeed on a new attempt:
+*
+* - A Convex write conflict. Two parallel update_environment_variables calls
+*   on one deployment gave HTTP 503 `OptimisticConcurrencyControlFailure`,
+*   "Data read or written in this mutation changed while it was being run",
+*   in a live run. The platform codes `OCC` and `WriteConflict` and the
+*   message "... changed while this mutation was being run ..." mean the same.
+* - Any other 5xx answer. Two parallel delete_preview_deploy_key calls on one
+*   project gave HTTP 500 `InternalServerError`, "Your request couldn't be
+*   completed. Try again later.", in a live run. The next attempt succeeded.
+*/
+const isRetryableWriteError = (error) => error.code === "OptimisticConcurrencyControlFailure" || error.code === "OCC" || error.code === "WriteConflict" || /changed while (it|this mutation) was being run/.test(error.message) || error.status >= 500;
+/**
+* Runs an idempotent write again after a retryable Convex error: at most
+* four more attempts, with exponential backoff from 100 ms and jitter. Other
+* errors fail at once, and so does the last retryable error. Use it only for
+* a write that has the same result when it runs twice, such as setting a
+* value or deleting by id. Never for a create that does not check first.
+*/
+const retryIdempotentWrite = (effect) => effect.pipe(Effect.retry({
+	while: (error) => error instanceof ConvexApiError && isRetryableWriteError(error),
+	times: 4,
+	schedule: Schedule.exponential("100 millis").pipe(Schedule.jittered)
+}));
+/** Turns a 404 into `undefined` so read and delete stay idempotent. */
+const absentAsUndefined = (effect) => effect.pipe(Effect.catchIf((error) => error.status === 404, () => Effect.succeed(void 0)));
+const TeamRow = Schema.Struct({
+	id: Schema.Number,
+	slug: Schema.String
+});
+const TeamRows = Schema.Array(TeamRow);
+/** The first page of GET /teams/{team_id}/projects: every row carries the slug of the team. */
+const ProjectSlugRows = Schema.Struct({ items: Schema.Array(Schema.Struct({ teamSlug: Schema.String })) });
+/** GET /token_details: the team of a team token, or the project of a project token. */
+const TokenDetails = Schema.Union([Schema.Struct({
+	type: Schema.Literal("teamToken"),
+	teamId: Schema.Number
+}), Schema.Struct({
+	type: Schema.Literal("projectToken"),
+	projectId: Schema.Number
+})]);
+/** The service for one way to get the bearer token. */
+const makeService = (credentials) => {
+	const client = Effect.cached(credentials.pipe(Effect.map((resolved) => createManagementClient(Redacted.value(resolved.accessToken))))).pipe(Effect.flatten);
+	const request = (operation, run) => client.pipe(Effect.flatMap((c) => settle(operation, () => run(c))));
+	const requestVoid = (operation, run) => client.pipe(Effect.flatMap((c) => settleVoid(operation, () => run(c))));
+	const deploymentRequest = (operation, deploymentUrlOrName, deployKey, run) => settle(operation, () => run(createDeploymentClient(deploymentUrlOrName, Redacted.value(deployKey))));
+	const tokenDetails = Effect.runSync(Effect.cached(request("get token details", (c) => c.GET("/token_details")).pipe(Effect.map((body) => Schema.decodeUnknownSync(TokenDetails)(body)), Effect.catchIf((error) => error.status === 403, () => Effect.succeed(void 0)))));
+	/** The slug of the team, from the first project of its listing, or undefined for a team without one. Read once. */
+	const teamSlug = (teamId) => request("list projects", (c) => c.GET("/teams/{team_id}/projects", { params: { path: { team_id: teamId } } })).pipe(Effect.map((body) => Schema.decodeUnknownSync(ProjectSlugRows)(body).items[0]?.teamSlug));
+	const resolveTeamId = (team) => Effect.gen(function* () {
+		if (typeof team === "number") return team;
+		if (team !== void 0 && /^\d+$/.test(team)) return Number(team);
+		const details = yield* tokenDetails;
+		if (details?.type === "teamToken") {
+			if (team === void 0) return details.teamId;
+			const slug = yield* teamSlug(details.teamId);
+			if (slug === void 0) return yield* new ConvexApiError({
+				operation: "resolve team",
+				status: 0,
+				message: `team "${team}" cannot be checked against the access token: team ${details.teamId} has no project yet. Set team to ${details.teamId}, or leave it out.`
+			});
+			if (slug !== team) return yield* new ConvexApiError({
+				operation: "resolve team",
+				status: 403,
+				message: `the access token belongs to team ${details.teamId} ("${slug}"), and team is "${team}". Use a token of "${team}", or set team to ${details.teamId}.`
+			});
+			return details.teamId;
+		}
+		if (details?.type === "projectToken") return yield* new ConvexApiError({
+			operation: "resolve team",
+			status: 403,
+			message: `the access token belongs to project ${details.projectId}, and a project token cannot create projects. Use a team access token.`
+		});
+		if (team === void 0) return yield* new ConvexApiError({
+			operation: "resolve team",
+			status: 0,
+			message: "set team to the slug or the id of the Convex team: this access token does not name a team."
+		});
+		const resolved = yield* credentials;
+		const match = (yield* Effect.tryPromise({
+			try: async () => {
+				const response = await fetch("https://api.convex.dev/api/dashboard/teams", { headers: { Authorization: `Bearer ${Redacted.value(resolved.accessToken)}` } });
+				if (!response.ok) throw new Error(`team lookup for "${team}" failed with HTTP ${response.status}`);
+				return Schema.decodeUnknownSync(TeamRows)(await response.json());
+			},
+			catch: (cause) => new ConvexApiError({
+				operation: "resolve team",
+				status: 0,
+				message: cause instanceof Error ? cause.message : String(cause)
+			})
+		})).find((row) => row.slug === team);
+		if (match === void 0) return yield* new ConvexApiError({
+			operation: "resolve team",
+			status: 404,
+			message: `no team with slug "${team}" for this token`
+		});
+		return match.id;
+	});
+	const isCredentialToken = (secret) => credentials.pipe(Effect.map((resolved) => tokenPart(Redacted.value(resolved.accessToken)) === tokenPart(secret)));
+	const withToken = (token) => makeService(Effect.succeed({
+		accessToken: token,
+		source: "explicit"
+	}));
+	return {
+		request,
+		requestVoid,
+		deploymentRequest,
+		resolveTeamId,
+		isCredentialToken,
+		withToken
+	};
+};
+const ManagementApiLive = () => Layer.effect(ManagementApi, Effect.gen(function* () {
+	const credentials = yield* Credentials;
+	return makeService(credentials.accessToken);
+}));
+//#endregion
+//#region src/Push.ts
+const sourceOf = (source) => typeof source === "string" ? {
+	path: source,
+	command: void 0,
+	include: void 0
+} : {
+	path: source.path,
+	command: source.command,
+	include: source.include
+};
+/** Lifetime of a push key. Long enough for a slow push with index backfills. */
+const PUSH_KEY_LIFETIME_MS = 72e5;
+/** The only actions a key for `convex deploy` gets. */
+const PUSH_KEY_ACTIONS = [
+	"deployment:deploy",
+	"deployment:env:view",
+	"deployment:env:write"
+];
+/** POST /deployments/{deployment_name}/create_deploy_key */
+const CreatedDeployKey = Schema.Struct({ deployKey: Schema.String });
+/** GET https://<deployment>.convex.cloud/api/v1/list_environment_variables */
+const EnvironmentVariableList = Schema.Struct({ environmentVariables: Schema.Record(Schema.String, Schema.String) });
+/** No `convex` package resolves from the app directory. */
+var ConvexCliNotFound = class extends Schema.TaggedError()("ConvexCliNotFound", { cwd: Schema.String }) {
+	get message() {
+		return `Convex.Deployment found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), or set rootDir to the directory of the app.`;
+	}
+};
+/** The app directory (`rootDir`) has no package.json. */
+var ConvexAppNotFound = class extends Schema.TaggedError()("ConvexAppNotFound", { 
+/** The app directory, resolved against the working directory of the deploy. */
+rootDir: Schema.String }) {
+	get message() {
+		return `Convex.Deployment found no package.json in ${this.rootDir}. Set rootDir to the directory of the Convex app, relative to the directory where the deploy runs, such as "apps/web".`;
+	}
+};
+/** The Convex CLI failed, or exited 0 without the deployment URL. The output tail never contains the key. */
+var CodePushFailed = class extends Schema.TaggedError()("CodePushFailed", {
+	/** Exit code of the CLI. Undefined when it did not start or a signal stopped it. */
+	exitCode: Schema.UndefinedOr(Schema.Number),
+	/** The last lines of the CLI output, with the deploy key removed. */
+	outputTail: Schema.String
+}) {
+	get message() {
+		return this.exitCode === 0 ? `convex deploy exited 0 but printed no "Deployed Convex functions to <url>" line. Last output, with the deploy key removed:\n${this.outputTail}` : `convex deploy failed${this.exitCode === void 0 ? "" : ` with exit code ${this.exitCode}`}. Last output, with the deploy key removed:\n${this.outputTail}`;
+	}
+};
+/** The CLI pushed to another deployment than the one of the resource. Checked after the push. */
+var PushTargetMismatch = class extends Schema.TaggedError()("PushTargetMismatch", {
+	expected: Schema.String,
+	actual: Schema.String
+}) {
+	get message() {
+		return `The Convex CLI pushed the functions to deployment ${this.actual}, but Convex.Deployment expected ${this.expected}. Check that convex.json does not select another deployment.`;
+	}
+};
+/** Variables in `env` exist on the deployment with other values, and adoption is off. */
+var VariablesOwnedBySomeoneElse = class extends Schema.TaggedError()("VariablesOwnedBySomeoneElse", {
+	deployment: Schema.String,
+	names: Schema.Array(Schema.String)
+}) {
+	get message() {
+		return `Environment variables ${this.names.join(", ")} already exist on deployment ${this.deployment} with other values. Re-run with --adopt to take them over and overwrite them, or remove them from env.`;
+	}
+};
+/** A preview deploy key cannot set variables: the deployment API takes only a deploy key of the deployment. */
+var EnvironmentNeedsDeployKey = class extends Schema.TaggedError()("EnvironmentNeedsDeployKey", { deployment: Schema.String }) {
+	get message() {
+		return `Convex.Deployment cannot set or remove env variables on preview deployment ${this.deployment} with a preview deploy key: Convex lets that key create, push to, and delete preview deployments, but not change their variables. Set CONVEX_ACCESS_TOKEN for this stage, or set the values as project default environment variables for preview deployments in the Convex dashboard.`;
+	}
+};
+/**
+* What a deploy key targets, from its prefix: `<type>:<deployment>|<secret>`
+* (or `<deployment>|<secret>` in old keys) for one deployment, and
+* `preview:<team>:<project>|<secret>` for the preview deployments of a
+* project. Same rules as convex 1.46 `cli/lib/deployment.js`.
+*/
+const keyTargetOf = (key) => {
+	const bar = key.indexOf("|");
+	if (bar <= 0 || /[\s#'"`]/.test(key)) return { kind: "other" };
+	const [first, second, third, ...rest] = key.slice(0, bar).split(":");
+	if (rest.length > 0) return { kind: "other" };
+	if (first === "preview" && second && third) return {
+		kind: "preview",
+		team: second,
+		project: third
+	};
+	if (third !== void 0) return { kind: "other" };
+	if (second) return {
+		kind: "deployment",
+		deployment: second
+	};
+	if (first && second === void 0) return {
+		kind: "deployment",
+		deployment: first
+	};
+	return { kind: "other" };
+};
+/**
+* The CLI prints this line with `logFinishedStep` after the push succeeds, to
+* stderr (convex 1.46 `cli/lib/deploy2.js`). The host is
+* `<deployment>.convex.cloud` or `<deployment>.<region>.convex.cloud`.
+*/
+const DEPLOYED_LINE = /Deployed Convex functions to (https:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)?\.convex\.cloud)\/?(?=\s|$)/m;
+/** Reads the deployment URL from `convex deploy` output. ANSI escape codes are removed first. */
+const parseDeployOutput = (text) => {
+	const match = DEPLOYED_LINE.exec(stripVTControlCharacters(text));
+	const url = match?.[1];
+	const deploymentName = match?.[2];
+	return url === void 0 || deploymentName === void 0 ? void 0 : {
+		url,
+		deploymentName
+	};
+};
+/** The last non-empty lines of `text`, without escape codes and with every secret replaced. */
+const outputTail = (text, secrets) => secrets.reduce((redacted, secret) => redacted.split(secret).join("[REDACTED]"), stripVTControlCharacters(text)).split(/\r?\n|\r/).filter((line) => line.trim() !== "").slice(-20).join("\n");
+const valueOf$1 = (value) => Redacted.isRedacted(value) ? Redacted.value(value) : value;
+/**
+* The app directory: `rootDir` resolved against the working directory of the
+* deploy. It must have a package.json. There is no search above it.
+*/
+const appDirectoryOf = (rootDir) => {
+	const directory = resolve(rootDir);
+	return Effect.tryPromise({
+		try: () => access(join(directory, "package.json")).then(() => directory),
+		catch: () => new ConvexAppNotFound({ rootDir: directory })
+	});
+};
+/** `source` is not the functions directory that the Convex CLI pushes from the app directory. */
+var SourceMismatch = class extends Schema.TaggedError()("SourceMismatch", {
+	/** The app directory, resolved. */
+	rootDir: Schema.String,
+	source: Schema.String,
+	functions: Schema.String
+}) {
+	get message() {
+		return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} from the app directory ${this.rootDir} (the "functions" field of convex.json, or convex/ by default). Set rootDir to the directory of the Convex app, and source to its functions directory relative to rootDir, such as "./convex".`;
+	}
+};
+const ConvexJson = Schema.Struct({ functions: Schema.optionalKey(Schema.String) });
+/** Fails with {@link SourceMismatch} when `path` is not the functions directory of the app in `cwd`. */
+const checkFunctionsDirectory = (cwd, path) => Effect.gen(function* () {
+	const text = yield* Effect.promise(() => readFile(join(cwd, "convex.json"), "utf8").catch(() => void 0));
+	const configured = text === void 0 ? void 0 : Schema.decodeUnknownSync(Schema.fromJsonString(ConvexJson))(text).functions;
+	const functions = resolve(cwd, configured ?? "convex");
+	if (functions !== path) return yield* new SourceMismatch({
+		rootDir: cwd,
+		source: path,
+		functions
+	});
+});
+const CliManifest = Schema.Struct({ bin: Schema.Union([Schema.String, Schema.Record(Schema.String, Schema.String)]) });
+/** `[node, <convex bin>]` for the `convex` package that `cwd` resolves. Never downloads. */
+const installedCli = (cwd) => Effect.tryPromise({
+	try: async () => {
+		const manifestPath = createRequire(join(cwd, "package.json")).resolve("convex/package.json");
+		const { bin } = Schema.decodeUnknownSync(Schema.fromJsonString(CliManifest))(await readFile(manifestPath, "utf8"));
+		const entry = typeof bin === "string" ? bin : bin["convex"];
+		if (entry === void 0) throw new Error("the convex package has no convex bin");
+		return [process.execPath, resolve(dirname(manifestPath), entry)];
+	},
+	catch: () => new ConvexCliNotFound({ cwd })
+});
+/**
+* The content identity of a push: the files of the app directory that git
+* does not ignore (or `path`, the manifests, and the `include` globs), the
+* nearest lockfile, the target deployment, and the `env` names and values.
+* A change in a workspace package outside the app directory is not seen.
+*/
+const pushHash = (options) => Effect.gen(function* () {
+	const source = options.source === void 0 ? void 0 : sourceOf(options.source);
+	const files = source === void 0 ? void 0 : yield* appDirectoryOf(options.rootDir).pipe(Effect.flatMap((cwd) => {
+		const functions = relative(cwd, resolve(cwd, source.path)).split("\\").join("/");
+		return hashDirectory({
+			cwd,
+			memo: source.include !== void 0 ? {
+				include: [
+					`${functions}/**`,
+					"package.json",
+					"convex.json",
+					...source.include
+				],
+				lockfile: true
+			} : functions === ".." || functions.startsWith("../") ? {
+				include: ["**/*", `${functions}/**`],
+				lockfile: true
+			} : {}
+		});
+	}));
+	const env = Object.entries(options.env).map(([name, value]) => [name, valueOf$1(value)]).sort(([a], [b]) => a < b ? -1 : 1);
+	return createHash("sha256").update(JSON.stringify({
+		files,
+		deployment: options.deployment,
+		env
+	})).digest("hex");
+});
+/**
+* Runs `use` with an env file that holds the key, in a new temporary
+* directory, and removes the directory afterwards: on success, on failure,
+* and on interruption.
+*/
+const withKeyFile = (key, use) => Effect.acquireUseRelease(Effect.promise(() => mkdtemp(join(tmpdir(), "alchemy-convex-"))), (home) => Effect.promise(() => writeFile(join(home, "deploy.env"), `CONVEX_DEPLOY_KEY=${key}\n`, { mode: 384 })).pipe(Effect.andThen(use({
+	envFile: join(home, "deploy.env"),
+	home
+}))), (home) => Effect.promise(() => rm(home, {
+	recursive: true,
+	force: true
+})));
+/** This process's variables without `CONVEX_*`, with `home` as the home directory. */
+const cliEnvironment = (home) => ({
+	...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toUpperCase().startsWith("CONVEX_"))),
+	HOME: home,
+	USERPROFILE: home,
+	XDG_CONFIG_HOME: home
+});
+/**
+* A deploy key of `deployment` that expires after PUSH_KEY_LIFETIME_MS, with
+* only `allowedActions`, or every action when that is undefined. Delete it
+* with {@link deleteDeployKey} when the work is done.
+*/
+const createDeployKey = (api, deployment, name, allowedActions) => Effect.gen(function* () {
+	const now = yield* Clock.currentTimeMillis;
+	const created = yield* api.request("create deploy key", (client) => client.POST("/deployments/{deployment_name}/create_deploy_key", {
+		params: { path: { deployment_name: deployment } },
+		body: {
+			name,
+			...allowedActions === void 0 ? {} : { allowedActions: [...allowedActions] },
+			expiresAt: now + PUSH_KEY_LIFETIME_MS
+		}
+	}));
+	return Redacted.make(Schema.decodeUnknownSync(CreatedDeployKey)(created).deployKey);
+});
+/**
+* Deletes a key that {@link createDeployKey} made. The delete is skipped for
+* a key that is the OAuth credential. A failed delete is logged: the key
+* expires anyway.
+*/
+const deleteDeployKey = (api, deployment, key) => Effect.gen(function* () {
+	if (yield* api.isCredentialToken(Redacted.value(key))) return;
+	yield* absentAsUndefined(retryIdempotentWrite(api.requestVoid("delete deploy key", (client) => client.POST("/deployments/{deployment_name}/delete_deploy_key", {
+		params: { path: { deployment_name: deployment } },
+		body: { id: Redacted.value(key) }
+	}))));
+}).pipe(Effect.catch((error) => Effect.logWarning(`Convex.Deployment could not delete its key on ${deployment} (${error.message}). The key expires on its own within ${PUSH_KEY_LIFETIME_MS / 6e4} minutes.`)));
+/**
+* Creates a deploy key for one push, runs `use` with it, and deletes it
+* afterwards, also after a failure. `allowedActions` is PUSH_KEY_ACTIONS for
+* `convex deploy`, or undefined for a push command, which can do more than a
+* push, such as the uploads of convex-hosting through `convex run`.
+*/
+const withPushKey = (api, deployment, allowedActions, use) => Effect.acquireUseRelease(createDeployKey(api, deployment, "alchemy-push", allowedActions), use, (key) => deleteDeployKey(api, deployment, key));
+/** Every variable of the deployment with its value. */
+const listVariables = (url, key) => settle("list environment variables", () => createDeploymentClient(url, Redacted.value(key)).GET("/list_environment_variables")).pipe(Effect.map((body) => Schema.decodeUnknownSync(EnvironmentVariableList)(body).environmentVariables));
+/** One call that sets variables, or removes those whose value is null. */
+const writeVariables = (url, key, changes) => settleVoid("update environment variables", () => createDeploymentClient(url, Redacted.value(key)).POST("/update_environment_variables", { body: { changes: changes.map(({ name, value }) => ({
+	name,
+	value
+})) } }));
+/**
+* The app directory and the program of a push. Fails before any change when
+* `rootDir` has no package.json, when `source` is not the functions directory
+* of the app, or when the app has no installed Convex CLI and no push command.
+*/
+const checkSource = (rootDir, input) => Effect.gen(function* () {
+	const source = sourceOf(input);
+	const cwd = yield* appDirectoryOf(rootDir);
+	yield* checkFunctionsDirectory(cwd, resolve(cwd, source.path));
+	return {
+		cwd,
+		program: source.command ?? (yield* installedCli(cwd))
+	};
+});
+/**
+* Sets the `env` variables and pushes the functions of `source` to one
+* deployment with `key`: a deploy key of the deployment, or a preview deploy
+* key of its project with `previewName`. Returns the URL that the CLI
+* printed, or undefined without `source`.
+*/
+const push = (spawner, key, options) => Effect.gen(function* () {
+	const source = options.source === void 0 ? void 0 : sourceOf(options.source);
+	const resolved = options.source === void 0 ? void 0 : yield* checkSource(options.rootDir, options.source);
+	const cwd = resolved?.cwd;
+	const program = resolved?.program;
+	const env = Object.entries(options.env).sort(([a], [b]) => a < b ? -1 : 1);
+	const removed = options.previousEnvNames.filter((name) => !Object.hasOwn(options.env, name));
+	const written = env.length === 0 && removed.length === 0 ? {
+		current: {},
+		changes: []
+	} : yield* retryIdempotentWrite(Effect.gen(function* () {
+		const current = yield* listVariables(options.url, key);
+		if (!options.adopt) {
+			const taken = env.filter(([name, value]) => !options.previousEnvNames.includes(name) && Object.hasOwn(current, name) && current[name] !== valueOf$1(value)).map(([name]) => name);
+			if (taken.length > 0) return yield* new VariablesOwnedBySomeoneElse({
+				deployment: options.deployment,
+				names: taken
+			});
+		}
+		const changes = [...env.filter(([name, value]) => current[name] !== valueOf$1(value)).map(([name, value]) => ({
+			name,
+			value: valueOf$1(value)
+		})), ...removed.filter((name) => Object.hasOwn(current, name)).map((name) => ({
+			name,
+			value: null
+		}))];
+		if (changes.length > 0) yield* writeVariables(options.url, key, changes);
+		return {
+			current,
+			changes
+		};
+	}));
+	/**
+	* After a failed push, the variables go back to their earlier values, so
+	* that the deployment matches the hash in state. A failed rollback is
+	* logged: the push error is the one to report.
+	*/
+	const rollback = written.changes.length === 0 ? Effect.void : retryIdempotentWrite(writeVariables(options.url, key, written.changes.map(({ name }) => ({
+		name,
+		value: Object.hasOwn(written.current, name) ? written.current[name] ?? null : null
+	})))).pipe(Effect.catch((error) => Effect.logWarning(`Convex.Deployment could not set the env variables of ${options.deployment} back after the failed push (${error.message}). Run the deploy again.`)));
+	if (source === void 0 || cwd === void 0 || program === void 0) return void 0;
+	return yield* runPush(spawner, key, {
+		...options,
+		cwd,
+		program,
+		command: source.command
+	}).pipe(Effect.onError(() => rollback));
+});
+/** Runs the installed CLI or the push command once, and checks the deployment that it names. */
+const runPush = (spawner, key, options) => Effect.gen(function* () {
+	const { cwd, program } = options;
+	const secret = Redacted.value(key);
+	const secrets = [secret, secret.slice(secret.indexOf("|") + 1)].filter((value) => value.length >= 8);
+	const result = yield* withKeyFile(secret, ({ envFile, home }) => Effect.gen(function* () {
+		const [command, ...programArgs] = program;
+		const args = options.command === void 0 ? [
+			...programArgs,
+			"deploy",
+			...options.previewName === void 0 ? [] : ["--preview-name", options.previewName],
+			"--env-file",
+			envFile
+		] : programArgs;
+		const child = yield* spawner.spawn(ChildProcess.make(command, args, {
+			cwd,
+			env: {
+				...cliEnvironment(home),
+				...options.command === void 0 ? {} : { CONVEX_DEPLOY_KEY: secret }
+			},
+			extendEnv: false,
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "pipe"
+		}));
+		const [exitCode, stdout, stderr] = yield* Effect.all([
+			child.exitCode,
+			Stream.mkString(Stream.decodeText(child.stdout)),
+			Stream.mkString(Stream.decodeText(child.stderr))
+		], { concurrency: "unbounded" });
+		return {
+			exitCode: Number(exitCode),
+			output: `${stdout}\n${stderr}`
+		};
+	}).pipe(Effect.scoped)).pipe(Effect.mapError((error) => new CodePushFailed({
+		exitCode: void 0,
+		outputTail: outputTail(error.message, secrets)
+	})));
+	const deployed = parseDeployOutput(result.output);
+	if (result.exitCode !== 0 || deployed === void 0) return yield* new CodePushFailed({
+		exitCode: result.exitCode,
+		outputTail: outputTail(result.output, secrets)
+	});
+	if (deployed.deploymentName !== options.deployment) return yield* new PushTargetMismatch({
+		expected: options.deployment,
+		actual: deployed.deploymentName
+	});
+	return deployed.url;
+});
+//#endregion
+//#region src/Deployment.ts
+/** The resource class. Stacks call {@link Deployment}, which writes `rootDir` into the props. */
+const DeploymentResource = Resource("Convex.Deployment", { defaultRemovalPolicy: "retain" });
+/** `rootDir` in POSIX form, without "./" and a trailing slash, such as `apps/web` or ".". */
+const normalizeRootDir = (rootDir) => {
+	const normalized = posix.normalize(rootDir.replaceAll("\\", "/"));
+	return normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+};
+/** `rootDir` is an absolute path. The declaration stops with it as a defect, before the plan. */
+var AbsoluteRootDir = class extends Schema.TaggedError()("AbsoluteRootDir", { rootDir: Schema.String }) {
+	get message() {
+		return `Convex.Deployment rootDir ${this.rootDir} is an absolute path. State keeps rootDir for every machine that runs the stack, so set it relative to the directory where the deploy runs, such as "apps/web".`;
+	}
+};
+/**
+* `Convex.Deployment("id", props)`. The props go to state with `rootDir` in
+* POSIX form, and with "." when it is not set, so that every row names the
+* app directory of its deployment. An absolute `rootDir` stops the
+* declaration, so it never reaches the plan or state. The check dies,
+* because the program of `Alchemy.Stack` can fail only with a ConfigError.
+* `win32.isAbsolute` also answers true for a POSIX absolute path. The other
+* fields keep it usable where Alchemy takes a resource class, such as
+* `Provider.collection`.
+*/
+const Deployment = Object.assign((id, props) => {
+	const rootDir = props.rootDir ?? ".";
+	return win32.isAbsolute(rootDir) ? Effect.die(new AbsoluteRootDir({ rootDir })) : DeploymentResource(id, {
+		...props,
+		rootDir: normalizeRootDir(rootDir)
+	});
+}, {
+	Type: DeploymentResource.Type,
+	Props: DeploymentResource.Props,
+	Self: DeploymentResource.Self,
+	Provider: DeploymentResource.Provider,
+	Aliases: DeploymentResource.Aliases,
+	ref: (id, options) => DeploymentResource.ref(id, options)
+});
+/** The props name another deployment than the one in state. */
+var DeploymentIdentityChange = class extends Schema.TaggedError()("DeploymentIdentityChange", {
+	/** Name of the deployment in state, such as `happy-animal-123`. */
+	deployment: Schema.String,
+	field: Schema.Literals([
+		"projectId",
+		"type",
+		"name"
+	]),
+	current: Schema.String,
+	requested: Schema.String
+}) {
+	get message() {
+		return `Convex.Deployment cannot change the ${this.field} of deployment ${this.deployment} from ${this.current} to ${this.requested}. Set ${this.field} back to ${this.current}. For another deployment, create a new resource with a new logical id.`;
+	}
+};
+/** The project has no default production deployment for a `prod` resource to take over. */
+var ProductionDeploymentNotFound = class extends Schema.TaggedError()("ProductionDeploymentNotFound", { projectId: Schema.Number }) {
+	get message() {
+		return `Project ${this.projectId} has no default production deployment, and Convex.Deployment does not create one. Create it in the Convex dashboard, or with \`npx convex deployment create --type prod --default\` in the project, then run the deploy again.`;
+	}
+};
+/** More than one deployment of the project has the name, so the lookup cannot choose one. */
+var AmbiguousDeployment = class extends Schema.TaggedError()("AmbiguousDeployment", {
+	projectId: Schema.Number,
+	type: Schema.Literals(["dev", "preview"]),
+	name: Schema.String,
+	deployments: Schema.Array(Schema.String)
+}) {
+	get message() {
+		return `Project ${this.projectId} has ${this.deployments.length} ${this.type} deployments named "${this.name}" (${this.deployments.join(", ")}). Convex.Deployment does not choose one. Delete the extra deployments in the Convex dashboard, or use another name.`;
+	}
+};
+/**
+* The URL of a Convex cloud deployment: `https://<name>.convex.cloud`, or
+* `https://<name>.<region>.convex.cloud` outside US East.
+*/
+const CLOUD_URL = /^https:\/\/[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)?\.convex\.cloud$/;
+/**
+* The HTTP actions URL of a deployment: the client URL with `.convex.site`
+* for `.convex.cloud`, as Convex sets CONVEX_SITE_URL. Custom domains are
+* not covered.
+*/
+const siteUrlOf = (url) => url.replace(/\.convex\.cloud$/, ".convex.site");
+/** One row of list_deployments, GET /deployments/{name}, and create_deployment. Only the fields the provider uses. */
+const DeploymentRow$1 = Schema.Struct({
+	name: Schema.String,
+	projectId: Schema.Number,
+	deploymentType: Schema.String,
+	isDefault: Schema.Boolean,
+	reference: Schema.String,
+	/** Set in list_deployments and create_deployment rows only: GET /deployments/{name} answers null. */
+	previewIdentifier: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	deploymentUrl: Schema.String.check(Schema.isPattern(CLOUD_URL)),
+	/** Absent or null until the first push: list_deployments leaves it out for a new deployment. */
+	lastDeployTime: Schema.optionalKey(Schema.NullOr(Schema.Number))
+});
+const DeploymentRows$1 = Schema.Array(DeploymentRow$1);
+/** GET https://<deployment>/api/v1/deployment_info, for a cloud deployment. Only the fields the provider uses. */
+const DeploymentInfo = Schema.Struct({
+	kind: Schema.Literal("cloud"),
+	projectId: Schema.Number,
+	deploymentType: Schema.String,
+	reference: Schema.optionalKey(Schema.NullOr(Schema.String))
+});
+/** GET https://<deployment>/api/v1/get_canonical_urls */
+const CanonicalUrls = Schema.Struct({
+	convexCloudUrl: Schema.String,
+	convexSiteUrl: Schema.String
+});
+const targetOf = (row, type, previewName) => ({
+	projectId: row.projectId,
+	type,
+	name: row.name,
+	reference: row.reference,
+	previewName: type === "preview" ? previewName : void 0,
+	url: row.deploymentUrl,
+	siteUrl: siteUrlOf(row.deploymentUrl)
+});
+/** True when the deployment has received a push. */
+const isDeployed = (row) => row.lastDeployTime !== void 0 && row.lastDeployTime !== null;
+/** The `name` prop of a deployment: the dev reference or the preview name. */
+const nameOf = (target) => target.type === "dev" ? target.reference : target.type === "preview" ? target.previewName : void 0;
+/**
+* Fails with {@link DeploymentIdentityChange} when the props name another
+* deployment than `current`: the attributes in state, or a live deployment.
+*/
+const checkIdentity = (current, news) => {
+	const change = (field, from, to) => Effect.fail(new DeploymentIdentityChange({
+		deployment: current.name,
+		field,
+		current: from,
+		requested: to
+	}));
+	if (current.projectId !== news.project.projectId) return change("projectId", String(current.projectId), String(news.project.projectId));
+	if (current.type !== news.type) return change("type", current.type, news.type);
+	const currentName = nameOf(current);
+	if (news.type !== "prod" && currentName !== news.name) return change("name", currentName ?? "(none)", news.name);
+	return Effect.void;
+};
+const addressOf = (props) => ({
+	projectId: props.project.projectId,
+	type: props.type,
+	name: props.type === "prod" ? void 0 : props.name
+});
+/** True when an update writes or removes variables: `env` has names, or state has names to remove. */
+const changesEnv = (news, output) => Object.keys(news.env ?? {}).length > 0 || envNamesOf(output).length > 0;
+/** The `env` names in state. State from 0.3 has none. */
+const envNamesOf = (output) => output?.envNames ?? [];
+/** The address of the deployment in state. */
+const addressInState = (output) => ({
+	projectId: output.projectId,
+	type: output.type,
+	name: nameOf(output)
+});
+const ProjectSlugs = Schema.Struct({
+	slug: Schema.String,
+	teamSlug: Schema.String
+});
+/** True for an answer that says this credential cannot read the object. */
+const isRefused = (error) => error.status === 400 || error.status === 401 || error.status === 403 || error.status === 404;
+const DeploymentProvider = () => Provider.effect(DeploymentResource, Effect.gen(function* () {
+	const api = yield* ManagementApi;
+	const credentials = yield* Credentials;
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	/** The live deployment, or undefined after a 404. GET /deployments/{name} answers no preview identifier. */
+	const getByName = (management, name) => absentAsUndefined(management.request("get deployment", (client) => client.GET("/deployments/{deployment_name}", { params: { path: { deployment_name: name } } }))).pipe(Effect.map((body) => body === void 0 ? void 0 : Schema.decodeUnknownSync(DeploymentRow$1)(body)));
+	const listDeployments = (management, projectId, type, isDefault) => management.request("list deployments", (client) => client.GET("/projects/{project_id}/list_deployments", { params: {
+		path: { project_id: projectId },
+		query: {
+			deploymentType: type,
+			...isDefault === void 0 ? {} : { isDefault }
+		}
+	} })).pipe(Effect.map((body) => Schema.decodeUnknownSync(DeploymentRows$1)(body)));
+	/** The row of the project's default production deployment, or undefined. */
+	const productionRow = (management, projectId) => listDeployments(management, projectId, "prod", true).pipe(Effect.map((rows) => rows.find((candidate) => candidate.deploymentType === "prod" && candidate.isDefault)));
+	/** The project's default production deployment, or undefined. */
+	const production = (management, projectId) => productionRow(management, projectId).pipe(Effect.map((row) => row === void 0 ? void 0 : targetOf(row, "prod", void 0)));
+	/**
+	* The one dev deployment with this reference, or the one preview
+	* deployment with this preview name, or undefined.
+	*/
+	const findByName = (management, projectId, type, name) => Effect.gen(function* () {
+		const matches = (yield* listDeployments(management, projectId, type)).filter((row) => row.deploymentType === type && (type === "dev" ? row.reference === name : row.previewIdentifier === name));
+		if (matches.length > 1) return yield* new AmbiguousDeployment({
+			projectId,
+			type,
+			name,
+			deployments: matches.map((row) => row.name)
+		});
+		return matches[0];
+	});
+	/** The deployment that the address names, through the Management API, or undefined. */
+	const lookup = (management, address) => address.type === "prod" || address.name === void 0 ? production(management, address.projectId) : findByName(management, address.projectId, address.type, address.name).pipe(Effect.map((row) => row === void 0 ? void 0 : targetOf(row, address.type, address.name)));
+	/** The deployment of a deploy key, when it is the deployment that the address names. */
+	const deployKeyTarget = (key, deployment, address) => Effect.gen(function* () {
+		const info = Schema.decodeUnknownSync(DeploymentInfo)(yield* api.deploymentRequest("get deployment info", deployment, key, (client) => client.GET("/deployment_info")));
+		const reference = info.reference ?? "";
+		if (info.projectId !== address.projectId || info.deploymentType !== address.type || address.type === "dev" && reference !== address.name) return;
+		const urls = Schema.decodeUnknownSync(CanonicalUrls)(yield* api.deploymentRequest("get canonical urls", deployment, key, (client) => client.GET("/get_canonical_urls")));
+		return {
+			projectId: info.projectId,
+			type: address.type,
+			name: deployment,
+			reference,
+			previewName: void 0,
+			url: urls.convexCloudUrl,
+			siteUrl: urls.convexSiteUrl
+		};
+	}).pipe(Effect.catchIf(isRefused, () => Effect.succeed(void 0)));
+	/** True when the preview deploy key belongs to the project. */
+	const previewKeyFits = (management, slugs, projectId) => management.request("get project", (client) => client.GET("/projects/{project_id}", { params: { path: { project_id: projectId } } })).pipe(Effect.map((body) => {
+		const project = Schema.decodeUnknownSync(ProjectSlugs)(body);
+		return project.slug === slugs.project && project.teamSlug === slugs.team;
+	}), Effect.catchIf(isRefused, () => Effect.succeed(false)));
+	/**
+	* The narrowest credential that reaches the deployment. See {@link Access}.
+	* When `changesEnv`, a preview deploy key gives way to the access token,
+	* because it cannot change variables.
+	*/
+	const accessFor = (address, changesEnv) => Effect.gen(function* () {
+		const key = yield* credentials.deployKey;
+		if (key !== void 0) {
+			const target = keyTargetOf(Redacted.value(key));
+			if (target.kind === "deployment" && address.type !== "preview") {
+				const found = yield* deployKeyTarget(key, target.deployment, address);
+				if (found !== void 0) return {
+					kind: "deployKey",
+					key,
+					target: found
+				};
+			}
+			if (target.kind === "preview" && address.type === "preview") {
+				const scoped = api.withToken(key);
+				if (!(changesEnv && (yield* credentials.hasAccessToken)) && (yield* previewKeyFits(scoped, target, address.projectId))) return {
+					kind: "previewKey",
+					key,
+					api: scoped
+				};
+			}
+		}
+		return {
+			kind: "token",
+			api
+		};
+	});
+	/** The live deployment of a resource in state, or undefined when it is gone. */
+	const live = (access, output) => Effect.gen(function* () {
+		if (access.kind === "deployKey") return access.target;
+		if (output.type === "prod") return yield* absentAsUndefined(production(access.api, output.projectId));
+		const row = yield* getByName(access.api, output.name);
+		return row === void 0 ? void 0 : targetOf(row, output.type, output.previewName);
+	});
+	/** The content identity of `source` and `env` on a deployment, or undefined when there is nothing to push. */
+	const wantedHash = (news, rootDir, deployment) => news.source === void 0 && Object.keys(news.env ?? {}).length === 0 ? Effect.succeed(void 0) : pushHash({
+		rootDir,
+		source: news.source,
+		deployment,
+		env: news.env ?? {}
+	});
+	return {
+		stables: [
+			"projectId",
+			"type",
+			"previewName"
+		],
+		diff: Effect.fn(function* ({ news, olds, output, oldBindings, newBindings }) {
+			if (!isResolved(news) || output === void 0) return void 0;
+			yield* checkIdentity(output, news);
+			if (!isResolved(newBindings)) return void 0;
+			const rootDir = news.rootDir ?? ".";
+			if (news.source !== void 0) yield* checkSource(rootDir, news.source);
+			if (olds.rootDir !== rootDir) return { action: "update" };
+			const access = yield* accessFor(addressOf(news), changesEnv(news, output));
+			const current = yield* live(access, output);
+			if (current?.name !== output.name) return { action: "update" };
+			if ((yield* wantedHash(news, rootDir, output.name)) !== output.hash) return { action: "update" };
+			if (diffBindings(oldBindings, newBindings).every((binding) => binding.action === "noop")) return { action: "noop" };
+			return {
+				action: "update",
+				stables: [
+					"hash",
+					"envNames",
+					...[
+						"projectId",
+						"type",
+						"previewName",
+						"name",
+						"reference",
+						"url",
+						"siteUrl"
+					].filter((key) => current[key] === output[key])
+				]
+			};
+		}),
+		read: Effect.fn(function* ({ olds, output }) {
+			if (output !== void 0) {
+				const access = yield* accessFor(addressInState(output), false);
+				const current = yield* live(access, output);
+				return current === void 0 ? void 0 : {
+					...output,
+					...current
+				};
+			}
+			const address = addressOf(olds);
+			const access = yield* accessFor(address, false);
+			if (access.kind === "deployKey") return Unowned({
+				...access.target,
+				hash: void 0,
+				envNames: []
+			});
+			if (olds.type === "prod") {
+				const row = yield* productionRow(access.api, address.projectId);
+				if (row === void 0) return void 0;
+				const attributes = {
+					...targetOf(row, "prod", void 0),
+					hash: void 0,
+					envNames: []
+				};
+				return isDeployed(row) ? Unowned(attributes) : attributes;
+			}
+			const found = yield* lookup(access.api, address);
+			if (found === void 0) return void 0;
+			return Unowned({
+				...found,
+				hash: void 0,
+				envNames: []
+			});
+		}),
+		reconcile: Effect.fn(function* ({ fqn, news, output }) {
+			if (output !== void 0) yield* checkIdentity(output, news);
+			const rootDir = news.rootDir ?? ".";
+			if (news.source !== void 0) yield* checkSource(rootDir, news.source);
+			const address = addressOf(news);
+			const access = yield* accessFor(address, changesEnv(news, output));
+			const env = news.env ?? {};
+			if (access.kind === "previewKey" && changesEnv(news, output)) return yield* new EnvironmentNeedsDeployKey({ deployment: output?.name ?? address.name ?? "(new)" });
+			const adopt = yield* shouldAdopt(fqn);
+			const refuse = (name) => new OwnedBySomeoneElse({
+				message: `Project ${address.projectId} already has ${news.type} deployment ${name}${news.type === "prod" ? " with code" : ` named "${news.name}"`}. Re-run with --adopt to take it over${news.type === "prod" ? "" : ", or use another name"}.`,
+				resourceType: DeploymentResource.Type,
+				physicalName: name
+			});
+			const { target, created } = yield* Effect.gen(function* () {
+				if (access.kind === "deployKey") {
+					if (output === void 0 && !adopt) return yield* refuse(access.target.name);
+					return {
+						target: access.target,
+						created: false
+					};
+				}
+				if (news.type === "prod") {
+					const row = yield* productionRow(access.api, address.projectId);
+					if (row === void 0) return yield* new ProductionDeploymentNotFound({ projectId: address.projectId });
+					if (output === void 0 && isDeployed(row) && !adopt) return yield* refuse(row.name);
+					return {
+						target: targetOf(row, "prod", void 0),
+						created: false
+					};
+				}
+				if (output !== void 0) {
+					const row = yield* getByName(access.api, output.name);
+					if (row !== void 0) {
+						if (row.deploymentType !== output.type) return yield* new DeploymentIdentityChange({
+							deployment: row.name,
+							field: "type",
+							current: row.deploymentType,
+							requested: news.type
+						});
+						const current = targetOf(row, output.type, output.previewName);
+						yield* checkIdentity(current, news);
+						return {
+							target: current,
+							created: false
+						};
+					}
+				}
+				const existing = yield* lookup(access.api, address);
+				if (existing !== void 0) {
+					if (!adopt) return yield* refuse(existing.name);
+					return {
+						target: existing,
+						created: false
+					};
+				}
+				const row = yield* access.api.request("create deployment", (client) => client.POST("/projects/{project_id}/create_deployment", {
+					params: { path: { project_id: address.projectId } },
+					body: {
+						type: news.type,
+						reference: news.name
+					}
+				}));
+				return {
+					target: targetOf(Schema.decodeUnknownSync(DeploymentRow$1)(row), news.type, news.name),
+					created: true
+				};
+			});
+			const previousEnvNames = output?.name === target.name ? envNamesOf(output) : [];
+			const before = yield* wantedHash(news, rootDir, target.name);
+			if (before === void 0 && previousEnvNames.length === 0) return {
+				...target,
+				hash: void 0,
+				envNames: []
+			};
+			if (output?.name === target.name && before === output.hash) return {
+				...target,
+				hash: output.hash,
+				envNames: previousEnvNames
+			};
+			const options = {
+				deployment: target.name,
+				url: target.url,
+				rootDir,
+				source: news.source,
+				env,
+				previousEnvNames,
+				adopt
+			};
+			yield* (access.kind === "deployKey" ? push(spawner, access.key, {
+				...options,
+				previewName: void 0
+			}) : access.kind === "previewKey" ? push(spawner, access.key, {
+				...options,
+				previewName: target.previewName
+			}) : withPushKey(access.api, target.name, typeof news.source === "object" && news.source.command !== void 0 ? void 0 : PUSH_KEY_ACTIONS, (key) => push(spawner, key, {
+				...options,
+				previewName: void 0
+			}))).pipe(Effect.onError(() => created && access.kind !== "deployKey" ? absentAsUndefined(retryIdempotentWrite(access.api.requestVoid("delete deployment", (client) => client.POST("/deployments/{deployment_name}/delete", { params: { path: { deployment_name: target.name } } })))).pipe(Effect.catch((error) => Effect.logWarning(`Convex.Deployment could not delete ${target.name} after the failed push (${error.message}). The next run takes it over only with --adopt.`))) : Effect.void));
+			return {
+				...target,
+				hash: yield* wantedHash(news, rootDir, target.name),
+				envNames: Object.keys(env).sort()
+			};
+		}),
+		delete: Effect.fn(function* ({ output }) {
+			const keep = Effect.logWarning(`Convex.Deployment does not delete production deployment ${output.name}: it belongs to project ${output.projectId}. To delete it, delete the project with RemovalPolicy.destroy() on Convex.Project.`);
+			if (output.type === "prod") return yield* keep;
+			const access = yield* accessFor(addressInState(output), false);
+			const management = access.kind === "deployKey" ? api : access.api;
+			const row = yield* getByName(management, output.name);
+			if (row === void 0) return;
+			if (row.deploymentType === "prod") return yield* keep;
+			yield* absentAsUndefined(retryIdempotentWrite(management.requestVoid("delete deployment", (client) => client.POST("/deployments/{deployment_name}/delete", { params: { path: { deployment_name: output.name } } }))));
+		})
+	};
+}));
+//#endregion
+//#region src/Project.ts
+const Project = Resource("Convex.Project", { defaultRemovalPolicy: "retain" });
+/** The props change the team of an existing project. Convex cannot move a project. */
+var ProjectTeamChange = class extends Schema.TaggedError()("ProjectTeamChange", {
+	projectId: Schema.Number,
+	teamId: Schema.Number,
+	requestedTeamId: Schema.Number
+}) {
+	get message() {
+		return `Convex.Project cannot move project ${this.projectId} from team ${this.teamId} to team ${this.requestedTeamId}. Set team back to ${this.teamId}. To use the other team, create a new resource with a new logical id and move the data yourself.`;
+	}
+};
+/**
+* The props change `deploymentType` or `deploymentRegion` of an existing
+* project. Convex uses them only when it creates the project.
+*/
+var ProjectDeploymentChange = class extends Schema.TaggedError()("ProjectDeploymentChange", {
+	projectId: Schema.Number,
+	field: Schema.Literals(["deploymentType", "deploymentRegion"]),
+	current: Schema.UndefinedOr(Schema.String),
+	requested: Schema.UndefinedOr(Schema.String)
+}) {
+	get message() {
+		const show = (value) => value === void 0 ? "(not set)" : value;
+		return `Convex.Project cannot change ${this.field} of project ${this.projectId} from ${show(this.current)} to ${show(this.requested)}: Convex uses it only when it creates a project. Set ${this.field} back to ${show(this.current)}. For a new deployment, create a new resource with a new logical id and move the data yourself.`;
+	}
+};
+/** More than one project in the team has the name, so the lookup cannot choose one. */
+var AmbiguousProject = class extends Schema.TaggedError()("AmbiguousProject", {
+	teamId: Schema.Number,
+	name: Schema.String,
+	projectIds: Schema.Array(Schema.Number)
+}) {
+	get message() {
+		return `Team ${this.teamId} has ${this.projectIds.length} projects named "${this.name}" (ids ${this.projectIds.join(", ")}). Convex.Project does not choose one. Rename the projects in the Convex dashboard so that only one has this name, or use a different name.`;
+	}
+};
+/** Convex answered a create call but then did not return the project. */
+var CreatedProjectNotFound = class extends Schema.TaggedError()("CreatedProjectNotFound", { projectId: Schema.Number }) {
+	get message() {
+		return `Convex created project ${this.projectId} but GET /projects/${this.projectId} did not return it. Run the deploy again with --adopt to take over project ${this.projectId}.`;
+	}
+};
+/** No project in the team has the slug. A `slug` resource never creates one. */
+var ProjectNotFound = class extends Schema.TaggedError()("ProjectNotFound", {
+	team: Schema.String,
+	slug: Schema.String
+}) {
+	get message() {
+		return `Team ${this.team} has no project with the slug "${this.slug}", and a Convex.Project with a slug never creates one. Check the slug in the project URL of the Convex dashboard, or use name to create a project.`;
+	}
+};
+/** The props change the slug of a `slug` resource: that is another project. */
+var ProjectSlugChange = class extends Schema.TaggedError()("ProjectSlugChange", {
+	projectId: Schema.Number,
+	slug: Schema.String,
+	requestedSlug: Schema.String
+}) {
+	get message() {
+		return `Convex.Project ${this.projectId} has the slug "${this.slug}", and the props ask for "${this.requestedSlug}", which is another project. Set slug back to "${this.slug}". For the other project, create a new resource with a new logical id.`;
+	}
+};
+/** Fields of GET /projects/{id}, PATCH /projects/{id}, and GET /teams/{team}/projects rows that the provider uses. */
+const ProjectDetails = Schema.Struct({
+	id: Schema.Number,
+	name: Schema.String,
+	slug: Schema.String,
+	teamId: Schema.Number,
+	teamSlug: Schema.String,
+	prodDeploymentName: Schema.NullOr(Schema.String)
+});
+/** GET /teams/{team_id}/projects: one page of projects. */
+const ProjectPage = Schema.Struct({
+	items: Schema.Array(ProjectDetails),
+	pagination: Schema.Struct({
+		hasMore: Schema.Boolean,
+		nextCursor: Schema.optionalKey(Schema.NullOr(Schema.String))
+	})
+});
+/** POST /teams/{team_id}/create_project. Only the id: everything else comes from GET /projects/{id}. */
+const CreatedProject = Schema.Struct({ projectId: Schema.Number });
+const DeploymentRow = Schema.Struct({
+	name: Schema.String,
+	deploymentType: Schema.String,
+	isDefault: Schema.Boolean,
+	deploymentUrl: Schema.String,
+	/** Absent or null until the first push. */
+	lastDeployTime: Schema.optionalKey(Schema.NullOr(Schema.Number))
+});
+const DeploymentRows = Schema.Array(DeploymentRow);
+/**
+* Fails with {@link ProjectDeploymentChange} when a create-time prop
+* changed. An omitted `deploymentType` means `prod`.
+*/
+const checkCreateTimeProps = (projectId, olds, news) => {
+	const oldType = olds.deploymentType ?? "prod";
+	const newType = news.deploymentType ?? "prod";
+	if (oldType !== newType) return Effect.fail(new ProjectDeploymentChange({
+		projectId,
+		field: "deploymentType",
+		current: oldType,
+		requested: newType
+	}));
+	if (olds.deploymentRegion !== news.deploymentRegion) return Effect.fail(new ProjectDeploymentChange({
+		projectId,
+		field: "deploymentRegion",
+		current: olds.deploymentRegion,
+		requested: news.deploymentRegion
+	}));
+	return Effect.void;
+};
+/** True when `team`, a slug or a numeric id, names the team of the project. */
+const isTeamOf = (details, team) => typeof team === "number" || /^\d+$/.test(team) ? details.teamId === Number(team) : details.teamSlug === team;
+/** The row of the project's default production deployment, or undefined. */
+const prodDeploymentOf = (api, projectId) => api.request("list deployments", (client) => client.GET("/projects/{project_id}/list_deployments", { params: { path: { project_id: projectId } } })).pipe(Effect.map((rows) => Schema.decodeUnknownSync(DeploymentRows)(rows).find((row) => row.deploymentType === "prod" && row.isDefault)));
+/** GET /projects/{id}, or undefined after a 404. */
+const getProjectById = (api, projectId) => absentAsUndefined(api.request("get project", (client) => client.GET("/projects/{project_id}", { params: { path: { project_id: projectId } } }))).pipe(Effect.map((body) => body === void 0 ? void 0 : Schema.decodeUnknownSync(ProjectDetails)(body)));
+/**
+* Every project in the team with exactly this name, in the order of the
+* listing. Reads every page. `q` narrows the listing on the server, and the
+* exact match here decides. Pattern from Confect
+* `packages/alchemy/src/ConvexClient.ts` and `Project.ts`
+* (https://github.com/rjdellecese/confect, ISC license).
+*/
+const listProjectsByName = (api, teamId, name) => Effect.gen(function* () {
+	const matches = [];
+	const seenCursors = /* @__PURE__ */ new Set();
+	let cursor;
+	while (true) {
+		const body = yield* api.request("list projects", (client) => client.GET("/teams/{team_id}/projects", { params: {
+			path: { team_id: teamId },
+			query: {
+				q: name,
+				...cursor === void 0 ? {} : { cursor }
+			}
+		} }));
+		const page = Schema.decodeUnknownSync(ProjectPage)(body);
+		matches.push(...page.items.filter((row) => row.name === name));
+		if (!page.pagination.hasMore) break;
+		const next = page.pagination.nextCursor;
+		if (next === void 0 || next === null || seenCursors.has(next)) return yield* new ConvexApiError({
+			operation: "list projects",
+			status: 0,
+			code: "InvalidPagination",
+			message: `The project listing of team ${teamId} reports more pages but gives no new cursor. Convex.Project stops so that it does not miss a project named "${name}".`
+		});
+		seenCursors.add(next);
+		cursor = next;
+	}
+	return matches;
+});
+/** The one project in the team with exactly this name, or undefined. More than one is an error. */
+const findProjectByName = (api, teamId, name) => listProjectsByName(api, teamId, name).pipe(Effect.flatMap((matches) => matches.length > 1 ? new AmbiguousProject({
+	teamId,
+	name,
+	projectIds: matches.map((row) => row.id)
+}) : Effect.succeed(matches[0])));
+/**
+* POST /teams/{team_id}/create_project, then GET /projects/{id}. The identity
+* comes from the create response, never from a name lookup.
+*/
+const createProject = (api, teamId, props) => Effect.gen(function* () {
+	const created = yield* api.request("create project", (client) => client.POST("/teams/{team_id}/create_project", {
+		params: { path: { team_id: teamId } },
+		body: {
+			projectName: props.name,
+			deploymentType: props.deploymentType,
+			...props.deploymentRegion === void 0 ? {} : { deploymentRegion: props.deploymentRegion }
+		}
+	}));
+	const { projectId } = Schema.decodeUnknownSync(CreatedProject)(created);
+	const details = yield* getProjectById(api, projectId);
+	if (details === void 0) return yield* new CreatedProjectNotFound({ projectId });
+	return details;
+});
+const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
+	const api = yield* ManagementApi;
+	const attributesOf = (details) => prodDeploymentOf(api, details.id).pipe(Effect.map((prod) => ({
+		projectId: details.id,
+		slug: details.slug,
+		name: details.name,
+		teamId: details.teamId,
+		prodDeploymentName: prod?.name ?? details.prodDeploymentName ?? void 0,
+		prodDeploymentUrl: prod?.deploymentUrl
+	})));
+	const getById = (projectId) => getProjectById(api, projectId);
+	/** The project with this slug in the team, or undefined. Official endpoint; the team can be a slug. */
+	const getBySlug = (team, slug) => absentAsUndefined(api.request("get project by slug", (client) => client.GET("/teams/{team_id_or_slug}/projects/{project_slug}", { params: { path: {
+		team_id_or_slug: String(team),
+		project_slug: slug
+	} } }))).pipe(Effect.map((body) => body === void 0 ? void 0 : Schema.decodeUnknownSync(ProjectDetails)(body)));
+	const findByName = (teamId, name) => findProjectByName(api, teamId, name);
+	/**
+	* Brings an existing project to the desired name. The team cannot
+	* change, so a project in another team fails.
+	*/
+	const converge = (details, teamId, name) => Effect.gen(function* () {
+		if (details.teamId !== teamId) return yield* new ProjectTeamChange({
+			projectId: details.id,
+			teamId: details.teamId,
+			requestedTeamId: teamId
+		});
+		if (details.name === name) return yield* attributesOf(details);
+		const updated = yield* api.request("update project", (client) => client.PATCH("/projects/{project_id}", {
+			params: { path: { project_id: details.id } },
+			body: { name }
+		}));
+		return yield* attributesOf(Schema.decodeUnknownSync(ProjectDetails)(updated));
+	});
+	return {
+		stables: [
+			"projectId",
+			"slug",
+			"teamId"
+		],
+		diff: Effect.fn(function* ({ olds, news, output }) {
+			if (!isResolved(news)) return void 0;
+			if (output === void 0) return void 0;
+			if ("slug" in news) {
+				if (news.slug !== output.slug) return yield* new ProjectSlugChange({
+					projectId: output.projectId,
+					slug: output.slug,
+					requestedSlug: news.slug
+				});
+				if (olds.team !== news.team) {
+					const details = yield* getById(output.projectId);
+					if (details !== void 0 && !isTeamOf(details, news.team)) return yield* new ProjectTeamChange({
+						projectId: output.projectId,
+						teamId: output.teamId,
+						requestedTeamId: yield* api.resolveTeamId(news.team)
+					});
+				}
+				return { action: "noop" };
+			}
+			if (olds.team !== news.team) {
+				const requestedTeamId = yield* api.resolveTeamId(news.team);
+				if (requestedTeamId !== output.teamId) return yield* new ProjectTeamChange({
+					projectId: output.projectId,
+					teamId: output.teamId,
+					requestedTeamId
+				});
+			}
+			return "name" in olds && olds.name === news.name ? void 0 : { action: "update" };
+		}),
+		read: Effect.fn(function* ({ olds, output }) {
+			if (output !== void 0) {
+				const details = yield* getById(output.projectId);
+				return details === void 0 ? void 0 : yield* attributesOf(details);
+			}
+			const existing = "slug" in olds ? yield* getBySlug(olds.team, olds.slug) : yield* findByName(yield* api.resolveTeamId(olds.team), olds.name);
+			return existing === void 0 ? void 0 : Unowned(yield* attributesOf(existing));
+		}),
+		reconcile: Effect.fn(function* ({ fqn, olds, news, output }) {
+			if ("slug" in news) {
+				const details = output === void 0 ? yield* getBySlug(news.team, news.slug) : yield* getById(output.projectId);
+				if (details === void 0) return yield* new ProjectNotFound({
+					team: String(news.team),
+					slug: news.slug
+				});
+				if (details.slug !== news.slug) return yield* new ProjectSlugChange({
+					projectId: details.id,
+					slug: details.slug,
+					requestedSlug: news.slug
+				});
+				if (!isTeamOf(details, news.team)) return yield* new ProjectTeamChange({
+					projectId: details.id,
+					teamId: details.teamId,
+					requestedTeamId: yield* api.resolveTeamId(news.team)
+				});
+				if (output === void 0 && !(yield* shouldAdopt(fqn))) return yield* new OwnedBySomeoneElse({
+					message: `Convex project ${details.id} ("${news.slug}") exists and is not in this stack's state. Re-run with --adopt to take it over.`,
+					resourceType: Project.Type,
+					physicalName: news.slug
+				});
+				return yield* attributesOf(details);
+			}
+			const teamId = yield* api.resolveTeamId(news.team);
+			if (output !== void 0) {
+				if (olds !== void 0 && "name" in olds) yield* checkCreateTimeProps(output.projectId, olds, news);
+				if (output.teamId !== teamId) return yield* new ProjectTeamChange({
+					projectId: output.projectId,
+					teamId: output.teamId,
+					requestedTeamId: teamId
+				});
+				const details = yield* getById(output.projectId);
+				if (details !== void 0) return yield* converge(details, teamId, news.name);
+			} else {
+				const existing = yield* findByName(teamId, news.name);
+				if (existing !== void 0) {
+					if (!(yield* shouldAdopt(fqn))) return yield* new OwnedBySomeoneElse({
+						message: `Convex project ${existing.id} in team ${teamId} already has the name "${news.name}". Re-run with --adopt to take it over, or use a different name.`,
+						resourceType: Project.Type,
+						physicalName: news.name
+					});
+					return yield* converge(existing, teamId, news.name);
+				}
+			}
+			const details = yield* createProject(api, teamId, {
+				name: news.name,
+				deploymentType: news.deploymentType ?? "prod",
+				deploymentRegion: news.deploymentRegion
+			});
+			return yield* converge(details, teamId, news.name);
+		}),
+		delete: Effect.fn(function* ({ output }) {
+			yield* absentAsUndefined(api.requestVoid("delete project", (client) => client.POST("/projects/{project_id}/delete", { params: { path: { project_id: output.projectId } } })));
+		})
+	};
+}));
+//#endregion
+//#region src/RunRecord.ts
+/** The key of the record in the stage output document. */
+const RUN_RECORD_KEY = "samebase.run";
+/** The name of the stack file. Alchemy resolves `--config` against the working directory and does not expose it to a state layer, so the record assumes the default name. */
+const STACK_FILE_NAME = "alchemy.run.ts";
+var RunRecordError = class extends Schema.TaggedError()("RunRecordError", { reason: Schema.String }) {
+	get message() {
+		return `The run record of the stage output cannot be made: ${this.reason}`;
+	}
+};
+/** The part of the GitHub Actions event payload that the record reads. A push event has no `pull_request`. */
+const EventPayload = Schema.Struct({ pull_request: Schema.optionalKey(Schema.Struct({
+	number: Schema.Number,
+	head: Schema.Struct({ sha: Schema.String })
+})) });
+/** `owner/name` of an https, ssh, or scp-like git URL with a host. A local path is not one. */
+const REMOTE_URL = /^(?:[a-z+]+:\/\/[^/]+\/|[^/@:]+@[^:/]+:)([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
+const execFileAsync = promisify(execFile);
+const now = Clock.currentTimeMillis.pipe(Effect.map((millis) => new Date(millis).toISOString()));
+const git = (cwd, args) => Effect.tryPromise({
+	try: async () => (await execFileAsync("git", [
+		"-C",
+		cwd,
+		...args
+	], { encoding: "utf8" })).stdout.trim(),
+	catch: (error) => new RunRecordError({ reason: `git ${args.join(" ")} failed in ${cwd} (${error instanceof Error ? error.message.split("\n")[0] : String(error)})` })
+});
+/** The stack file from the repository root: the working directory below the git top level, plus {@link STACK_FILE_NAME}. */
+const stackFileOf = (cwd) => Effect.gen(function* () {
+	const top = yield* git(cwd, ["rev-parse", "--show-toplevel"]);
+	const [realTop, realCwd] = yield* Effect.tryPromise({
+		try: () => Promise.all([realpath(top), realpath(cwd)]),
+		catch: () => new RunRecordError({ reason: `${cwd} is gone` })
+	});
+	return [...relative(realTop, realCwd).split(sep).filter((part) => part !== ""), STACK_FILE_NAME].join("/");
+});
+const variable = (env, name) => Effect.suspend(() => {
+	const value = env[name];
+	return value === void 0 || value === "" ? Effect.fail(new RunRecordError({ reason: `GITHUB_ACTIONS is true, and ${name} is not set` })) : Effect.succeed(value);
+});
+const fromGitHubActions = (where) => Effect.gen(function* () {
+	const { env } = where;
+	const repository = yield* variable(env, "GITHUB_REPOSITORY");
+	const refName = yield* variable(env, "GITHUB_REF_NAME");
+	const sha = yield* variable(env, "GITHUB_SHA");
+	const serverUrl = yield* variable(env, "GITHUB_SERVER_URL");
+	const runId = yield* variable(env, "GITHUB_RUN_ID");
+	const runAttempt = yield* variable(env, "GITHUB_RUN_ATTEMPT");
+	const eventPath = env["GITHUB_EVENT_PATH"];
+	const pullRequest = (eventPath === void 0 || eventPath === "" ? void 0 : yield* Effect.tryPromise({
+		try: () => readFile(eventPath, "utf8"),
+		catch: () => new RunRecordError({ reason: `GITHUB_EVENT_PATH ${eventPath} cannot be read` })
+	}).pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(EventPayload))), Effect.mapError((error) => error instanceof RunRecordError ? error : new RunRecordError({ reason: `GITHUB_EVENT_PATH ${eventPath} is not an event payload` }))))?.pull_request;
+	const headCommit = pullRequest?.head.sha ?? sha;
+	const headRef = env["GITHUB_HEAD_REF"];
+	const mergeRef = /^refs\/pull\/(\d+)\/merge$/.exec(env["GITHUB_REF"] ?? "");
+	return {
+		version: 1,
+		repository,
+		stackFile: yield* stackFileOf(where.cwd),
+		branch: headRef === void 0 || headRef === "" ? refName : headRef,
+		pullRequest: pullRequest?.number ?? (mergeRef === null ? null : Number(mergeRef[1])),
+		headCommit,
+		runUrl: `${serverUrl}/${repository}/actions/runs/${runId}/attempts/${runAttempt}`,
+		source: "github-actions",
+		recordedAt: yield* now
+	};
+});
+const fromGit = (where) => Effect.gen(function* () {
+	const { cwd } = where;
+	const origin = yield* git(cwd, [
+		"remote",
+		"get-url",
+		"origin"
+	]);
+	const match = REMOTE_URL.exec(origin);
+	if (match === null) return yield* new RunRecordError({ reason: `the origin remote of ${cwd} is not a git URL with a host and owner/name: ${origin}` });
+	const branch = yield* git(cwd, [
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	]);
+	if (branch === "HEAD") return yield* new RunRecordError({ reason: `the checkout at ${cwd} is on no branch (detached HEAD)` });
+	return {
+		version: 1,
+		repository: `${match[1]}/${match[2]}`,
+		stackFile: yield* stackFileOf(cwd),
+		branch,
+		pullRequest: null,
+		headCommit: yield* git(cwd, ["rev-parse", "HEAD"]),
+		runUrl: null,
+		source: "laptop",
+		recordedAt: yield* now
+	};
+});
+/**
+* The record of this run: from the GitHub Actions variables and the event
+* payload when GITHUB_ACTIONS is `true`, else from git in `cwd`, which needs
+* a branch and an `origin` remote with `owner/name`. Fails when a value is
+* missing; nothing is guessed.
+*/
+const runRecord = (where) => where.env["GITHUB_ACTIONS"] === "true" ? fromGitHubActions(where) : fromGit(where);
+/** A plain object, which a spread keeps whole. A Date, a Duration, or a Redacted value is an object too, and a spread loses it. */
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+/**
+* The output document of a stage: the stack's output plus the record under
+* {@link RUN_RECORD_KEY}, or undefined for an output with no place for the
+* key: a string, an array, null, or an object that is not plain, such as a
+* Date. A value that the stack itself put under the key stays.
+*/
+const withRunRecord = (output, record) => isPlainObject(output) ? "samebase.run" in output ? output : {
+	...output,
+	[RUN_RECORD_KEY]: record
+} : void 0;
+//#endregion
+//#region src/State.ts
+/** The name of the state project in each team. */
+const STORE_PROJECT_NAME = "samebase";
+/**
+* The actions of the key of one run: the internal queries and mutations of
+* the store, nothing else. Measured: `deployment:data:view` and
+* `deployment:data:write` do not run an internal function.
+*/
+const RUN_KEY_ACTIONS = ["deployment:functions:runInternalQueries", "deployment:functions:runInternalMutations"];
+/** The body of POST /api/function, with HTTP 200 for a function error too. */
+const Reply = Schema.Union([Schema.Struct({
+	status: Schema.Literal("success"),
+	value: Schema.Unknown
+}), Schema.Struct({
+	status: Schema.Literal("error"),
+	errorMessage: Schema.String
+})]);
+/** The error reply of /api/function for a function that the deployment does not have (recorded). */
+const MISSING_FUNCTION = /Could not find function for '/;
+/** HTTP 401 or 403 from the function API: the key is gone or expired (recorded: 403 without a key). */
+const isUnauthorized = (error) => error.http?.status === 401 || error.http?.status === 403;
+const failure = (message) => new StateStoreError({ message: `Convex state: ${message}` });
+/** No reply, HTTP 429, or HTTP 5xx: a new attempt can succeed. Every call of the store is idempotent. */
+const isTransient = (error) => error.http !== void 0 && (error.http.status === void 0 || error.http.status === 429 || error.http.status >= 500);
+const post = (url, headers, body) => Effect.tryPromise({
+	try: () => fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			...headers
+		},
+		body: JSON.stringify(body)
+	}),
+	catch: () => new StateStoreError({
+		message: `Convex state: POST ${url} failed`,
+		http: {}
+	})
+}).pipe(Effect.flatMap((response) => response.ok || response.status === 560 ? Effect.tryPromise({
+	try: () => response.json(),
+	catch: () => failure(`${url} gave no JSON`)
+}) : Effect.fail(new StateStoreError({
+	message: `Convex state: POST ${url} failed with HTTP ${response.status}`,
+	http: { status: response.status }
+}))), Effect.retry({
+	while: isTransient,
+	schedule: Schedule.exponential("100 millis").pipe(Schedule.jittered),
+	times: 5
+}));
+const decode = (schema, what) => (value) => Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => failure(`bad ${what}`)));
+const makeFunctionApi = (url, key) => ({ call: (path, args) => post(`${url}/api/function`, { Authorization: `Convex ${Redacted.value(key)}` }, {
+	path,
+	args,
+	format: "json"
+}).pipe(Effect.flatMap(decode(Reply, `reply of ${path}`))) });
+/** The value of a reply, or the Convex message, which names the function and the cause, such as a missing key action. */
+const valueOf = (reply) => reply.status === "success" ? Effect.succeed(reply.value) : Effect.fail(failure(reply.errorMessage.trim()));
+/** The functions of the store with Alchemy's encoding: the JSON text of encodeState. */
+const remoteOf = (api, record) => {
+	const run = (name, args) => api.call(`state:${name}`, args).pipe(Effect.flatMap(valueOf));
+	const write = (name, args) => Effect.gen(function* () {
+		const currentRun = record === void 0 ? void 0 : {
+			...record,
+			recordedAt: new Date(yield* Clock.currentTimeMillis).toISOString()
+		};
+		return yield* run(name, {
+			...args,
+			run: currentRun
+		});
+	});
+	const strings = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.Array(Schema.String), name)));
+	const optional = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.NullOr(Schema.String), name)));
+	const encode = (value) => JSON.stringify(encodeState(value));
+	return {
+		listStacks: () => strings("stacks", {}),
+		listStages: (stack) => strings("stages", { stack }),
+		list: (r) => strings("list", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		get: (r) => optional("get", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		getReplacedResources: (r) => strings("replaced", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((texts) => texts.map((text) => JSON.parse(text, reviveState)))),
+		getOutput: (r) => optional("getOutput", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		set: (r) => write("set", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn,
+			value: encode(r.value)
+		}),
+		delete: (r) => write("remove", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}),
+		deleteStack: (r) => run("removeStack", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		setOutput: (r) => write("setOutput", {
+			stack: r.stack,
+			stage: r.stage,
+			value: encode(r.value)
+		})
+	};
+};
+/** The version that the store answers, or undefined when the deployment has no `state:version`. */
+const storeVersion = (api) => api.call("state:version", {}).pipe(Effect.flatMap((reply) => reply.status === "error" && MISSING_FUNCTION.test(reply.errorMessage) ? Effect.succeed(void 0) : valueOf(reply).pipe(Effect.flatMap(decode(Schema.Number, "store version")))));
+/**
+* The app that serves the store. A store without `state:host` is a seed: it
+* was pushed before 0.14.0, and only the store app of this package served
+* those stores.
+*/
+const storeHost = (api) => api.call("state:host", {}).pipe(Effect.flatMap((reply) => reply.status === "error" && MISSING_FUNCTION.test(reply.errorMessage) ? Effect.succeed("seed") : valueOf(reply).pipe(Effect.flatMap(decode(Schema.Literals(["seed", "base"]), "store host")))));
+/**
+* The base app of the team serves an older store. Convex.state() never
+* pushes its store app over a base, because the push replaces every function
+* of the deployment and so erases the base app.
+*/
+var OutdatedBase = class extends Schema.TaggedError()("OutdatedBase", {
+	team: Schema.Union([Schema.String, Schema.Number]),
+	deployment: Schema.String,
+	version: Schema.Number
+}) {
+	get message() {
+		return `The base of team ${this.team} (${this.deployment}) answers store version ${this.version}, and this package needs store version 4. Convex.state does not push over a base. Upgrade the dependency @samebase/alchemy-convex of the base app to the version of this package, and push the base app.`;
+	}
+};
+/**
+* The functions directory of the store app, `src/store/convex` of this
+* package. This file is `src/State.ts` in a checkout and a chunk in `lib/`
+* in the installed package, which ships `src` too, so the directory is
+* `../src/store/convex` from either place. Its `convex.config.ts` mounts the
+* alchemyState component of `src/store/component`, inside the same push root.
+*/
+const storeDirectory = () => join(dirname(fileURLToPath(import.meta.url)), "..", "src", "store", "convex");
+/**
+* Pushes `store` to the production deployment of the state project with the
+* installed Convex CLI: no typecheck, no codegen, the key only in the
+* environment of the CLI.
+*/
+const pushStore = (options, deployment) => Effect.gen(function* () {
+	const cli = yield* installedCli(join(options.store, ".."));
+	yield* Effect.logInfo(`Convex state: pushing the store version 4 to ${deployment.name}`);
+	yield* withPushKey(options.api, deployment.name, PUSH_KEY_ACTIONS, (key) => push(options.spawner, key, {
+		deployment: deployment.name,
+		url: deployment.deploymentUrl,
+		rootDir: join(options.store, ".."),
+		source: {
+			path: options.store,
+			command: [
+				...cli,
+				"deploy",
+				"--typecheck",
+				"disable",
+				"--codegen",
+				"disable"
+			]
+		},
+		env: {},
+		previousEnvNames: [],
+		adopt: false,
+		previewName: void 0
+	}));
+});
+/**
+* Creates the state project of the team. Two first runs can both create one:
+* the run whose project is not the oldest deletes its own, which holds
+* nothing yet, and uses the oldest, so that every run ends on one store.
+*/
+const createStoreProject = (api, teamId, team) => Effect.gen(function* () {
+	yield* Effect.logInfo(`Convex state: creating the project ${STORE_PROJECT_NAME} in team ${team}`);
+	const created = yield* createProject(api, teamId, {
+		name: STORE_PROJECT_NAME,
+		deploymentType: "prod",
+		deploymentRegion: void 0
+	});
+	const oldest = (yield* listProjectsByName(api, teamId, STORE_PROJECT_NAME)).reduce((a, b) => b.id < a.id ? b : a, created);
+	if (oldest.id === created.id) return created;
+	yield* Effect.logInfo(`Convex state: another run created ${STORE_PROJECT_NAME} ${oldest.id} first; project ${created.id} is deleted again.`);
+	yield* absentAsUndefined(retryIdempotentWrite(api.requestVoid("delete project", (client) => client.POST("/projects/{project_id}/delete", { params: { path: { project_id: created.id } } }))));
+	return oldest;
+});
+/**
+* The StateService over the `samebase` project of the team: found or
+* created, its store app pushed when the store is missing or an older seed,
+* and read and written with the keys of this run.
+*/
+const makeConvexState = (options) => Effect.gen(function* () {
+	const { api } = options;
+	const teamId = yield* api.resolveTeamId(options.team);
+	const team = options.team ?? teamId;
+	const project = (yield* findProjectByName(api, teamId, "samebase")) ?? (yield* createStoreProject(api, teamId, team));
+	const deployment = yield* prodDeploymentOf(api, project.id);
+	if (deployment === void 0) return yield* new ProductionDeploymentNotFound({ projectId: project.id });
+	const keys = [];
+	yield* Scope.addFinalizer(options.scope, Effect.suspend(() => Effect.forEach(keys, (key) => deleteDeployKey(api, deployment.name, key), { discard: true })));
+	const mint = createDeployKey(api, deployment.name, STORE_PROJECT_NAME, RUN_KEY_ACTIONS).pipe(Effect.map((key) => {
+		keys.push(key);
+		return makeFunctionApi(deployment.deploymentUrl, key);
+	}), Effect.mapError((error) => failure(`no key for ${deployment.name}: ${error.message}`)));
+	let current = yield* mint;
+	const functions = { call: (path, args) => current.call(path, args).pipe(Effect.catchIf(isUnauthorized, () => mint.pipe(Effect.flatMap((next) => {
+		current = next;
+		return next.call(path, args);
+	})))) };
+	const needsPush = (found) => found === void 0 ? Effect.succeed(true) : found < 4 ? storeHost(functions).pipe(Effect.map((host) => host === "seed")) : Effect.succeed(false);
+	let version = yield* storeVersion(functions);
+	if (yield* needsPush(version)) {
+		if (version === void 0 && deployment.lastDeployTime) return yield* failure(`project ${STORE_PROJECT_NAME} (${project.id}) of team ${team} has code that is not the state store, and Convex.state does not push over it. Rename that project in the Convex dashboard.`);
+		version = yield* storeVersion(functions);
+		if (yield* needsPush(version)) {
+			yield* pushStore(options, deployment);
+			version = yield* storeVersion(functions);
+		}
+	}
+	if (version !== void 0 && version < 4 && (yield* storeHost(functions)) === "base") return yield* new OutdatedBase({
+		team,
+		deployment: deployment.name,
+		version
+	});
+	if (version !== 4) return yield* failure(`${deployment.name} answers store version ${version ?? "none"}, and this package needs store version 4.`);
+	const remote = remoteOf(functions, options.run);
+	/** The stack's output plus the record, when the run has one and the output has a place for it. */
+	const documentOf = (request) => Effect.gen(function* () {
+		const { run } = options;
+		if (run === void 0) return request.value;
+		const recordedAt = new Date(yield* Clock.currentTimeMillis).toISOString();
+		const document = withRunRecord(request.value, {
+			...run,
+			recordedAt
+		});
+		if (document === void 0) {
+			yield* Effect.logWarning(`Convex state: the output of ${request.stack}/${request.stage} is not a plain object, so it carries no run record.`);
+			return request.value;
+		}
+		return document;
+	});
+	return {
+		id: "convex",
+		getVersion: () => Effect.succeed(STATE_STORE_VERSION),
+		listStacks: remote.listStacks,
+		listStages: remote.listStages,
+		list: remote.list,
+		get: remote.get,
+		getReplacedResources: remote.getReplacedResources,
+		getOutput: remote.getOutput,
+		set: (request) => remote.set(request).pipe(Effect.as(request.value)),
+		delete: (request) => remote.delete(request).pipe(Effect.asVoid),
+		deleteStack: (request) => remote.deleteStack(request).pipe(Effect.asVoid),
+		setOutput: (request) => Effect.gen(function* () {
+			const value = yield* documentOf(request);
+			yield* remote.setOutput({
+				stack: request.stack,
+				stage: request.stage,
+				value
+			});
+			return value;
+		})
+	};
+});
+/**
+* Alchemy state in the `samebase` project of `team`, with the team token
+* in CONVEX_ACCESS_TOKEN or the Convex CLI login. A team access token names
+* its team, so `team` is optional with one; the Convex CLI login needs the
+* slug or the id. The first use of the run finds or creates the project and
+* pushes the store app when the store is missing or an older seed. An older
+* base fails the run with {@link OutdatedBase}. `alchemy plan` on another
+* stack never touches Convex.
+*/
+const state = (options = {}) => Layer.effect(State, Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const scope = yield* Scope.Scope;
+	const context = yield* Effect.context();
+	return yield* Effect.cached(Effect.gen(function* () {
+		const api = yield* ManagementApi.pipe(Effect.provide(ManagementApiLive().pipe(Layer.provide(fromConfig()))));
+		const run = yield* runRecord({
+			cwd: process.cwd(),
+			env: process.env
+		}).pipe(Effect.catch((error) => Effect.logWarning(`Convex state: the stage outputs of this run carry no record. ${error.message}`).pipe(Effect.as(void 0))));
+		return yield* makeConvexState({
+			team: options.team,
+			api,
+			spawner,
+			scope,
+			store: storeDirectory(),
+			run
+		});
+	}).pipe(Effect.provideContext(context), Effect.orDie));
+}));
+//#endregion
+//#region src/HubClient.ts
+const HubClient = Resource("IdentityHub.Client");
+/** The base of the team could not do the call. The reason is the Convex message: it holds no secret. */
+var HubClientFailed = class extends Schema.TaggedError()("HubClientFailed", {
+	team: Schema.Union([Schema.String, Schema.Number]),
+	reason: Schema.String
+}) {
+	get message() {
+		return `Convex.HubClient: the base of team ${this.team}: ${this.reason}.`;
+	}
+};
+/** The reply of `identityBroker:registerClient`. */
+const Registered = Schema.Struct({
+	issuer: Schema.NonEmptyString,
+	clientId: Schema.NonEmptyString,
+	clientSecret: Schema.NonEmptyString
+});
+/** Runs `use` with the function API of the base of `team`, with a key of this call only. */
+const withBase = (api, team, use) => Effect.gen(function* () {
+	const teamId = yield* api.resolveTeamId(team);
+	const project = yield* findProjectByName(api, teamId, STORE_PROJECT_NAME);
+	if (project === void 0) return yield* new HubClientFailed({
+		team,
+		reason: `no project ${STORE_PROJECT_NAME}, which holds the hub`
+	});
+	const deployment = yield* prodDeploymentOf(api, project.id);
+	if (deployment === void 0) return yield* new HubClientFailed({
+		team,
+		reason: `project ${STORE_PROJECT_NAME} has no production deployment`
+	});
+	return yield* withPushKey(api, deployment.name, RUN_KEY_ACTIONS, (key) => use(makeFunctionApi(deployment.deploymentUrl, key)));
+});
+/** One internal function of the hub: its value, or the Convex message as an error. */
+const runHub = (functions, team, name, args) => functions.call(`identityBroker:${name}`, args).pipe(Effect.mapError((error) => new HubClientFailed({
+	team,
+	reason: error.message
+})), Effect.flatMap((reply) => reply.status === "success" ? Effect.succeed(reply.value) : Effect.fail(new HubClientFailed({
+	team,
+	reason: reply.errorMessage.trim()
+}))));
+/**
+* Registers one client. An attempt that a lost reply repeats leaves one spare
+* client on the hub, which signs nobody in.
+*/
+const registerHubClient = (api, props) => withBase(api, props.team, (functions) => runHub(functions, props.team, "registerClient", {
+	appId: props.app,
+	redirectUri: props.redirectUri,
+	deploymentType: props.deploymentType,
+	clientName: props.clientName,
+	softwareVersion: props.softwareVersion ?? "unknown",
+	tokenEndpointAuthMethod: "client_secret_post"
+})).pipe(Effect.flatMap((value) => Schema.decodeUnknownEffect(Registered)(value).pipe(Effect.mapError(() => new HubClientFailed({
+	team: props.team,
+	reason: "registerClient gave no client"
+})))), Effect.map(({ issuer, clientId, clientSecret }) => ({
+	issuer,
+	clientId,
+	clientSecret: Redacted.make(clientSecret)
+})));
+const unregister = (api, team, clientId) => withBase(api, team, (functions) => runHub(functions, team, "deleteClient", { clientId }));
+/** True when the client in state serves the redirect URI and deployment type of `props`. */
+const registeredFor = (output, props) => output.redirectUri === props.redirectUri && output.deploymentType === props.deploymentType;
+const HubClientProvider = () => Provider.effect(HubClient, Effect.gen(function* () {
+	const api = yield* ManagementApi;
+	return {
+		diff: ({ news, olds, output }) => Effect.succeed(!isResolved(news) || output === void 0 ? void 0 : !registeredFor(output, news) ? { action: "replace" } : olds.team === news.team && olds.app === news.app ? { action: "noop" } : { action: "update" }),
+		read: ({ output }) => Effect.succeed(output),
+		reconcile: Effect.fn(function* ({ news, output }) {
+			if (output !== void 0 && registeredFor(output, news)) return output;
+			const client = yield* registerHubClient(api, news);
+			if (output !== void 0) yield* unregister(api, news.team, output.clientId).pipe(Effect.catchTag("HubClientFailed", (error) => Effect.logWarning(`Client ${output.clientId} stays on the hub: ${error.message} Delete it with \`npx convex run --prod identityBroker:deleteClient\`.`)));
+			return {
+				...client,
+				redirectUri: news.redirectUri,
+				deploymentType: news.deploymentType,
+				clientName: news.clientName
+			};
+		}),
+		delete: ({ olds, output }) => unregister(api, olds.team, output.clientId).pipe(Effect.asVoid)
+	};
+}));
+/** The variables that a deployment reads to sign in through the hub. */
+const HUB_VARIABLES = [
+	"HUB_ISSUER",
+	"HUB_CLIENT_ID",
+	"HUB_CLIENT_SECRET"
+];
+/**
+* `alchemy-convex hub-client`: a stack deploys production and previews, and this covers the
+* development deployment, which no stack deploys. A deployment with all three variables keeps
+* them. So a deployment that holds placeholder values for a checkout without a hub is left alone.
+* The secret reaches the Convex CLI on standard input, never in its arguments.
+*/
+const registerDevelopmentClient = (options) => Effect.gen(function* () {
+	const { convex } = options;
+	const names = convex([
+		"env",
+		"list",
+		"--names-only"
+	]).split("\n");
+	if (HUB_VARIABLES.every((name) => names.includes(name))) return void 0;
+	const siteUrl = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.String))(convex([
+		"run",
+		"--inline-query",
+		"process.env.CONVEX_SITE_URL"
+	])).pipe(Effect.mapError(() => new HubClientFailed({
+		team: options.team,
+		reason: "no CONVEX_SITE_URL to register"
+	})));
+	const callbackUrl = `${siteUrl.replace(/\/$/, "")}${options.callbackPath}`;
+	const client = yield* registerHubClient(yield* ManagementApi, {
+		team: options.team,
+		app: options.app,
+		redirectUri: callbackUrl,
+		deploymentType: "development",
+		clientName: "development",
+		softwareVersion: new URL(siteUrl).host
+	});
+	convex([
+		"env",
+		"set",
+		"--force"
+	], `HUB_ISSUER='${client.issuer}'\nHUB_CLIENT_ID='${client.clientId}'\nHUB_CLIENT_SECRET='${Redacted.value(client.clientSecret)}'\n`);
+	return callbackUrl;
+});
+//#endregion
+export { PushTargetMismatch as A, DEPLOY_KEY_ENV as B, DeploymentProvider as C, ConvexAppNotFound as D, CodePushFailed as E, ManagementApi as F, fromValues as H, ManagementApiLive as I, ACCESS_TOKEN_ENV as L, installedCli as M, parseDeployOutput as N, ConvexCliNotFound as O, ConvexApiError as P, Credentials as R, DeploymentIdentityChange as S, ProductionDeploymentNotFound as T, fromConfig as V, ProjectProvider as _, OutdatedBase as a, AmbiguousDeployment as b, RUN_RECORD_KEY as c, withRunRecord as d, AmbiguousProject as f, ProjectNotFound as g, ProjectDeploymentChange as h, registerDevelopmentClient as i, VariablesOwnedBySomeoneElse as j, EnvironmentNeedsDeployKey as k, RunRecordError as l, Project as m, HubClientFailed as n, STORE_PROJECT_NAME as o, CreatedProjectNotFound as p, HubClientProvider as r, state as s, HubClient as t, runRecord as u, ProjectTeamChange as v, DeploymentResource as w, Deployment as x, AbsoluteRootDir as y, CredentialsError as z };
+
+//# sourceMappingURL=HubClient-C_nvjlvW.js.map