@bedrock-rbx/core 0.1.0-beta.14 → 0.1.0-beta.16

package/dist/{migrate-mantle-state-qejWFAR0.mjs → migrate-mantle-state-F4zdhxV4.mjs}

@@ -1,6 +1,7 @@
+import { cancel, intro, log, outro } from "@clack/prompts";
 import { ApiError, PermissionError } from "@bedrock-rbx/ocale";
 import { ArkErrors, type } from "arktype";
-import { cancel, intro, log, outro } from "@clack/prompts";
+import { execFile, spawn } from "node:child_process";
 import process from "node:process";
 import { defu } from "defu";
 import { createHash } from "node:crypto";
@@ -12,9 +13,51 @@ import { readFile } from "node:fs/promises";
 import { loadConfig } from "c12";
 import { existsSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { execFile } from "node:child_process";
 import { tmpdir } from "node:os";
 import { parseYAML, stringifyYAML } from "confbox";
+//#region src/cli/clack-port.ts
+/**
+* Construct a `ClackPort` whose methods delegate to `@clack/prompts`. The
+* resulting port writes to `process.stdout` via clack's defaults. Kept in
+* its own module so consumers that never need the clack-backed rendering
+* (programmatic deploys, custom adapters) do not pull `@clack/prompts`
+* into their bundle.
+*
+* @example
+*
+* ```ts
+* import { createClackPort } from "@bedrock-rbx/core";
+*
+* const port = createClackPort();
+*
+* expect(typeof port.logSuccess).toBe("function");
+* ```
+*
+* @returns A port whose six methods each invoke the matching clack helper.
+*/
+function createClackPort() {
+	return {
+		cancel: (message) => {
+			cancel(message);
+		},
+		intro: (message) => {
+			intro(message);
+		},
+		logError: (message) => {
+			log.error(message);
+		},
+		logMessage: (message) => {
+			log.message(message);
+		},
+		logSuccess: (message) => {
+			log.success(message);
+		},
+		outro: (message) => {
+			outro(message);
+		}
+	};
+}
+//#endregion
 //#region src/cli/render.ts
 /**
 * Render a `DeployError` to the supplied `ClackPort`. Most variants emit a
@@ -46,6 +89,30 @@ function renderParseError(err, port) {
 	port.logError(parseErrorMessage(err));
 }
 /**
+* Render a `SpawnOverrideError` to the supplied `ClackPort` as a single
+* error line that names the environment alongside the failure mode. On
+* `launchFailed` the child never produced output of its own, so the parent
+* carries the diagnostic; on `nonZeroExit` the parent's line attributes the
+* exit code to a specific environment when several spawns are running.
+* @param input - Environment + spawn-override error to describe.
+* @param port - The output port the diagnostic is written to.
+*/
+function renderOverrideError(input, port) {
+	port.logError(overrideErrorMessage(input));
+}
+/**
+* Render the failure surfaced when override discovery throws a non-absence
+* filesystem error (for example `EACCES` on a `.bedrock/<command>.ts` that
+* exists but cannot be read). Discovery refuses to fall through to the
+* built-in path in that case, so the CLI reports the cause and exits rather
+* than crashing on the unhandled throw.
+* @param error - The value thrown during override discovery.
+* @param port - The output port the diagnostic is written to.
+*/
+function renderOverrideDiscoveryError(error, port) {
+	port.logError(`override discovery failed: ${safeStringify(error)}`);
+}
+/**
 * Render a `ParseMigrateError` to the supplied `ClackPort`. Reuses
 * `parseErrorMessage` for the three flag-shape variants and adds a
 * dedicated message for `unknownSource` listing the supported sources.
@@ -182,6 +249,11 @@ function parseErrorMessage(err) {
 		case "unknownFlag": return `unknown flag '--${err.flag}'`;
 	}
 }
+function overrideErrorMessage(input) {
+	const { environment, err } = input;
+	if (err.kind === "launchFailed") return `${environment}: failed to launch override - ${err.cause.message}`;
+	return `${environment}: override exited with code ${String(err.exitCode)}`;
+}
 function migrateParseErrorMessage(err) {
 	if (err.kind === "unknownSource") return `unknown migration source '${err.received}' (supported: ${err.supported.join(", ")})`;
 	return parseErrorMessage(err);
@@ -1235,6 +1307,27 @@ function createClackProgressAdapter(deps) {
 		renderEvent(event, deps);
 	} };
 }
+/**
+* Build a {@link ProgressPort} for the default CLI rendering path: wires a
+* fresh {@link createClackPort} into {@link createClackProgressAdapter}. The
+* `config` argument (raw `Config` or env-resolved `ResolvedConfig`) is
+* forwarded so `stateWritten` events can name the persistence backend; pass
+* `undefined` when the config has not yet loaded.
+*
+* Internal: used by `deploy()`'s default-port resolver when callers omit
+* `progress` and `BEDROCK_CLI` is set.
+*
+* @param config - Pre-loaded or env-resolved config used to format the
+*   state-backend label, or `undefined` to render the generic placeholder.
+* @returns A clack-backed `ProgressPort` that writes to `process.stdout`.
+*/
+function createDefaultProgressAdapter(config) {
+	const clack = createClackPort();
+	return config === void 0 ? createClackProgressAdapter({ clack }) : createClackProgressAdapter({
+		clack,
+		config
+	});
+}
 function applySummaryLine(event) {
 	return `Succeeded in ${(event.durationMs / 1e3).toFixed(1)}s: ${[
 		`${event.created} create`,
@@ -1800,7 +1893,9 @@ const GITHUB_API_BASE = "https://api.github.com";
 const GITHUB_API_VERSION = "2026-03-10";
 const USER_AGENT = "bedrock";
 const MAX_INLINE_BYTES = 1e7;
-const MAX_RETRIES = 3;
+const MAX_RETRIES = 6;
+const BASE_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 16e3;
 const RETRYABLE_STATUSES = new Set([
 	409,
 	502,
@@ -1843,6 +1938,7 @@ function createGistStateAdapter(deps) {
 	const ctx = {
 		fetchFn: deps.fetch ?? globalThis.fetch.bind(globalThis),
 		gistId: deps.gistId,
+		random: deps.random ?? Math.random,
 		sleep: deps.sleep ?? defaultSleep,
 		token: deps.token
 	};
@@ -1938,14 +2034,15 @@ async function sendGet(ctx) {
 function isRetryableStatus(status) {
 	return RETRYABLE_STATUSES.has(status);
 }
-function backoffMs(attempt) {
-	return 1e3 * 2 ** attempt;
+function backoffMs(attempt, random) {
+	const half = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** attempt) / 2;
+	return half + random() * half;
 }
-async function withRetry(sleep, operation) {
+async function withRetry(retry, operation) {
 	let response = await operation();
 	for (let attempt = 0; attempt < MAX_RETRIES; attempt += 1) {
 		if (response.ok || !isRetryableStatus(response.status)) return response;
-		await sleep(backoffMs(attempt));
+		await retry.sleep(backoffMs(attempt, retry.random));
 		response = await operation();
 	}
 	return response;
@@ -1953,7 +2050,7 @@ async function withRetry(sleep, operation) {
 async function fetchGistBody(ctx, file) {
 	let response;
 	try {
-		response = await withRetry(ctx.sleep, async () => sendGet(ctx));
+		response = await withRetry(ctx, async () => sendGet(ctx));
 	} catch (err) {
 		return {
 			err: networkError(err, file),
@@ -1983,14 +2080,14 @@ function stateErr(file, reason) {
 		success: false
 	};
 }
-async function readGistContent({ entry, fetchFn, file, sleep }) {
+async function readGistContent({ entry, fetchFn, file, retry }) {
 	if (entry.size > MAX_INLINE_BYTES) return stateErr(file, `state file too large: ${entry.size} bytes`);
 	if (entry.isTruncated) {
 		if (entry.rawUrl === void 0) return stateErr(file, "truncated gist file missing raw_url");
 		const { rawUrl } = entry;
 		let rawResponse;
 		try {
-			rawResponse = await withRetry(sleep, async () => fetchFn(rawUrl));
+			rawResponse = await withRetry(retry, async () => fetchFn(rawUrl));
 		} catch (err) {
 			return {
 				err: networkError(err, file),
@@ -2016,7 +2113,7 @@ async function readPath(ctx, environment) {
 		entry,
 		fetchFn: ctx.fetchFn,
 		file,
-		sleep: ctx.sleep
+		retry: ctx
 	});
 }
 async function sendPatch(ctx, body) {
@@ -2065,7 +2162,7 @@ async function writePath(ctx, state) {
 	const body = JSON.stringify({ files: { [fileName(state.environment)]: { content: serializeStateFile(state) } } });
 	let response;
 	try {
-		response = await withRetry(ctx.sleep, async () => sendPatch(ctx, body));
+		response = await withRetry(ctx, async () => sendPatch(ctx, body));
 	} catch (err) {
 		return {
 			err: networkError(err, file),
@@ -2092,6 +2189,30 @@ async function writePath(ctx, state) {
 	};
 }
 //#endregion
+//#region src/adapters/no-op-progress-adapter.ts
+/**
+* Build a {@link ProgressPort} that silently drops every event. Useful for
+* tests and programmatic callers who want to invoke deploy logic without
+* any rendering.
+*
+* @example
+*
+* ```ts
+* import { createNoOpProgressAdapter } from "@bedrock-rbx/core";
+*
+* const port = createNoOpProgressAdapter();
+*
+* expect(() =>
+*     port.emit({ environment: "production", kind: "deploySuccess", resourceCount: 3 }),
+* ).not.toThrow();
+* ```
+*
+* @returns A `ProgressPort` whose `emit` method is a no-op.
+*/
+function createNoOpProgressAdapter() {
+	return { emit() {} };
+}
+//#endregion
 //#region src/core/resources.ts
 /**
 * Ordered list of optional metadata fields the driver routes through
@@ -2470,46 +2591,192 @@ async function reconcileUniverse(inputs) {
 	};
 }
 //#endregion
-//#region src/cli/clack-port.ts
+//#region src/cli/default-spawner.ts
 /**
-* Construct a `ClackPort` whose methods delegate to `@clack/prompts`. The
-* resulting port writes to `process.stdout` via clack's defaults. Kept in
-* its own module so consumers that never need the clack-backed rendering
-* (programmatic deploys, custom adapters) do not pull `@clack/prompts`
-* into their bundle.
-*
+* Translate a `child.on("close", code, signal)` payload into the
+* {@link Spawner.spawn} return shape. Extracted from the adapter so the
+* signal-terminated branch can be exercised without launching a real
+* process. The caller normalizes node's `null` to `undefined` at the
+* boundary so this helper never sees `null`.
+* @param code - Exit code reported by the child, or `undefined` if the
+*   child was terminated by a signal before exiting.
+* @param signal - Signal name reported by the child, or `undefined` when
+*   no signal terminated it.
+* @returns `Ok(code)` for a clean exit (including `0`); otherwise
+*   `Err(launchFailed)` carrying a synthetic Error whose message names
+*   the signal.
+*/
+function classifySpawnClose(code, signal) {
+	if (code !== void 0) return {
+		data: code,
+		success: true
+	};
+	return {
+		err: {
+			cause: /* @__PURE__ */ new Error(`spawned process terminated by signal ${signal ?? "unknown"}`),
+			kind: "launchFailed"
+		},
+		success: false
+	};
+}
+/**
+* Construct a {@link Spawner} backed by `node:child_process.spawn` with
+* `stdio` inherited from the parent process. The child's environment is
+* `process.env` overlaid with {@link SpawnInvocation.envOverrides} (overrides
+* win on key collision).
+*
+* - Exit codes resolve as `Ok(exitCode)` (including `0`).
+* - `ENOENT` and other launch-time errors resolve as `Err(launchFailed)`
+*   with the original error in `cause` (its `code` field carries the
+*   errno where present).
+* - Children terminated by signal before producing an exit code collapse
+*   into `launchFailed` with a synthetic `Error` whose message names the
+*   signal; a distinct variant lands the day a caller needs to act on the
+*   difference.
+*
+* @returns A `Spawner` whose `spawn` settles once the child closes.
 * @example
 *
 * ```ts
-* import { createClackPort } from "@bedrock-rbx/core";
+* import { createDefaultSpawner } from "@bedrock-rbx/core";
+* import process from "node:process";
 *
-* const port = createClackPort();
+* const spawner = createDefaultSpawner();
 *
-* expect(typeof port.logSuccess).toBe("function");
+* return spawner
+*     .spawn({
+*         args: ["-e", "process.exit(0)"],
+*         command: process.execPath,
+*         envOverrides: {},
+*     })
+*     .then((result) => {
+*         expect(result.success).toBeTrue();
+*         if (result.success) {
+*             expect(result.data).toBe(0);
+*         }
+*     });
 * ```
+*/
+function createDefaultSpawner() {
+	return { spawn: spawnViaChildProcess };
+}
+async function spawnViaChildProcess(invocation) {
+	return new Promise((resolve) => {
+		const child = spawn(invocation.command, [...invocation.args], {
+			env: {
+				...process.env,
+				...invocation.envOverrides
+			},
+			stdio: "inherit"
+		});
+		child.once("error", (error) => {
+			resolve({
+				err: {
+					cause: error,
+					kind: "launchFailed"
+				},
+				success: false
+			});
+		});
+		child.once("close", (code, signal) => {
+			resolve(classifySpawnClose(code ?? void 0, signal ?? void 0));
+		});
+	});
+}
+//#endregion
+//#region src/cli/credential-environment-overrides.ts
+/**
+* Map CLI credential flags to their corresponding env-var names, omitting
+* entries whose flag is `undefined`.
+* @param flags - CLI credential flag values to translate.
+* @returns An immutable record of env-var names to their override values.
+*/
+function buildCredentialOverrides(flags) {
+	const overrides = {};
+	if (flags.apiKey !== void 0) overrides["BEDROCK_API_KEY"] = flags.apiKey;
+	if (flags.githubToken !== void 0) overrides["BEDROCK_GITHUB_TOKEN"] = flags.githubToken;
+	return overrides;
+}
+//#endregion
+//#region src/cli/dispatch-override.ts
+/**
+* Dispatch a single `.bedrock/<command>.ts` override invocation through the
+* supplied {@link Spawner}. Encapsulates the spawn protocol:
+*
+* - argv = `[overridePath, "--env", environment]`, with `"--config", configFile`
+*   appended when supplied.
+* - `apiKey` becomes the `BEDROCK_API_KEY` env-var override; `githubToken`
+*   becomes `BEDROCK_GITHUB_TOKEN`. Neither value appears in argv.
+* - `BEDROCK_CLI=1` is always set in the env. The override's `deploy()`
+*   reads this on the `getEnv` seam to default to the clack progress
+*   adapter; absent that downstream wiring, the variable is a forward-
+*   compatible signal a future caller can act on.
+*
+* The dispatcher itself reads no ambient state: every input arrives via the
+* `invocation` argument and the `Spawner` port is the only side-effect seam.
+*
+* @param invocation - Path, environment, and parsed deploy-flag inputs.
+* @param spawner - Port the dispatcher hands the resolved
+*   {@link SpawnInvocation} to.
+* @returns `Ok(undefined)` when the child exited zero; otherwise an
+*   {@link SpawnOverrideError} discriminating launch vs non-zero exit.
 *
-* @returns A port whose six methods each invoke the matching clack helper.
+* @example
+*
+* ```ts
+* import { dispatchOverride, type Spawner } from "@bedrock-rbx/core";
+*
+* const spawner: Spawner = {
+*     async spawn() {
+*         return { data: 0, success: true };
+*     },
+* };
+*
+* return dispatchOverride(
+*     {
+*         environment: "production",
+*         overridePath: "/abs/.bedrock/deploy.ts",
+*     },
+*     spawner,
+* ).then((result) => {
+*     expect(result.success).toBeTrue();
+* });
+* ```
 */
-function createClackPort() {
-	return {
-		cancel: (message) => {
-			cancel(message);
-		},
-		intro: (message) => {
-			intro(message);
-		},
-		logError: (message) => {
-			log.error(message);
-		},
-		logMessage: (message) => {
-			log.message(message);
+async function dispatchOverride(invocation, spawner) {
+	const args = [
+		invocation.overridePath,
+		"--env",
+		invocation.environment
+	];
+	if (invocation.configFile !== void 0) args.push("--config", invocation.configFile);
+	const credentialOverrides = buildCredentialOverrides(invocation);
+	const launched = await spawner.spawn({
+		args,
+		command: "bun",
+		envOverrides: {
+			...credentialOverrides,
+			BEDROCK_CLI: "1"
+		}
+	});
+	if (!launched.success) return {
+		err: {
+			cause: launched.err.cause,
+			kind: "launchFailed"
 		},
-		logSuccess: (message) => {
-			log.success(message);
+		success: false
+	};
+	const exitCode = launched.data;
+	if (exitCode !== 0) return {
+		err: {
+			exitCode,
+			kind: "nonZeroExit"
 		},
-		outro: (message) => {
-			outro(message);
-		}
+		success: false
+	};
+	return {
+		data: void 0,
+		success: true
 	};
 }
 //#endregion
@@ -2600,7 +2867,7 @@ function assertReconcilable(current, desired) {
 /**
 * Resource-kind module for Roblox developer products. Owns the entry
 * schema, flattening, icon-hash normalization, drift-equality, and the
-* plan-time icon-removal rejection for the `developerProduct` kind.
+* pre-reconcile icon-removal rejection for the `developerProduct` kind.
 */
 const developerProductKind = {
 	assertReconcilable,
@@ -2890,7 +3157,7 @@ const defaultKindRegistry = {
 *
 * @param desired - Declared desired state from user config, already normalized
 *   (file hashes computed, nullable wire values mapped to `undefined`).
-* @param current - Last-known live state from the state file.
+* @param current - Last-known current state from the state file.
 * @returns Operations to reconcile the two snapshots.
 *
 * @example
@@ -3100,7 +3367,7 @@ const PLACE_ENV_FIELDS = ["description", "displayName"];
 * disambiguating suffix on a redacted developer-product's default `name`.
 * Stable across config edits (driven only by the bedrock resource key, not
 * declaration order) and opaque to a Roblox player browsing the marketplace.
-* A natural collision is caught at plan time by `validatePlan`.
+* A natural collision is caught before any apply-side driver I/O by `assertAllReconcilable`.
 *
 * @param key - Bedrock resource key for the developer product being redacted.
 * @returns The first six lowercase hex characters of the SHA-256 digest of `key`.
@@ -3617,105 +3884,6 @@ function redactAndPrefix(inputs) {
 	};
 }
 //#endregion
-//#region src/core/validate-plan.ts
-/**
-* Plan-time invariant check that runs after `buildDesired` and before
-* `diff`. Walks paired `(kind, key)` entries and dispatches to each
-* kind module's optional `assertReconcilable` hook so kind-specific
-* rejections (e.g. Removing a developer-product icon, which the upstream
-* API has no documented unset path for) surface as typed errors before
-* `diff` runs and before any apply-side driver I/O is attempted.
-*
-* Pure and synchronous. Current-only entries (no matching desired) are
-* ignored: their reconciliation is `diff`'s concern, not this seam's.
-*
-* @param desired - Desired state from `buildDesired`.
-* @param current - Prior current state from the state port.
-* @returns `Ok(undefined)` when every paired entry passes its kind-level
-*   reconcilability check, or the first `Err` returned by a hook.
-*
-* @example
-*
-* ```ts
-* import { asResourceKey, asRobloxAssetId, asSha256Hex, validatePlan } from "@bedrock-rbx/core";
-*
-* const result = validatePlan(
-*     [
-*         {
-*             description: "Stocks the player up with 1,000 premium gems.",
-*             isRegionalPricingEnabled: undefined,
-*             key: asResourceKey("gem-pack"),
-*             kind: "developerProduct",
-*             name: "Gem Pack",
-*             price: undefined,
-*             storePageEnabled: undefined,
-*         },
-*     ],
-*     [
-*         {
-*             description: "Stocks the player up with 1,000 premium gems.",
-*             icon: { "en-us": "assets/gem-pack.png" },
-*             iconFileHashes: {
-*                 "en-us": asSha256Hex(
-*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-*                 ),
-*             },
-*             isRegionalPricingEnabled: undefined,
-*             key: asResourceKey("gem-pack"),
-*             kind: "developerProduct",
-*             name: "Gem Pack",
-*             outputs: { productId: asRobloxAssetId("9876543210") },
-*             price: undefined,
-*             storePageEnabled: undefined,
-*         },
-*     ],
-* );
-*
-* expect(result.success).toBeFalse();
-* if (!result.success) {
-*     expect(result.err.kind).toBe("iconRemovalRejected");
-* }
-* ```
-*/
-function validatePlan(desired, current) {
-	const collision = detectProductNameCollision(desired);
-	if (collision !== void 0) return collision;
-	const currentByKey = new Map(current.map((entry) => [compositeKey(entry), entry]));
-	for (const entry of desired) {
-		const matched = currentByKey.get(compositeKey(entry));
-		if (matched === void 0) continue;
-		const check = defaultKindRegistry[entry.kind].assertReconcilable?.(matched, entry);
-		if (check !== void 0 && !check.success) return check;
-	}
-	return {
-		data: void 0,
-		success: true
-	};
-}
-function compositeKey(resource) {
-	return `${resource.kind}:${resource.key}`;
-}
-function detectProductNameCollision(desired) {
-	const seenByName = /* @__PURE__ */ new Map();
-	for (const entry of desired) {
-		if (entry.kind !== "developerProduct") continue;
-		const prior = seenByName.get(entry.name);
-		if (prior === void 0) {
-			seenByName.set(entry.name, entry.key);
-			continue;
-		}
-		return {
-			err: {
-				keys: [prior, entry.key],
-				kind: "redactedNameCollision",
-				message: `developer products '${prior}' and '${entry.key}' both resolve to the wire name '${entry.name}'. Roblox enforces per-universe uniqueness on developer-product names, so the second update would be rejected as DuplicateProductName. Set 'redacted: { name: "<unique>" }' on one of them to disambiguate.`,
-				resolvedName: entry.name
-			},
-			success: false
-		};
-	}
-}
-//#endregion
 //#region src/shell/apply-ops.ts
 /**
 * Dispatch reconciliation operations to their matching drivers in two phases
@@ -4169,7 +4337,7 @@ const STATE_PORT_HINT = "pass a custom statePort via opts.statePort";
 * const port = buildStatePort({
 *     fetch: async () =>
 *         new Response(JSON.stringify({ files: {} }), { status: 200 }),
-*     getEnv: (name) => (name === "GITHUB_TOKEN" ? "ghp_example" : undefined),
+*     getEnv: (name) => (name === "BEDROCK_GITHUB_TOKEN" ? "ghp_example" : undefined),
 *     stateConfig: { backend: "gist", gistId: "abc123" },
 * });
 *
@@ -4192,12 +4360,12 @@ function buildStatePort(deps) {
 	};
 }
 function buildGistStatePort(stateConfig, deps) {
-	const token = deps.getEnv("GITHUB_TOKEN");
+	const token = deps.getEnv("BEDROCK_GITHUB_TOKEN") ?? deps.getEnv("GITHUB_TOKEN");
 	if (token === void 0) return {
 		err: {
 			kind: "missingCredential",
 			purpose: "stateBackend",
-			variable: "GITHUB_TOKEN"
+			variable: "BEDROCK_GITHUB_TOKEN"
 		},
 		success: false
 	};
@@ -4211,6 +4379,62 @@ function buildGistStatePort(stateConfig, deps) {
 	};
 }
 //#endregion
+//#region src/core/assert-all-reconcilable.ts
+/**
+* Batch reconcilability check that runs after `buildDesired` and before
+* `diff`. Walks paired `(kind, key)` entries and dispatches to each
+* kind module's optional `assertReconcilable` hook so kind-specific
+* rejections (e.g. Removing a developer-product icon, which the upstream
+* API has no documented unset path for) surface as typed errors before
+* `diff` runs and before any apply-side driver I/O is attempted.
+*
+* Pure and synchronous. Current-only entries (no matching desired) are
+* ignored: their reconciliation is `diff`'s concern, not this seam's.
+*
+* @param desired - Desired state from `buildDesired`.
+* @param current - Prior current state from the state port.
+* @returns `Ok(undefined)` when every paired entry passes its kind-level
+*   reconcilability check, or the first `Err` returned by a hook.
+*/
+function assertAllReconcilable(desired, current) {
+	const collision = detectProductNameCollision(desired);
+	if (collision !== void 0) return collision;
+	const currentByKey = new Map(current.map((entry) => [compositeKey(entry), entry]));
+	for (const entry of desired) {
+		const matched = currentByKey.get(compositeKey(entry));
+		if (matched === void 0) continue;
+		const check = defaultKindRegistry[entry.kind].assertReconcilable?.(matched, entry);
+		if (check !== void 0 && !check.success) return check;
+	}
+	return {
+		data: void 0,
+		success: true
+	};
+}
+function compositeKey(resource) {
+	return `${resource.kind}:${resource.key}`;
+}
+function detectProductNameCollision(desired) {
+	const seenByName = /* @__PURE__ */ new Map();
+	for (const entry of desired) {
+		if (entry.kind !== "developerProduct") continue;
+		const prior = seenByName.get(entry.name);
+		if (prior === void 0) {
+			seenByName.set(entry.name, entry.key);
+			continue;
+		}
+		return {
+			err: {
+				keys: [prior, entry.key],
+				kind: "redactedNameCollision",
+				message: `developer products '${prior}' and '${entry.key}' both resolve to the wire name '${entry.name}'. Roblox enforces per-universe uniqueness on developer-product names, so the second update would be rejected as DuplicateProductName. Set 'redacted: { name: "<unique>" }' on one of them to disambiguate.`,
+				resolvedName: entry.name
+			},
+			success: false
+		};
+	}
+}
+//#endregion
 //#region src/shell/load-config-internal.ts
 const LUAU_BOOTSTRAP_TEMP_PREFIX = "bedrock-luau-bootstrap-";
 /**
@@ -4356,14 +4580,9 @@ async function evaluateLuauWithLute(absPath) {
 */
 async function loadConfigWith(deps, options) {
 	const cwd = options?.cwd ?? process.cwd();
-	const configFile = options?.configFile === void 0 ? void 0 : resolveConfigPath(cwd, options.configFile);
-	if (configFile !== void 0 && !isExistingFile(configFile)) return {
-		err: {
-			kind: "fileNotFound",
-			searchedFrom: cwd
-		},
-		success: false
-	};
+	const explicit = resolveExplicitConfigFile(cwd, options?.configFile);
+	if (!explicit.success) return explicit;
+	const configFile = explicit.data ?? discoverConfigFallback(cwd);
 	let resolved;
 	try {
 		resolved = await loadConfig({
@@ -4394,9 +4613,12 @@ async function loadConfigWith(deps, options) {
 /**
 * Discover, parse, and validate the project config.
 *
-* Looks for `bedrock.config.{ts,js,mjs,cjs,yaml,yml,json}`, `.bedrockrc*`,
-* and `package.json#bedrock` starting at `options.cwd` (or the current
-* working directory). Returns a fresh, mutable `Config` on every call so
+* Looks for `bedrock.config.{ts,js,mjs,cjs,yaml,yml,json,luau}`,
+* `.bedrockrc*`, and `package.json#bedrock` starting at `options.cwd` (or the
+* current working directory). When no config sits at the project root, the
+* loader also probes `.bedrock/bedrock.config.*` so users can colocate the
+* file with their other `.bedrock/` artifacts. The project root always wins
+* on collision. Returns a fresh, mutable `Config` on every call so
 * long-running scripts see up-to-date values.
 *
 * When the exported default is a function (sync or async), `loadConfig`
@@ -4483,6 +4705,8 @@ const NATIVE_CONFIG_EXTENSIONS = [
 	"yaml",
 	"yml"
 ];
+const DISCOVERY_EXTENSIONS = [...NATIVE_CONFIG_EXTENSIONS, "luau"];
+const BEDROCK_CONFIG_DIRECTORY = ".bedrock";
 /**
 * Internal-only wrapper used at the c12 boundary: makeLuauResolver maps an
 * evaluator `Err` into this throwable, which `attributeLoadError` unwraps
@@ -4496,6 +4720,44 @@ var EvaluatorThrow = class extends Error {
 		this.configError = configError;
 	}
 };
+function resolveExplicitConfigFile(cwd, configFile) {
+	if (configFile === void 0) return {
+		data: void 0,
+		success: true
+	};
+	const resolved = resolveConfigPath(cwd, configFile);
+	if (!isExistingFile(resolved)) return {
+		err: {
+			kind: "fileNotFound",
+			searchedFrom: cwd
+		},
+		success: false
+	};
+	return {
+		data: resolved,
+		success: true
+	};
+}
+function findConfigInDirectory(directory) {
+	for (const extension of DISCOVERY_EXTENSIONS) {
+		const candidate = join(directory, `bedrock.config.${extension}`);
+		if (isExistingFile(candidate)) return candidate;
+	}
+}
+/**
+* Pick the `.bedrock/bedrock.config.*` fallback only when no `bedrock.config.*`
+* exists at the project root, letting c12 run its own discovery so a root file
+* always wins. Other c12 sources (`.bedrockrc`, `package.json#bedrock`) are
+* still merged in by c12 either way; the configFile we hand back wins
+* overlapping keys per c12's standard layering precedence.
+* @param cwd - The directory to search.
+* @returns Absolute path of the `.bedrock/` candidate, or `undefined` to defer
+* to c12's own discovery on the project root.
+*/
+function discoverConfigFallback(cwd) {
+	if (findConfigInDirectory(cwd) !== void 0) return;
+	return findConfigInDirectory(join(cwd, BEDROCK_CONFIG_DIRECTORY));
+}
 /**
 * Decide which Luau file the resolver should evaluate for a given c12 source,
 * or `undefined` to defer to c12's built-in loaders.
@@ -4556,15 +4818,18 @@ function extractConfigFileFromStack(err) {
 		if (match !== null) return match[0];
 	}
 }
-function discoverConfigFile(cwd) {
+function findConfigEntry(directory) {
 	let entries;
 	try {
-		entries = readdirSync(cwd);
+		entries = readdirSync(directory);
 	} catch {
 		return;
 	}
 	const match = entries.toSorted().find((entry) => entry.startsWith("bedrock.config."));
-	return match === void 0 ? void 0 : join(cwd, match);
+	return match === void 0 ? void 0 : join(directory, match);
+}
+function discoverConfigFile(cwd) {
+	return findConfigEntry(cwd) ?? findConfigEntry(join(cwd, BEDROCK_CONFIG_DIRECTORY));
 }
 function attributeLoadError(err, cwd) {
 	if (err instanceof EvaluatorThrow) return err.configError;
@@ -4584,10 +4849,26 @@ function attributeLoadError(err, cwd) {
 //#endregion
 //#region src/shell/deploy.ts
 /**
+* Decide whether `BEDROCK_CLI` should select the clack-backed default
+* progress adapter. Exported for direct unit coverage of the boundary
+* (`undefined` and empty string both flip to no-op; any non-empty value
+* picks clack).
+*
+* @param value - Raw `BEDROCK_CLI` value as returned by `getEnv`.
+* @returns `true` if the clack adapter should be the default.
+*/
+function isCliEnvironmentFlagSet(value) {
+	return value !== void 0 && value !== "";
+}
+/**
 * Run a full reconcile end-to-end. Default-constructs missing deps from
-* the project config and the environment variables `GITHUB_TOKEN` and
-* `BEDROCK_API_KEY`; never reads `process.env` when `statePort`,
-* `registry`, and `config` are all supplied explicitly.
+* the project config and the environment variables `BEDROCK_GITHUB_TOKEN`
+* and `BEDROCK_API_KEY`; emits a terminal `deploySuccess` or `deployFailure`
+* event through the resolved `progress` port. When `progress` is omitted,
+* the default port comes from `BEDROCK_CLI`: a non-empty value selects the
+* clack-backed adapter, any other reading selects the no-op adapter. No
+* environment lookups happen when `statePort`, `registry`, `config`, and
+* `progress` are all supplied explicitly.
 *
 * @param options - Target environment plus optional overrides.
 * @returns The persisted `BedrockState` on success, or a stage-tagged
@@ -4648,9 +4929,15 @@ function attributeLoadError(err, cwd) {
 * ```
 */
 async function deploy(options) {
-	const resolved = await resolveDeps(options);
-	if (!resolved.success) return resolved;
-	return runReconcile(options.environment, resolved.data);
+	if (options.progress !== void 0) return runAndEmit(options, options.progress);
+	if (!isCliEnvironmentFlagSet(getEnvironmentOf(options)("BEDROCK_CLI"))) return runAndEmit(options, createNoOpProgressAdapter());
+	return runWithDeferredClackProgress(options);
+}
+function readProcessEnvironment(name) {
+	return process.env[name];
+}
+function getEnvironmentOf(options) {
+	return options.getEnv ?? readProcessEnvironment;
 }
 async function pickConfig(options) {
 	if (options.config !== void 0) return {
@@ -4670,12 +4957,6 @@ async function pickConfig(options) {
 		success: true
 	};
 }
-function readProcessEnvironment(name) {
-	return process.env[name];
-}
-function getEnvironmentOf(options) {
-	return options.getEnv ?? readProcessEnvironment;
-}
 function pickStatePort(options, config) {
 	if (options.statePort !== void 0) return {
 		data: options.statePort,
@@ -4724,7 +5005,6 @@ async function resolveDeps(options) {
 	return {
 		data: {
 			config: effective,
-			progress: options.progress,
 			readFile: readFile$2,
 			registry: registry.data,
 			statePort: statePort.data
@@ -4785,7 +5065,7 @@ async function runReconcile(environment, deps) {
 		success: false
 	};
 	const priorResources = prior.data?.resources ?? [];
-	const validated = validatePlan(desired.data, priorResources);
+	const validated = assertAllReconcilable(desired.data, priorResources);
 	if (!validated.success) return {
 		err: {
 			cause: validated.err,
@@ -4793,7 +5073,7 @@ async function runReconcile(environment, deps) {
 		},
 		success: false
 	};
-	const applied = await applyOps(diff(desired.data, priorResources), deps.registry, deps.progress === void 0 ? void 0 : {
+	const applied = await applyOps(diff(desired.data, priorResources), deps.registry, {
 		environment,
 		progress: deps.progress
 	});
@@ -4803,7 +5083,7 @@ async function runReconcile(environment, deps) {
 		priorResources
 	});
 	const written = await deps.statePort.write(merged);
-	if (written.success) deps.progress?.emit({
+	if (written.success) deps.progress.emit({
 		environment,
 		kind: "stateWritten"
 	});
@@ -4813,6 +5093,61 @@ async function runReconcile(environment, deps) {
 		written
 	});
 }
+async function runDeploy(options, progress) {
+	const resolved = await resolveDeps(options);
+	if (!resolved.success) return resolved;
+	return runReconcile(options.environment, {
+		...resolved.data,
+		progress
+	});
+}
+function emitTerminalEvent(inputs) {
+	const { environment, progress, result } = inputs;
+	if (result.success) {
+		progress.emit({
+			environment,
+			kind: "deploySuccess",
+			resourceCount: result.data.resources.length
+		});
+		return;
+	}
+	progress.emit({
+		environment,
+		error: result.err,
+		kind: "deployFailure"
+	});
+}
+async function runAndEmit(options, progress) {
+	const result = await runDeploy(options, progress);
+	emitTerminalEvent({
+		environment: options.environment,
+		progress,
+		result
+	});
+	return result;
+}
+async function runWithDeferredClackProgress(options) {
+	const resolved = await resolveDeps(options);
+	const progress = createDefaultProgressAdapter(resolved.success ? resolved.data.config : options.config);
+	if (!resolved.success) {
+		emitTerminalEvent({
+			environment: options.environment,
+			progress,
+			result: resolved
+		});
+		return resolved;
+	}
+	const result = await runReconcile(options.environment, {
+		...resolved.data,
+		progress
+	});
+	emitTerminalEvent({
+		environment: options.environment,
+		progress,
+		result
+	});
+	return result;
+}
 //#endregion
 //#region src/core/migrate/build-state.ts
 /**
@@ -6963,6 +7298,6 @@ function isFileMissing(err) {
 	return typeof err === "object" && err !== null && "code" in err && typeof err.code === "string" && FILE_MISSING_CODES.has(err.code);
 }
 //#endregion
-export { createClackProgressAdapter as A, isSha256Hex as B, UNIVERSE_SINGLETON_KEY as C, createGamePassDriver as D, serializeStateFile as E, asResourceKey as F, renderMigrateParseError as G, renderBuildStatePortError as H, asRobloxAssetId as I, renderStateWriteError as J, renderMigrationSummary as K, asSha256Hex as L, validateConfig as M, shouldReuploadIcon as N, createDeveloperProductDriver as O, validateEnvironmentName as P, isResourceKey as R, SOCIAL_LINK_FIELDS as S, parseStateFile as T, renderDeployError as U, resolveStateConfig as V, renderMigrateError as W, diff as _, buildStatePort as a, createUniverseDriver as b, applyOps as c, selectEnvironment as d, selectMergedEnvironment as f, renderDisplayNamePrefix as g, DEFAULT_PREFIX_FORMAT as h, loadConfig$1 as i, isGistStateConfig as j, derivePriceFields as k, validatePlan as l, flattenConfig as m, serializeConfig as n, buildDesired as o, collectRedactionAnnotations as p, renderParseError as q, deploy as r, buildDefaultRegistry as s, migrateMantleState as t, extractResourceRedaction as u, defaultKindRegistry as v, createGistStateAdapter as w, createPlaceDriver as x, createClackPort as y, isRobloxAssetId as z };
+export { renderStateWriteError as $, createGamePassDriver as A, asSha256Hex as B, createPlaceDriver as C, createGistStateAdapter as D, createNoOpProgressAdapter as E, validateConfig as F, renderBuildStatePortError as G, isRobloxAssetId as H, shouldReuploadIcon as I, renderMigrateParseError as J, renderDeployError as K, validateEnvironmentName as L, derivePriceFields as M, createClackProgressAdapter as N, parseStateFile as O, isGistStateConfig as P, renderParseError as Q, asResourceKey as R, createUniverseDriver as S, UNIVERSE_SINGLETON_KEY as T, isSha256Hex as U, isResourceKey as V, resolveStateConfig as W, renderOverrideDiscoveryError as X, renderMigrationSummary as Y, renderOverrideError as Z, diff as _, assertAllReconcilable as a, buildCredentialOverrides as b, buildDefaultRegistry as c, selectEnvironment as d, createClackPort as et, selectMergedEnvironment as f, renderDisplayNamePrefix as g, DEFAULT_PREFIX_FORMAT as h, loadConfig$1 as i, createDeveloperProductDriver as j, serializeStateFile as k, applyOps as l, flattenConfig as m, serializeConfig as n, buildStatePort as o, collectRedactionAnnotations as p, renderMigrateError as q, deploy as r, buildDesired as s, migrateMantleState as t, extractResourceRedaction as u, defaultKindRegistry as v, SOCIAL_LINK_FIELDS as w, createDefaultSpawner as x, dispatchOverride as y, asRobloxAssetId as z };
 
-//# sourceMappingURL=migrate-mantle-state-qejWFAR0.mjs.map
+//# sourceMappingURL=migrate-mantle-state-F4zdhxV4.mjs.map