@gaganref/confect-alchemy 0.0.0-stage → 10.3.1-fork.2

package/dist/internal/CommandRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRunner.js","names":[],"sources":["../../src/internal/CommandRunner.ts"],"sourcesContent":["import * as Config from \"effect/Config\";\nimport * as Context from \"effect/Context\";\nimport * as Effect from \"effect/Effect\";\nimport * as FileSystem from \"effect/FileSystem\";\nimport * as Layer from \"effect/Layer\";\nimport * as Path from \"effect/Path\";\nimport * as Redacted from \"effect/Redacted\";\nimport * as Schema from \"effect/Schema\";\nimport { ChildProcess, ChildProcessSpawner } from \"effect/process\";\n\nexport interface PrepareCommand {\n  readonly command: string;\n  readonly args: ReadonlyArray<string>;\n}\n\n/**\n * Where a push goes: a cloud deployment through its deploy key, or a local\n * backend through the CLI's self-hosted target and its admin key.\n */\nexport type PushTarget =\n  | {\n      readonly _tag: \"Cloud\";\n      readonly deploymentName: string;\n      readonly deployKey: Redacted.Redacted<string>;\n    }\n  | {\n      readonly _tag: \"SelfHosted\";\n      readonly deploymentName: string;\n      readonly url: string;\n      readonly adminKey: Redacted.Redacted<string>;\n    };\n\nconst selection = (target: PushTarget) =>\n  target._tag === \"Cloud\"\n    ? `CONVEX_DEPLOY_KEY=${Redacted.value(target.deployKey)}\\n`\n    : `CONVEX_SELF_HOSTED_URL=${target.url}\\nCONVEX_SELF_HOSTED_ADMIN_KEY=${Redacted.value(target.adminKey)}\\n`;\n\nexport class CommandError extends Schema.TaggedError<CommandError>()(\n  \"CommandError\",\n  {\n    operation: Schema.Literals([\"prepare\", \"deploy\"]),\n    reason: Schema.Literals([\"configuration\", \"spawn\", \"exit\"]),\n    exitCode: Schema.optionalKey(Schema.Finite),\n  },\n) {}\n\nexport class CommandRunner extends Context.Service<\n  CommandRunner,\n  {\n    readonly prepare: (\n      command: PrepareCommand,\n      cwd?: string,\n    ) => Effect.Effect<void, CommandError>;\n    readonly deploy: (\n      target: PushTarget,\n      cwd?: string,\n    ) => Effect.Effect<void, CommandError>;\n  }\n>()(\"@confect/alchemy/internal/CommandRunner\") {}\n\n/**\n * The ambient variables a child process needs to run on every platform; the\n * rest of the parent environment, credentials included, is withheld.\n */\nexport const processEnvironment = Config.all({\n  PATH: Config.String(\"PATH\").pipe(\n    Config.orElse(() => Config.String(\"Path\")),\n    Config.withDefault(\"\"),\n  ),\n  HOME: Config.String(\"HOME\").pipe(Config.withDefault(\"\")),\n  USERPROFILE: Config.String(\"USERPROFILE\").pipe(Config.withDefault(\"\")),\n  SystemRoot: Config.String(\"SystemRoot\").pipe(\n    Config.orElse(() => Config.String(\"SYSTEMROOT\")),\n    Config.withDefault(\"\"),\n  ),\n  TMPDIR: Config.String(\"TMPDIR\").pipe(Config.withDefault(\"\")),\n  TEMP: Config.String(\"TEMP\").pipe(Config.withDefault(\"\")),\n});\n\nconst packageBin = Effect.fn(\"CommandRunner.packageBin\")(function* (\n  fs: FileSystem.FileSystem,\n  path: Path.Path,\n  cwd: string,\n  packageName: string,\n  binName: string,\n) {\n  const invalid = () =>\n    new CommandError({\n      operation: packageName === \"convex\" ? \"deploy\" : \"prepare\",\n      reason: \"configuration\",\n    });\n  let directory = cwd;\n  while (true) {\n    const manifestPath = path.join(\n      directory,\n      \"node_modules\",\n      packageName,\n      \"package.json\",\n    );\n    if (yield* fs.exists(manifestPath).pipe(Effect.mapError(invalid))) {\n      const manifest = yield* fs.readFileString(manifestPath).pipe(\n        Effect.flatMap(\n          Schema.decodeEffect(\n            Schema.fromJsonString(\n              Schema.Struct({\n                bin: Schema.Union([\n                  Schema.String,\n                  Schema.Record(Schema.String, Schema.String),\n                ]),\n              }),\n            ),\n          ),\n        ),\n        Effect.mapError(invalid),\n      );\n      const relative =\n        typeof manifest.bin === \"string\" ? manifest.bin : manifest.bin[binName];\n      if (!relative) return yield* invalid();\n      return path.resolve(path.dirname(manifestPath), relative);\n    }\n    const parent = path.dirname(directory);\n    if (parent === directory) return yield* invalid();\n    directory = parent;\n  }\n});\n\nexport const layer = Layer.effect(\n  CommandRunner,\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    const path = yield* Path.Path;\n    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;\n    const run = Effect.fn(\"CommandRunner.run\")(function* (\n      operation: \"prepare\" | \"deploy\",\n      command: string,\n      args: ReadonlyArray<string>,\n      cwd: string,\n      env: Record<string, string | undefined>,\n    ) {\n      const code = yield* spawner\n        .exitCode(\n          ChildProcess.make(command, args, {\n            cwd,\n            env,\n            extendEnv: false,\n            stdin: \"ignore\",\n            stdout: \"ignore\",\n            stderr: \"ignore\",\n          }),\n        )\n        .pipe(\n          Effect.mapError(\n            () => new CommandError({ operation, reason: \"spawn\" }),\n          ),\n        );\n      if (code !== 0)\n        return yield* new CommandError({\n          operation,\n          reason: \"exit\",\n          exitCode: Number(code),\n        });\n    });\n    const environment = processEnvironment.pipe(\n      Effect.map((env) => ({ ...env, CI: \"true\", DO_NOT_TRACK: \"1\" })),\n    );\n    return CommandRunner.of({\n      prepare: Effect.fn(\"CommandRunner.prepare\")(function* (\n        command,\n        cwd = process.cwd(),\n      ) {\n        const directory = path.resolve(cwd);\n        const env = yield* environment.pipe(\n          Effect.mapError(\n            () =>\n              new CommandError({\n                operation: \"prepare\",\n                reason: \"configuration\",\n              }),\n          ),\n        );\n        if (command.command === \"confect\") {\n          const bin = yield* packageBin(\n            fs,\n            path,\n            directory,\n            \"@confect/cli\",\n            \"confect\",\n          );\n          yield* run(\n            \"prepare\",\n            process.execPath,\n            [bin, ...command.args],\n            directory,\n            env,\n          );\n        } else {\n          yield* run(\"prepare\", command.command, command.args, directory, env);\n        }\n      }),\n      deploy: Effect.fn(\"CommandRunner.deploy\")(function* (\n        target,\n        cwd = process.cwd(),\n      ) {\n        const directory = path.resolve(cwd);\n        const bin = yield* packageBin(fs, path, directory, \"convex\", \"convex\");\n        const env = yield* environment.pipe(\n          Effect.mapError(\n            () =>\n              new CommandError({\n                operation: \"deploy\",\n                reason: \"configuration\",\n              }),\n          ),\n        );\n        yield* Effect.scoped(\n          Effect.gen(function* () {\n            const temp = yield* fs.makeTempDirectoryScoped({\n              prefix: \"confect-deploy-\",\n            });\n            const envFile = path.join(temp, \"deployment.env\");\n            yield* fs.writeFileString(envFile, selection(target), {\n              mode: 0o600,\n            });\n            yield* run(\n              \"deploy\",\n              process.execPath,\n              [bin, \"deploy\", \"--yes\", \"--env-file\", envFile],\n              directory,\n              {\n                ...env,\n                HOME: temp,\n                USERPROFILE: temp,\n                LOCALAPPDATA: temp,\n                XDG_CONFIG_HOME: temp,\n              },\n            );\n          }).pipe(\n            Effect.mapError((error) =>\n              Schema.is(CommandError)(error)\n                ? error\n                : new CommandError({\n                    operation: \"deploy\",\n                    reason: \"configuration\",\n                  }),\n            ),\n          ),\n        );\n      }),\n    });\n  }),\n);\n"],"mappings":"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"}

package/dist/internal/FileLock.d.ts

@@ -0,0 +1,30 @@
+import * as Crypto from "effect/Crypto";
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+declare const FileLockError_base: Schema.Class<FileLockError, Schema.TaggedStruct<"FileLockError", {
+    readonly reason: Schema.Literals<readonly ["held", "timeout", "filesystem"]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class FileLockError extends FileLockError_base {
+}
+/**
+ * Hold an exclusive lock file for the ambient scope, waiting up to `wait` for
+ * another holder or failing with `held` at once when `wait` is omitted.
+ *
+ * The holder, `{ pid, token }`, is written to a private claim file and
+ * published with a hard link, which fails when the lock exists, so a visible
+ * lock always names its holder. A lock whose holder has exited is removed only
+ * under `<file>.recovery`, after re-reading that the same dead holder still
+ * owns it, so a successor's lock is never removed in its place. Publishing and
+ * recovering are uninterruptible: Node cannot cancel a link or unlink it has
+ * started, so stopping early would let one land after `.recovery` is released.
+ * The recovery lock is never reclaimed: a crash inside its few file operations
+ * leaves waiters timing out rather than overlapping. A timeout that lands while
+ * an attempt succeeds still fails, and the published lock is removed only when
+ * the ambient scope closes.
+ */
+export declare const acquire: (file: string, wait?: Duration.Input | undefined) => Effect.Effect<undefined, FileLockError, Crypto.Crypto | FileSystem.FileSystem | Path.Path | import("effect/Scope").Scope>;
+export {};
+//# sourceMappingURL=FileLock.d.ts.map

package/dist/internal/FileLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileLock.d.ts","sourceRoot":"","sources":["../../src/internal/FileLock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAGpC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;;;;AAExC,qBAAa,aAAc,SAAQ,kBAGlC;CAAG;AAgBJ;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,gLA0FlB,CAAC"}

package/dist/internal/FileLock.js

@@ -0,0 +1,83 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Option from "effect/Option";
+import * as Crypto from "effect/Crypto";
+import * as Predicate from "effect/Predicate";
+import * as Schedule from "effect/Schedule";
+//#region src/internal/FileLock.ts
+var FileLockError = class extends Schema.TaggedError()("FileLockError", { reason: Schema.Literals([
+	"held",
+	"timeout",
+	"filesystem"
+]) }) {};
+const Holder = Schema.fromJsonString(Schema.Struct({
+	pid: Schema.Finite,
+	token: Schema.String
+}));
+const decodeHolder = Schema.decodeUnknownOption(Holder);
+const isAlive = (pid) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return Predicate.hasProperty(error, "code") && error.code === "EPERM";
+	}
+};
+/**
+* Hold an exclusive lock file for the ambient scope, waiting up to `wait` for
+* another holder or failing with `held` at once when `wait` is omitted.
+*
+* The holder, `{ pid, token }`, is written to a private claim file and
+* published with a hard link, which fails when the lock exists, so a visible
+* lock always names its holder. A lock whose holder has exited is removed only
+* under `<file>.recovery`, after re-reading that the same dead holder still
+* owns it, so a successor's lock is never removed in its place. Publishing and
+* recovering are uninterruptible: Node cannot cancel a link or unlink it has
+* started, so stopping early would let one land after `.recovery` is released.
+* The recovery lock is never reclaimed: a crash inside its few file operations
+* leaves waiters timing out rather than overlapping. A timeout that lands while
+* an attempt succeeds still fails, and the published lock is removed only when
+* the ambient scope closes.
+*/
+const acquire = Effect.fn("FileLock.acquire")(function* (file, wait) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const crypto = yield* Crypto.Crypto;
+	const failed = () => new FileLockError({ reason: "filesystem" });
+	const token = Buffer.from(yield* crypto.randomBytes(16).pipe(Effect.mapError(failed))).toString("hex");
+	const holder = yield* Schema.encodeEffect(Holder)({
+		pid: process.pid,
+		token
+	}).pipe(Effect.mapError(failed));
+	const claim = `${file}.${token}`;
+	const recovery = `${file}.recovery`;
+	const removeIfOwned = (target) => fs.readFileString(target).pipe(Effect.flatMap((content) => content === holder ? fs.remove(target) : Effect.void), Effect.ignore);
+	yield* Effect.addFinalizer(() => Effect.all([removeIfOwned(file), fs.remove(claim, { force: true }).pipe(Effect.ignore)]));
+	yield* fs.makeDirectory(path.dirname(file), { recursive: true }).pipe(Effect.mapError(failed));
+	yield* fs.writeFileString(claim, holder, { mode: 384 }).pipe(Effect.mapError(failed));
+	const read = (target) => fs.readFileString(target).pipe(Effect.map(decodeHolder), Effect.orElseSucceed(() => Option.none()));
+	const publish = (target) => fs.link(claim, target).pipe(Effect.as(true), Effect.catchReason("PlatformError", "AlreadyExists", () => Effect.succeed(false)));
+	const reclaim = Effect.gen(function* () {
+		const stale = yield* read(file);
+		if (Option.isNone(stale) || isAlive(stale.value.pid)) return false;
+		if (!(yield* publish(recovery))) return false;
+		return yield* read(file).pipe(Effect.flatMap((current) => Option.isSome(current) && current.value.token === stale.value.token ? fs.remove(file).pipe(Effect.as(true)) : Effect.succeed(false)), Effect.ensuring(removeIfOwned(recovery)));
+	});
+	const attempt = publish(file).pipe(Effect.flatMap((acquired) => acquired ? Effect.succeed(true) : Effect.flatMap(reclaim, (removed) => removed ? publish(file) : Effect.succeed(false))), Effect.uninterruptible, Effect.mapError(failed));
+	if (wait === void 0) {
+		if (!(yield* attempt)) return yield* new FileLockError({ reason: "held" });
+	} else yield* attempt.pipe(Effect.repeat({
+		until: (acquired) => acquired,
+		schedule: Schedule.spaced("100 millis")
+	}), Effect.timeoutOrElse({
+		duration: wait,
+		orElse: () => Effect.fail(new FileLockError({ reason: "timeout" }))
+	}));
+	yield* fs.remove(claim, { force: true }).pipe(Effect.ignore);
+});
+//#endregion
+export { FileLockError, acquire };
+
+//# sourceMappingURL=FileLock.js.map

package/dist/internal/FileLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileLock.js","names":[],"sources":["../../src/internal/FileLock.ts"],"sourcesContent":["import * as Crypto from \"effect/Crypto\";\nimport type * as Duration from \"effect/Duration\";\nimport * as Effect from \"effect/Effect\";\nimport * as FileSystem from \"effect/FileSystem\";\nimport * as Option from \"effect/Option\";\nimport * as Path from \"effect/Path\";\nimport * as Predicate from \"effect/Predicate\";\nimport * as Schedule from \"effect/Schedule\";\nimport * as Schema from \"effect/Schema\";\n\nexport class FileLockError extends Schema.TaggedError<FileLockError>()(\n  \"FileLockError\",\n  { reason: Schema.Literals([\"held\", \"timeout\", \"filesystem\"]) },\n) {}\n\nconst Holder = Schema.fromJsonString(\n  Schema.Struct({ pid: Schema.Finite, token: Schema.String }),\n);\nconst decodeHolder = Schema.decodeUnknownOption(Holder);\n\nconst isAlive = (pid: number) => {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (error) {\n    return Predicate.hasProperty(error, \"code\") && error.code === \"EPERM\";\n  }\n};\n\n/**\n * Hold an exclusive lock file for the ambient scope, waiting up to `wait` for\n * another holder or failing with `held` at once when `wait` is omitted.\n *\n * The holder, `{ pid, token }`, is written to a private claim file and\n * published with a hard link, which fails when the lock exists, so a visible\n * lock always names its holder. A lock whose holder has exited is removed only\n * under `<file>.recovery`, after re-reading that the same dead holder still\n * owns it, so a successor's lock is never removed in its place. Publishing and\n * recovering are uninterruptible: Node cannot cancel a link or unlink it has\n * started, so stopping early would let one land after `.recovery` is released.\n * The recovery lock is never reclaimed: a crash inside its few file operations\n * leaves waiters timing out rather than overlapping. A timeout that lands while\n * an attempt succeeds still fails, and the published lock is removed only when\n * the ambient scope closes.\n */\nexport const acquire = Effect.fn(\"FileLock.acquire\")(function* (\n  file: string,\n  wait?: Duration.Input,\n) {\n  const fs = yield* FileSystem.FileSystem;\n  const path = yield* Path.Path;\n  const crypto = yield* Crypto.Crypto;\n  const failed = () => new FileLockError({ reason: \"filesystem\" });\n  const token = Buffer.from(\n    yield* crypto.randomBytes(16).pipe(Effect.mapError(failed)),\n  ).toString(\"hex\");\n  const holder = yield* Schema.encodeEffect(Holder)({\n    pid: process.pid,\n    token,\n  }).pipe(Effect.mapError(failed));\n  const claim = `${file}.${token}`;\n  const recovery = `${file}.recovery`;\n  const removeIfOwned = (target: string) =>\n    fs.readFileString(target).pipe(\n      Effect.flatMap((content) =>\n        content === holder ? fs.remove(target) : Effect.void,\n      ),\n      Effect.ignore,\n    );\n  yield* Effect.addFinalizer(() =>\n    Effect.all([\n      removeIfOwned(file),\n      fs.remove(claim, { force: true }).pipe(Effect.ignore),\n    ]),\n  );\n  yield* fs\n    .makeDirectory(path.dirname(file), { recursive: true })\n    .pipe(Effect.mapError(failed));\n  yield* fs\n    .writeFileString(claim, holder, { mode: 0o600 })\n    .pipe(Effect.mapError(failed));\n\n  const read = (target: string) =>\n    fs.readFileString(target).pipe(\n      Effect.map(decodeHolder),\n      Effect.orElseSucceed(() => Option.none()),\n    );\n  const publish = (target: string) =>\n    fs.link(claim, target).pipe(\n      Effect.as(true),\n      Effect.catchReason(\"PlatformError\", \"AlreadyExists\", () =>\n        Effect.succeed(false),\n      ),\n    );\n  // Whether a dead holder's lock was removed.\n  const reclaim = Effect.gen(function* () {\n    const stale = yield* read(file);\n    if (Option.isNone(stale) || isAlive(stale.value.pid)) return false;\n    if (!(yield* publish(recovery))) return false;\n    return yield* read(file).pipe(\n      Effect.flatMap((current) =>\n        Option.isSome(current) && current.value.token === stale.value.token\n          ? fs.remove(file).pipe(Effect.as(true))\n          : Effect.succeed(false),\n      ),\n      Effect.ensuring(removeIfOwned(recovery)),\n    );\n  });\n  const attempt = publish(file).pipe(\n    Effect.flatMap((acquired) =>\n      acquired\n        ? Effect.succeed(true)\n        : Effect.flatMap(reclaim, (removed) =>\n            removed ? publish(file) : Effect.succeed(false),\n          ),\n    ),\n    Effect.uninterruptible,\n    Effect.mapError(failed),\n  );\n\n  if (wait === undefined) {\n    if (!(yield* attempt)) return yield* new FileLockError({ reason: \"held\" });\n  } else {\n    yield* attempt.pipe(\n      Effect.repeat({\n        until: (acquired) => acquired,\n        schedule: Schedule.spaced(\"100 millis\"),\n      }),\n      Effect.timeoutOrElse({\n        duration: wait,\n        orElse: () => Effect.fail(new FileLockError({ reason: \"timeout\" })),\n      }),\n    );\n  }\n  yield* fs.remove(claim, { force: true }).pipe(Effect.ignore);\n});\n"],"mappings":"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"}

package/dist/internal/Lifecycle.d.ts

@@ -0,0 +1,11 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+declare const LifecycleStateError_base: Schema.Class<LifecycleStateError, Schema.TaggedStruct<"LifecycleStateError", {
+    readonly fqn: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class LifecycleStateError extends LifecycleStateError_base {
+}
+export declare const checkpointCreate: (fqn: string, instanceId: string, props: object, output?: object | undefined) => Effect.Effect<undefined, LifecycleStateError | import("alchemy/State/State").StateStoreError, never>;
+export declare const shouldAdopt: (fqn: string) => Effect.Effect<boolean, never, never>;
+export {};
+//# sourceMappingURL=Lifecycle.d.ts.map

package/dist/internal/Lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lifecycle.d.ts","sourceRoot":"","sources":["../../src/internal/Lifecycle.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;;;;AAExC,qBAAa,mBAAoB,SAAQ,wBAGxC;CAAG;AAEJ,eAAO,MAAM,gBAAgB,uLAqB5B,CAAC;AAEF,eAAO,MAAM,WAAW,uDAYtB,CAAC"}

package/dist/internal/Lifecycle.js

@@ -0,0 +1,45 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+import { AdoptPolicy } from "alchemy/AdoptPolicy";
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import { Stack } from "alchemy/Stack";
+import { State } from "alchemy/State/State";
+//#region src/internal/Lifecycle.ts
+var LifecycleStateError = class extends Schema.TaggedError()("LifecycleStateError", { fqn: Schema.String }) {};
+const checkpointCreate = Effect.fn("Lifecycle.checkpointCreate")(function* (fqn, instanceId, props, output) {
+	const stack = yield* Effect.serviceOption(Stack);
+	if (Option.isNone(stack)) return;
+	const state = yield* Effect.serviceOption(State);
+	if (Option.isNone(state)) return yield* new LifecycleStateError({ fqn });
+	const store = yield* state.value;
+	const key = {
+		stack: stack.value.name,
+		stage: stack.value.stage,
+		fqn
+	};
+	const row = yield* store.get(key);
+	if (!row || row.kind === "action" || row.instanceId !== instanceId) return yield* new LifecycleStateError({ fqn });
+	if (row.status !== "creating") return;
+	yield* store.set({
+		...key,
+		value: {
+			...row,
+			props,
+			...output === void 0 ? {} : { attr: output }
+		}
+	});
+});
+const shouldAdopt = Effect.fn("Lifecycle.shouldAdopt")(function* (fqn) {
+	const stack = yield* Effect.serviceOption(Stack);
+	const resourcePolicy = Option.isSome(stack) ? stack.value.resources[fqn]?.Adopt : void 0;
+	if (resourcePolicy !== void 0) return resourcePolicy;
+	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
+export { LifecycleStateError, checkpointCreate, shouldAdopt };
+
+//# sourceMappingURL=Lifecycle.js.map

package/dist/internal/Lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lifecycle.js","names":[],"sources":["../../src/internal/Lifecycle.ts"],"sourcesContent":["import { AdoptPolicy } from \"alchemy/AdoptPolicy\";\nimport { AlchemyContext } from \"alchemy/AlchemyContext\";\nimport { Stack } from \"alchemy/Stack\";\nimport { State } from \"alchemy/State/State\";\nimport * as Effect from \"effect/Effect\";\nimport * as Option from \"effect/Option\";\nimport * as Schema from \"effect/Schema\";\n\nexport class LifecycleStateError extends Schema.TaggedError<LifecycleStateError>()(\n  \"LifecycleStateError\",\n  { fqn: Schema.String },\n) {}\n\nexport const checkpointCreate = Effect.fn(\"Lifecycle.checkpointCreate\")(\n  function* (fqn: string, instanceId: string, props: object, output?: object) {\n    const stack = yield* Effect.serviceOption(Stack);\n    if (Option.isNone(stack)) return;\n    const state = yield* Effect.serviceOption(State);\n    if (Option.isNone(state)) return yield* new LifecycleStateError({ fqn });\n    const store = yield* state.value;\n    const key = { stack: stack.value.name, stage: stack.value.stage, fqn };\n    const row = yield* store.get(key);\n    if (!row || row.kind === \"action\" || row.instanceId !== instanceId)\n      return yield* new LifecycleStateError({ fqn });\n    if (row.status !== \"creating\") return;\n    yield* store.set({\n      ...key,\n      value: {\n        ...row,\n        props,\n        ...(output === undefined ? {} : { attr: output }),\n      },\n    });\n  },\n);\n\nexport const shouldAdopt = Effect.fn(\"Lifecycle.shouldAdopt\")(function* (\n  fqn: string,\n) {\n  const stack = yield* Effect.serviceOption(Stack);\n  const resourcePolicy = Option.isSome(stack)\n    ? stack.value.resources[fqn]?.Adopt\n    : undefined;\n  if (resourcePolicy !== undefined) return resourcePolicy;\n  const policy = yield* Effect.serviceOption(AdoptPolicy);\n  if (Option.isSome(policy)) return policy.value;\n  const context = yield* Effect.serviceOption(AlchemyContext);\n  return Option.isSome(context) && context.value.adopt;\n});\n"],"mappings":";;;;;;;;AAQA,IAAa,sBAAb,cAAyC,OAAO,YAAiC,CAAC,CAChF,uBACA,EAAE,KAAK,OAAO,OAAO,CACvB,CAAC,CAAC,CAAC;AAEH,MAAa,mBAAmB,OAAO,GAAG,4BAA4B,CAAC,CACrE,WAAW,KAAa,YAAoB,OAAe,QAAiB;CAC1E,MAAM,QAAQ,OAAO,OAAO,cAAc,KAAK;CAC/C,IAAI,OAAO,OAAO,KAAK,GAAG;CAC1B,MAAM,QAAQ,OAAO,OAAO,cAAc,KAAK;CAC/C,IAAI,OAAO,OAAO,KAAK,GAAG,OAAO,OAAO,IAAI,oBAAoB,EAAE,IAAI,CAAC;CACvE,MAAM,QAAQ,OAAO,MAAM;CAC3B,MAAM,MAAM;EAAE,OAAO,MAAM,MAAM;EAAM,OAAO,MAAM,MAAM;EAAO;CAAI;CACrE,MAAM,MAAM,OAAO,MAAM,IAAI,GAAG;CAChC,IAAI,CAAC,OAAO,IAAI,SAAS,YAAY,IAAI,eAAe,YACtD,OAAO,OAAO,IAAI,oBAAoB,EAAE,IAAI,CAAC;CAC/C,IAAI,IAAI,WAAW,YAAY;CAC/B,OAAO,MAAM,IAAI;EACf,GAAG;EACH,OAAO;GACL,GAAG;GACH;GACA,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM,OAAO;EACjD;CACF,CAAC;AACH,CACF;AAEA,MAAa,cAAc,OAAO,GAAG,uBAAuB,CAAC,CAAC,WAC5D,KACA;CACA,MAAM,QAAQ,OAAO,OAAO,cAAc,KAAK;CAC/C,MAAM,iBAAiB,OAAO,OAAO,KAAK,IACtC,MAAM,MAAM,UAAU,IAAI,EAAE,QAC5B,KAAA;CACJ,IAAI,mBAAmB,KAAA,GAAW,OAAO;CACzC,MAAM,SAAS,OAAO,OAAO,cAAc,WAAW;CACtD,IAAI,OAAO,OAAO,MAAM,GAAG,OAAO,OAAO;CACzC,MAAM,UAAU,OAAO,OAAO,cAAc,cAAc;CAC1D,OAAO,OAAO,OAAO,OAAO,KAAK,QAAQ,MAAM;AACjD,CAAC"}

package/dist/internal/LocalBackend.d.ts

@@ -0,0 +1,63 @@
+import { Stack } from "alchemy/Stack";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as HttpClient from "effect/http/HttpClient";
+import { ChildProcessSpawner } from "effect/process";
+/**
+ * The backend release a new local deployment runs. An existing data directory
+ * keeps running the release that created it, so upgrading this package never
+ * opens a database with a different release.
+ */
+export declare const backendVersion = "precompiled-2026-10-06-a3538c6";
+declare const LocalBackendError_base: Schema.Class<LocalBackendError, Schema.TaggedStruct<"LocalBackendError", {
+    readonly deploymentName: Schema.String;
+    readonly reason: Schema.Literals<readonly ["configuration", "filesystem", "install", "identity", "ports", "running", "spawn", "exit", "timeout"]>;
+    readonly exitCode: Schema.optionalKey<Schema.Finite>;
+}>, import("effect/Cause").YieldableError>;
+export declare class LocalBackendError extends LocalBackendError_base {
+    get message(): string;
+}
+export interface LocalBackend {
+    readonly url: string;
+    readonly siteUrl: string;
+    readonly adminKey: Redacted.Redacted<string>;
+    /**
+     * Completes when the backend process has exited and released its data
+     * directory, so the deployment can be booted again.
+     */
+    readonly exited: Effect.Effect<void>;
+}
+/**
+ * Resolves the directory that holds one local deployment's identity, database,
+ * and file storage: `.alchemy/convex/<stack>/<stage>/<deployment>`. Keyed by
+ * the deployment name because a deploy key resource only knows that name.
+ */
+export declare const dataDirectories: Effect.Effect<(deploymentName: string) => string, never, Path.Path | Stack>;
+/**
+ * The admin key of a local deployment, for its deploy key resource.
+ */
+export declare const adminKey: (deploymentName: string, directory: string) => Effect.Effect<Redacted.Redacted<string>, LocalBackendError, FileSystem.FileSystem | Path.Path>;
+export declare const remove: (deploymentName: string, directory: string) => Effect.Effect<void, LocalBackendError, FileSystem.FileSystem>;
+/**
+ * Boot the local backend for one deployment and keep it running for the ambient
+ * scope. The process and the data directory's `owner.lock` share a child scope
+ * that closes when the boot fails or is interrupted and when the process exits,
+ * so a deployment can be booted again in the same session. The first boot
+ * installs the pinned release, generates an instance secret and admin key, and
+ * picks two free loopback ports; later boots reuse all of them, so stored
+ * credentials and URLs stay valid. A saved port that something else now holds
+ * is an error rather than a move, because resources keep the URL.
+ */
+export declare const boot: (deploymentName: string, directory: string) => Effect.Effect<{
+    url: string;
+    siteUrl: string;
+    adminKey: Redacted.Redacted<string>;
+    exited: Effect.Effect<void, never, never>;
+}, LocalBackendError, ChildProcessSpawner.ChildProcessSpawner | Crypto.Crypto | FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | Scope.Scope>;
+export {};
+//# sourceMappingURL=LocalBackend.d.ts.map

package/dist/internal/LocalBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalBackend.d.ts","sourceRoot":"","sources":["../../src/internal/LocalBackend.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAgB,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAOnE;;;;GAIG;AACH,eAAO,MAAM,cAAc,mCAAmC,CAAC;;;;;;AAE/D,qBAAa,iBAAkB,SAAQ,sBAiBtC;IACC,IAAa,OAAO,WAsBnB;CACF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACtC;AAmED;;;;GAIG;AACH,eAAO,MAAM,eAAe,iCASF,MAAM,sCAC9B,CAAC;AAuBH;;GAEG;AACH,eAAO,MAAM,QAAQ,+IAQnB,CAAC;AAEH,eAAO,MAAM,MAAM,8GAYjB,CAAC;AA0CH;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI;;;;;wJAiOf,CAAC"}

package/dist/internal/LocalBackend.js

@@ -0,0 +1,333 @@
+import { processEnvironment } from "./CommandRunner.js";
+import { origin, parsePortRange } from "./Loopback.js";
+import { acquire } from "./FileLock.js";
+import { userCache } from "./UserCache.js";
+import { extract } from "./Zip.js";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import * as Config from "effect/Config";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import * as Option from "effect/Option";
+import * as Crypto from "effect/Crypto";
+import * as Scope from "effect/Scope";
+import * as Schedule from "effect/Schedule";
+import * as HttpClient from "effect/http/HttpClient";
+import { dotAlchemyDirectory } from "alchemy/AlchemyContext";
+import { Stack } from "alchemy/Stack";
+import { createServer } from "node:net";
+import * as Deferred from "effect/Deferred";
+import * as Exit from "effect/Exit";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+//#region src/internal/LocalBackend.ts
+/**
+* The backend release a new local deployment runs. An existing data directory
+* keeps running the release that created it, so upgrading this package never
+* opens a database with a different release.
+*/
+const backendVersion = "precompiled-2026-10-06-a3538c6";
+var LocalBackendError = class extends Schema.TaggedError()("LocalBackendError", {
+	deploymentName: Schema.String,
+	reason: Schema.Literals([
+		"configuration",
+		"filesystem",
+		"install",
+		"identity",
+		"ports",
+		"running",
+		"spawn",
+		"exit",
+		"timeout"
+	]),
+	exitCode: Schema.optionalKey(Schema.Finite)
+}) {
+	get message() {
+		const subject = `Local backend for ${this.deploymentName}`;
+		switch (this.reason) {
+			case "configuration": return `${subject} needs a home directory and, when set, CONFECT_LOCAL_BACKEND_PORTS as a range such as 3300-3399`;
+			case "filesystem": return `${subject} could not read or write its data directory`;
+			case "install": return `${subject} could not download or install the backend binary`;
+			case "identity": return `${subject} could not read, create, or save its identity`;
+			case "ports": return `${subject} could not get its ports; another process is using them`;
+			case "running": return `${subject} is already running: stop the other alchemy dev session, or the backend process left over from one, that serves its data directory`;
+			case "spawn": return `${subject} could not be started`;
+			case "exit": return `${subject} exited${this.exitCode === void 0 ? "" : ` with code ${this.exitCode}`} before it was ready`;
+			case "timeout": return `${subject} did not become ready in time`;
+		}
+	}
+};
+const Identity = Schema.fromJsonString(Schema.Struct({
+	name: Schema.String,
+	version: Schema.String,
+	instanceSecret: Schema.String,
+	adminKey: Schema.String,
+	ports: Schema.optionalKey(Schema.Struct({
+		port: Schema.Int,
+		sitePort: Schema.Int
+	}))
+}));
+const artifacts = {
+	"darwin-arm64": "convex-local-backend-aarch64-apple-darwin.zip",
+	"darwin-x64": "convex-local-backend-x86_64-apple-darwin.zip",
+	"linux-arm64": "convex-local-backend-aarch64-unknown-linux-gnu.zip",
+	"linux-x64": "convex-local-backend-x86_64-unknown-linux-gnu.zip",
+	"win32-arm64": "convex-local-backend-x86_64-pc-windows-msvc.zip",
+	"win32-x64": "convex-local-backend-x86_64-pc-windows-msvc.zip"
+};
+const executable = process.platform === "win32" ? "convex-local-backend.exe" : "convex-local-backend";
+const close = (server) => Effect.callback((resume) => {
+	server.close(() => resume(Effect.void));
+});
+const listen = (port) => Effect.acquireRelease(Effect.callback((resume) => {
+	const server = createServer();
+	server.once("error", () => resume(Effect.undefined));
+	server.listen(port, "127.0.0.1", () => resume(Effect.succeed(server)));
+}), (server) => server ? close(server) : Effect.void);
+const isFree = (port) => listen(port).pipe(Effect.map((server) => server !== void 0), Effect.scoped);
+const portOf = (server) => {
+	const address = server?.address();
+	return typeof address === "object" && address !== null ? address.port : void 0;
+};
+const startup = Semaphore.makeUnsafe(1);
+/**
+* Resolves the directory that holds one local deployment's identity, database,
+* and file storage: `.alchemy/convex/<stack>/<stage>/<deployment>`. Keyed by
+* the deployment name because a deploy key resource only knows that name.
+*/
+const dataDirectories = Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const stack = yield* Stack;
+	const root = path.resolve(yield* dotAlchemyDirectory, "convex", stack.name, stack.stage);
+	return (deploymentName) => path.join(root, deploymentName);
+});
+const readIdentity = Effect.fn("LocalBackend.readIdentity")(function* (deploymentName, directory) {
+	const fs = yield* FileSystem.FileSystem;
+	const file = (yield* Path.Path).join(directory, "identity.json");
+	const invalid = () => new LocalBackendError({
+		deploymentName,
+		reason: "identity"
+	});
+	if (!(yield* fs.exists(file).pipe(Effect.mapError(invalid)))) return Option.none();
+	const identity = yield* fs.readFileString(file).pipe(Effect.flatMap(Schema.decodeEffect(Identity)), Effect.mapError(invalid));
+	if (identity.name !== deploymentName) return yield* invalid();
+	return Option.some(identity);
+});
+/**
+* The admin key of a local deployment, for its deploy key resource.
+*/
+const adminKey = Effect.fn("LocalBackend.adminKey")(function* (deploymentName, directory) {
+	const identity = yield* readIdentity(deploymentName, directory);
+	if (Option.isNone(identity)) return yield* new LocalBackendError({
+		deploymentName,
+		reason: "identity"
+	});
+	return Redacted.make(identity.value.adminKey);
+});
+const remove = Effect.fn("LocalBackend.remove")(function* (deploymentName, directory) {
+	yield* (yield* FileSystem.FileSystem).remove(directory, {
+		recursive: true,
+		force: true
+	}).pipe(Effect.mapError(() => new LocalBackendError({
+		deploymentName,
+		reason: "filesystem"
+	})));
+});
+/**
+* Install a backend release into the Convex CLI's binary cache,
+* `<cache>/convex/binaries/<version>/`, unless it is already there.
+*/
+const install = Effect.fn("LocalBackend.install")(function* (deploymentName, version, cache) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const http = yield* HttpClient.HttpClient;
+	const failed = () => new LocalBackendError({
+		deploymentName,
+		reason: "install"
+	});
+	const binaries = path.join(cache, "convex", "binaries");
+	const binary = path.join(binaries, version, executable);
+	const artifact = artifacts[`${process.platform}-${process.arch}`];
+	return yield* Effect.gen(function* () {
+		if (yield* fs.exists(binary)) return binary;
+		if (artifact === void 0) return yield* failed();
+		yield* fs.makeDirectory(binaries, { recursive: true });
+		const temp = yield* fs.makeTempDirectoryScoped({
+			directory: binaries,
+			prefix: ".download-"
+		});
+		const archive = path.join(temp, artifact);
+		const response = yield* http.get(`https://github.com/get-convex/convex-backend/releases/download/${version}/${artifact}`);
+		if (response.status !== 200) return yield* failed();
+		yield* response.stream.pipe(Stream.run(fs.sink(archive)));
+		const extracted = path.join(temp, executable);
+		yield* extract(archive, executable, extracted);
+		yield* fs.chmod(extracted, 493);
+		yield* fs.makeDirectory(path.dirname(binary), { recursive: true });
+		yield* fs.rename(extracted, binary);
+		return binary;
+	}).pipe(Effect.scoped, Effect.mapError(failed));
+});
+/**
+* Boot the local backend for one deployment and keep it running for the ambient
+* scope. The process and the data directory's `owner.lock` share a child scope
+* that closes when the boot fails or is interrupted and when the process exits,
+* so a deployment can be booted again in the same session. The first boot
+* installs the pinned release, generates an instance secret and admin key, and
+* picks two free loopback ports; later boots reuse all of them, so stored
+* credentials and URLs stay valid. A saved port that something else now holds
+* is an error rather than a move, because resources keep the URL.
+*/
+const boot = Effect.fn("LocalBackend.boot")(function* (deploymentName, directory) {
+	const path = yield* Path.Path;
+	const fs = yield* FileSystem.FileSystem;
+	const http = yield* HttpClient.HttpClient;
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const crypto = yield* Crypto.Crypto;
+	const fail = (reason, exitCode) => new LocalBackendError({
+		deploymentName,
+		reason,
+		...exitCode === void 0 ? {} : { exitCode }
+	});
+	const settings = yield* Config.all({
+		environment: processEnvironment,
+		ports: Config.String("CONFECT_LOCAL_BACKEND_PORTS").pipe(Config.option)
+	}).pipe(Effect.mapError(() => fail("configuration")));
+	const cache = yield* userCache.pipe(Effect.mapError(() => fail("configuration")));
+	if (Option.isNone(cache)) return yield* fail("configuration");
+	const range = Option.map(settings.ports, parsePortRange);
+	if (Option.isSome(range) && Option.isNone(range.value)) return yield* fail("configuration");
+	const env = {
+		...settings.environment,
+		DISABLE_BEACON: "1",
+		DO_NOT_TRACK: "1"
+	};
+	const answer = (url) => http.get(`${url}/instance_name`).pipe(Effect.flatMap((response) => response.status === 200 ? response.text : Effect.undefined), Effect.orElseSucceed(() => void 0));
+	const allocate = Effect.gen(function* () {
+		if (Option.isNone(range) || Option.isNone(range.value)) {
+			const [port, sitePort] = yield* Effect.all([listen(0), listen(0)]).pipe(Effect.map((servers) => servers.map(portOf)), Effect.scoped);
+			if (port === void 0 || sitePort === void 0) return yield* fail("ports");
+			return {
+				port,
+				sitePort
+			};
+		}
+		const free = [];
+		const { from, to } = range.value.value;
+		for (let port = from; port <= to && free.length < 2; port++) if (yield* isFree(port)) free.push(port);
+		const [port, sitePort] = free;
+		if (port === void 0 || sitePort === void 0) return yield* fail("ports");
+		return {
+			port,
+			sitePort
+		};
+	});
+	const generate = (binary) => Effect.gen(function* () {
+		const instanceSecret = Buffer.from(yield* crypto.randomBytes(32)).toString("hex");
+		const key = (yield* spawner.string(ChildProcess.make(binary, [
+			"keygen",
+			"admin-key",
+			"--instance-name",
+			deploymentName,
+			"--instance-secret",
+			instanceSecret
+		], {
+			env,
+			extendEnv: false,
+			stdin: "ignore",
+			stderr: "ignore"
+		}))).trim();
+		if (!key.startsWith(`${deploymentName}|`)) return yield* fail("identity");
+		return {
+			instanceSecret,
+			adminKey: key
+		};
+	}).pipe(Effect.catchTag("PlatformError", () => Effect.fail(fail("identity"))));
+	const save = (identity) => Effect.gen(function* () {
+		const file = path.join(directory, "identity.json");
+		const temp = `${file}.${process.pid}.tmp`;
+		yield* fs.writeFileString(temp, yield* Schema.encodeEffect(Identity)(identity), { mode: 384 });
+		yield* fs.rename(temp, file);
+	}).pipe(Effect.uninterruptible, Effect.mapError(() => fail("identity")));
+	const session = yield* Scope.Scope;
+	const owned = yield* Scope.fork(session);
+	const stopped = yield* Deferred.make();
+	yield* Scope.addFinalizer(owned, Deferred.succeed(stopped, void 0));
+	const start = Effect.gen(function* () {
+		yield* acquire(path.join(directory, "owner.lock")).pipe(Effect.mapError((error) => fail(error.reason === "held" ? "running" : "filesystem")));
+		const saved = yield* readIdentity(deploymentName, directory);
+		const version = Option.isSome(saved) ? saved.value.version : backendVersion;
+		const binary = yield* install(deploymentName, version, cache.value);
+		let identity;
+		if (Option.isSome(saved)) identity = saved.value;
+		else {
+			identity = {
+				name: deploymentName,
+				version,
+				...yield* generate(binary)
+			};
+			yield* save(identity);
+		}
+		const ports = identity.ports ?? (yield* allocate);
+		if (identity.ports !== void 0) {
+			if (!(yield* isFree(ports.port)) || !(yield* isFree(ports.sitePort))) return yield* fail((yield* answer(origin(ports.port))) === deploymentName ? "running" : "ports");
+		}
+		const url = origin(ports.port);
+		const siteUrl = origin(ports.sitePort);
+		const handle = yield* spawner.spawn(ChildProcess.make(binary, [
+			"--interface",
+			"127.0.0.1",
+			"--port",
+			String(ports.port),
+			"--site-proxy-port",
+			String(ports.sitePort),
+			"--instance-name",
+			deploymentName,
+			"--instance-secret",
+			identity.instanceSecret,
+			"--convex-origin",
+			url,
+			"--convex-site",
+			siteUrl,
+			"--local-storage",
+			path.join(directory, "convex_local_storage"),
+			"--disable-beacon",
+			path.join(directory, "convex_local_backend.sqlite3")
+		], {
+			cwd: directory,
+			env,
+			extendEnv: false,
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			forceKillAfter: "3 seconds"
+		})).pipe(Effect.mapError(() => fail("spawn")));
+		const ready = answer(url).pipe(Effect.flatMap((name) => name === void 0 || name === deploymentName ? Effect.succeed(name === deploymentName) : Effect.fail(fail("ports"))), Effect.repeat({
+			until: (isReady) => isReady,
+			schedule: Schedule.spaced("100 millis")
+		}));
+		const exit = handle.exitCode.pipe(Effect.mapError(() => fail("exit")), Effect.flatMap((code) => Effect.fail(fail("exit", Number(code)))));
+		yield* Effect.raceFirst(ready, exit).pipe(Effect.timeoutOrElse({
+			duration: "60 seconds",
+			orElse: () => Effect.fail(fail("timeout"))
+		}));
+		if (identity.ports === void 0) yield* save({
+			...identity,
+			ports
+		});
+		yield* handle.exitCode.pipe(Effect.ignore, Effect.andThen(Scope.close(owned, Exit.void)), Effect.forkIn(session));
+		return {
+			url,
+			siteUrl,
+			adminKey: Redacted.make(identity.adminKey),
+			exited: Deferred.await(stopped)
+		};
+	});
+	return yield* startup.withPermits(1)(start).pipe(Scope.provide(owned), Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : Scope.close(owned, exit)));
+});
+//#endregion
+export { LocalBackendError, adminKey, backendVersion, boot, dataDirectories, remove };
+
+//# sourceMappingURL=LocalBackend.js.map