@capxul/sandbox 1.0.0-alpha.1

package/dist/main.mjs

@@ -0,0 +1,848 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { cancel, confirm, intro, isCancel, note, outro, select, spinner, text } from "@clack/prompts";
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region \0rolldown/runtime.js
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
+//#region ../../packages/backend/scripts/publishable-key-minting.ts
+var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
+	const fs = __require("fs");
+	const path = __require("path");
+	const os = __require("os");
+	const crypto = __require("crypto");
+	const TIPS = [
+		"◈ encrypted .env [www.dotenvx.com]",
+		"◈ secrets for agents [www.dotenvx.com]",
+		"⌁ auth for agents [www.vestauth.com]",
+		"⌘ custom filepath { path: '/custom/path/.env' }",
+		"⌘ enable debugging { debug: true }",
+		"⌘ override existing { override: true }",
+		"⌘ suppress logs { quiet: true }",
+		"⌘ multiple files { path: ['.env.local', '.env'] }"
+	];
+	function _getRandomTip() {
+		return TIPS[Math.floor(Math.random() * TIPS.length)];
+	}
+	function parseBoolean(value) {
+		if (typeof value === "string") return ![
+			"false",
+			"0",
+			"no",
+			"off",
+			""
+		].includes(value.toLowerCase());
+		return Boolean(value);
+	}
+	function supportsAnsi() {
+		return process.stdout.isTTY;
+	}
+	function dim(text) {
+		return supportsAnsi() ? `\x1b[2m${text}\x1b[0m` : text;
+	}
+	const LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+	function parse(src) {
+		const obj = {};
+		let lines = src.toString();
+		lines = lines.replace(/\r\n?/gm, "\n");
+		let match;
+		while ((match = LINE.exec(lines)) != null) {
+			const key = match[1];
+			let value = match[2] || "";
+			value = value.trim();
+			const maybeQuote = value[0];
+			value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+			if (maybeQuote === "\"") {
+				value = value.replace(/\\n/g, "\n");
+				value = value.replace(/\\r/g, "\r");
+			}
+			obj[key] = value;
+		}
+		return obj;
+	}
+	function _parseVault(options) {
+		options = options || {};
+		const vaultPath = _vaultPath(options);
+		options.path = vaultPath;
+		const result = DotenvModule.configDotenv(options);
+		if (!result.parsed) {
+			const err = /* @__PURE__ */ new Error(`MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`);
+			err.code = "MISSING_DATA";
+			throw err;
+		}
+		const keys = _dotenvKey(options).split(",");
+		const length = keys.length;
+		let decrypted;
+		for (let i = 0; i < length; i++) try {
+			const attrs = _instructions(result, keys[i].trim());
+			decrypted = DotenvModule.decrypt(attrs.ciphertext, attrs.key);
+			break;
+		} catch (error) {
+			if (i + 1 >= length) throw error;
+		}
+		return DotenvModule.parse(decrypted);
+	}
+	function _warn(message) {
+		console.error(`⚠ ${message}`);
+	}
+	function _debug(message) {
+		console.log(`┆ ${message}`);
+	}
+	function _log(message) {
+		console.log(`◇ ${message}`);
+	}
+	function _dotenvKey(options) {
+		if (options && options.DOTENV_KEY && options.DOTENV_KEY.length > 0) return options.DOTENV_KEY;
+		if (process.env.DOTENV_KEY && process.env.DOTENV_KEY.length > 0) return process.env.DOTENV_KEY;
+		return "";
+	}
+	function _instructions(result, dotenvKey) {
+		let uri;
+		try {
+			uri = new URL(dotenvKey);
+		} catch (error) {
+			if (error.code === "ERR_INVALID_URL") {
+				const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development");
+				err.code = "INVALID_DOTENV_KEY";
+				throw err;
+			}
+			throw error;
+		}
+		const key = uri.password;
+		if (!key) {
+			const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: Missing key part");
+			err.code = "INVALID_DOTENV_KEY";
+			throw err;
+		}
+		const environment = uri.searchParams.get("environment");
+		if (!environment) {
+			const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: Missing environment part");
+			err.code = "INVALID_DOTENV_KEY";
+			throw err;
+		}
+		const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`;
+		const ciphertext = result.parsed[environmentKey];
+		if (!ciphertext) {
+			const err = /* @__PURE__ */ new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`);
+			err.code = "NOT_FOUND_DOTENV_ENVIRONMENT";
+			throw err;
+		}
+		return {
+			ciphertext,
+			key
+		};
+	}
+	function _vaultPath(options) {
+		let possibleVaultPath = null;
+		if (options && options.path && options.path.length > 0) if (Array.isArray(options.path)) {
+			for (const filepath of options.path) if (fs.existsSync(filepath)) possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
+		} else possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
+		else possibleVaultPath = path.resolve(process.cwd(), ".env.vault");
+		if (fs.existsSync(possibleVaultPath)) return possibleVaultPath;
+		return null;
+	}
+	function _resolveHome(envPath) {
+		return envPath[0] === "~" ? path.join(os.homedir(), envPath.slice(1)) : envPath;
+	}
+	function _configVault(options) {
+		const debug = parseBoolean(process.env.DOTENV_CONFIG_DEBUG || options && options.debug);
+		const quiet = parseBoolean(process.env.DOTENV_CONFIG_QUIET || options && options.quiet);
+		if (debug || !quiet) _log("loading env from encrypted .env.vault");
+		const parsed = DotenvModule._parseVault(options);
+		let processEnv = process.env;
+		if (options && options.processEnv != null) processEnv = options.processEnv;
+		DotenvModule.populate(processEnv, parsed, options);
+		return { parsed };
+	}
+	function configDotenv(options) {
+		const dotenvPath = path.resolve(process.cwd(), ".env");
+		let encoding = "utf8";
+		let processEnv = process.env;
+		if (options && options.processEnv != null) processEnv = options.processEnv;
+		let debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || options && options.debug);
+		let quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || options && options.quiet);
+		if (options && options.encoding) encoding = options.encoding;
+		else if (debug) _debug("no encoding is specified (UTF-8 is used by default)");
+		let optionPaths = [dotenvPath];
+		if (options && options.path) if (!Array.isArray(options.path)) optionPaths = [_resolveHome(options.path)];
+		else {
+			optionPaths = [];
+			for (const filepath of options.path) optionPaths.push(_resolveHome(filepath));
+		}
+		let lastError;
+		const parsedAll = {};
+		for (const path of optionPaths) try {
+			const parsed = DotenvModule.parse(fs.readFileSync(path, { encoding }));
+			DotenvModule.populate(parsedAll, parsed, options);
+		} catch (e) {
+			if (debug) _debug(`failed to load ${path} ${e.message}`);
+			lastError = e;
+		}
+		const populated = DotenvModule.populate(processEnv, parsedAll, options);
+		debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || debug);
+		quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || quiet);
+		if (debug || !quiet) {
+			const keysCount = Object.keys(populated).length;
+			const shortPaths = [];
+			for (const filePath of optionPaths) try {
+				const relative = path.relative(process.cwd(), filePath);
+				shortPaths.push(relative);
+			} catch (e) {
+				if (debug) _debug(`failed to load ${filePath} ${e.message}`);
+				lastError = e;
+			}
+			_log(`injected env (${keysCount}) from ${shortPaths.join(",")} ${dim(`// tip: ${_getRandomTip()}`)}`);
+		}
+		if (lastError) return {
+			parsed: parsedAll,
+			error: lastError
+		};
+		else return { parsed: parsedAll };
+	}
+	function config(options) {
+		if (_dotenvKey(options).length === 0) return DotenvModule.configDotenv(options);
+		const vaultPath = _vaultPath(options);
+		if (!vaultPath) {
+			_warn(`you set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}`);
+			return DotenvModule.configDotenv(options);
+		}
+		return DotenvModule._configVault(options);
+	}
+	function decrypt(encrypted, keyStr) {
+		const key = Buffer.from(keyStr.slice(-64), "hex");
+		let ciphertext = Buffer.from(encrypted, "base64");
+		const nonce = ciphertext.subarray(0, 12);
+		const authTag = ciphertext.subarray(-16);
+		ciphertext = ciphertext.subarray(12, -16);
+		try {
+			const aesgcm = crypto.createDecipheriv("aes-256-gcm", key, nonce);
+			aesgcm.setAuthTag(authTag);
+			return `${aesgcm.update(ciphertext)}${aesgcm.final()}`;
+		} catch (error) {
+			const isRange = error instanceof RangeError;
+			const invalidKeyLength = error.message === "Invalid key length";
+			const decryptionFailed = error.message === "Unsupported state or unable to authenticate data";
+			if (isRange || invalidKeyLength) {
+				const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: It must be 64 characters long (or more)");
+				err.code = "INVALID_DOTENV_KEY";
+				throw err;
+			} else if (decryptionFailed) {
+				const err = /* @__PURE__ */ new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
+				err.code = "DECRYPTION_FAILED";
+				throw err;
+			} else throw error;
+		}
+	}
+	function populate(processEnv, parsed, options = {}) {
+		const debug = Boolean(options && options.debug);
+		const override = Boolean(options && options.override);
+		const populated = {};
+		if (typeof parsed !== "object") {
+			const err = /* @__PURE__ */ new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
+			err.code = "OBJECT_REQUIRED";
+			throw err;
+		}
+		for (const key of Object.keys(parsed)) if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
+			if (override === true) {
+				processEnv[key] = parsed[key];
+				populated[key] = parsed[key];
+			}
+			if (debug) if (override === true) _debug(`"${key}" is already defined and WAS overwritten`);
+			else _debug(`"${key}" is already defined and was NOT overwritten`);
+		} else {
+			processEnv[key] = parsed[key];
+			populated[key] = parsed[key];
+		}
+		return populated;
+	}
+	const DotenvModule = {
+		configDotenv,
+		_configVault,
+		_parseVault,
+		config,
+		decrypt,
+		parse,
+		populate
+	};
+	module.exports.configDotenv = DotenvModule.configDotenv;
+	module.exports._configVault = DotenvModule._configVault;
+	module.exports._parseVault = DotenvModule._parseVault;
+	module.exports.config = DotenvModule.config;
+	module.exports.decrypt = DotenvModule.decrypt;
+	module.exports.parse = DotenvModule.parse;
+	module.exports.populate = DotenvModule.populate;
+	module.exports = DotenvModule;
+})))();
+const backendRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const repoRoot = resolve(backendRoot, "..", "..");
+const defaultOperatorSecretsPath = resolve(homedir(), ".config/capxul/secrets.env");
+const DEFAULT_APP_NAME = "Customer Next.js Quickstart";
+const DEFAULT_ALLOWED_ORIGIN = "http://localhost:3000";
+const DEFAULT_HANDOFF_PATH = resolve(homedir(), ".config/capxul/quickstart-handoffs/customer-nextjs-quickstart.md");
+const CANONICAL_QUICKSTART_DEPLOYMENT = {
+	deployment: "dev:glad-jaguar-154",
+	convexUrl: "https://glad-jaguar-154.convex.cloud",
+	convexSiteUrl: "https://glad-jaguar-154.convex.site"
+};
+function loadOperatorEnv(sourceEnv = process.env) {
+	const env = { ...sourceEnv };
+	const envFiles = [defaultOperatorSecretsPath, env.CAPXUL_SECRETS_FILE ? resolve(env.CAPXUL_SECRETS_FILE) : void 0].filter((path) => path !== void 0);
+	for (const path of envFiles) if (existsSync(path)) {
+		const parsed = (0, import_main.config)({
+			path,
+			processEnv: env,
+			override: true
+		});
+		if (parsed.error !== void 0) throw parsed.error;
+	}
+	env.CONVEX_URL ||= env.CAPXUL_E2E_CONVEX_URL;
+	env.CONVEX_SITE_URL ||= env.CAPXUL_E2E_CONVEX_SITE_URL;
+	env.CAPXUL_E2E_ORIGIN ||= env.CAPXUL_E2E_BOOTSTRAP_URL || env.SITE_URL;
+	return env;
+}
+function requiredEnv(env, name) {
+	const value = env[name]?.trim();
+	if (value === void 0 || value.length === 0) throw new Error(`Missing required env: ${name}`);
+	return value;
+}
+function normalizeHttpOrigin(raw) {
+	const value = raw.trim();
+	if (value.length === 0) throw new Error("Origin is required.");
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error("Origin must be a valid URL, for example http://localhost:3000.");
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("Origin must use http or https.");
+	if (url.username || url.password) throw new Error("Origin must not include credentials.");
+	if (url.pathname !== "/" || url.search || url.hash) throw new Error("Origin must not include a path, query, or hash.");
+	return `${url.protocol}//${url.host}`;
+}
+function writeConvexDeploymentEnvFile(deployment) {
+	const path = resolve(mkdtempSync(resolve(tmpdir(), "capxul-convex-")), "deployment.env");
+	writeFileSync(path, `CONVEX_DEPLOYMENT=${deployment}\n`, {
+		encoding: "utf8",
+		mode: 384
+	});
+	return path;
+}
+function minimalConvexEnv() {
+	return {
+		CI: "true",
+		HOME: homedir(),
+		PATH: process.env.PATH ?? "",
+		TMPDIR: process.env.TMPDIR ?? tmpdir()
+	};
+}
+function runConvex(deploymentEnvFile, args) {
+	const result = spawnSync(resolve(backendRoot, "node_modules/.bin/convex"), [
+		...args,
+		"--env-file",
+		deploymentEnvFile
+	], {
+		cwd: backendRoot,
+		env: minimalConvexEnv(),
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		ok: result.status === 0,
+		output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
+	};
+}
+function extractField(output, field) {
+	const quoted = new RegExp(`"${field}"\\s*:\\s*"([^"]+)"`).exec(output);
+	if (quoted?.[1]) return quoted[1];
+	const jsLike = new RegExp(`${field}\\s*:\\s*"([^"]+)"`).exec(output);
+	if (jsLike?.[1]) return jsLike[1];
+	throw new Error(`Convex output did not include ${field}`);
+}
+function packageVersion(packageDir) {
+	const pkg = JSON.parse(readFileSync(resolve(repoRoot, "packages", packageDir, "package.json"), "utf8"));
+	if (!pkg.version) throw new Error(`Missing version in packages/${packageDir}/package.json`);
+	return pkg.version;
+}
+function redactPublishableKeys(output) {
+	return output.replace(/cap_pk_(test|live)_[0-9A-HJKMNP-TV-Z]+/g, "cap_pk_$1_REDACTED");
+}
+function writeSecureHandoff(path, values) {
+	const handoffDir = dirname(path);
+	const handoffDirAlreadyExisted = existsSync(handoffDir);
+	mkdirSync(handoffDir, {
+		recursive: true,
+		mode: 448
+	});
+	if (!handoffDirAlreadyExisted) chmodSync(handoffDir, 448);
+	const body = `# Capxul Next.js Quickstart Secure Handoff
+
+Generated: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+| Value | Customer value |
+| --- | --- |
+| Package versions | @capxul/sdk@${values.sdkVersion}, @capxul/sdk-react@${values.sdkReactVersion} |
+| npm dist tag | alpha |
+| Environment | ${values.environment} |
+| Developer application | ${values.appName} |
+| Application id | ${values.applicationId} |
+| Publishable key id | ${values.keyId} |
+| Publishable key | ${values.publishableKey} |
+| Capxul site URL | ${values.convexSiteUrl} |
+| Convex URL | ${values.convexUrl} |
+| Local allowed origin | ${values.allowedOrigin} |
+| Production allowed origin | <set after customer domain is known> |
+| Auth method | Email OTP |
+
+Put the publishable key in \`.env.local\` as
+\`NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY\`, and set server-side
+\`CAPXUL_SITE_URL=${values.convexSiteUrl}\` for the Next.js rewrites. Do not send
+backend secrets, private keys, Convex deploy keys, Resend keys, Openfort server
+keys, or operator credentials to the customer.
+`;
+	const tmpDir = mkdtempSync(join(handoffDir, ".handoff-"));
+	try {
+		const tmpPath = join(tmpDir, "quickstart.md");
+		writeFileSync(tmpPath, body, {
+			encoding: "utf8",
+			mode: 384
+		});
+		chmodSync(tmpPath, 384);
+		renameSync(tmpPath, path);
+		chmodSync(path, 384);
+	} finally {
+		rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function mintNextjsQuickstartKey(input, deps = {}) {
+	const environment = input.environment ?? "test";
+	const pushBackend = input.pushBackend ?? true;
+	const openfortPublishableKey = requiredEnv(input.env, "OPENFORT_PUBLISHABLE_KEY");
+	const shieldPublishableKey = requiredEnv(input.env, "SHIELD_PUBLISHABLE_KEY");
+	const allowedOrigin = normalizeHttpOrigin(input.allowedOrigin);
+	const convexSiteUrl = input.convexSiteUrl.replace(/\/$/, "");
+	const convexUrl = input.convexUrl.replace(/\/$/, "");
+	const authBaseUrl = `${convexSiteUrl}/api/auth`;
+	const deploymentEnvFile = writeConvexDeploymentEnvFile(input.deployment);
+	const run = deps.runConvex ?? runConvex;
+	const resolvePackageVersion = deps.packageVersion ?? packageVersion;
+	if (pushBackend) {
+		const deploy = run(deploymentEnvFile, ["dev", "--once"]);
+		if (!deploy.ok) throw new Error(deploy.output || "Convex deploy failed.");
+	}
+	const publishableKeyConfig = {
+		allowedOrigins: [allowedOrigin],
+		authBaseUrl,
+		convexUrl,
+		siteBaseUrl: convexSiteUrl,
+		openfortPublishableKey,
+		shieldPublishableKey
+	};
+	const app = run(deploymentEnvFile, [
+		"run",
+		"credentials/mutations:createDeveloperApplication",
+		JSON.stringify({
+			name: input.appName,
+			...publishableKeyConfig
+		})
+	]);
+	if (!app.ok) throw new Error(app.output || "Developer application creation failed.");
+	const applicationId = extractField(app.output, "applicationId");
+	const key = run(deploymentEnvFile, [
+		"run",
+		"credentials/mutations:mintPublishableKey",
+		JSON.stringify({
+			applicationId,
+			environment,
+			...publishableKeyConfig
+		})
+	]);
+	if (!key.ok) throw new Error(redactPublishableKeys(key.output || "Publishable key mint failed."));
+	const keyId = extractField(key.output, "keyId");
+	const publishableKey = extractField(key.output, "publishableKey");
+	writeSecureHandoff(input.handoffPath, {
+		appName: input.appName,
+		applicationId,
+		keyId,
+		publishableKey,
+		allowedOrigin,
+		convexSiteUrl,
+		convexUrl,
+		sdkVersion: resolvePackageVersion("sdk"),
+		sdkReactVersion: resolvePackageVersion("sdk-react"),
+		environment
+	});
+	return {
+		appName: input.appName,
+		applicationId,
+		keyId,
+		publishableKey,
+		allowedOrigin,
+		convexSiteUrl,
+		convexUrl,
+		handoffPath: input.handoffPath,
+		environment
+	};
+}
+//#endregion
+//#region src/runtime.ts
+const bundledPackageVersions = {
+	sdk: "1.0.0-alpha.11",
+	"sdk-react": "1.0.0-alpha.11"
+};
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const FAUCET_DECIMALS = 6n;
+const FAUCET_DECIMAL_PLACES = Number(FAUCET_DECIMALS);
+const FAUCET_SCALE = 10n ** FAUCET_DECIMALS;
+const FAUCET_MAX_BASE_UNITS = 10000n * FAUCET_SCALE;
+const EVM_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
+const PLATFORM_ENV_NAMES = [
+	"COMSPEC",
+	"ComSpec",
+	"PATHEXT",
+	"SystemRoot",
+	"WINDIR",
+	"windir"
+];
+function convexArgsForDeployment(args, deployment, hasDeployKey) {
+	if (hasDeployKey) return [...args];
+	if (args[0] === "run") return [
+		"run",
+		"--deployment",
+		deployment,
+		...args.slice(1)
+	];
+	return [
+		...args,
+		"--deployment",
+		deployment
+	];
+}
+function convexChildEnv(deployment, sourceEnv) {
+	const env = {
+		CI: "true",
+		CONVEX_DEPLOYMENT: deployment,
+		HOME: homedir(),
+		PATH: process.env.PATH ?? "",
+		TMPDIR: process.env.TMPDIR ?? tmpdir()
+	};
+	const deployKey = sourceEnv.CONVEX_DEPLOY_KEY?.trim();
+	if (deployKey !== void 0 && deployKey.length > 0) env.CONVEX_DEPLOY_KEY = deployKey;
+	for (const name of PLATFORM_ENV_NAMES) {
+		const value = process.env[name];
+		if (value !== void 0 && value.length > 0) env[name] = value;
+	}
+	return env;
+}
+function bundledPackageVersion(packageDir) {
+	const version = bundledPackageVersions[packageDir];
+	if (version === void 0 || version.length === 0) throw new Error(`Missing bundled package version for ${packageDir}`);
+	return version;
+}
+function createConvexPathRunner({ deployment, env: sourceEnv = process.env, spawn = spawnSync }) {
+	return (_deploymentEnvFile, args) => {
+		const childEnv = convexChildEnv(deployment, sourceEnv);
+		const result = spawn("convex", convexArgsForDeployment(args, deployment, childEnv.CONVEX_DEPLOY_KEY !== void 0), {
+			cwd: packageRoot,
+			env: childEnv,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const processError = result.error instanceof Error ? result.error.message : "";
+		return {
+			ok: result.status === 0,
+			output: `${result.stdout ?? ""}${result.stderr ?? ""}${processError}`.trim()
+		};
+	};
+}
+function normalizeEvmAddress(value) {
+	const address = value.trim();
+	if (!EVM_ADDRESS_PATTERN.test(address)) throw new Error("Address must be a 0x-prefixed 20-byte EVM address.");
+	return address;
+}
+function usdAmountToBaseUnits(value) {
+	const amount = value.trim();
+	const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(amount);
+	if (match === null) throw new Error("Amount must be a positive decimal, for example 10 or 10.5.");
+	const whole = BigInt(match[1] ?? "0");
+	const fractional = match[2] ?? "";
+	if (fractional.length > FAUCET_DECIMAL_PLACES) throw new Error("Amount supports at most 6 decimal places.");
+	const fractionalBaseUnits = BigInt(fractional.padEnd(FAUCET_DECIMAL_PLACES, "0"));
+	const baseUnits = whole * FAUCET_SCALE + fractionalBaseUnits;
+	if (baseUnits <= 0n) throw new Error("Amount must be greater than 0.");
+	if (baseUnits > FAUCET_MAX_BASE_UNITS) throw new Error("Amount must not exceed 10000 USDX.");
+	return baseUnits.toString();
+}
+//#endregion
+//#region src/commands/shared.ts
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function canonicalConvexRunner(env = process.env) {
+	return createConvexPathRunner({
+		deployment: CANONICAL_QUICKSTART_DEPLOYMENT.deployment,
+		env
+	});
+}
+//#endregion
+//#region src/commands/faucet-send.ts
+const DEFAULT_FAUCET_AMOUNT = "10";
+const FAUCET_FUNCTION = "dev/faucetMintTo:mintTo";
+async function runFaucetSend() {
+	intro("Capxul sandbox faucet send");
+	note([
+		`Deployment: ${CANONICAL_QUICKSTART_DEPLOYMENT.deployment}`,
+		"Chain: Base Sepolia (84532)",
+		"Asset: test USDX, 6 decimals",
+		"This command calls the canonical backend dev faucet and cannot select live/mainnet."
+	].join("\n"), "Canonical sandbox");
+	const addressPrompt = await text({
+		message: "Recipient EVM address",
+		validate(value) {
+			try {
+				normalizeEvmAddress(value ?? "");
+			} catch (error) {
+				return errorMessage(error);
+			}
+		}
+	});
+	if (isCancel(addressPrompt)) {
+		cancel("No faucet funds sent.");
+		return 0;
+	}
+	const amountPrompt = await text({
+		message: "USDX amount",
+		initialValue: DEFAULT_FAUCET_AMOUNT,
+		validate(value) {
+			try {
+				usdAmountToBaseUnits(value ?? "");
+			} catch (error) {
+				return errorMessage(error);
+			}
+		}
+	});
+	if (isCancel(amountPrompt)) {
+		cancel("No faucet funds sent.");
+		return 0;
+	}
+	const holderAddress = normalizeEvmAddress(addressPrompt);
+	const rawAmount = usdAmountToBaseUnits(amountPrompt);
+	const displayAmount = amountPrompt.trim();
+	const shouldSend = await confirm({
+		message: `Mint ${displayAmount} test USDX to ${holderAddress}?`,
+		initialValue: true
+	});
+	if (isCancel(shouldSend) || shouldSend === false) {
+		cancel("No faucet funds sent.");
+		return 0;
+	}
+	const s = spinner();
+	s.start("Minting testnet funds");
+	try {
+		const result = canonicalConvexRunner(loadOperatorEnv())("", [
+			"run",
+			FAUCET_FUNCTION,
+			JSON.stringify({
+				holderAddress,
+				rawAmount
+			})
+		]);
+		if (!result.ok) throw new Error(result.output || "Faucet mint failed.");
+		const txHash = extractField(result.output, "txHash");
+		s.stop("Faucet funds sent");
+		note([
+			`Recipient: ${holderAddress}`,
+			`Amount: ${displayAmount} USDX`,
+			`Raw amount: ${rawAmount}`,
+			`Chain: Base Sepolia (84532)`,
+			`Transaction hash: ${txHash}`
+		].join("\n"), "Funded");
+		outro("Done.");
+		return 0;
+	} catch (error) {
+		s.stop("Faucet send failed");
+		cancel(errorMessage(error));
+		return 1;
+	}
+}
+//#endregion
+//#region src/commands/key-create.ts
+async function runKeyCreate() {
+	intro("Capxul sandbox key create");
+	note([
+		`Deployment: ${CANONICAL_QUICKSTART_DEPLOYMENT.deployment}`,
+		`Site URL: ${CANONICAL_QUICKSTART_DEPLOYMENT.convexSiteUrl}`,
+		`Convex URL: ${CANONICAL_QUICKSTART_DEPLOYMENT.convexUrl}`,
+		"This npx CLI calls the already-deployed canonical backend; it does not push code."
+	].join("\n"), "Canonical deployment");
+	const appNamePrompt = await text({
+		message: "Developer application name",
+		initialValue: DEFAULT_APP_NAME,
+		validate(value) {
+			if ((value ?? "").trim().length === 0) return "Application name is required.";
+		}
+	});
+	if (isCancel(appNamePrompt)) {
+		cancel("No key created.");
+		return 0;
+	}
+	const allowedOriginPrompt = await text({
+		message: "Allowed local origin",
+		initialValue: DEFAULT_ALLOWED_ORIGIN,
+		validate(value) {
+			try {
+				normalizeHttpOrigin(value ?? "");
+			} catch (error) {
+				return errorMessage(error);
+			}
+		}
+	});
+	if (isCancel(allowedOriginPrompt)) {
+		cancel("No key created.");
+		return 0;
+	}
+	const handoffPathPrompt = await text({
+		message: "Secure handoff file",
+		initialValue: DEFAULT_HANDOFF_PATH,
+		validate(value) {
+			if ((value ?? "").trim().length === 0) return "Handoff path is required.";
+		}
+	});
+	if (isCancel(handoffPathPrompt)) {
+		cancel("No key created.");
+		return 0;
+	}
+	const appName = appNamePrompt.trim();
+	const allowedOrigin = normalizeHttpOrigin(allowedOriginPrompt);
+	const handoffPath = handoffPathPrompt.trim();
+	const shouldCreate = await confirm({
+		message: `Create a test publishable key for ${appName}?`,
+		initialValue: true
+	});
+	if (isCancel(shouldCreate) || shouldCreate === false) {
+		cancel("No key created.");
+		return 0;
+	}
+	const s = spinner();
+	s.start("Creating developer application and test publishable key");
+	try {
+		const operatorEnv = loadOperatorEnv();
+		const result = await mintNextjsQuickstartKey({
+			env: operatorEnv,
+			...CANONICAL_QUICKSTART_DEPLOYMENT,
+			appName,
+			allowedOrigin,
+			handoffPath,
+			environment: "test",
+			pushBackend: false
+		}, {
+			packageVersion: bundledPackageVersion,
+			runConvex: canonicalConvexRunner(operatorEnv)
+		});
+		s.stop("Publishable key captured in secure handoff");
+		note([
+			`Handoff: ${result.handoffPath}`,
+			`Application id: ${result.applicationId}`,
+			`Key id: ${result.keyId}`,
+			`Allowed origin: ${result.allowedOrigin}`,
+			`Capxul site URL: ${result.convexSiteUrl}`,
+			"Raw publishable key was not printed; copy it from the handoff file.",
+			"Before handoff, ensure CAPXUL_TRUSTED_ORIGINS and CORS_ALLOWED_ORIGINS include this origin."
+		].join("\n"), "Created");
+		outro("Done.");
+		return 0;
+	} catch (error) {
+		s.stop("Publishable key creation failed");
+		cancel(errorMessage(error));
+		return 1;
+	}
+}
+//#endregion
+//#region src/main.ts
+const SANDBOX_COMMANDS = [{
+	value: "key create",
+	label: "Create publishable key",
+	usage: "npx @capxul/sandbox key create",
+	description: "Create a canonical quickstart test publishable key.",
+	run: runKeyCreate
+}, {
+	value: "faucet send",
+	label: "Send testnet faucet funds",
+	usage: "npx @capxul/sandbox faucet send",
+	description: "Mint test USDX to an EVM address on Base Sepolia.",
+	run: runFaucetSend
+}];
+const HELP_COMMANDS = {
+	"--help": true,
+	"-h": true,
+	help: true
+};
+const COMMAND_BY_ARGS = {
+	"key create": "key create",
+	"faucet send": "faucet send"
+};
+const HELP_TEXT = [
+	"Usage:",
+	...SANDBOX_COMMANDS.map(({ usage }) => `  ${usage}`),
+	"",
+	"Commands:",
+	...SANDBOX_COMMANDS.map(({ value, description }) => `  ${value.padEnd(13)} ${description}`)
+].join("\n");
+function commandFromArgs(argv) {
+	const command = (argv[0] === "--" ? argv.slice(1) : argv).join(" ");
+	if (command.length === 0) return null;
+	return HELP_COMMANDS[command] ? "help" : COMMAND_BY_ARGS[command] ?? "invalid";
+}
+async function selectCommand() {
+	const command = await select({
+		message: "Sandbox action",
+		options: SANDBOX_COMMANDS.map(({ value, label }) => ({
+			value,
+			label
+		}))
+	});
+	if (isCancel(command)) {
+		cancel("No sandbox command run.");
+		return null;
+	}
+	return command;
+}
+function runCommand(command) {
+	return SANDBOX_COMMANDS.find(({ value }) => value === command)?.run() ?? Promise.resolve(1);
+}
+async function main() {
+	const command = commandFromArgs(process.argv.slice(2)) ?? await selectCommand();
+	if (command === null) return 0;
+	if (command === "help") {
+		note(HELP_TEXT, "Capxul sandbox");
+		return 0;
+	}
+	if (command === "invalid") {
+		note(HELP_TEXT, "Invalid sandbox command");
+		return 1;
+	}
+	return runCommand(command);
+}
+main().then((code) => {
+	process.exitCode = code;
+}).catch((error) => {
+	cancel(errorMessage(error));
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@capxul/sandbox",
+  "version": "1.0.0-alpha.1",
+  "private": false,
+  "description": "Capxul sandbox CLI for canonical quickstart keys and testnet faucet funds.",
+  "keywords": [
+    "capxul",
+    "cli",
+    "sandbox",
+    "testnet"
+  ],
+  "homepage": "https://github.com/Xelmar-tech/infrastructure#readme",
+  "bugs": {
+    "url": "https://github.com/Xelmar-tech/infrastructure/issues"
+  },
+  "license": "UNLICENSED",
+  "author": "Xelmar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
+    "directory": "apps/sandbox"
+  },
+  "bin": {
+    "capxul-sandbox": "./dist/main.mjs",
+    "sandbox": "./dist/main.mjs"
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "convex": "^1.39.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsx": "^4.22.1",
+    "typescript": "5.9.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.1.23",
+    "vite-plus": "0.1.23"
+  },
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "check-types": "vp exec tsc -p tsconfig.json --noEmit",
+    "build": "NODE_OPTIONS=--max-old-space-size=4096 vp pack"
+  }
+}