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

package/README.md

@@ -0,0 +1,180 @@
+# @bedrock-rbx/core
+
+Infrastructure-as-Code for Roblox, with a bundled `bedrock` CLI.
+
+[![npm version](https://img.shields.io/npm/v/@bedrock-rbx/core.svg)](https://npmx.dev/package/@bedrock-rbx/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/christopher-buss/bedrock/blob/main/LICENSE)
+[![CI](https://github.com/christopher-buss/bedrock/actions/workflows/ci.yaml/badge.svg)](https://github.com/christopher-buss/bedrock/actions/workflows/ci.yaml)
+
+> **Status: 0.1 beta.** The public API is stabilizing. Breaking changes may land in minor releases (0.1 to 0.2) until 1.0.
+
+## What is `@bedrock-rbx/core`?
+
+Bedrock defines a Roblox experience's setup, including the universe, places, game passes, and developer products, in a single config file you keep alongside your game code. Each deploy diffs that config against the live state in Roblox and applies the create or update operations needed to bring them into sync. Adding a new place (lobby, mini-game, hub world) means editing the config instead of clicking through Creator Hub.
+
+It is a spiritual successor to [Mantle](https://github.com/blake-mealey/mantle) (no longer maintained), rebuilt on top of [Roblox Open Cloud](https://create.roblox.com/docs/cloud). That means API-key authentication only, no `ROBLOSECURITY` cookies or legacy endpoints.
+
+Bedrock ships two paths to the same engine. The `bedrock` CLI reconciles a config file (TypeScript, JavaScript, YAML, JSON, or Luau) against live Roblox state. The programmatic API exposes the same `deploy()`, `diff()`, and `applyOps()` functions for direct use in TypeScript, so deploys can be triggered from a webhook handler, a chat bot, or any other service in your stack. Both surfaces run identical code below the entry point.
+
+## Install
+
+```bash
+pnpm add -D @bedrock-rbx/core
+# or: npm install --save-dev @bedrock-rbx/core
+# or: bun add -d @bedrock-rbx/core
+```
+
+The `bedrock` binary is then available via your package manager (`pnpm bedrock`, `npx bedrock`, `bunx bedrock`).
+
+**Runtime:** Node >= 24.12 or Bun >= 1.3.
+
+**Authentication:** bedrock reads two environment variables.
+
+| Variable | Purpose | Where to get it |
+|---|---|---|
+| `BEDROCK_API_KEY` | Authenticates Open Cloud calls. | [Creator Hub > Credentials > API Keys](https://create.roblox.com/dashboard/credentials). Needs the scopes for the resources you manage (universe-place, universe-place-config, universe-passes, universe-developer-products, asset-create). |
+| `BEDROCK_GITHUB_TOKEN` | Reads and writes the state gist (the default state backend). | A GitHub personal access token with the `gist` scope. The gist itself starts empty: create one at [gist.github.com](https://gist.github.com), then put its ID in your config's `state.gistId`. |
+
+Both can be overridden per environment in your config (or via `--api-key` / `--github-token` flags on the CLI).
+
+## Quick start (programmatic)
+
+A bedrock config is a plain `Config` object. The `defineConfig` helper is identity at runtime; it exists only to give TypeScript users full type inference and autocomplete.
+
+```ts
+// bedrock.config.ts
+import { defineConfig } from "@bedrock-rbx/core/config";
+
+export default defineConfig({
+	environments: {
+		production: { universe: { universeId: 1234567890 } },
+	},
+	passes: {
+		"vip-pass": {
+			name: "VIP Pass",
+			description: "Grants VIP perks.",
+			icon: { "en-us": "assets/vip-icon.png" },
+			price: 500,
+		},
+	},
+	places: {
+		"start-place": {
+			name: "Start Place",
+			file: "places/start.rbxl",
+		},
+	},
+	state: { backend: "gist", gistId: "abc123def456" },
+	universe: {
+		name: "My Game",
+		description: "An adventure.",
+	},
+});
+```
+
+Place your custom deploy orchestration at `.bedrock/deploy.ts`. The `bedrock deploy` CLI auto-discovers and invokes this file when present, and the same exports can be imported from a webhook handler, chat bot, or other service that wants to trigger deploys directly.
+
+```ts
+// .bedrock/deploy.ts
+import { deploy } from "@bedrock-rbx/core";
+
+/**
+ * Triggered from a webhook handler whenever a release tag is pushed.
+ * Wraps `deploy` with custom orchestration: structured logging on
+ * failure, success reporting back to the caller.
+ *
+ * @param environment - Target environment from the webhook payload.
+ * @returns Whether the deploy completed successfully.
+ */
+export async function deployFromWebhook(environment: string): Promise<boolean> {
+	const result = await deploy({ environment });
+	if (!result.success) {
+		console.error("bedrock deploy failed", { environment, err: result.err });
+		return false;
+	}
+
+	console.log("bedrock deploy succeeded", { environment });
+	return true;
+}
+```
+
+`deploy()` returns a `Result<BedrockState, DeployError>` rather than throwing on failure. `Result` is a discriminated union: `result.success` is `true` with the value on `result.data`, or `false` with the error on `result.err`. `DeployError` is itself stage-tagged (`configLoadFailed`, `stateReadFailed`, `applyFailed`, and similar) so callers can branch on `kind` to distinguish what went wrong without parsing error messages.
+
+## Quick start (CLI)
+
+Using the same `bedrock.config.ts` from above:
+
+```bash
+export BEDROCK_API_KEY=...
+export BEDROCK_GITHUB_TOKEN=...
+
+pnpm bedrock deploy --env production
+```
+
+`bedrock deploy` discovers `bedrock.config.{ts,js,mjs,yaml,yml,json,luau}` in the current directory, loads it, and runs the same reconcile as the programmatic path. If no config sits at the project root, bedrock also looks inside `.bedrock/` so you can colocate the file with your other `.bedrock/` artifacts; a root-level config always wins on collision. Output is rendered via `@clack/prompts` (interactive progress, summary, and error reporting).
+
+`--env` may be repeated to deploy to multiple environments in one invocation; each environment is reconciled with its own merged config and its own state slot.
+
+## What bedrock manages today
+
+| Kind | Key example | What bedrock manages | Notes |
+|---|---|---|---|
+| `universe` | `"main"` (singleton) | Name, description, social links, age guidelines, opt-in studio access. | Adopted by ID. Bedrock does not create new universes. |
+| `place` | `"start-place"` | Place metadata (name, description, server-fill mode, max-player count), `.rbxl` file uploads. | The root place is adopted; secondary places are provisioned by bedrock. |
+| `gamePass` | `"vip-pass"` | Name, description, icon upload, price, on-sale state. | Provisioned by bedrock; the asset ID is recorded in outputs. |
+| `developerProduct` | `"gem-pack-100"` | Name, description, icon upload, price. | Provisioned by bedrock; the asset ID is recorded in outputs. |
+
+Bedrock does not delete resources. Removing an entry from your config leaves the upstream entity in place; delete it from Creator Hub directly if you want it gone. Additional kinds (badges, place settings, more) are on the [roadmap](https://github.com/christopher-buss/bedrock/projects).
+
+## CLI reference
+
+```text
+bedrock <command> [options]
+```
+
+**`bedrock deploy`** - reconciles every configured environment (or only those passed via `--env`) against live Roblox state, writing the new state snapshot on success.
+
+Options: `--env <name>` (repeatable), `--config <path>`, `--api-key <value>`, `--github-token <value>`.
+
+**`bedrock diff`** - previews the operations a deploy *would* apply, without writing state or hitting any mutating Roblox endpoints. Suitable for code review and CI.
+
+Options: same as `deploy`.
+
+**`bedrock migrate [stateFilePath]`** - translates a state file from another deployment tool into a bedrock project. Currently supports Mantle (`--from mantle`); other sources will be added as needed. The maintainer-prompt UI walks through naming the project, choosing a backend, and resolving any unrecognized fields.
+
+Options: `--from <tool>`.
+
+Pass `--help` to any command for the full option list at the version you have installed.
+
+## Programmatic API surface
+
+The most commonly imported entry points:
+
+| Symbol | Module | Role |
+|---|---|---|
+| `deploy()` | `@bedrock-rbx/core` | Full reconcile end-to-end. |
+| `diff()` | `@bedrock-rbx/core` | Pure function from desired and current state to an operation list. |
+| `applyOps()` | `@bedrock-rbx/core` | Dispatch an operation list to its drivers and collect outputs. |
+| `loadConfig()` | `@bedrock-rbx/core` | Discover and load a `bedrock.config.*` file. |
+| `buildDesired()` | `@bedrock-rbx/core` | Compute the desired-state list from a resolved config. |
+| `defineConfig()` | `@bedrock-rbx/core/config` | Type-helper for `bedrock.config.ts`. |
+| `ResourceDriver<K>` | `@bedrock-rbx/core` | Plugin contract for resource kinds. |
+| `StatePort` | `@bedrock-rbx/core` | Plugin contract for state backends. |
+| `ProgressPort` | `@bedrock-rbx/core` | Listener interface for per-resource and aggregate deploy events. |
+
+`ResourceDriver<K>`, `StatePort`, and `ProgressPort` are published contracts today; the plugin runtime that lets you register custom implementations against a real deploy ships in v0.3.
+
+See the [full reference on the docs site](https://bedrock-livid.vercel.app/) for the complete list of exports.
+
+## Status, docs, and contributing
+
+Bedrock is in active development ahead of a first public release. Track scope and timing on the [project board](https://github.com/christopher-buss/bedrock/projects).
+
+- [Documentation site](https://bedrock-livid.vercel.app/) (work in progress)
+- [Source repository](https://github.com/christopher-buss/bedrock)
+- [Issues](https://github.com/christopher-buss/bedrock/issues) (maintainer-only; external feedback runs through [Discussions](https://github.com/christopher-buss/bedrock/discussions) as prompt requests)
+- [Contributing guide](https://github.com/christopher-buss/bedrock/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/christopher-buss/bedrock/blob/main/SECURITY.md)
+
+## License
+
+[MIT](https://github.com/christopher-buss/bedrock/blob/main/LICENSE) (c) Christopher Buss.

package/dist/cli/run.mjs

@@ -1,25 +1,94 @@
 #!/usr/bin/env node
-import { A as createClackProgressAdapter, E as serializeStateFile, G as renderMigrateParseError, H as renderBuildStatePortError, J as renderStateWriteError, K as renderMigrationSummary, U as renderDeployError, V as resolveStateConfig, W as renderMigrateError, _ as diff, a as buildStatePort, d as selectEnvironment, f as selectMergedEnvironment, i as loadConfig, l as validatePlan, m as flattenConfig, n as serializeConfig, o as buildDesired, p as collectRedactionAnnotations, q as renderParseError, r as deploy, t as migrateMantleState, u as extractResourceRedaction, y as createClackPort } from "../migrate-mantle-state-qejWFAR0.mjs";
+import { $ as renderStateWriteError, G as renderBuildStatePortError, J as renderMigrateParseError, K as renderDeployError, N as createClackProgressAdapter, Q as renderParseError, W as resolveStateConfig, X as renderOverrideDiscoveryError, Y as renderMigrationSummary, Z as renderOverrideError, _ as diff, a as assertAllReconcilable, b as buildCredentialOverrides, d as selectEnvironment, et as createClackPort, f as selectMergedEnvironment, i as loadConfig, k as serializeStateFile, m as flattenConfig, n as serializeConfig, o as buildStatePort, p as collectRedactionAnnotations, q as renderMigrateError, r as deploy, s as buildDesired, t as migrateMantleState, u as extractResourceRedaction, x as createDefaultSpawner, y as dispatchOverride } from "../migrate-mantle-state-F4zdhxV4.mjs";
 import { isCancel, path, select, text } from "@clack/prompts";
 import process from "node:process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import sade from "sade";
 //#region package.json
-var version = "0.1.0-beta.14";
+var version = "0.1.0-beta.16";
 //#endregion
-//#region src/cli/credential-environment-overrides.ts
+//#region src/cli/build-override-invocation.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.
+* Translate the deploy command's parsed inputs into a single-environment
+* {@link OverrideInvocation}. Optional flags (`apiKey`, `configFile`,
+* `githubToken`) are *omitted* from the returned object when their parsed
+* value is `undefined`, rather than included with an `undefined` value: the
+* spawn protocol's downstream argv and env-var routing relies on field
+* presence, not just defined-ness.
+* @param inputs - {@link BuildOverrideInvocationInputs}.
+* @returns A single-environment {@link OverrideInvocation}.
 */
-function buildCredentialOverrides(flags) {
-	const overrides = {};
-	if (flags.apiKey !== void 0) overrides["BEDROCK_API_KEY"] = flags.apiKey;
-	if (flags.githubToken !== void 0) overrides["GITHUB_TOKEN"] = flags.githubToken;
-	return overrides;
+function buildOverrideInvocation(inputs) {
+	const { environment, overridePath, parsed } = inputs;
+	return {
+		...parsed.apiKey === void 0 ? {} : { apiKey: parsed.apiKey },
+		...parsed.configFile === void 0 ? {} : { configFile: parsed.configFile },
+		environment,
+		...parsed.githubToken === void 0 ? {} : { githubToken: parsed.githubToken },
+		overridePath
+	};
+}
+//#endregion
+//#region src/cli/discover-override.ts
+const OVERRIDE_DIR_NAME = ".bedrock";
+const OVERRIDE_EXTENSION = ".ts";
+const VALID_COMMAND = /^[a-z][a-z0-9-]*$/;
+/**
+* Stat-injectable variant of {@link discoverOverride}. Exported so tests can
+* drive `EACCES`-class errors and malformed-throw cases that real fs fixtures
+* cannot reliably produce on every supported OS.
+* @param inputs - {@link DiscoverOverrideInputs}.
+* @returns The absolute path to the override file when it exists, otherwise
+* `undefined`.
+*/
+function discoverOverrideWith(inputs) {
+	const { command, projectRoot, stat } = inputs;
+	if (!VALID_COMMAND.test(command)) return;
+	const candidate = resolve(projectRoot, OVERRIDE_DIR_NAME, `${command}${OVERRIDE_EXTENSION}`);
+	try {
+		return stat(candidate).isFile() ? candidate : void 0;
+	} catch (err) {
+		if (isAbsenceError(err)) return;
+		throw err;
+	}
+}
+/**
+* Resolve the path of a user-authored `.bedrock/<command>.ts` override for
+* the given command, or return `undefined` when no such file exists.
+*
+* The CLI uses this primitive to decide whether a subcommand invocation
+* should be handed to an override script or run through the built-in path.
+* `undefined` therefore means "fall through to the built-in implementation",
+* so only absence-style stat failures (`ENOENT`, `ENOTDIR`) are swallowed.
+* Permission and other errors propagate; the dispatcher must refuse to
+* silently route a `deploy` (or any other destructive command) through the
+* built-in path when the override file demonstrably exists but is
+* unreadable.
+*
+* `command` is validated against the subcommand grammar before any path
+* construction. An out-of-shape input cannot be a real subcommand and
+* returns `undefined` without touching the filesystem.
+* @param projectRoot - Absolute path of the directory `bedrock` was invoked
+* from. Relative inputs are resolved against `process.cwd()`.
+* @param command - The CLI subcommand name to look up (`deploy`, `diff`,
+* ...). Must match `/^[a-z][a-z0-9-]*$/`; anything else returns `undefined`.
+* @returns The absolute path to the override file when it exists, otherwise
+* `undefined`.
+* @throws When the stat call fails with anything other than `ENOENT` or
+* `ENOTDIR` (e.g. `EACCES`, `EPERM`).
+*/
+function discoverOverride(projectRoot, command) {
+	return discoverOverrideWith({
+		command,
+		projectRoot,
+		stat: statSync
+	});
+}
+function isAbsenceError(error) {
+	if (!(error instanceof Error) || !("code" in error)) return false;
+	return error.code === "ENOENT" || error.code === "ENOTDIR";
 }
 //#endregion
 //#region src/cli/parse-options.ts
@@ -124,6 +193,14 @@ function pickString(rawOptions, ...keys) {
 * `deploy()` for each `--env` value in order. Per-env successes and failures
 * render through clack as a single line each; the aggregated exit code is
 * `EXIT_OK` only when every env succeeded.
+*
+* When a `.bedrock/deploy.ts` override is discovered under the resolved
+* project root, each `--env` is handed to the spawner via
+* {@link dispatchOverride} instead of the in-process `deploy()` call. The
+* aggregation rule is identical: every env still runs and the exit code is
+* `EXIT_OK` only when every spawn returned a zero exit code. Unlike the
+* in-process path, only failures emit a per-env line here; a successful
+* spawn's output comes from the override script's own inherited stdout.
 * @param deps - Dependency overrides; missing slots are default-constructed
 *   from real implementations.
 * @returns An async sade action that returns once `deps.exit` was invoked.
@@ -139,9 +216,12 @@ function resolveDeploy(deps) {
 	return {
 		clack: deps.clack ?? createClackPort(),
 		deploy: deps.deploy ?? deploy,
+		discoverOverride: deps.discoverOverride ?? discoverOverride,
 		exit: deps.exit ?? ((code) => process.exit(code)),
 		loadConfig: deps.loadConfig ?? loadConfig,
-		progressOverride: deps.progress
+		progressOverride: deps.progress,
+		projectRoot: deps.projectRoot ?? process.cwd(),
+		spawner: deps.spawner ?? createDefaultSpawner()
 	};
 }
 function loadOptionsFor$1(parsed) {
@@ -151,28 +231,30 @@ function cancelAsFailed$1(clack) {
 	clack.cancel("deploy failed");
 }
 async function dispatchEnvironments$1(inputs) {
-	const { config, environments, getEnv, progress, resolved } = inputs;
+	const { config, getEnv, overridePath, parsed, progress, resolved } = inputs;
 	const failed = [];
-	for (const environment of environments) {
-		const result = await resolved.deploy({
+	for (const environment of parsed.environments) {
+		if (overridePath !== void 0) {
+			const result = await dispatchOverride(buildOverrideInvocation({
+				environment,
+				overridePath,
+				parsed
+			}), resolved.spawner);
+			if (!result.success) {
+				renderOverrideError({
+					environment,
+					err: result.err
+				}, resolved.clack);
+				failed.push(environment);
+			}
+			continue;
+		}
+		if (!(await resolved.deploy({
 			config,
 			environment,
 			getEnv,
 			progress
-		});
-		if (result.success) progress.emit({
-			environment,
-			kind: "deploySuccess",
-			resourceCount: result.data.resources.length
-		});
-		else {
-			progress.emit({
-				environment,
-				error: result.err,
-				kind: "deployFailure"
-			});
-			failed.push(environment);
-		}
+		})).success) failed.push(environment);
 	}
 	return failed;
 }
@@ -181,15 +263,16 @@ function buildGetEnvironment$1(parsed) {
 	return (name) => overrides[name] ?? process.env[name];
 }
 async function dispatchAndReport(input) {
-	const { loaded, parsed, resolved } = input;
+	const { loaded, overridePath, parsed, resolved } = input;
 	const progress = resolved.progressOverride ?? createClackProgressAdapter({
 		clack: resolved.clack,
 		config: loaded
 	});
 	if ((await dispatchEnvironments$1({
 		config: loaded,
-		environments: parsed.environments,
 		getEnv: buildGetEnvironment$1(parsed),
+		overridePath,
+		parsed,
 		progress,
 		resolved
 	})).length > 0) {
@@ -199,6 +282,18 @@ async function dispatchAndReport(input) {
 	resolved.clack.outro("deploy succeeded");
 	return 0;
 }
+function discoverOverridePath(resolved) {
+	try {
+		return {
+			kind: "discovered",
+			overridePath: resolved.discoverOverride(resolved.projectRoot, "deploy")
+		};
+	} catch (err) {
+		renderOverrideDiscoveryError(err, resolved.clack);
+		cancelAsFailed$1(resolved.clack);
+		return { kind: "failed" };
+	}
+}
 async function runDeploy(rawOptions, resolved) {
 	resolved.clack.intro("bedrock deploy");
 	const parsed = parseCommonOptions(rawOptions);
@@ -216,8 +311,11 @@ async function runDeploy(rawOptions, resolved) {
 		cancelAsFailed$1(resolved.clack);
 		return 1;
 	}
+	const discovery = discoverOverridePath(resolved);
+	if (discovery.kind === "failed") return 1;
 	return dispatchAndReport({
 		loaded: loaded.data,
+		overridePath: discovery.overridePath,
 		parsed: parsed.data,
 		resolved
 	});
@@ -227,7 +325,7 @@ async function runDeploy(rawOptions, resolved) {
 /**
 * Compute the operations `deploy` would apply for a target environment
 * without writing state. Default-constructs missing deps from the project
-* config and `GITHUB_TOKEN`; never reads `process.env` when `statePort`
+* config and `BEDROCK_GITHUB_TOKEN`; never reads `process.env` when `statePort`
 * and `config` are both supplied explicitly.
 *
 * @param options - Target environment plus optional overrides.
@@ -336,7 +434,7 @@ async function runPreview(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,
@@ -1328,8 +1426,8 @@ const PROGRAM_DESCRIBE = "Infrastructure-as-Code deployment tool for Roblox";
 */
 function createProg(deps = {}) {
 	const prog = sade(PROGRAM_NAME).describe(PROGRAM_DESCRIBE).version(version);
-	prog.command("deploy").describe("Reconcile a project's resources against the configured environment(s)").option("--env", "Target environment (repeat for multiple)").option("--config", "Config file path (overrides discovery)").option("--api-key", "Override the BEDROCK_API_KEY environment variable").option("--github-token", "Override the GITHUB_TOKEN environment variable").action(deployCommand(deps));
-	prog.command("diff").describe("Preview the operations a deploy would apply, without writing state").option("--env", "Target environment (repeat for multiple)").option("--config", "Config file path (overrides discovery)").option("--api-key", "Override the BEDROCK_API_KEY environment variable").option("--github-token", "Override the GITHUB_TOKEN environment variable").action(diffCommand(deps));
+	prog.command("deploy").describe("Reconcile a project's resources against the configured environment(s)").option("--env", "Target environment (repeat for multiple)").option("--config", "Config file path (overrides discovery)").option("--api-key", "Override the BEDROCK_API_KEY environment variable").option("--github-token", "Override the BEDROCK_GITHUB_TOKEN environment variable").action(deployCommand(deps));
+	prog.command("diff").describe("Preview the operations a deploy would apply, without writing state").option("--env", "Target environment (repeat for multiple)").option("--config", "Config file path (overrides discovery)").option("--api-key", "Override the BEDROCK_API_KEY environment variable").option("--github-token", "Override the BEDROCK_GITHUB_TOKEN environment variable").action(diffCommand(deps));
 	prog.command("migrate [stateFilePath]").describe("Translate a state file from another tool into a bedrock project").option("--from", "Source format to migrate from (mantle; prompted if omitted)").action(migrateCommand(deps));
 	return prog;
 }