@samebase/alchemy-convex 0.3.0 → 0.4.1

package/lib/index.js

@@ -1,49 +1,40 @@
 import { createRequire } from "node:module";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { stripVTControlCharacters } from "node:util";
+import { dirname, join, relative, resolve } from "node:path";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+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 * as Schema from "effect/Schema";
 import { Resource } from "alchemy";
 import { AdoptPolicy, OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
 import * as Provider from "alchemy/Provider";
-import * as Clock from "effect/Clock";
-import * as Effect from "effect/Effect";
-import * as ChildProcess from "effect/process/ChildProcess";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
-import * as Redacted from "effect/Redacted";
-import * as Schema from "effect/Schema";
-import * as Stream from "effect/Stream";
 import { AlchemyContext } from "alchemy/AlchemyContext";
 import { Stack } from "alchemy/Stack";
-import * as Option from "effect/Option";
-import { havePropsChanged, isResolved } from "alchemy/Diff";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
-import * as Context from "effect/Context";
-import * as Layer from "effect/Layer";
 import * as Schedule from "effect/Schedule";
-import * as Config from "effect/Config";
-import { CommandExecutor, CommandExecutorLive } from "alchemy/Command";
-import { hashDirectory } from "alchemy/Command/Memo";
 import { createHash } from "node:crypto";
-//#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
+import { 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";
 //#region src/Credentials.ts
 var Credentials = class extends Context.Service()("@samebase/alchemy-convex/Credentials") {};
-/** Environment variable read by {@link fromConfig}. */
+/** 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.
@@ -52,7 +43,7 @@ const readConvexCliLogin = Effect.gen(function* () {
 	const path = convexCliConfigPath();
 	const text = yield* Effect.tryPromise({
 		try: () => readFile(path, "utf8"),
-		catch: () => new CredentialsError({ reason: `no Convex CLI login at ${path}` })
+		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 {
@@ -60,22 +51,47 @@ const readConvexCliLogin = Effect.gen(function* () {
 		source: "convex-cli-login"
 	};
 });
-var CredentialsError = class extends Schema.TaggedError()("CredentialsError", { reason: Schema.String }) {};
 /**
-* Default resolution: `CONVEX_ACCESS_TOKEN` from the stack ConfigProvider
-* (process env, `.env`, stack secrets), then the Convex CLI login on this
-* machine. CI sets the variable; a developer who ran `npx convex login` needs
-* nothing.
+* 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.succeed(Credentials, Effect.cached(Config.Redacted(ACCESS_TOKEN_ENV).pipe(Effect.map((accessToken) => ({
-	accessToken,
-	source: "env"
-})), Effect.catch(() => readConvexCliLogin), Effect.orDie)).pipe(Effect.flatten));
-/** Explicit token, for tests or callers that already hold a value. */
-const fromToken = (accessToken) => Layer.succeed(Credentials, Effect.succeed({
-	accessToken,
-	source: "explicit"
+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
 /**
@@ -150,8 +166,8 @@ const TeamRow = Schema.Struct({
 	slug: Schema.String
 });
 const TeamRows = Schema.Array(TeamRow);
-const ManagementApiLive = () => Layer.effect(ManagementApi, Effect.gen(function* () {
-	const credentials = yield* Credentials;
+/** 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))));
@@ -180,15 +196,382 @@ const ManagementApiLive = () => Layer.effect(ManagementApi, Effect.gen(function*
 		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
+		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 push key 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 source to the functions directory of the app.`;
+	}
+};
+/** No directory at or above the parent of `source` has a package.json. */
+var ConvexAppNotFound = class extends Schema.TaggedError()("ConvexAppNotFound", { source: Schema.String }) {
+	get message() {
+		return `Convex.Deployment found no package.json at or above the parent of ${this.source}. Set source to the functions directory of a Convex app, such as "./convex".`;
+	}
+};
+/** 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 = (value) => Redacted.isRedacted(value) ? Redacted.value(value) : value;
+/** The app directory: the nearest directory at or above the parent of `source` with a package.json. */
+const appDirectoryOf = (source) => Effect.tryPromise({
+	try: async () => {
+		let directory = dirname(resolve(source));
+		while (true) try {
+			await access(join(directory, "package.json"));
+			return directory;
+		} catch {
+			const parent = dirname(directory);
+			if (parent === directory) throw new Error("no package.json");
+			directory = parent;
+		}
+	},
+	catch: () => new ConvexAppNotFound({ source })
+});
+/** `source` is not the functions directory that the Convex CLI pushes from this app. */
+var SourceMismatch = class extends Schema.TaggedError()("SourceMismatch", {
+	source: Schema.String,
+	functions: Schema.String
+}) {
+	get message() {
+		return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} in this app (the "functions" field of convex.json, or convex/ by default). Set source to ${this.functions}.`;
+	}
+};
+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 !== resolve(path)) return yield* new SourceMismatch({
+		source: resolve(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(source.path).pipe(Effect.flatMap((cwd) => hashDirectory({
+		cwd,
+		memo: source.include === void 0 ? {} : {
+			include: [
+				`${relative(cwd, resolve(source.path)).split("\\").join("/")}/**`,
+				"package.json",
+				"convex.json",
+				...source.include
+			],
+			lockfile: true
+		}
+	})));
+	const env = Object.entries(options.env).map(([name, value]) => [name, valueOf(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
+});
+/**
+* Creates a deploy key for one push, runs `use` with it, and deletes it
+* afterwards. Without a push command, the key can only deploy and read and
+* write variables. The delete is skipped for a key that is the OAuth credential.
+* A failed delete is logged: the key expires anyway.
+*/
+const withPushKey = (api, deployment, source, use) => Effect.acquireUseRelease(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: "alchemy-push",
+			...source === void 0 || sourceOf(source).command === void 0 ? { allowedActions: [...PUSH_KEY_ACTIONS] } : {},
+			expiresAt: now + PUSH_KEY_LIFETIME_MS
+		}
+	}));
+	return Redacted.make(Schema.decodeUnknownSync(CreatedDeployKey)(created).deployKey);
+}), use, (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 push key on ${deployment} (${error.message}). The key expires on its own within ${PUSH_KEY_LIFETIME_MS / 6e4} minutes.`))));
+/** 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
+* `source` is not the functions directory of the app, or when the app has no
+* installed Convex CLI and no push command.
+*/
+const checkSource = (input) => Effect.gen(function* () {
+	const source = sourceOf(input);
+	const cwd = yield* appDirectoryOf(source.path);
+	yield* checkFunctionsDirectory(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.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(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(value)).map(([name, value]) => ({
+			name,
+			value: valueOf(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
 const Deployment = Resource("Convex.Deployment", { defaultRemovalPolicy: "retain" });
 /** The props name another deployment than the one in state. */
@@ -244,10 +627,24 @@ const DeploymentRow$1 = Schema.Struct({
 	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))
+	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);
-const attributesOf = (row, type, previewName) => ({
+/** 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,
@@ -256,47 +653,71 @@ const attributesOf = (row, type, previewName) => ({
 	url: row.deploymentUrl,
 	siteUrl: siteUrlOf(row.deploymentUrl)
 });
-/** The `name` prop of the deployment in state: the dev reference or the preview name. */
-const nameOf = (attributes) => attributes.type === "dev" ? attributes.reference : attributes.type === "preview" ? attributes.previewName : void 0;
+/** 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 row.
+* deployment than `current`: the attributes in state, or a live deployment.
 */
-const checkIdentity$2 = (current, news) => {
+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.projectId) return change("projectId", String(current.projectId), String(news.projectId));
+	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(Deployment, 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 = (name) => absentAsUndefined(api.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 = (projectId, type, isDefault) => api.request("list deployments", (client) => client.GET("/projects/{project_id}/list_deployments", { params: {
+	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 = (projectId) => listDeployments(projectId, "prod", true).pipe(Effect.map((rows) => {
-		const row = rows.find((candidate) => candidate.deploymentType === "prod" && candidate.isDefault);
-		return row === void 0 ? void 0 : attributesOf(row, "prod", void 0);
-	}));
+	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 = (projectId, type, name) => Effect.gen(function* () {
-		const matches = (yield* listDeployments(projectId, type)).filter((row) => row.deploymentType === type && (type === "dev" ? row.reference === name : row.previewIdentifier === name));
+	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,
@@ -305,8 +726,73 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 		});
 		return matches[0];
 	});
-	/** The deployment that the props name, for a resource without state. */
-	const lookup = (news) => news.type === "prod" ? production(news.projectId) : findByName(news.projectId, news.type, news.name).pipe(Effect.map((row) => row === void 0 ? void 0 : attributesOf(row, news.type, news.name)));
+	/** 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, deployment) => news.source === void 0 && Object.keys(news.env ?? {}).length === 0 ? Effect.succeed(void 0) : pushHash({
+		source: news.source,
+		deployment,
+		env: news.env ?? {}
+	});
 	return {
 		stables: [
 			"projectId",
@@ -315,852 +801,157 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 		],
 		diff: Effect.fn(function* ({ news, output }) {
 			if (!isResolved(news) || output === void 0) return void 0;
-			yield* checkIdentity$2(output, news);
-			if (news.type === "prod") return (yield* absentAsUndefined(production(news.projectId)))?.name === output.name ? void 0 : { action: "update" };
-			return (yield* getByName(output.name)) === void 0 ? { action: "update" } : void 0;
+			yield* checkIdentity(output, news);
+			const access = yield* accessFor(addressOf(news), changesEnv(news, output));
+			if ((yield* live(access, output))?.name !== output.name) return { action: "update" };
+			return (yield* wantedHash(news, output.name)) === output.hash ? { action: "noop" } : { action: "update" };
 		}),
 		read: Effect.fn(function* ({ olds, output }) {
-			if (output?.type === "prod") return yield* absentAsUndefined(production(output.projectId));
 			if (output !== void 0) {
-				const live = yield* getByName(output.name);
-				return live === void 0 ? void 0 : attributesOf(live, output.type, output.previewName);
+				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(olds);
+			const found = yield* lookup(access.api, address);
 			if (found === void 0) return void 0;
-			return olds.type === "prod" ? found : Unowned(found);
+			return Unowned({
+				...found,
+				hash: void 0,
+				envNames: []
+			});
 		}),
 		reconcile: Effect.fn(function* ({ fqn, news, output }) {
-			if (output !== void 0) yield* checkIdentity$2(output, news);
-			if (news.type === "prod") {
-				const current = yield* production(news.projectId);
-				if (current === void 0) return yield* new ProductionDeploymentNotFound({ projectId: news.projectId });
-				return current;
-			}
-			if (output !== void 0) {
-				const live = yield* getByName(output.name);
-				if (live !== void 0) {
-					if (live.deploymentType !== output.type) return yield* new DeploymentIdentityChange({
-						deployment: live.name,
-						field: "type",
-						current: live.deploymentType,
-						requested: news.type
-					});
-					const current = attributesOf(live, output.type, output.previewName);
-					yield* checkIdentity$2(current, news);
-					return current;
+			if (output !== void 0) yield* checkIdentity(output, news);
+			if (news.source !== void 0) yield* checkSource(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: Deployment.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
+					};
 				}
-			}
-			const existing = yield* lookup(news);
-			if (existing !== void 0) {
-				if (!(yield* shouldAdopt(fqn))) return yield* new OwnedBySomeoneElse({
-					message: `Project ${news.projectId} already has ${news.type} deployment ${existing.name} named "${news.name}". Re-run with --adopt to take it over, or use another name.`,
-					resourceType: Deployment.Type,
-					physicalName: existing.name
-				});
-				return existing;
-			}
-			const created = yield* api.request("create deployment", (client) => client.POST("/projects/{project_id}/create_deployment", {
-				params: { path: { project_id: news.projectId } },
-				body: {
-					type: news.type,
-					reference: news.name
+				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
+					};
 				}
-			}));
-			return attributesOf(Schema.decodeUnknownSync(DeploymentRow$1)(created), news.type, news.name);
-		}),
-		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 live = yield* getByName(output.name);
-			if (live === void 0) return;
-			if (live.deploymentType === "prod") return yield* keep;
-			yield* absentAsUndefined(retryIdempotentWrite(api.requestVoid("delete deployment", (client) => client.POST("/deployments/{deployment_name}/delete", { params: { path: { deployment_name: output.name } } }))));
-		})
-	};
-}));
-//#endregion
-//#region src/EnvironmentVariable.ts
-/**
-* The variable's identity when the listing has `name`. Own keys only: a
-* valid variable name such as `toString` must not match the object prototype.
-*/
-const findVariable = (list, deployment, name) => Object.hasOwn(list.environmentVariables, name) ? {
-	deployment,
-	name
-} : void 0;
-/**
-* One attempt to set variables, or to remove those whose `value` is null, in
-* one call. The deployment answers 200 with an empty body, so this reads no
-* response data.
-*/
-const writeVariables = (deployment, deployKey, changes) => settleVoid("update environment variables", () => createDeploymentClient(deployment, Redacted.value(deployKey)).POST("/update_environment_variables", { body: { changes: changes.map(({ name, value }) => ({
-	name,
-	value: Redacted.isRedacted(value) ? Redacted.value(value) : value
-})) } }));
-/** One attempt to set one variable, or to remove it when `value` is null. */
-const writeVariable = (deployment, deployKey, name, value) => writeVariables(deployment, deployKey, [{
-	name,
-	value
-}]);
-/**
-* Sets one variable, or removes it when `value` is null. The call sets a
-* value, so it runs again after a write conflict or a 5xx answer, for example
-* when another resource writes a variable of the same deployment at the same
-* time. Use it only where the variable is already ours to set.
-*/
-const updateVariable = (deployment, deployKey, name, value) => retryIdempotentWrite(writeVariable(deployment, deployKey, name, value));
-/** GET https://<deployment>.convex.cloud/api/v1/list_environment_variables */
-const EnvironmentVariableList = Schema.Struct({ environmentVariables: Schema.Record(Schema.String, Schema.String) });
-/** Every variable of the deployment with its value. Fails with a 404 when the deployment is gone. */
-const listVariables = (deployment, deployKey) => settle("list environment variables", () => createDeploymentClient(deployment, Redacted.value(deployKey)).GET("/list_environment_variables")).pipe(Effect.map((body) => Schema.decodeUnknownSync(EnvironmentVariableList)(body).environmentVariables));
-/** The variable's identity, or undefined when the variable or the deployment is absent. */
-const readVariable = (api, deployment, deployKey, name) => absentAsUndefined(api.deploymentRequest("list environment variables", deployment, deployKey, (client) => client.GET("/list_environment_variables"))).pipe(Effect.map((body) => body === void 0 ? void 0 : findVariable(Schema.decodeUnknownSync(EnvironmentVariableList)(body), deployment, name)));
-const EnvironmentVariable = Resource("Convex.EnvironmentVariable");
-/**
-* The props name another variable than the one in state. Used by
-* Convex.EnvironmentVariable and Convex.DefaultEnvironmentVariable.
-*/
-var VariableIdentityChange = class extends Schema.TaggedError()("VariableIdentityChange", {
-	resourceType: Schema.String,
-	field: Schema.Literals([
-		"name",
-		"deployment",
-		"projectId",
-		"deploymentType"
-	]),
-	current: Schema.String,
-	requested: Schema.String
-}) {
-	get message() {
-		return `${this.resourceType} cannot change its ${this.field} from ${this.current} to ${this.requested}. Create a new resource with a new logical id for the new name or deployment, and remove this one.`;
-	}
-};
-/** Fails with {@link VariableIdentityChange} when the props name another variable than the one in state. */
-const checkIdentity$1 = (output, news) => output.name !== news.name ? Effect.fail(new VariableIdentityChange({
-	resourceType: EnvironmentVariable.Type,
-	field: "name",
-	current: output.name,
-	requested: news.name
-})) : output.deployment !== news.deployment ? Effect.fail(new VariableIdentityChange({
-	resourceType: EnvironmentVariable.Type,
-	field: "deployment",
-	current: output.deployment,
-	requested: news.deployment
-})) : Effect.void;
-/**
-* The deploy key for the variable in state: from the attributes, or, for
-* state from 0.1.x, from props that name the same deployment.
-*/
-const keyOf = (output, olds) => output.deployKey ?? (olds?.deployment === output.deployment ? olds.deployKey : void 0);
-const EnvironmentVariableProvider = () => Provider.effect(EnvironmentVariable, Effect.gen(function* () {
-	const api = yield* ManagementApi;
-	return {
-		diff: Effect.fn(function* ({ news, output }) {
-			if (!isResolved(news) || output === void 0) return void 0;
-			yield* checkIdentity$1(output, news);
-		}),
-		read: Effect.fn(function* ({ olds, output }) {
-			if (output !== void 0) {
-				const key = keyOf(output, olds);
-				if (key === void 0) return output;
-				return (yield* readVariable(api, output.deployment, key, output.name)) === void 0 ? void 0 : output;
-			}
-			const found = yield* readVariable(api, olds.deployment, olds.deployKey, olds.name);
-			return found === void 0 ? void 0 : Unowned({
-				...found,
-				deployKey: olds.deployKey
-			});
-		}),
-		reconcile: Effect.fn(function* ({ fqn, news, output }) {
-			if (output !== void 0) yield* checkIdentity$1(output, news);
-			const write = writeVariable(news.deployment, news.deployKey, news.name, news.value);
-			if (output !== void 0 || (yield* shouldAdopt(fqn))) yield* retryIdempotentWrite(write);
-			else yield* retryIdempotentWrite(Effect.gen(function* () {
-				if ((yield* readVariable(api, news.deployment, news.deployKey, news.name)) !== void 0) return yield* new OwnedBySomeoneElse({
-					message: `Environment variable ${news.name} already exists on deployment ${news.deployment}. Re-run with --adopt to take it over and overwrite its value, or use a different name.`,
-					resourceType: EnvironmentVariable.Type,
-					physicalName: news.name
-				});
-				yield* write;
-			}));
-			return {
-				deployment: news.deployment,
-				name: news.name,
-				deployKey: news.deployKey
-			};
-		}),
-		delete: Effect.fn(function* ({ olds, output }) {
-			const key = keyOf(output, olds);
-			if (key === void 0) {
-				yield* Effect.logWarning(`Environment variable ${output.name} on deployment ${output.deployment} stays: Alchemy has no deploy key for that deployment. Remove it in the Convex dashboard.`);
-				return;
-			}
-			yield* absentAsUndefined(updateVariable(output.deployment, key, output.name, null));
-		})
-	};
-}));
-//#endregion
-//#region src/Code.ts
-const Code = Resource("Convex.Code");
-/**
-* The CLI prints this line with `logFinishedStep` after the push succeeds, to
-* stderr (convex 1.46 `cli/lib/deploy2.js` for existing deployments,
-* `cli/deploy.js` for preview deployments). 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
-	};
-};
-/**
-* What a deploy key targets, from its prefix: `<type>:<deployment>|<secret>`
-* (or `<deployment>|<secret>` in old keys) for one deployment,
-* `preview:<team>:<project>|<secret>` for preview deployments of a project,
-* `project:<team>:<project>|<secret>` for the project's production
-* deployment. 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: "unknown" };
-	const parts = key.slice(0, bar).split(":");
-	const [first, second] = parts;
-	if (parts.length === 3 && first === "preview") return { kind: "preview" };
-	if (parts.length === 3 && first === "project") return { kind: "project" };
-	if (parts.length === 2 && second) return {
-		kind: "deployment",
-		deployment: second
-	};
-	if (parts.length === 1 && first) return {
-		kind: "deployment",
-		deployment: first
-	};
-	return { kind: "unknown" };
-};
-/** The deploy key does not fit the deployment. Checked before the push. */
-var DeployKeyMismatch = class extends Schema.TaggedError()("DeployKeyMismatch", {
-	/** The deployment that should receive the push. */
-	deployment: Schema.String,
-	/** What the key targets. */
-	key: Schema.Literals([
-		"deployment",
-		"preview",
-		"project",
-		"unknown"
-	]),
-	/** For a deployment key: the deployment in the key prefix. Never the secret. */
-	keyDeployment: Schema.UndefinedOr(Schema.String)
-}) {
-	get message() {
-		switch (this.key) {
-			case "deployment": return `The deploy key is for deployment ${this.keyDeployment}, not for ${this.deployment}. Pass a deploy key of ${this.deployment}, such as Convex.DeployKey with deployment ${this.deployment}.`;
-			case "preview": return `A preview deploy key pushes to a preview deployment by its preview name, and ${this.deployment} is not a Convex.Deployment of type "preview". Pass the Convex.Deployment preview resource as deployment, or a deploy key of ${this.deployment}.`;
-			case "project": return `Convex.Code does not take a project deploy key: it cannot check before the push that the key targets ${this.deployment}. Pass a deploy key of ${this.deployment} (Convex.DeployKey).`;
-			case "unknown": return `deployKey is not a Convex deploy key ("<type>:<deployment>|<secret>" or "preview:<team>:<project>|<secret>"). Pass Convex.DeployKey(...).deployKey or Convex.PreviewDeployKey(...).previewDeployKey.`;
-		}
-	}
-};
-/** `env` needs the deployment API, which takes only a deploy key of the deployment. */
-var EnvironmentNeedsDeployKey = class extends Schema.TaggedError()("EnvironmentNeedsDeployKey", { deployment: Schema.String }) {
-	get message() {
-		return `Convex.Code cannot set or remove env variables on ${this.deployment} with a preview deploy key: the deployment API takes only a deploy key of the deployment. Pass a Convex.DeployKey of ${this.deployment}, or use Convex.DefaultEnvironmentVariable with deploymentType "preview" for values that every new preview deployment gets.`;
-	}
-};
-/** No `convex` package resolves from `cwd`. */
-var ConvexCliNotFound = class extends Schema.TaggedError()("ConvexCliNotFound", { cwd: Schema.String }) {
-	get message() {
-		return `Convex.Code found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), set cwd to the app directory, or set the command prop.`;
-	}
-};
-/** 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, so Convex.Code has no deployment URL. 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 in the props. 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.Code expected ${this.expected}. With a preview deploy key, this happens when the key belongs to another project, or when the preview deployment ${this.expected} expired during the deploy and the CLI created ${this.actual} for the same preview name. Check the key. After an expiry, run the deploy again with --adopt, so that Convex.Deployment takes over ${this.actual}.`;
-	}
-};
-/**
-* Checks that the key fits the deployment, and returns the preview name for
-* `--preview-name` when the key is a preview deploy key.
-*/
-const previewNameFor = (target, keyTarget, changesEnvironment) => {
-	const mismatch = new DeployKeyMismatch({
-		deployment: target.name,
-		key: keyTarget.kind,
-		keyDeployment: keyTarget.kind === "deployment" ? keyTarget.deployment : void 0
-	});
-	switch (keyTarget.kind) {
-		case "deployment": return keyTarget.deployment === target.name ? Effect.succeed(void 0) : Effect.fail(mismatch);
-		case "preview":
-			if (target.type !== "preview" || target.previewName === void 0) return Effect.fail(mismatch);
-			return changesEnvironment ? Effect.fail(new EnvironmentNeedsDeployKey({ deployment: target.name })) : Effect.succeed(target.previewName);
-		case "project":
-		case "unknown": return Effect.fail(mismatch);
-		default: return keyTarget;
-	}
-};
-/** 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 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 })
-});
-/**
-* 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
-})));
-/**
-* The environment of the CLI: 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
-});
-const CodeProvider = () => Provider.effect(Code, Effect.gen(function* () {
-	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-	/** Runs the CLI with piped output. Interruption stops its process group. */
-	const run = (argv, cwd, home) => Effect.gen(function* () {
-		const [command, ...args] = argv;
-		const child = yield* spawner.spawn(ChildProcess.make(command, args, {
-			cwd,
-			env: cliEnvironment(home),
-			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);
-	return {
-		diff: () => Effect.succeed({ action: "update" }),
-		reconcile: Effect.fn(function* ({ fqn, news, output }) {
-			const target = typeof news.deployment === "string" ? {
-				name: news.deployment,
-				address: news.deployment,
-				type: void 0,
-				previewName: void 0
-			} : {
-				...news.deployment,
-				address: news.deployment.url
-			};
-			const key = Redacted.value(news.deployKey);
-			const secrets = [key, key.slice(key.indexOf("|") + 1)].filter((secret) => secret.length >= 8);
-			const env = Object.entries(news.env ?? {}).sort(([a], [b]) => a < b ? -1 : 1);
-			const previous = output !== void 0 && output.deploymentName === target.name ? output.envNames : [];
-			const removed = previous.filter((name) => !env.some(([envName]) => envName === name));
-			const previewName = yield* previewNameFor(target, keyTargetOf(key), env.length > 0 || removed.length > 0);
-			const cwd = resolve(news.cwd);
-			const program = news.command ?? (yield* installedCli(cwd));
-			if (env.length > 0 || removed.length > 0) {
-				const adopt = yield* shouldAdopt(fqn);
-				const fresh = env.filter(([name]) => !previous.includes(name));
-				yield* retryIdempotentWrite(Effect.gen(function* () {
-					if (fresh.length > 0 && !adopt) {
-						const current = yield* listVariables(target.address, news.deployKey);
-						const taken = fresh.filter(([name, value]) => Object.hasOwn(current, name) && current[name] !== (Redacted.isRedacted(value) ? Redacted.value(value) : value)).map(([name]) => name);
-						if (taken.length > 0) return yield* new OwnedBySomeoneElse({
-							message: `Environment variables ${taken.join(", ")} already exist on deployment ${target.name} with other values. Re-run with --adopt to take them over and overwrite them, or remove them from env.`,
-							resourceType: Code.Type,
-							physicalName: target.name
+				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
+						};
 					}
-					yield* writeVariables(target.address, news.deployKey, [...env.map(([name, value]) => ({
-						name,
-						value
-					})), ...removed.map((name) => ({
-						name,
-						value: null
-					}))]);
-				}));
-			}
-			const args = [
-				"deploy",
-				...previewName === void 0 ? [] : ["--preview-name", previewName],
-				...news.typecheck === void 0 ? [] : [`--typecheck=${news.typecheck}`],
-				...news.codegen === void 0 ? [] : [`--codegen=${news.codegen}`]
-			];
-			const result = yield* withKeyFile(key, ({ envFile, home }) => run([
-				...program,
-				...args,
-				"--env-file",
-				envFile
-			], cwd, home)).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 !== target.name) return yield* new PushTargetMismatch({
-				expected: target.name,
-				actual: deployed.deploymentName
-			});
-			return {
-				deploymentName: deployed.deploymentName,
-				url: deployed.url,
-				siteUrl: siteUrlOf(deployed.url),
-				deployedAt: yield* Clock.currentTimeMillis,
-				envNames: env.map(([name]) => name)
-			};
-		}),
-		delete: () => Effect.void
-	};
-}));
-//#endregion
-//#region src/DefaultEnvironmentVariable.ts
-/**
-* Attributes when the listing has `name` for `deploymentType`. An unfiltered
-* listing merges the deployment types that share one value into one row, so
-* the match checks membership in `deploymentTypes`.
-*/
-const findDefault = (list, projectId, name, deploymentType) => list.items.some((item) => item.name === name && item.deploymentTypes.includes(deploymentType)) ? {
-	projectId,
-	name,
-	deploymentType
-} : void 0;
-/**
-* Lists the defaults named `name` for `deploymentType`. Convex filters on
-* both, so the listing has at most one row and needs no pagination.
-*/
-const listDefaults = (api, projectId, name, deploymentType) => api.request("list default environment variables", (client) => client.GET("/projects/{project_id}/list_default_environment_variables", { params: {
-	path: { project_id: projectId },
-	query: {
-		name,
-		deploymentType
-	}
-} })).pipe(Effect.map((body) => Schema.decodeUnknownSync(DefaultEnvironmentVariableList)(body)));
-/** One attempt to set one default, or to remove it when `value` is null. */
-const writeDefault = (api, projectId, name, deploymentType, value) => api.requestVoid("update default environment variables", (client) => client.POST("/projects/{project_id}/update_default_environment_variables", {
-	params: { path: { project_id: projectId } },
-	body: { changes: [{
-		name,
-		deploymentType,
-		value: Redacted.isRedacted(value) ? Redacted.value(value) : value
-	}] }
-}));
-/**
-* Sets one default, or removes it when `value` is null. Convex answers 200
-* with an empty body, so this reads no response data. The call sets a value,
-* so it runs again after a write conflict or a 5xx answer, for example when
-* another resource writes a default of the same project at the same time.
-*/
-const updateDefault = (api, projectId, name, deploymentType, value) => retryIdempotentWrite(writeDefault(api, projectId, name, deploymentType, value));
-/** The default's identity, or undefined when the default or the project is absent. */
-const readDefault = (api, projectId, name, deploymentType) => absentAsUndefined(listDefaults(api, projectId, name, deploymentType)).pipe(Effect.map((list) => list === void 0 ? void 0 : findDefault(list, projectId, name, deploymentType)));
-/**
-* GET /projects/{project_id}/list_default_environment_variables. Only the
-* fields the provider uses: the row's `value` is the secret in plain text.
-*/
-const DefaultEnvironmentVariableList = Schema.Struct({ items: Schema.Array(Schema.Struct({
-	name: Schema.String,
-	deploymentTypes: Schema.Array(Schema.String)
-})) });
-const DefaultEnvironmentVariable = Resource("Convex.DefaultEnvironmentVariable");
-/** Fails with VariableIdentityChange when the props name another default than the one in state. */
-const checkIdentity = (output, news) => {
-	const changed = output.projectId !== news.projectId ? {
-		field: "projectId",
-		current: `${output.projectId}`,
-		requested: `${news.projectId}`
-	} : output.name !== news.name ? {
-		field: "name",
-		current: output.name,
-		requested: news.name
-	} : output.deploymentType !== news.deploymentType ? {
-		field: "deploymentType",
-		current: output.deploymentType,
-		requested: news.deploymentType
-	} : void 0;
-	return changed === void 0 ? Effect.void : Effect.fail(new VariableIdentityChange({
-		resourceType: DefaultEnvironmentVariable.Type,
-		...changed
-	}));
-};
-const DefaultEnvironmentVariableProvider = () => Provider.effect(DefaultEnvironmentVariable, Effect.gen(function* () {
-	const api = yield* ManagementApi;
-	return {
-		diff: Effect.fn(function* ({ news, output }) {
-			if (!isResolved(news) || output === void 0) return void 0;
-			yield* checkIdentity(output, news);
-		}),
-		read: Effect.fn(function* ({ olds, output }) {
-			const at = output ?? olds;
-			const found = yield* readDefault(api, at.projectId, at.name, at.deploymentType);
-			if (found === void 0) return void 0;
-			return output ?? Unowned(found);
-		}),
-		reconcile: Effect.fn(function* ({ fqn, news, output }) {
-			if (output !== void 0) yield* checkIdentity(output, news);
-			const write = writeDefault(api, news.projectId, news.name, news.deploymentType, news.value);
-			if (output !== void 0 || (yield* shouldAdopt(fqn))) yield* retryIdempotentWrite(write);
-			else yield* retryIdempotentWrite(Effect.gen(function* () {
-				if ((yield* readDefault(api, news.projectId, news.name, news.deploymentType)) !== void 0) return yield* new OwnedBySomeoneElse({
-					message: `Project ${news.projectId} already has a ${news.deploymentType} default environment variable ${news.name}. Re-run with --adopt to take it over and overwrite its value, or use a different name.`,
-					resourceType: DefaultEnvironmentVariable.Type,
-					physicalName: news.name
-				});
-				yield* write;
-			}));
-			return {
-				projectId: news.projectId,
-				name: news.name,
-				deploymentType: news.deploymentType
-			};
-		}),
-		delete: Effect.fn(function* ({ output }) {
-			yield* absentAsUndefined(updateDefault(api, output.projectId, output.name, output.deploymentType, null));
-		})
-	};
-}));
-//#endregion
-//#region src/Deploy.ts
-/**
-* @deprecated Since 0.3.0. Use Convex.Code with a Convex.Deployment: it
-* runs the installed Convex CLI, keeps the deploy key out of the process
-* environment, checks that the key fits the deployment, and outputs the site
-* URL. Removing a Deploy resource changes nothing in Convex.
-*/
-const Deploy = Resource("Convex.Deploy");
-/** The `convex deploy` argv, starting with `npx`. */
-const deployArgs = (props) => [
-	"npx",
-	"convex",
-	"deploy",
-	...props.previewName === void 0 ? [] : ["--preview-name", props.previewName],
-	...props.previewCreate === void 0 ? [] : ["--preview-create", props.previewCreate],
-	...props.previewRun === void 0 ? [] : ["--preview-run", props.previewRun],
-	...props.extraArgs ?? []
-];
-/** A `convex deploy` argument contains whitespace, which Alchemy's command runner splits on. */
-var DeployArgumentError = class extends Schema.TaggedError()("DeployArgumentError", { argument: Schema.String }) {
-	get message() {
-		return `Convex.Deploy argument "${this.argument}" contains whitespace, and Alchemy splits the command on whitespace. Use the --flag=value form, such as --typecheck=disable, and names without spaces.`;
-	}
-};
-/** `npx convex deploy` exited 0 but did not print the deployment URL. */
-var DeployOutputError = class extends Schema.TaggedError()("DeployOutputError", { outputTail: Schema.String }) {
-	get message() {
-		return `npx convex deploy exited 0 but printed no "Deployed Convex functions to <url>" line, so Convex.Deploy has no deployment URL. Remove --dry-run from extraArgs if it is there, and read the CLI output. Last output:\n${this.outputTail}`;
-	}
-};
-const DeployProvider = () => Provider.effect(Deploy, Effect.gen(function* () {
-	const { run } = yield* CommandExecutor;
-	const hashOf = (props) => props.memo === false ? Effect.succeed(void 0) : hashDirectory({
-		...props.cwd === void 0 ? {} : { cwd: props.cwd },
-		memo: props.memo === true || props.memo === void 0 ? {} : props.memo
-	});
-	return {
-		diff: Effect.fn(function* ({ olds, news, output }) {
-			if (!isResolved(news)) return void 0;
-			if (news.previewName !== void 0 || news.previewCreate !== void 0 || output === void 0 || output.hash === void 0 || havePropsChanged(olds, news)) return { action: "update" };
-			return { action: (yield* hashOf(news)) === output.hash ? "noop" : "update" };
-		}),
-		reconcile: Effect.fn(function* ({ news, session }) {
-			const args = deployArgs(news);
-			const spaced = args.find((arg) => /\s/.test(arg));
-			if (spaced !== void 0) return yield* new DeployArgumentError({ argument: spaced });
-			const { stdout, stderr } = yield* run({
-				command: args.join(" "),
-				...news.cwd === void 0 ? {} : { cwd: news.cwd },
-				...news.timeout === void 0 ? {} : { timeout: news.timeout },
-				env: {
-					...news.env,
-					CONVEX_DEPLOY_KEY: news.deployKey
 				}
-			}, session);
-			const output = `${stdout}\n${stderr}`;
-			const deployed = parseDeployOutput(output);
-			if (deployed === void 0) return yield* new DeployOutputError({ outputTail: stripVTControlCharacters(output).split(/\r?\n|\r/).filter((line) => line.trim() !== "").slice(-20).join("\n") });
-			return {
-				...deployed,
-				hash: yield* hashOf(news)
-			};
-		}),
-		delete: () => Effect.void
-	};
-}));
-//#endregion
-//#region src/DeployKey.ts
-/**
-* True when `listedName` is how Convex lists a key created as `name`: the
-* requested name itself, or the requested name, a space, and one
-* parenthesized suffix without spaces. The suffix check keeps `my-key` from
-* matching a key created as `my-key (old)`.
-*/
-const isListedAs = (listedName, name) => {
-	const prefix = `${name} (`;
-	return listedName === name || listedName.startsWith(prefix) && /^[^\s()]+\)$/.test(listedName.slice(prefix.length));
-};
-/**
-* True when the listing still has the key in state: by numeric id, or by
-* listed name for state written by 0.1.x, which has no id.
-*/
-const isKeyListed = (entries, key) => entries.some((entry) => key.keyId === void 0 ? entry.name === key.uniqueName : entry.id === key.keyId);
-/** The listed keys that Convex shows for a key created as `name`. */
-const keysListedAs = (entries, name) => entries.filter((entry) => isListedAs(entry.name, name));
-/**
-* The name that a resource instance requests: `name`, a dash, and the first
-* 12 hex characters of sha256("<fqn>:<instanceId>"). Two resources, or the
-* old and the new generation of one replaced resource, never request the
-* same name. Pattern from Confect `packages/alchemy/src/internal/ResourceIdentity.ts`
-* (https://github.com/rjdellecese/confect, ISC license).
-*/
-const requestedKeyName = (name, fqn, instanceId) => `${name}-${createHash("sha256").update(`${fqn}:${instanceId}`).digest("hex").slice(0, 12)}`;
-/** One row of list_deploy_keys and list_preview_deploy_keys. Only the fields the providers use. */
-const ListedKey = Schema.Struct({
-	id: Schema.Number,
-	name: Schema.String
-});
-/** GET /deployments/{deployment_name}/list_deploy_keys */
-const DeployKeyList = Schema.Array(ListedKey);
-/** POST /deployments/{deployment_name}/create_deploy_key */
-const CreatedDeployKey = Schema.Struct({ deployKey: Schema.String });
-/**
-* A key cannot be tied to one resource: before the create, listed keys
-* already have the requested name, or after the create, not exactly one has it.
-*/
-var DeployKeyRecoveryRequired = class extends Schema.TaggedError()("DeployKeyRecoveryRequired", {
-	/** Where the keys live, such as `deployment happy-otter-123` or `project 3145389`. */
-	target: Schema.String,
-	/** The requested name. */
-	name: Schema.String,
-	/** The listed keys with the requested name. */
-	keys: Schema.Array(ListedKey),
-	/** True when this run created a key before the listing check failed. */
-	afterCreate: Schema.Boolean
-}) {
-	get message() {
-		const listed = this.keys.length === 0 ? "no key" : this.keys.map((key) => `"${key.name}" (id ${key.id})`).join(", ");
-		return this.afterCreate ? `Convex created deploy key "${this.name}" on ${this.target}, but the listing shows ${listed} with that name, not exactly one, so this resource cannot track the new key. Alchemy does not revoke it. Delete the keys with that name in the Convex dashboard, then run the deploy again.` : `${this.target} already lists ${listed} with the name "${this.name}", but Alchemy state has no such key. An interrupted run probably created it, and its secret is lost. Delete these keys in the Convex dashboard, then run the deploy again.`;
-	}
-};
-/**
-* Convex returned the Management API credential itself as the new key. This
-* happens with an OAuth token: Convex creates no key. A delete of the
-* returned secret would revoke the credential, so the resource does not keep it.
-*/
-var DeployKeyIsCredential = class extends Schema.TaggedError()("DeployKeyIsCredential", {
-	target: Schema.String,
-	name: Schema.String
-}) {
-	get message() {
-		return `Convex returned the Management API credential itself as deploy key "${this.name}" on ${this.target}. With an OAuth token, Convex creates no new key, and deleting the returned key would revoke the OAuth token. Alchemy does not keep it. Use a team access token in CONVEX_ACCESS_TOKEN, or the Convex CLI login.`;
-	}
-};
-/**
-* Creates a key named `name` and ties it to the caller. Fails before the
-* create when keys with that name already exist. After the create, fails
-* when the secret is the Management API credential itself, or when the
-* listing does not show exactly one key with that name. It never revokes a
-* key: the returned secret can be a shared credential.
-*/
-const createTrackedKey = (options) => Effect.gen(function* () {
-	const { target, name } = options;
-	const existing = keysListedAs(yield* options.list, name);
-	if (existing.length > 0) return yield* new DeployKeyRecoveryRequired({
-		target,
-		name,
-		keys: existing,
-		afterCreate: false
-	});
-	const secret = yield* options.create;
-	if (yield* options.isCredentialToken(secret)) return yield* new DeployKeyIsCredential({
-		target,
-		name
-	});
-	const listed = keysListedAs(yield* options.list, name);
-	const [only] = listed;
-	if (only === void 0 || listed.length !== 1) return yield* new DeployKeyRecoveryRequired({
-		target,
-		name,
-		keys: listed,
-		afterCreate: true
-	});
-	return {
-		keyId: only.id,
-		uniqueName: only.name,
-		secret: Redacted.make(secret)
-	};
-});
-/**
-* The secret to send to a delete call, or undefined when a delete is not
-* safe. Only a key with a `keyId` in state is known to be a new key that
-* this resource owns: createTrackedKey found exactly one new listed key, and
-* the secret was not the credential. State from 0.1.x has no `keyId`, and its
-* secret can be an OAuth token that Convex returned as a key, so a delete
-* could revoke that OAuth token. Such a key stays, and a warning names it.
-*/
-const secretToDelete = (key, label) => Effect.gen(function* () {
-	if (key.keyId === void 0 || !Redacted.isRedacted(key.secret)) {
-		yield* Effect.logWarning(`${label} has no verified key id and secret in state (state from 0.1.x, for example), so Alchemy does not delete it. Delete it in the Convex dashboard.`);
-		return;
-	}
-	return Redacted.value(key.secret);
-});
-const DeployKey = Resource("Convex.DeployKey");
-const DeployKeyProvider = () => Provider.effect(DeployKey, Effect.gen(function* () {
-	const api = yield* ManagementApi;
-	const listKeys = (deployment) => api.request("list deploy keys", (client) => client.GET("/deployments/{deployment_name}/list_deploy_keys", { params: { path: { deployment_name: deployment } } })).pipe(Effect.map((body) => Schema.decodeUnknownSync(DeployKeyList)(body)));
-	/**
-	* `id` is the secret: Convex accepts it, and it matches only the key
-	* that this resource created. A second delete answers 404.
-	*/
-	const deleteKey = (deployment, secret) => retryIdempotentWrite(api.requestVoid("delete deploy key", (client) => client.POST("/deployments/{deployment_name}/delete_deploy_key", {
-		params: { path: { deployment_name: deployment } },
-		body: { id: secret }
-	})));
-	return {
-		stables: ["uniqueName", "deployment"],
-		diff: ({ olds, news, output }) => {
-			if (!isResolved(news)) return Effect.succeed(void 0);
-			return Effect.succeed(output !== void 0 && output.deployKey === void 0 || havePropsChanged(olds, news) ? { action: "replace" } : { action: "noop" });
-		},
-		read: Effect.fn(function* ({ output }) {
-			if (output === void 0) return void 0;
-			const entries = yield* absentAsUndefined(listKeys(output.deployment));
-			return entries !== void 0 && isKeyListed(entries, output) ? output : void 0;
-		}),
-		reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
-			if (output !== void 0) {
-				if (isKeyListed(yield* listKeys(news.deployment), output)) return output;
-			}
-			const name = requestedKeyName(news.name, fqn, instanceId);
-			const { keyId, uniqueName, secret } = yield* createTrackedKey({
-				target: `deployment ${news.deployment}`,
-				name,
-				list: listKeys(news.deployment),
-				create: api.request("create deploy key", (client) => client.POST("/deployments/{deployment_name}/create_deploy_key", {
-					params: { path: { deployment_name: news.deployment } },
+				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: {
-						name,
-						...news.allowedActions === void 0 ? {} : { allowedActions: [...news.allowedActions] }
+						type: news.type,
+						reference: news.name
 					}
-				})).pipe(Effect.map((body) => Schema.decodeUnknownSync(CreatedDeployKey)(body).deployKey)),
-				isCredentialToken: api.isCredentialToken
+				}));
+				return {
+					target: targetOf(Schema.decodeUnknownSync(DeploymentRow$1)(row), news.type, news.name),
+					created: true
+				};
 			});
-			return {
-				uniqueName,
-				keyId,
-				deployment: news.deployment,
-				deployKey: secret
+			const previousEnvNames = output?.name === target.name ? envNamesOf(output) : [];
+			const before = yield* wantedHash(news, target.name);
+			if (before === void 0 && previousEnvNames.length === 0) return {
+				...target,
+				hash: void 0,
+				envNames: []
 			};
-		}),
-		delete: Effect.fn(function* ({ output }) {
-			const secret = yield* secretToDelete({
-				keyId: output.keyId,
-				secret: output.deployKey
-			}, `Convex.DeployKey "${output.uniqueName}" on ${output.deployment}`);
-			if (secret === void 0) return;
-			yield* absentAsUndefined(deleteKey(output.deployment, secret));
-		})
-	};
-}));
-//#endregion
-//#region src/PreviewDeployKey.ts
-/** GET /projects/{project_id}/list_preview_deploy_keys */
-const PreviewDeployKeyList = Schema.Struct({ items: Schema.Array(ListedKey) });
-/** POST /projects/{project_id}/create_preview_deploy_key */
-const CreatedPreviewDeployKey = Schema.Struct({ previewDeployKey: Schema.String });
-const PreviewDeployKey = Resource("Convex.PreviewDeployKey");
-const PreviewDeployKeyProvider = () => Provider.effect(PreviewDeployKey, Effect.gen(function* () {
-	const api = yield* ManagementApi;
-	const listKeys = (projectId) => api.request("list preview deploy keys", (client) => client.GET("/projects/{project_id}/list_preview_deploy_keys", { params: { path: { project_id: projectId } } })).pipe(Effect.map((body) => Schema.decodeUnknownSync(PreviewDeployKeyList)(body).items));
-	/**
-	* `id` is the secret: Convex accepts it, and it matches only the key
-	* that this resource created. A second delete answers 404.
-	*/
-	const deleteKey = (projectId, secret) => retryIdempotentWrite(api.requestVoid("delete preview deploy key", (client) => client.POST("/projects/{project_id}/delete_preview_deploy_key", {
-		params: { path: { project_id: projectId } },
-		body: { id: secret }
-	})));
-	return {
-		stables: ["uniqueName", "projectId"],
-		diff: ({ olds, news, output }) => {
-			if (!isResolved(news)) return Effect.succeed(void 0);
-			return Effect.succeed(output !== void 0 && output.previewDeployKey === void 0 || havePropsChanged(olds, news) ? { action: "replace" } : { action: "noop" });
-		},
-		read: Effect.fn(function* ({ output }) {
-			if (output === void 0) return void 0;
-			const entries = yield* absentAsUndefined(listKeys(output.projectId));
-			return entries !== void 0 && isKeyListed(entries, output) ? output : void 0;
-		}),
-		reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
-			if (output !== void 0) {
-				if (isKeyListed(yield* listKeys(news.projectId), output)) return output;
-			}
-			const name = requestedKeyName(news.name, fqn, instanceId);
-			const { keyId, uniqueName, secret } = yield* createTrackedKey({
-				target: `project ${news.projectId}`,
-				name,
-				list: listKeys(news.projectId),
-				create: api.request("create preview deploy key", (client) => client.POST("/projects/{project_id}/create_preview_deploy_key", {
-					params: { path: { project_id: news.projectId } },
-					body: { name }
-				})).pipe(Effect.map((body) => Schema.decodeUnknownSync(CreatedPreviewDeployKey)(body).previewDeployKey)),
-				isCredentialToken: api.isCredentialToken
-			});
+			if (output?.name === target.name && before === output.hash) return {
+				...target,
+				hash: output.hash,
+				envNames: previousEnvNames
+			};
+			const options = {
+				deployment: target.name,
+				url: target.url,
+				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, news.source, (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 {
-				uniqueName,
-				keyId,
-				projectId: news.projectId,
-				previewDeployKey: secret
+				...target,
+				hash: yield* wantedHash(news, target.name),
+				envNames: Object.keys(env).sort()
 			};
 		}),
 		delete: Effect.fn(function* ({ output }) {
-			const secret = yield* secretToDelete({
-				keyId: output.keyId,
-				secret: output.previewDeployKey
-			}, `Convex.PreviewDeployKey "${output.uniqueName}" in project ${output.projectId}`);
-			if (secret === void 0) return;
-			yield* absentAsUndefined(deleteKey(output.projectId, secret));
+			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 } } }))));
 		})
 	};
 }));
@@ -1208,12 +999,32 @@ var CreatedProjectNotFound = class extends Schema.TaggedError()("CreatedProjectN
 		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. */
@@ -1254,6 +1065,8 @@ const checkCreateTimeProps = (projectId, olds, news) => {
 	}));
 	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;
 const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 	const api = yield* ManagementApi;
 	const prodDeployment = (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)));
@@ -1266,6 +1079,11 @@ const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 		prodDeploymentUrl: prod?.deploymentUrl
 	})));
 	const getById = (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)));
+	/** 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)));
 	/**
 	* The one project in the team with exactly this name, or undefined.
 	* Reads every page. `q` narrows the listing on the server, and the
@@ -1331,6 +1149,22 @@ const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 		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({
@@ -1339,20 +1173,43 @@ const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 					requestedTeamId
 				});
 			}
-			return olds.name === news.name ? void 0 : { action: "update" };
+			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 = yield* findByName(yield* api.resolveTeamId(olds.team), olds.name);
+			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) yield* checkCreateTimeProps(output.projectId, olds, news);
+				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,
@@ -1393,20 +1250,12 @@ const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 //#region src/Providers.ts
 var Providers = class extends Provider.ProviderCollection()("Convex") {};
 /**
-* All Convex resource providers. Pass a credentials layer to override the
-* default lookup (`CONVEX_ACCESS_TOKEN`, then the Convex CLI login).
+* The Convex resource providers. Pass a credentials layer to override the
+* default lookup (`CONVEX_ACCESS_TOKEN`, then the Convex CLI login, and
+* `CONVEX_DEPLOY_KEY`).
 */
-const providers = (credentials = fromConfig()) => Layer.effect(Providers, Provider.collection([
-	Project,
-	Deployment,
-	DeployKey,
-	PreviewDeployKey,
-	EnvironmentVariable,
-	DefaultEnvironmentVariable,
-	Code,
-	Deploy
-])).pipe(Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider(), DeployKeyProvider(), PreviewDeployKeyProvider(), EnvironmentVariableProvider(), DefaultEnvironmentVariableProvider(), CodeProvider(), DeployProvider())), Layer.provide(ManagementApiLive()), Layer.provide(credentials), Layer.provide(CommandExecutorLive()), Layer.orDie);
+const providers = (credentials = fromConfig()) => Layer.effect(Providers, Provider.collection([Project, Deployment])).pipe(Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())), Layer.provide(ManagementApiLive()), Layer.provide(credentials), Layer.orDie);
 //#endregion
-export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, Code, CodePushFailed, ConvexApiError, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DefaultEnvironmentVariable, Deploy, DeployArgumentError, DeployKey, DeployKeyIsCredential, DeployKeyMismatch, DeployKeyRecoveryRequired, DeployOutputError, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, EnvironmentVariable, ManagementApi, PreviewDeployKey, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectTeamChange, Providers, PushTargetMismatch, VariableIdentityChange, deployArgs, fromConfig, fromToken, parseDeployOutput, providers };
+export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers };
 
 //# sourceMappingURL=index.js.map