@layers/amba 4.0.3 → 4.0.4

package/dist/index.js

@@ -8,11 +8,460 @@ import { createServer } from "node:http";
 import open from "open";
 import { createHash, randomBytes } from "node:crypto";
 import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createWriteStream, watch } from "node:fs";
 import { spawn } from "node:child_process";
 import { build } from "esbuild";
-//#region ../shared/dist/index.js
+new Map([
+	{
+		type: "user.created",
+		plane: "app",
+		description: "An app user (end user) was created in the project.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			external_id: "auth0|abc",
+			created_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "user.updated",
+		plane: "app",
+		description: "An app user's profile or attributes changed.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			changed: ["display_name"]
+		},
+		status: "live"
+	},
+	{
+		type: "user.deleted",
+		plane: "app",
+		description: "An app user was deleted.",
+		payloadExample: { app_user_id: "usr_123" },
+		status: "live"
+	},
+	{
+		type: "user.reset",
+		plane: "app",
+		description: "An app user's gamification, economy, engagement and participation state was reset to zero (the user row itself was kept).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			cleared: {
+				user_xp: 1,
+				xp_ledger: 12
+			}
+		},
+		status: "live"
+	},
+	{
+		type: "engagement.push.delivered",
+		plane: "app",
+		description: "A push notification was delivered to a device.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			campaign_id: "cmp_1",
+			delivered_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "engagement.push.failed",
+		plane: "app",
+		description: "A push notification failed to deliver.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			campaign_id: "cmp_1",
+			reason: "unregistered_token"
+		},
+		status: "live"
+	},
+	{
+		type: "email.sent",
+		plane: "app",
+		description: "A transactional email was accepted by the provider for delivery.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			template: "welcome",
+			to: "a@b.com"
+		},
+		status: "live"
+	},
+	{
+		type: "email.failed",
+		plane: "app",
+		description: "A transactional email failed to send.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			template: "welcome",
+			reason: "bounce"
+		},
+		status: "live"
+	},
+	{
+		type: "email.suppressed",
+		plane: "app",
+		description: "An email was suppressed (recipient on the suppression list).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			to: "a@b.com",
+			reason: "unsubscribed"
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.xp.granted",
+		plane: "app",
+		description: "XP was granted to a user.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			amount: 50,
+			total_xp: 1250,
+			rule: "mission_completed",
+			transaction_id: "xpl_abc"
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.level.up",
+		plane: "app",
+		description: "A user crossed an XP threshold into a new level.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			level: 7,
+			previous_level: 6
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.achievement.unlocked",
+		plane: "app",
+		description: "A user unlocked an achievement.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			achievement_id: "first_win",
+			unlocked_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.streak.advanced",
+		plane: "app",
+		description: "A user's streak advanced (a qualifying action extended it).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			streak_id: "daily",
+			count: 12
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.streak.broken",
+		plane: "app",
+		description: "A user's streak reset to zero after a missed window.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			streak_id: "daily",
+			previous_count: 12
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.challenge.completed",
+		plane: "app",
+		description: "A user completed a challenge.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			challenge_id: "ch_1"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.currency.granted",
+		plane: "app",
+		description: "Currency was granted to a user.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			currency: "coins",
+			amount: 100,
+			balance: 350,
+			transaction_id: "ctx_abc"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.currency.spent",
+		plane: "app",
+		description: "A user spent currency.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			currency: "coins",
+			amount: 100,
+			balance: 250,
+			transaction_id: "ctx_def"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.catalog.purchased",
+		plane: "app",
+		description: "A user purchased a catalog item.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			item_id: "sword",
+			price: 100,
+			currency: "coins"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.inventory.granted",
+		plane: "app",
+		description: "An item was granted into a user inventory.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			item_id: "sword",
+			quantity: 1
+		},
+		status: "live"
+	},
+	{
+		type: "subscription.started",
+		plane: "app",
+		description: "A user gained an active subscription / entitlement.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly",
+			store: "app_store",
+			period_type: "normal"
+		},
+		status: "live"
+	},
+	{
+		type: "subscription.renewed",
+		plane: "app",
+		description: "An active subscription renewed for another billing period.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly",
+			store: "app_store"
+		},
+		status: "live"
+	},
+	{
+		type: "subscription.expired",
+		plane: "app",
+		description: "A subscription lapsed / was revoked and access ended.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly"
+		},
+		status: "live"
+	},
+	{
+		type: "entitlement.granted",
+		plane: "app",
+		description: "An entitlement became active for a user (any source).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly",
+			source: "webhook"
+		},
+		status: "live"
+	},
+	{
+		type: "entitlement.revoked",
+		plane: "app",
+		description: "An entitlement became inactive for a user (any source).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			source: "manual"
+		},
+		status: "live"
+	},
+	{
+		type: "social.friendship.created",
+		plane: "app",
+		description: "A friendship was established between two users.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			friend_id: "usr_456"
+		},
+		status: "live"
+	},
+	{
+		type: "social.message.sent",
+		plane: "app",
+		description: "A message was sent in a conversation.",
+		payloadExample: {
+			conversation_id: "cnv_1",
+			sender_id: "usr_123"
+		},
+		status: "live"
+	},
+	{
+		type: "social.review.created",
+		plane: "app",
+		description: "A review was submitted.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			rating: 5,
+			target_id: "item_1"
+		},
+		status: "live"
+	},
+	{
+		type: "content.published",
+		plane: "app",
+		description: "A content item was published / went live.",
+		payloadExample: {
+			item_id: "post_1",
+			library: "news"
+		},
+		status: "live"
+	},
+	{
+		type: "moderation.flagged",
+		plane: "app",
+		description: "User content entered the moderation queue.",
+		payloadExample: {
+			queue_id: "mq_1",
+			content_type: "message",
+			reason: "auto_flag"
+		},
+		status: "live"
+	},
+	{
+		type: "moderation.rejected",
+		plane: "app",
+		description: "Moderated content was rejected.",
+		payloadExample: {
+			queue_id: "mq_1",
+			moderator: "auto"
+		},
+		status: "live"
+	},
+	{
+		type: "project.provisioning.started",
+		plane: "control",
+		description: "Project provisioning began (tenant DB + keys being created).",
+		payloadExample: { project_id: "prj_1" },
+		status: "live"
+	},
+	{
+		type: "project.provisioned",
+		plane: "control",
+		description: "The project finished provisioning and is ready to use.",
+		payloadExample: {
+			project_id: "prj_1",
+			provisioned_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "project.provisioning.failed",
+		plane: "control",
+		description: "Project provisioning failed and was compensated.",
+		payloadExample: {
+			project_id: "prj_1",
+			reason: "neon_quota"
+		},
+		status: "live"
+	},
+	{
+		type: "site.deploy.completed",
+		plane: "control",
+		description: "A static site deploy completed and is serving.",
+		payloadExample: {
+			site: "marketing",
+			deployment_id: "dep_1",
+			url: "https://x.app.amba.host",
+			file_count: 4,
+			serving_configured: true
+		},
+		status: "live"
+	},
+	{
+		type: "site.deploy.failed",
+		plane: "control",
+		description: "A static site deploy failed.",
+		payloadExample: {
+			project_id: "prj_1",
+			site: "marketing",
+			reason: "storage_write_failed"
+		},
+		status: "live"
+	},
+	{
+		type: "domain.registered",
+		plane: "control",
+		description: "A domain was registered through Amba.",
+		payloadExample: {
+			domain: "myapp.com",
+			site: "marketing"
+		},
+		status: "live"
+	},
+	{
+		type: "domain.cert.issued",
+		plane: "control",
+		description: "The TLS certificate for an attached domain became active.",
+		payloadExample: {
+			project_id: "prj_1",
+			domain: "app.myapp.com"
+		},
+		status: "live"
+	},
+	{
+		type: "domain.connected",
+		plane: "control",
+		description: "A domain is fully connected to a site and serving.",
+		payloadExample: {
+			project_id: "prj_1",
+			domain: "myapp.com",
+			site: "marketing"
+		},
+		status: "live"
+	},
+	{
+		type: "billing.subscription.updated",
+		plane: "control",
+		description: "The project's subscription state changed.",
+		payloadExample: {
+			project_id: "prj_1",
+			tier: "pro",
+			status: "active"
+		},
+		status: "live"
+	},
+	{
+		type: "billing.invoice.paid",
+		plane: "control",
+		description: "An invoice was paid.",
+		payloadExample: {
+			project_id: "prj_1",
+			invoice_id: "in_1",
+			amount_usd: 49
+		},
+		status: "live"
+	},
+	{
+		type: "billing.payment_failed",
+		plane: "control",
+		description: "A payment attempt failed.",
+		payloadExample: {
+			project_id: "prj_1",
+			invoice_id: "in_1",
+			reason: "card_declined"
+		},
+		status: "live"
+	}
+].map((e) => [e.type, e]));
 /**
 * Shared email-shape validation.
 *
@@ -529,7 +978,8 @@ async function deployFunctionViaApi(projectId, input) {
 	fd.set("script", new Blob([input.bundleCode], { type: "application/javascript+module" }), `${input.name}.js`);
 	const metadata = {
 		name: input.name,
-		...input.rate_limit !== void 0 ? { rate_limit: input.rate_limit } : {}
+		...input.rate_limit !== void 0 ? { rate_limit: input.rate_limit } : {},
+		...input.public === true ? { public: true } : {}
 	};
 	fd.set("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }), "metadata.json");
 	return request("POST", `/projects/${projectId}/functions/deploy`, fd);
@@ -545,6 +995,7 @@ async function getFunctionLogs(projectId, functionName, options = {}) {
 	if (options.since) params.set("since", options.since);
 	if (options.until) params.set("until", options.until);
 	if (options.limit !== void 0) params.set("limit", String(options.limit));
+	if (options.requestId) params.set("request_id", options.requestId);
 	const qs = params.toString();
 	return request("GET", `/projects/${projectId}/functions/${functionName}/logs${qs ? `?${qs}` : ""}`);
 }
@@ -672,6 +1123,17 @@ async function deleteFunctionViaApi(projectId, functionName, options) {
 async function listSiteDomains(projectId, siteName) {
 	return request("GET", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}/domains`);
 }
+/** GET the current project's declarative configuration bundle. */
+async function exportPromotionBundle(projectId) {
+	return request("GET", `/projects/${projectId}/promotion/export`);
+}
+/** POST a declarative bundle to import it into the project. */
+async function importPromotionBundle(projectId, bundle, mode) {
+	return request("POST", `/projects/${projectId}/promotion/import`, {
+		bundle,
+		mode
+	});
+}
 async function validateApiKey(apiKey) {
 	const res = await fetch(`${getApiRoot()}/v1/auth/validate`, {
 		method: "POST",
@@ -2149,6 +2611,14 @@ Tell the user where their credentials live:
 
 **Already have a PAT?** Skip the signup. Call \`amba_developer_me({})\` to verify the Bearer; if it succeeds, either reuse the most recent project (\`amba_projects_list\`) or call \`amba_projects_create({ name: "<app-name>", platform: "all" })\` and then \`amba_api_keys_create\` twice to mint client + server keys for \`environment: "development"\`.
 
+**Can't reach \`amba_developer_signup\` — it's not in your tool list, or your harness blocks the call?** Do NOT try to work around it by adding the MCP server yourself, running an installer, or editing your own settings/permissions — refusing to self-modify or widen your own permissions is the correct call, and you should not circumvent it. Instead, hand the developer **one** command to run in **their own** terminal (which is not subject to your sandbox):
+
+\`\`\`bash
+npx @layers/amba init
+\`\`\`
+
+It creates the account with no browser and writes \`AMBA_PROJECT_ID\` + \`AMBA_CLIENT_KEY\` to \`.env.local\` (and wires this MCP server up for your next session). Ask them to run it, tell you when it's done, then resume from this Step 0 by reading \`.env.local\`. Asking the developer to paste an \`amb_ck_…\` client key is the last-resort lite path — it's enough to wire \`Amba.configure()\` + runtime calls and verify events land, but a client key alone can't do admin provisioning (creating achievements, collections, segments, etc.), which needs the PAT or server key.
+
 ## Step 1 — Classify the app
 
 Look at what the user told you and at any files they shared. You're trying to pick one of ten presets in 30 seconds, not write a treatise. Inputs:
@@ -2270,7 +2740,7 @@ SKIPPED (low signal — re-run with /amba <feature> if you want them)
 NEEDS YOUR INPUT
   - Apple Sign In: add the "Sign in with Apple" capability in Xcode > Signing & Capabilities.
   - Google Sign In: paste your Google OAuth client ID into amba_projects_update({ google_oauth_client_id: "..." }).
-  - APNs / FCM: upload credentials in app.amba.dev before push delivers.
+  - APNs / FCM: configure credentials with amba_integrations_configure (paste the .p8 / service-account JSON inline) before push delivers.
 
 NEXT STEPS
   - Paste AMBA_CLIENT_KEY into your build env (already shown above)
@@ -4081,7 +4551,7 @@ function confirm$1(question) {
 		});
 	});
 }
-function handleError$1(err) {
+function handleError$2(err) {
 	if (err instanceof ApiClientError) if (err.statusCode === 401 || err.statusCode === 403) console.log(pc.red("  ✗") + " Not authenticated — run `amba login` first.");
 	else console.log(pc.red("  ✗") + ` ${err.message}`);
 	else if (err instanceof Error) console.log(pc.red("  ✗") + ` ${err.message}`);
@@ -4131,7 +4601,7 @@ async function projectsListCommand() {
 		console.log(pc.dim(`  ${projects.length} project${projects.length === 1 ? "" : "s"}`));
 		console.log();
 	} catch (err) {
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsCreateCommand(input) {
@@ -4177,7 +4647,7 @@ async function projectsCreateCommand(input) {
 		console.log(pc.dim("  Next: ") + pc.cyan(`amba projects show ${id}`));
 		console.log();
 	} catch (err) {
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsUpdateCommand(projectId, input) {
@@ -4203,7 +4673,7 @@ async function projectsUpdateCommand(projectId, input) {
 			console.log();
 			process.exit(1);
 		}
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsShowCommand(projectId) {
@@ -4221,7 +4691,7 @@ async function projectsShowCommand(projectId) {
 			console.log();
 			process.exit(1);
 		}
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsDeleteCommand(projectId, opts = {}) {
@@ -4246,7 +4716,7 @@ async function projectsDeleteCommand(projectId, opts = {}) {
 			console.log();
 			process.exit(1);
 		}
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 //#endregion
@@ -4989,6 +5459,47 @@ function parseEnv(content) {
 * empty; customer code is expected to be self-contained.
 */
 /**
+* Conventional entry-point filenames probed (in order) when
+* `amba functions deploy <dir>` is pointed at a directory rather than a
+* single file. Mirrors the Node / bundler convention (`index.*`) so a
+* developer can `amba functions deploy ./my-fn` with an `index.ts` inside.
+*/
+const FUNCTION_ENTRY_CANDIDATES = [
+	"index.ts",
+	"index.js",
+	"index.mjs"
+];
+/**
+* Resolve the bundler entry point from a deploy target that may be either a
+* single file OR a directory.
+*
+*   - File  → returned as-is (single-file back-compat path).
+*   - Dir   → resolved by convention to `index.{ts,js,mjs}`, or to an
+*             explicit `entry` (relative to the directory) when provided.
+*
+* Throws an actionable error when the target doesn't exist, or when a
+* directory has no resolvable entry point (and no `--entry` was passed).
+*/
+async function resolveFunctionEntry(target, explicitEntry) {
+	const st = await stat(target).catch(() => null);
+	if (!st) throw new Error(`Deploy target not found: ${target}`);
+	if (st.isFile()) {
+		if (explicitEntry) throw new Error(`--entry is only valid when deploying a directory; ${target} is a file. Drop --entry, or point the deploy at the directory containing ${explicitEntry}.`);
+		return target;
+	}
+	if (!st.isDirectory()) throw new Error(`Deploy target is neither a file nor a directory: ${target}`);
+	if (explicitEntry) {
+		const candidate = join(target, explicitEntry);
+		if (!(await stat(candidate).catch(() => null))?.isFile()) throw new Error(`--entry file not found: ${candidate}`);
+		return candidate;
+	}
+	for (const name of FUNCTION_ENTRY_CANDIDATES) {
+		const candidate = join(target, name);
+		if ((await stat(candidate).catch(() => null))?.isFile()) return candidate;
+	}
+	throw new Error(`No entry point found in directory ${target}. Add one of ${FUNCTION_ENTRY_CANDIDATES.join(", ")}, or pass --entry <file> (relative to the directory).`);
+}
+/**
 * Modules the bundler treats as `external` by default. The Amba
 * function runtime exposes zero npm packages — there is no "platform
 * stdlib" for customer functions to import. Keep this list empty.
@@ -5011,6 +5522,91 @@ var BundleSizeError = class extends Error {
 	}
 };
 /**
+* The single source-of-truth message for the wrong-handler-shape failure.
+* Shared between the CLI bundler (pre-upload), the local `dev` runner, and
+* the server-side deploy hint so dev / deploy / prod all describe the fix
+* identically. Customer functions run as Module Workers; the legacy
+* service-worker shape (`export default async function (req) { … }`) is
+* rejected by the runtime at upload, so we reject it before the round-trip.
+*/
+const HANDLER_SHAPE_FIX_MESSAGE = "Function entrypoint must `export default { async fetch(req, env, ctx) { … } }` (the Module Worker shape). Found a default-exported function instead.";
+/** Message used when the entry file has no `export default` at all. */
+const HANDLER_SHAPE_MISSING_DEFAULT_MESSAGE = "Function entrypoint must `export default { async fetch(req, env, ctx) { … } }` (the Module Worker shape). No default export was found.";
+/** Message used when the default export is present but has no `fetch` method. */
+const HANDLER_SHAPE_NO_FETCH_MESSAGE = "Function entrypoint must `export default { async fetch(req, env, ctx) { … } }` (the Module Worker shape). The default export has no `fetch` method.";
+/**
+* Thrown when the bundled entry's `export default` is not the Module Worker
+* shape (`{ fetch(req, env, ctx) }`). Raised BEFORE any upload so a wrong
+* handler shape fails fast on the developer's machine with an actionable
+* message instead of an opaque upstream rejection at deploy time.
+*/
+var HandlerShapeError = class extends Error {
+	kind;
+	constructor(message, kind) {
+		super(message);
+		this.kind = kind;
+		this.name = "HandlerShapeError";
+	}
+};
+/**
+* Inspect an already-imported module namespace and assert it has the
+* Module Worker handler shape: a default export that is an object (or
+* function-with-properties) carrying a callable `fetch`.
+*
+* Pure + side-effect free — it only reads the shape of `mod.default`, never
+* invokes `fetch`. This is the unit-testable core; `assertModuleWorkerShape`
+* wraps the import-from-code plumbing around it.
+*
+* Throws `HandlerShapeError` on:
+*   - no default export (`missing-default`)
+*   - a default-exported plain function — the legacy service-worker shape
+*     (`plain-function`)
+*   - a default export with no callable `fetch` (`no-fetch`)
+*/
+function assertHandlerShape(mod) {
+	const def = mod.default;
+	if (def === void 0 || def === null) throw new HandlerShapeError(HANDLER_SHAPE_MISSING_DEFAULT_MESSAGE, "missing-default");
+	if (typeof def === "function") {
+		if (typeof def.fetch !== "function") throw new HandlerShapeError(HANDLER_SHAPE_FIX_MESSAGE, "plain-function");
+		return;
+	}
+	if (typeof def !== "object") throw new HandlerShapeError(HANDLER_SHAPE_NO_FETCH_MESSAGE, "no-fetch");
+	if (typeof def.fetch !== "function") throw new HandlerShapeError(HANDLER_SHAPE_NO_FETCH_MESSAGE, "no-fetch");
+}
+/**
+* Validate that the bundled customer code exports the Module Worker handler
+* shape, by importing it in isolation and inspecting `mod.default`.
+*
+* Mechanism: write the bundle to a throwaway temp `.mjs` and dynamic-import
+* it, then hand the namespace to `assertHandlerShape`. This is the same
+* import-and-inspect approach the local `dev` runner uses
+* (`functions.ts` DEV_RUNNER_SOURCE) — reused here so the pre-upload check
+* and the dev runner agree on what "valid shape" means. Importing runs the
+* module's top-level code (unavoidable to read the export), but the handler
+* itself is NEVER invoked — we only read the shape of the exported object.
+*
+* The temp file is always cleaned up (best-effort) before returning.
+*/
+async function assertModuleWorkerShape(code) {
+	const dir = await mkdtemp(join(tmpdir(), "amba-fn-shape-"));
+	const filePath = join(dir, "fn.mjs");
+	try {
+		await writeFile(filePath, code, "utf8");
+		let mod;
+		try {
+			mod = await import(pathToFileURL(filePath).href);
+		} catch (err) {
+			throw new Error(`Failed to load the function entrypoint while validating its handler shape: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		assertHandlerShape(mod);
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/**
 * Bundle a customer function file for upload to a Workers dispatch
 * namespace. Returns the bundled code + metadata; throws
 * `BundleSizeError` when the compressed size exceeds the cap so the CLI
@@ -5043,6 +5639,7 @@ async function bundleFunction(options) {
 	const compressedSize = await gzipSizeOf(output.contents);
 	const max = options.maxSizeBytes ?? 8388608;
 	if (compressedSize > max) throw new BundleSizeError(compressedSize, max);
+	if (options.validateHandlerShape !== false) await assertModuleWorkerShape(code);
 	return {
 		code,
 		sha256: await hashSha256Hex(output.contents),
@@ -5091,16 +5688,19 @@ function formatBytes$1(n) {
 * records the deployment in a single round-trip. The other subcommands
 * are thin shells over the admin API helpers in `api-client.ts`.
 */
-async function functionsDeployCommand(entryPoint, options = {}) {
+async function functionsDeployCommand(target, options = {}) {
 	const projectId = (await loadProjectConfig()).projectId;
-	const functionName = options.name ?? basename(entryPoint).replace(/\.[^.]+$/, "");
+	const targetIsDir = (await stat(target).catch(() => null))?.isDirectory() ?? false;
+	const entryPoint = await resolveFunctionEntry(target, options.entry);
+	const defaultName = targetIsDir ? basename(target.replace(/[/\\]+$/, "")) : basename(entryPoint).replace(/\.[^.]+$/, "");
+	const functionName = options.name ?? defaultName;
 	validateFunctionName(functionName);
 	const rateLimit = parseRateLimitFlags(options);
 	console.log();
 	console.log(pc.bold(`  amba functions deploy ${pc.cyan(functionName)}`));
 	console.log(pc.dim("  ─────────────────────────────────"));
 	console.log();
-	console.log(pc.dim("  Bundling…"));
+	console.log(pc.dim(`  Bundling ${entryPoint}…`));
 	const bundle = await bundleFunction({ entryPoint });
 	printBundleReport(bundle);
 	if (options.dryRun) {
@@ -5113,7 +5713,8 @@ async function functionsDeployCommand(entryPoint, options = {}) {
 		result = await deployFunctionViaApi(projectId, {
 			name: functionName,
 			bundleCode: bundle.code,
-			rate_limit: rateLimit
+			rate_limit: rateLimit,
+			public: options.public === true ? true : void 0
 		});
 	} catch (err) {
 		if (err instanceof ApiClientError && err.statusCode === 503) {
@@ -5126,6 +5727,7 @@ async function functionsDeployCommand(entryPoint, options = {}) {
 	console.log(pc.green("  ✓") + ` Deployed ${pc.cyan(functionName)} ${pc.dim(`v${result.data.version}`)}`);
 	console.log(pc.green("  ✓") + ` URL: ${pc.underline(result.fn_url)}`);
 	if (rateLimit) console.log(pc.dim(`  Rate limit: ${rateLimit.max} per ${rateLimit.window} (key=${rateLimit.key}) — enforced pre-dispatch`));
+	if (options.public === true) console.log(pc.yellow("  ! Public") + pc.dim(" — no X-Api-Key required. Verify the webhook signature inside your handler."));
 	console.log();
 }
 async function functionsListCommand() {
@@ -5481,11 +6083,15 @@ try {
       return fetchFn(req, env, ctx);
     };
   } else if (typeof mod.default === 'function') {
-    // Legacy plain-function shape — still accepted for backward compat but env
-    // parameter is not available (secrets only reachable via process.env).
-    handler = mod.default;
+    // Legacy service-worker shape (\`export default async function (req) { ... }\`).
+    // REJECTED — production runs functions as Module Workers and the runtime
+    // rejects this shape at upload. Accepting it in dev was a dev/prod parity
+    // trap: a function that ran here would fail \`amba functions deploy\`. Reject
+    // with the same fix the bundler + server hint use so dev and prod agree.
+    process.stderr.write('  Error: Function entrypoint must \`export default { async fetch(req, env, ctx) { … } }\` (the Module Worker shape). Found a default-exported function instead.\\n');
+    process.exit(2);
   } else {
-    process.stderr.write('  Error: entry file must export default { async fetch(req, env, ctx) { ... } }\\n');
+    process.stderr.write('  Error: Function entrypoint must \`export default { async fetch(req, env, ctx) { … } }\` (the Module Worker shape). The default export has no \`fetch\` method.\\n');
     process.exit(2);
   }
 } catch (err) {
@@ -5653,7 +6259,8 @@ async function functionsLogsCommand(functionName, options = {}) {
 	const res = await getFunctionLogs(projectConfig.projectId, functionName, {
 		since: options.since,
 		until: options.until,
-		limit: options.limit
+		limit: options.limit,
+		requestId: options.requestId
 	});
 	printEvents(res.data.events, options.json);
 	if (res.data.truncated) if (options.json) process.stderr.write(`{"truncated":true}\n`);
@@ -5669,7 +6276,8 @@ async function runTail(projectId, functionName, options) {
 		try {
 			result = await getFunctionLogs(projectId, functionName, {
 				since: new Date(highWaterMs).toISOString(),
-				limit: options.limit ?? 200
+				limit: options.limit ?? 200,
+				requestId: options.requestId
 			});
 		} catch (err) {
 			console.error(pc.yellow(`  ! tail fetch failed: `) + (err instanceof Error ? err.message : String(err)));
@@ -5900,7 +6508,7 @@ function renderStatus(status) {
 * Project is resolved via `loadProjectConfig` (AMBA_PROJECT_ID env, then
 * .env / .env.local in the cwd) — same pattern as `amba secrets *`.
 */
-function handleError(err) {
+function handleError$1(err) {
 	if (err instanceof ApiClientError) if (err.statusCode === 401 || err.statusCode === 403) console.log(pc.red("  ✗") + " Not authenticated — run `amba login` first.");
 	else console.log(pc.red("  ✗") + ` ${err.message}`);
 	else if (err instanceof Error) console.log(pc.red("  ✗") + ` ${err.message}`);
@@ -5914,7 +6522,7 @@ function handleError(err) {
 * its own request wrapper — same auth flow as `request()` in api-client,
 * intentionally not exported there so we don't grow the public surface.
 */
-async function adminWrite(method, path, body) {
+async function adminWrite$1(method, path, body) {
 	const token = await resolveBearerToken();
 	const url = `${process.env["AMBA_API_URL"] ?? "https://api.amba.dev"}/v1/admin${path}`;
 	const res = await fetch(url, {
@@ -5976,7 +6584,7 @@ async function billingStatusCommand() {
 			console.log();
 		}
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function billingUpgradeCommand(input) {
@@ -5987,7 +6595,7 @@ async function billingUpgradeCommand(input) {
 	try {
 		const { projectId } = await loadProjectConfig();
 		const interval = input.interval ?? "month";
-		const res = await adminWrite("POST", `/projects/${projectId}/billing/checkout`, {
+		const res = await adminWrite$1("POST", `/projects/${projectId}/billing/checkout`, {
 			tier: input.tier,
 			interval
 		});
@@ -6001,7 +6609,7 @@ async function billingUpgradeCommand(input) {
 		console.log(pc.dim("  Subscription status updates automatically once Stripe confirms (a few seconds)."));
 		console.log();
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function billingPortalCommand() {
@@ -6011,13 +6619,13 @@ async function billingPortalCommand() {
 	console.log();
 	try {
 		const { projectId } = await loadProjectConfig();
-		const res = await adminWrite("POST", `/projects/${projectId}/billing/portal`);
+		const res = await adminWrite$1("POST", `/projects/${projectId}/billing/portal`);
 		console.log(pc.bold("  Open this URL to manage your subscription:"));
 		console.log();
 		console.log(`  ${pc.cyan(res.data.url)}`);
 		console.log();
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function billingSetCeilingCommand(input) {
@@ -6027,15 +6635,374 @@ async function billingSetCeilingCommand(input) {
 	console.log();
 	try {
 		const { projectId } = await loadProjectConfig();
-		await adminWrite(`PUT`, `/projects/${projectId}/billing/ceiling`, { ceiling_usd: input.ceiling });
+		await adminWrite$1(`PUT`, `/projects/${projectId}/billing/ceiling`, { ceiling_usd: input.ceiling });
 		if (input.ceiling === null) console.log(pc.green("  ✓") + " Spend ceiling removed (linear overage continues).");
 		else console.log(pc.green("  ✓") + ` Spend ceiling set to $${input.ceiling}/mo.`);
 		console.log();
+	} catch (err) {
+		handleError$1(err);
+	}
+}
+//#endregion
+//#region src/commands/payments.ts
+/**
+* `amba payments *` subcommands — CLI access to the Amba Payments (Stripe
+* Connect platform) surface at `/v1/admin/projects/:id/payments/*`
+* (tracker #10).
+*
+* Amba is the payments rail for the developer's app: the app is the seller,
+* Amba takes a platform fee, Stripe carries money-transmission. This is the
+* developer-facing onboarding + config + reporting surface, so naming Stripe
+* here is by intent (same as `amba billing`).
+*
+*   amba payments setup                    — create the connected account +
+*                                            print the hosted onboarding URL.
+*   amba payments status                   — onboarding stage + capability flags.
+*   amba payments set-fee <bps|off>        — default platform fee (basis points).
+*   amba payments balance                  — connected-account balance.
+*   amba payments payouts                  — recent payouts.
+*
+* Every live call is gated by the platform's PAYMENTS_CONNECT_LIVE
+* kill-switch — when off the API returns PAYMENTS_NOT_ENABLED, surfaced
+* verbatim here. Project resolved via loadProjectConfig (same as billing).
+*/
+function handleError(err) {
+	if (err instanceof ApiClientError) if (err.statusCode === 401 || err.statusCode === 403) console.log(pc.red("  ✗") + " Not authenticated — run `amba login` first.");
+	else if (err.errorCode === "PAYMENTS_NOT_ENABLED") console.log(pc.yellow("  •") + " Payments are not enabled on this Amba platform yet. The platform owner must finish setup before payments go live.");
+	else console.log(pc.red("  ✗") + ` ${err.message}`);
+	else if (err instanceof Error) console.log(pc.red("  ✗") + ` ${err.message}`);
+	else console.log(pc.red("  ✗") + " Unknown error");
+	console.log();
+	process.exit(1);
+}
+/**
+* POST/PUT to the admin API. Mirrors the helper in billing.ts (api-client
+* doesn't export a generic write for arbitrary paths).
+*/
+async function adminWrite(method, path, body) {
+	const token = await resolveBearerToken();
+	const url = `${process.env["AMBA_API_URL"] ?? "https://api.amba.dev"}/v1/admin${path}`;
+	const res = await fetch(url, {
+		method,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json",
+			"User-Agent": "amba-cli/0.1.1"
+		},
+		body: body === void 0 ? void 0 : JSON.stringify(body)
+	});
+	if (!res.ok) {
+		let message = `API request failed: ${res.status} ${res.statusText}`;
+		let code;
+		try {
+			const errorBody = await res.json();
+			if (errorBody.error?.message) {
+				message = errorBody.error.message;
+				code = errorBody.error.code;
+			}
+		} catch {}
+		throw new ApiClientError(message, res.status, code);
+	}
+	return await res.json();
+}
+function printAccount(a) {
+	console.log(`  Account:            ${pc.dim(a.stripe_account_id)}`);
+	console.log(`  Onboarding:         ${pc.bold(a.onboarding_status)}`);
+	console.log(`  Charges enabled:    ${a.charges_enabled ? pc.green("yes") : pc.yellow("no")}`);
+	console.log(`  Payouts enabled:    ${a.payouts_enabled ? pc.green("yes") : pc.yellow("no")}`);
+	console.log(`  Country:            ${a.country ?? pc.dim("—")}`);
+	console.log(`  Default fee:        ${a.default_platform_fee_bps === null ? pc.dim("none") : `${a.default_platform_fee_bps} bps (${(a.default_platform_fee_bps / 100).toFixed(2)}%)`}`);
+}
+async function paymentsSetupCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba payments setup"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		printAccount((await adminWrite("POST", `/projects/${projectId}/payments/accounts`, {
+			...input.country ? { country: input.country } : {},
+			...input.email ? { email: input.email } : {}
+		})).data);
+		console.log();
+		const link = await adminWrite("POST", `/projects/${projectId}/payments/accounts/link`);
+		console.log(pc.bold("  Open this URL to finish setting up payments:"));
+		console.log();
+		console.log(`  ${pc.cyan(link.data.url)}`);
+		console.log();
+		console.log(pc.dim("  Status updates automatically once setup completes."));
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsStatusCommand() {
+	console.log();
+	console.log(pc.bold("  amba payments status"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const res = await adminGet(`/projects/${projectId}/payments/accounts`);
+		if (!res.data.connected_account) {
+			console.log(pc.dim("  No payments account yet. Run `amba payments setup`."));
+			console.log();
+			return;
+		}
+		printAccount(res.data.connected_account);
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsSetFeeCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba payments set-fee"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		await adminWrite("PUT", `/projects/${projectId}/payments/config`, { default_platform_fee_bps: input.bps });
+		if (input.bps === null) console.log(pc.green("  ✓") + " Default platform fee cleared.");
+		else console.log(pc.green("  ✓") + ` Default platform fee set to ${input.bps} bps (${(input.bps / 100).toFixed(2)}%).`);
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsBalanceCommand() {
+	console.log();
+	console.log(pc.bold("  amba payments balance"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const res = await adminGet(`/projects/${projectId}/payments/balance`);
+		const fmt = (b) => `${(b.amount / 100).toFixed(2)} ${b.currency.toUpperCase()}`;
+		console.log(`  Available:  ${res.data.available.length ? res.data.available.map(fmt).join(", ") : pc.dim("—")}`);
+		console.log(`  Pending:    ${res.data.pending.length ? res.data.pending.map(fmt).join(", ") : pc.dim("—")}`);
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsPayoutsCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba payments payouts"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const res = await adminGet(`/projects/${projectId}/payments/payouts${input.limit ? `?limit=${input.limit}` : ""}`);
+		if (res.data.length === 0) {
+			console.log(pc.dim("  No payouts yet."));
+			console.log();
+			return;
+		}
+		for (const p of res.data) {
+			const arrival = (/* @__PURE__ */ new Date(p.arrival_date * 1e3)).toLocaleDateString();
+			console.log(`  ${pc.dim(p.id.padEnd(28))} ${(p.amount / 100).toFixed(2)} ${p.currency.toUpperCase().padEnd(4)} ${pc.dim(p.status.padEnd(12))} arrives ${arrival}`);
+		}
+		console.log();
 	} catch (err) {
 		handleError(err);
 	}
 }
 //#endregion
+//#region src/commands/monetization.ts
+/**
+* `amba monetization *` subcommands — CLI access to the monetization control
+* plane behind `/v1/admin/projects/:id/monetization/*`.
+*
+*   amba monetization plan     — three-way diff (declared vs adopted baseline
+*                                vs live provider) + store-floor preflight +
+*                                drift. READ-ONLY — previews; applies nothing.
+*   amba monetization drift    — out-of-band changes to Amba-managed objects.
+*   amba monetization export   — snapshot the live config to a declarative
+*                                bundle (the `monetization` section), to stdout
+*                                or a file.
+*   amba monetization adopt    — record the live config as the managed baseline
+*                                so the next plan is a no-op. Writes ONLY Amba's
+*                                own state — never the provider. Idempotent.
+*   amba monetization apply    — push the declared config to the provider.
+*                                ADDITIVE only: create entitlements/offerings/
+*                                packages/paywall-drafts + attach products.
+*                                Refuses if the provider drifted since the plan;
+*                                never does destructive changes.
+*
+* Project is resolved via `loadProjectConfig` — same pattern as the other
+* project-scoped CLI commands.
+*/
+/**
+* Authenticated write helper (POST). Mirrors the `adminWrite` in
+* `commands/billing.ts` — kept local so the api-client public surface doesn't
+* grow a generic POST.
+*/
+async function adminPost(path, body) {
+	const token = await resolveBearerToken();
+	const url = `${process.env["AMBA_API_URL"] ?? "https://api.amba.dev"}/v1/admin${path}`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json",
+			"User-Agent": "amba-cli/0.1.1"
+		},
+		body: body === void 0 ? void 0 : JSON.stringify(body)
+	});
+	if (!res.ok) {
+		let message = `API request failed: ${res.status} ${res.statusText}`;
+		let code;
+		try {
+			const errorBody = await res.json();
+			if (errorBody.error?.message) {
+				message = errorBody.error.message;
+				code = errorBody.error.code;
+			}
+		} catch {}
+		throw new ApiClientError(message, res.status, code);
+	}
+	return await res.json();
+}
+function header(title) {
+	console.log();
+	console.log(pc.bold(`  amba monetization ${title}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+}
+async function monetizationPlanCommand() {
+	const { projectId } = await loadProjectConfig();
+	header("plan");
+	const plan = (await adminGet(`/projects/${projectId}/monetization/plan`)).data;
+	if (plan.clean) {
+		console.log(pc.green("  ✓") + " No changes — declared config matches the live provider.");
+		console.log();
+		return;
+	}
+	if (plan.ops.length > 0) {
+		console.log(pc.bold("  Pending operations (preview — nothing is applied):"));
+		for (const op of plan.ops) console.log(`    ${pc.cyan(op.op.padEnd(12))} ${pc.bold(op.object_type)} ${op.identifier}  ${pc.dim(`[${op.status}]`)}`);
+		console.log();
+	}
+	if (plan.store_floor.length > 0) {
+		console.log(pc.yellow("  Store-floor preflight — referenced products missing in the provider:"));
+		for (const sf of plan.store_floor) console.log(`    ${pc.bold(sf.product_key)} → ${sf.store_identifier} (${sf.store})`);
+		console.log();
+	}
+	if (plan.drift.length > 0) {
+		console.log(pc.yellow("  Drift — managed objects changed out-of-band in the provider:"));
+		for (const d of plan.drift) console.log(`    ${pc.bold(d.object_type)} ${d.identifier}`);
+		console.log();
+	}
+}
+async function monetizationDriftCommand() {
+	const { projectId } = await loadProjectConfig();
+	header("drift");
+	const data = (await adminGet(`/projects/${projectId}/monetization/drift`)).data;
+	if (!data.has_drift) {
+		console.log(pc.green("  ✓") + " No drift — managed config matches the live provider.");
+		console.log();
+		return;
+	}
+	console.log(pc.yellow("  Drift detected:"));
+	for (const d of data.drift) console.log(`    ${pc.bold(d.object_type)} ${d.identifier}`);
+	console.log();
+}
+async function monetizationExportCommand(options = {}) {
+	const { projectId } = await loadProjectConfig();
+	const bundle = {
+		version: 1,
+		monetization: (await adminGet(`/projects/${projectId}/monetization/export`)).data.monetization
+	};
+	const json = JSON.stringify(bundle, null, 2);
+	if (options.file) {
+		await writeFile(resolve(options.file), json + "\n", "utf-8");
+		console.log();
+		console.log(pc.green("  ✓") + ` Wrote live monetization config to ${pc.cyan(options.file)}.`);
+		console.log();
+	} else console.log(json);
+}
+async function monetizationAdoptCommand(options = {}) {
+	const { projectId } = await loadProjectConfig();
+	header("adopt");
+	if (!options.all) {
+		console.log("  ✗ Pass --all to adopt the entire live config as the managed baseline.");
+		process.exit(1);
+	}
+	const d = (await adminPost(`/projects/${projectId}/monetization/adopt`, { adopt_all: true })).data;
+	console.log(pc.green("  ✓") + ` Adopted ${d.adopted} object(s) as the managed baseline ` + pc.dim(`(${d.entitlements} entitlements · ${d.products} products · ${d.offerings} offerings · ${d.packages} packages · ${d.paywalls} paywalls)`));
+	console.log(pc.dim("    The next `amba monetization plan` is now a clean no-op."));
+	console.log();
+}
+async function monetizationApplyCommand(options = {}) {
+	const { projectId } = await loadProjectConfig();
+	header("apply");
+	const plan = (await adminGet(`/projects/${projectId}/monetization/plan`)).data;
+	if (plan.store_floor.length > 0) {
+		console.log(pc.yellow("  Store floor not satisfied — these products must exist in the provider first:"));
+		for (const sf of plan.store_floor) console.log(`    ${pc.bold(sf.product_key)} → ${sf.store_identifier} (${sf.store})`);
+		console.log();
+		console.log("  ✗ Configure these in the store, then run plan + apply again.");
+		process.exit(1);
+	}
+	if (plan.clean) {
+		console.log(pc.green("  ✓") + " Nothing to apply — declared config matches the provider.");
+		console.log();
+		return;
+	}
+	if (options.reconcile && options.reconcile !== "amba" && options.reconcile !== "adopt") {
+		console.log(pc.red("  ✗") + " --reconcile must be 'amba' or 'adopt'.");
+		process.exit(1);
+	}
+	const body = { plan_hash: plan.plan_hash };
+	if (options.confirm) body["confirm"] = plan.plan_hash;
+	if (options.allowDetachLive) body["allow_detach_live"] = true;
+	if (options.reconcile) body["reconcile"] = options.reconcile;
+	let res;
+	try {
+		res = await adminPost(`/projects/${projectId}/monetization/apply`, body);
+	} catch (err) {
+		if (err instanceof ApiClientError && err.errorCode === "MONETIZATION_CONFIRM_REQUIRED") {
+			console.log(pc.yellow("  ⚠ This plan includes gated destructive operation(s) — nothing was applied."));
+			console.log(pc.dim("    Review the plan, then re-run with --confirm to execute the gated ops:"));
+			console.log(`    ${pc.cyan("amba monetization apply --confirm")}`);
+			console.log();
+			process.exit(1);
+		}
+		if (err instanceof ApiClientError && err.errorCode === "MONETIZATION_INVARIANT") {
+			console.log(pc.red("  ✗ Blocked by the ordering invariant — nothing was applied:"));
+			console.log(pc.dim(`    ${err.message}`));
+			console.log();
+			process.exit(1);
+		}
+		throw err;
+	}
+	const d = res.data;
+	if (d.sandbox_stage?.ran) {
+		const tag = d.sandbox_stage.passed ? pc.green("✓ sandbox passed") : pc.red("✗ sandbox failed");
+		console.log(`  ${tag} ` + pc.dim(d.sandbox_stage.detail));
+		console.log();
+	}
+	if (d.status === "succeeded") console.log(pc.green("  ✓") + ` Applied ${d.applied} change(s) to the provider ` + pc.dim(`(${d.skipped_existing} already present, ${d.gated_applied} destructive)`));
+	else {
+		console.log(pc.red("  ✗") + ` Apply stopped after a failure (${d.applied} applied, ${d.failed} failed).` + (d.stopped_at ? ` Stopped at: ${d.stopped_at}` : ""));
+		const failed = d.results.find((r) => r.status === "failed");
+		if (failed?.error) console.log(pc.dim(`    ${failed.error}`));
+	}
+	if (d.gated.length > 0) {
+		console.log();
+		console.log(pc.yellow("  Gated (destructive — run with --confirm to execute):"));
+		for (const g of d.gated) console.log(`    ${pc.bold(g.op.op)} ${g.op.object_type} ${g.op.identifier}`);
+	}
+	if (d.refused.length > 0) {
+		console.log();
+		console.log(pc.yellow("  Not applicable via API (do these in the provider dashboard):"));
+		for (const r of d.refused) console.log(`    ${pc.bold(r.op.op)} ${r.op.object_type} ${r.op.identifier}`);
+	}
+	console.log();
+	if (d.status !== "succeeded") process.exit(1);
+}
+//#endregion
 //#region src/commands/collections.ts
 /**
 * `amba collections ...` — thin shells over the admin collection routes.
@@ -6334,8 +7301,22 @@ const PG_TYPE_TO_TS = {
 	jsonb: "unknown",
 	json: "unknown"
 };
+const ARRAY_UDT_TO_TS = {
+	_text: "string",
+	_varchar: "string",
+	_uuid: "string",
+	_int4: "number",
+	_int8: "number",
+	_int2: "number",
+	_numeric: "number",
+	_float8: "number",
+	_float4: "number",
+	_bool: "boolean"
+};
 function tsTypeForColumn(col) {
-	const base = PG_TYPE_TO_TS[col.data_type] ?? "unknown";
+	let base;
+	if (col.data_type === "ARRAY") base = `${col.udt_name ? ARRAY_UDT_TO_TS[col.udt_name] ?? "unknown" : "unknown"}[]`;
+	else base = PG_TYPE_TO_TS[col.data_type] ?? "unknown";
 	if (col.column_name === "deleted_at") return "string | null";
 	if (col.is_nullable === "YES") return `${base} | null`;
 	return base;
@@ -6885,9 +7866,351 @@ async function domainsListCommand() {
 	console.log();
 }
 //#endregion
+//#region src/commands/iac.ts
+/**
+* `amba apply` / `amba diff` / `amba export` — declarative
+* infrastructure-as-code for a project's reusable configuration.
+*
+* A declarative bundle (default `amba.config.json`) captures the entities a
+* developer hand-builds once and wants to stand up identically elsewhere:
+* remote configs, collection schemas, content libraries + items, currencies,
+* achievements, streaks, challenges, leaderboards, and xp_rules. It carries
+* CONFIGURATION ONLY — no secrets, no per-user data.
+*
+* These commands wrap the platform's promotion endpoints:
+*   GET  /v1/admin/projects/:p/promotion/export
+*   POST /v1/admin/projects/:p/promotion/import   (mode=skip_existing|merge)
+*
+*   - `amba export [file]`  writes the current project's bundle to disk.
+*   - `amba apply  [file]`  POSTs the local bundle to the import endpoint and
+*                           prints a `{ created, updated, skipped }` summary
+*                           per section (the server's authoritative result).
+*   - `amba diff   [file]`  shows what `apply` WOULD change without writing.
+*                           The import route has NO server-side dry-run, so
+*                           `diff` exports the current project and computes the
+*                           created/updated/skipped per section LOCALLY.
+*/
+/** Default declarative bundle filename when no `[file]` is passed. */
+const DEFAULT_BUNDLE_FILE = "amba.config.json";
+/** The ordered list of bundle sections + their natural-key field. */
+const BUNDLE_SECTIONS = [
+	{
+		key: "remote_configs",
+		naturalKey: "key"
+	},
+	{
+		key: "collections",
+		naturalKey: "name"
+	},
+	{
+		key: "currencies",
+		naturalKey: "code"
+	},
+	{
+		key: "achievements",
+		naturalKey: "key"
+	},
+	{
+		key: "streaks",
+		naturalKey: "key"
+	},
+	{
+		key: "leaderboards",
+		naturalKey: "name"
+	},
+	{
+		key: "xp_rules",
+		naturalKey: "name"
+	},
+	{
+		key: "challenges",
+		naturalKey: "name"
+	},
+	{
+		key: "content_libraries",
+		naturalKey: "name"
+	},
+	{
+		key: "monetization",
+		naturalKey: "key"
+	}
+];
+/**
+* Read + parse a declarative bundle from disk. JSON only — we deliberately
+* don't pull in a YAML dependency the CLI doesn't already ship (the package
+* has no YAML lib), so `.yaml`/`.yml` files are rejected with a clear hint
+* rather than silently mis-parsed.
+*/
+async function readBundleFile(file) {
+	const path = resolve(file);
+	if (/\.ya?ml$/i.test(path)) throw new Error(`YAML bundles are not supported. Convert ${file} to JSON (the bundle format is plain JSON).`);
+	let raw;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch {
+		throw new Error(`Bundle file not found: ${file}. Run \`amba export\` to scaffold one from your current project.`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse ${file} as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Bundle in ${file} must be a JSON object with a \`version\` field.`);
+	const bundle = parsed;
+	if (typeof bundle["version"] !== "number") throw new Error(`Bundle in ${file} is missing a numeric \`version\` field. Re-export it with \`amba export\`.`);
+	return bundle;
+}
+/**
+* Index a section array by its natural key. Definitions missing the key (or
+* non-object entries) are skipped — they can't be matched and the server
+* will reject them on apply.
+*/
+function indexByNaturalKey(items, naturalKey) {
+	const out = /* @__PURE__ */ new Map();
+	if (!Array.isArray(items)) return out;
+	for (const item of items) {
+		if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+		const rec = item;
+		const k = rec[naturalKey];
+		if (typeof k !== "string" && typeof k !== "number") continue;
+		out.set(String(k), rec);
+	}
+	return out;
+}
+/**
+* Pure section-by-section diff of a desired bundle against the current
+* project's exported bundle. The classification MIRRORS the server's import
+* (`apps/api/src/lib/promotion-bundle.ts`) so `amba diff` agrees with what
+* `amba apply` will report:
+*   - created — natural key absent in current.
+*   - updated — natural key present AND `mode === 'merge'`. The server runs an
+*               UNCONDITIONAL update for every existing key in merge mode and
+*               increments `updated` — it does NOT compare field values, so we
+*               don't either (a local field comparison made `diff` under-report).
+*   - skipped — natural key present under `skip_existing`; OR an existing
+*               collection (always — collections are create-if-absent, never
+*               merged); OR a `remote_configs` row flagged `is_system: true`
+*               (the server always skips those before any existence check); OR
+*               a desired row with no valid natural key (can't be matched
+*               against the export, and the server import dedups by that key —
+*               so it is never a reliable create).
+*
+* Within one bundle section, the server walks rows sequentially and each
+* insert mutates the DB, so a SECOND row sharing a natural key already created
+* by an EARLIER row in the same section is seen as existing (→ skip under
+* skip_existing, update under merge) rather than created a second time. We
+* track already-seen keys per section to mirror that, so duplicate-keyed local
+* rows don't inflate the `created` total versus what `apply` does.
+*/
+function computeLocalDiff(desired, current, mode) {
+	const diff = {};
+	for (const { key, naturalKey } of BUNDLE_SECTIONS) {
+		const desiredItems = desired[key];
+		if (!Array.isArray(desiredItems) || desiredItems.length === 0) continue;
+		const currentIndex = indexByNaturalKey(current[key], naturalKey);
+		const section = {
+			created: 0,
+			updated: 0,
+			skipped: 0
+		};
+		const seen = /* @__PURE__ */ new Set();
+		for (const item of desiredItems) {
+			if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+			const rec = item;
+			if (key === "remote_configs" && rec["is_system"] === true) {
+				section.skipped++;
+				continue;
+			}
+			const k = rec[naturalKey];
+			const matchKey = typeof k === "string" || typeof k === "number" ? String(k) : null;
+			if (matchKey === null) {
+				section.skipped++;
+				continue;
+			}
+			const existing = currentIndex.has(matchKey) || seen.has(matchKey);
+			seen.add(matchKey);
+			if (!existing) {
+				section.created++;
+				continue;
+			}
+			if (key === "collections" || mode === "skip_existing") {
+				section.skipped++;
+				continue;
+			}
+			section.updated++;
+		}
+		diff[key] = section;
+	}
+	const monDiff = computeMonetizationLocalDiff(desired["monetization"], current["monetization"], mode);
+	if (monDiff) diff["monetization"] = monDiff;
+	return diff;
+}
+/**
+* Natural keys per monetization sub-collection. All key on `key` except the
+* package join, which is unique within an offering — but for diff purposes the
+* package counts roll into their owning offering, so only the four top-level
+* collections are counted here.
+*/
+const MONETIZATION_SUBSECTIONS = [
+	"entitlements",
+	"products",
+	"offerings",
+	"paywalls"
+];
+function computeMonetizationLocalDiff(desired, current, mode) {
+	if (desired === null || typeof desired !== "object" || Array.isArray(desired)) return null;
+	const desiredObj = desired;
+	const currentObj = current !== null && typeof current === "object" && !Array.isArray(current) ? current : {};
+	const section = {
+		created: 0,
+		updated: 0,
+		skipped: 0
+	};
+	let any = false;
+	for (const sub of MONETIZATION_SUBSECTIONS) {
+		const desiredItems = desiredObj[sub];
+		if (!Array.isArray(desiredItems) || desiredItems.length === 0) continue;
+		any = true;
+		const currentIndex = indexByNaturalKey(currentObj[sub], "key");
+		const seen = /* @__PURE__ */ new Set();
+		for (const item of desiredItems) {
+			if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+			const k = item["key"];
+			const matchKey = typeof k === "string" || typeof k === "number" ? String(k) : null;
+			if (matchKey === null) {
+				section.skipped++;
+				continue;
+			}
+			const existing = currentIndex.has(matchKey) || seen.has(matchKey);
+			seen.add(matchKey);
+			if (!existing) section.created++;
+			else if (mode === "skip_existing") section.skipped++;
+			else section.updated++;
+		}
+	}
+	return any ? section : null;
+}
+/** Roll a per-section diff up into grand totals across every section. */
+function summarizeDiff(diff) {
+	return Object.values(diff).reduce((acc, s) => ({
+		created: acc.created + s.created,
+		updated: acc.updated + s.updated,
+		skipped: acc.skipped + s.skipped
+	}), {
+		created: 0,
+		updated: 0,
+		skipped: 0
+	});
+}
+function renderSummary(summary, verb) {
+	let created = 0;
+	let updated = 0;
+	let skipped = 0;
+	const sections = Object.keys(summary);
+	if (sections.length === 0) console.log(pc.dim("  Nothing to " + verb + " — bundle is empty."));
+	for (const section of sections) {
+		const s = summary[section];
+		created += s.created;
+		updated += s.updated;
+		skipped += s.skipped;
+		console.log(`  ${pc.bold(section)}  ${pc.green(`${s.created} created`)} · ${pc.cyan(`${s.updated} updated`)} · ` + pc.dim(`${s.skipped} skipped`));
+	}
+	console.log();
+	console.log(pc.dim(`  Total: ${created} created · ${updated} updated · ${skipped} skipped`));
+}
+/**
+* `amba export [file]` — write the current project's declarative bundle to
+* disk so it can be checked in, diffed, and re-applied.
+*/
+async function exportConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
+	const projectId = await requireProjectId(process.cwd(), options.project);
+	const path = resolve(file);
+	console.log();
+	console.log(pc.bold(`  amba export ${pc.cyan(file)}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	console.log(pc.dim(`  Project: ${projectId}`));
+	console.log(pc.dim("  Fetching current configuration…"));
+	const bundle = (await exportPromotionBundle(projectId)).data;
+	await writeFile(path, JSON.stringify(bundle, null, 2) + "\n", "utf-8");
+	const sectionCount = BUNDLE_SECTIONS.reduce((sum, { key }) => {
+		const v = bundle[key];
+		if (Array.isArray(v)) return sum + v.length;
+		if (key === "monetization" && v !== null && typeof v === "object") {
+			const m = v;
+			return sum + MONETIZATION_SUBSECTIONS.reduce((n, sub) => n + (Array.isArray(m[sub]) ? m[sub].length : 0), 0);
+		}
+		return sum;
+	}, 0);
+	console.log();
+	console.log(pc.green("  ✓") + ` Wrote ${pc.cyan(file)} (${sectionCount} definitions).`);
+	console.log(pc.dim("    Edit it, then ") + pc.cyan("amba diff") + pc.dim(" to preview and ") + pc.cyan("amba apply") + pc.dim(" to apply."));
+	console.log();
+}
+/**
+* `amba apply [file]` — read a local declarative bundle and POST it to the
+* import endpoint. Prints the server's authoritative `{ created, updated,
+* skipped }` per section.
+*/
+async function applyConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
+	const projectId = await requireProjectId(process.cwd(), options.project);
+	const mode = options.mode ?? "skip_existing";
+	const bundle = await readBundleFile(file);
+	console.log();
+	console.log(pc.bold(`  amba apply ${pc.cyan(file)}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	console.log(pc.dim(`  Project: ${projectId}`));
+	console.log(pc.dim(`  Mode:    ${mode}`));
+	console.log(pc.dim("  Applying…"));
+	console.log();
+	let res;
+	try {
+		res = await importPromotionBundle(projectId, bundle, mode);
+	} catch (err) {
+		if (err instanceof ApiClientError && (err.statusCode === 400 || err.statusCode === 422)) throw new Error(`${err.message}\n  → Re-export a fresh bundle with \`amba export\` if this was hand-edited.`);
+		throw err;
+	}
+	renderSummary(res.data.summary, "apply");
+	console.log();
+}
+/**
+* `amba diff [file]` — show what `apply` WOULD change without writing.
+*
+* The import route has no server-side dry-run, so this fetches the current
+* project's exported bundle and computes the diff LOCALLY. Output mirrors the
+* `apply` summary shape so the two read identically.
+*/
+async function diffConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
+	const projectId = await requireProjectId(process.cwd(), options.project);
+	const mode = options.mode ?? "skip_existing";
+	const desired = await readBundleFile(file);
+	console.log();
+	console.log(pc.bold(`  amba diff ${pc.cyan(file)}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	console.log(pc.dim(`  Project: ${projectId}`));
+	console.log(pc.dim(`  Mode:    ${mode}`));
+	console.log(pc.dim("  (computed locally — the import route has no server dry-run)"));
+	console.log(pc.dim("  Fetching current configuration…"));
+	console.log();
+	const diff = computeLocalDiff(desired, (await exportPromotionBundle(projectId)).data, mode);
+	renderSummary(diff, "change");
+	const totals = summarizeDiff(diff);
+	console.log();
+	if (totals.created > 0 || totals.updated > 0) console.log(pc.dim("  Run ") + pc.cyan(`amba apply ${file}`) + pc.dim(" to apply these changes."));
+	else if (totals.skipped > 0) if (mode === "skip_existing") {
+		console.log(pc.green("  ✓") + " apply would make no changes (skip_existing leaves existing entities untouched).");
+		console.log(pc.dim("    Skipped entities are NOT compared — re-run with ") + pc.cyan("--mode merge") + pc.dim(" to overwrite them, or `amba export` to see current values."));
+	} else console.log(pc.green("  ✓") + " apply would make no changes.");
+	else console.log(pc.green("  ✓") + " No changes — nothing in the bundle to apply.");
+	console.log();
+}
+//#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("0.1.0");
+program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.0.4");
 program.option("--token <pat>", "Use a Personal Access Token for headless / CI / agent use (overrides ~/.amba/credentials.json + AMBA_PAT env)");
 program.hook("preAction", (thisCommand) => {
 	setBearerOverride(resolveTokenSource({
@@ -7029,8 +8352,8 @@ program.command("schema").description("Schema export commands").command("export"
 	}));
 });
 const functions = program.command("functions").description("Customer serverless functions deployed to the edge");
-functions.command("deploy <file>").description("Bundle a function file and deploy to the dispatch namespace").option("--name <name>", "Function name (default: filename without extension)").option("--dry-run", "Bundle and report size without uploading").option("--rate-limit-window <duration>", "Rate-limit window: 60s | 5m | 1h").option("--rate-limit-max <int>", "Rate-limit max requests per window", (v) => Number.parseInt(v, 10)).option("--rate-limit-key <kind>", "Rate-limit bucket key: user_id | ip").action(async (file, opts) => {
-	await runAction(() => functionsDeployCommand(file, opts));
+functions.command("deploy <target>").description("Bundle a function (a single file OR a directory) and deploy to the dispatch namespace. A directory resolves its entry by convention (index.ts/js/mjs) or via --entry.").option("--name <name>", "Function name (default: file name without extension, or the directory leaf name)").option("--entry <file>", "Entry file when <target> is a directory (relative to it). Default: index.ts/js/mjs.").option("--dry-run", "Bundle and report size without uploading").option("--rate-limit-window <duration>", "Rate-limit window: 60s | 5m | 1h").option("--rate-limit-max <int>", "Rate-limit max requests per window", (v) => Number.parseInt(v, 10)).option("--rate-limit-key <kind>", "Rate-limit bucket key: user_id | ip").option("--public", "Deploy WITHOUT the X-Api-Key gate so external webhook senders can call it. You MUST verify the webhook signature in your handler. Default: private.").action(async (target, opts) => {
+	await runAction(() => functionsDeployCommand(target, opts));
 });
 functions.command("list").description("List active functions for the current project").action(async () => {
 	await runAction(functionsListCommand);
@@ -7047,11 +8370,12 @@ functions.command("dev <file>").description("Run a local dev server for your fun
 		noWatch: opts.watch === false
 	}));
 });
-functions.command("logs <name>").description("Stream log events for a deployed function").option("--since <iso>", "Start of the time range (default: 1 hour ago)").option("--until <iso>", "End of the time range (default: now). Ignored on --tail.").option("--limit <n>", "Max events per fetch (default 100, max 1000)", (v) => parseInt(v, 10)).option("--tail", "Follow new events; polls every 3s. Ctrl+C to stop.").option("--follow", "Alias for --tail (kept for backwards compatibility with v1 log commands).").option("--json", "NDJSON output to stdout (one event per line)").action(async (name, opts) => {
+functions.command("logs <name>").description("Stream log events for a deployed function").option("--since <iso>", "Start of the time range (default: 1 hour ago)").option("--until <iso>", "End of the time range (default: now). Ignored on --tail.").option("--limit <n>", "Max events per fetch (default 100, max 1000)", (v) => parseInt(v, 10)).option("--request-id <id>", "Only show events whose logs mention this request id (e.g. r_...). Works with --tail.").option("--tail", "Follow new events; polls every 3s. Ctrl+C to stop.").option("--follow", "Alias for --tail (kept for backwards compatibility with v1 log commands).").option("--json", "NDJSON output to stdout (one event per line)").action(async (name, opts) => {
 	await runAction(() => functionsLogsCommand(name, {
 		since: opts.since,
 		until: opts.until,
 		limit: opts.limit,
+		requestId: opts.requestId,
 		tail: opts.tail || opts.follow,
 		json: opts.json
 	}));
@@ -7114,6 +8438,60 @@ billing.command("set-ceiling <amount>").description("Cap the monthly bill at <am
 	}
 	await runAction(() => billingSetCeilingCommand({ ceiling }));
 });
+const payments = program.command("payments").description("Accept payments in your app (Amba is the rail; your app is the seller)");
+payments.command("setup").description("Create the connected payments account and print the hosted onboarding URL").option("--country <code>", "Two-letter ISO country code for the seller (e.g. US)").option("--email <email>", "Contact email for the connected account").action(async (opts) => {
+	if (opts.country && !/^[A-Za-z]{2}$/.test(opts.country)) {
+		console.log("  ✗ --country must be a two-letter ISO code (e.g. US)");
+		process.exit(1);
+	}
+	await runAction(() => paymentsSetupCommand({
+		country: opts.country ? opts.country.toUpperCase() : void 0,
+		email: opts.email
+	}));
+});
+payments.command("status").description("Show onboarding stage + whether charges/payouts are enabled").action(async () => {
+	await runAction(paymentsStatusCommand);
+});
+payments.command("set-fee <bps>").description("Set the default platform fee in basis points (250 = 2.5%), or 'off' to clear").action(async (bps) => {
+	let value;
+	if (bps.toLowerCase() === "off" || bps === "") value = null;
+	else {
+		const parsed = Number(bps);
+		if (!Number.isInteger(parsed) || parsed < 0 || parsed > 1e4) {
+			console.log("  ✗ bps must be an integer between 0 and 10000, or \"off\"");
+			process.exit(1);
+		}
+		value = parsed;
+	}
+	await runAction(() => paymentsSetFeeCommand({ bps: value }));
+});
+payments.command("balance").description("Show the connected account's available and pending balance").action(async () => {
+	await runAction(paymentsBalanceCommand);
+});
+payments.command("payouts").description("List recent payouts to the seller bank account").option("--limit <n>", "How many payouts to show (default 10)").action(async (opts) => {
+	const limit = opts.limit ? Number(opts.limit) : void 0;
+	if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1 || limit > 100)) {
+		console.log("  ✗ --limit must be an integer between 1 and 100");
+		process.exit(1);
+	}
+	await runAction(() => paymentsPayoutsCommand({ limit }));
+});
+const monetization = program.command("monetization").description("Monetization control plane: plan, drift, export, adopt, and apply your subscription config as Infrastructure-as-Code.");
+monetization.command("plan").description("Preview the three-way diff (declared vs adopted vs live) + store-floor + drift").action(async () => {
+	await runAction(monetizationPlanCommand);
+});
+monetization.command("drift").description("Show managed objects changed out-of-band in the provider").action(async () => {
+	await runAction(monetizationDriftCommand);
+});
+monetization.command("export").description("Snapshot the live monetization config to a declarative bundle (stdout or --file)").option("--file <path>", "Write the bundle to this file instead of stdout").action(async (opts) => {
+	await runAction(() => monetizationExportCommand(opts));
+});
+monetization.command("adopt").description("Record the live config as the managed baseline (writes Amba state only; idempotent)").option("--all", "Adopt the entire live config").action(async (opts) => {
+	await runAction(() => monetizationAdoptCommand(opts));
+});
+monetization.command("apply").description("Apply the declared config to the provider. Additive ops (create entitlements/offerings/packages/paywall-drafts + attach products) apply automatically; destructive ops (detach/archive/remove) need --confirm.").option("--confirm", "Confirm and execute the gated destructive ops (detach/archive/remove). Without it they are reported but not run.").option("--allow-detach-live", "Accept detaching a product a live customer currently resolves (otherwise refused).").option("--reconcile <mode>", "Out-of-band drift mode: 'amba' (default) or 'adopt'.").action(async (opts) => {
+	await runAction(() => monetizationApplyCommand(opts));
+});
 const collections = program.command("collections").description("Customer collections (schema-first Postgres in each tenant database)");
 collections.command("create <name>").description("Create a collection with the given fields").option("--field <spec>", "Field spec: name:type[:nullable] (e.g. user_id:uuid, parsed:jsonb:nullable). Repeatable.", (val, prev) => [...prev ?? [], val], []).option("--index <spec>", "Index spec: \"col1 [asc|desc], col2 [asc|desc]\". Repeatable.", (val, prev) => [...prev ?? [], val], []).action(async (name, opts) => {
 	await runAction(() => collectionsCreateCommand(name, opts));
@@ -7199,6 +8577,29 @@ aiProviders.command("list").description("List registered AI providers for the cu
 aiProviders.command("delete <provider>").description("Remove a provider registration (refuses if active prompts reference it)").action(async (provider) => {
 	await runAction(() => aiProvidersDeleteCommand(provider));
 });
+function parseImportMode(raw) {
+	if (raw === void 0) return "skip_existing";
+	if (raw === "merge" || raw === "skip_existing") return raw;
+	console.log("  ✗ --mode must be \"skip_existing\" (default) or \"merge\"");
+	process.exit(1);
+}
+program.command("export [file]").description("Write the current project's declarative configuration bundle to disk (default: amba.config.json)").option("--project <id>", "Project id (overrides .env.local)").action(async (file, opts) => {
+	await runAction(() => exportConfigCommand(file, { project: opts.project }));
+});
+program.command("diff [file]").description("Show what `amba apply` WOULD change (created/updated/skipped per section) without writing. Computed locally by exporting the current project and comparing — the import route has no server dry-run.").option("--project <id>", "Project id (overrides .env.local)").option("--mode <mode>", "'skip_existing' (default) or 'merge'").action(async (file, opts) => {
+	const mode = parseImportMode(opts.mode);
+	await runAction(() => diffConfigCommand(file, {
+		project: opts.project,
+		mode
+	}));
+});
+program.command("apply [file]").description("Apply a declarative configuration bundle (default: amba.config.json) — JSON only. Prints { created, updated, skipped } per section.").option("--project <id>", "Project id (overrides .env.local)").option("--mode <mode>", "'skip_existing' (default — no-op on conflict) or 'merge' (refresh existing definitions)").action(async (file, opts) => {
+	const mode = parseImportMode(opts.mode);
+	await runAction(() => applyConfigCommand(file, {
+		project: opts.project,
+		mode
+	}));
+});
 program.parse();
 //#endregion
 export {};