@unbound-app/cli 0.1.0

package/dist/index.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/index.mjs

@@ -0,0 +1,984 @@
+#!/usr/bin/env node
+import { cli, command } from "cleye";
+import { z } from "zod";
+import { existsSync, mkdirSync, readFileSync, readdirSync, watch, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { ControllerClient } from "@unbound-app/debugger-protocol/controller";
+import { CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT } from "@unbound-app/debugger-protocol";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { cancel, confirm, intro, isCancel, note, outro, select, text } from "@clack/prompts";
+import { spawn, spawnSync } from "node:child_process";
+import { glob } from "node:fs/promises";
+import pc from "picocolors";
+//#region src/lib/stdin.ts
+/**
+* @description Whether stdin is piped rather than an interactive terminal, meaning a command may read
+* its input from it.
+* @returns `true` when stdin is not a TTY.
+*/
+function isStdinPiped() {
+	return !process.stdin.isTTY;
+}
+/**
+* @description Reads all of stdin to a trimmed string, for commands fed their input through a pipe.
+* @returns The piped input.
+*/
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8").trim();
+}
+//#endregion
+//#region src/lib/config.ts
+/** The filename walked up the directory tree to locate a workspace root. */
+const CONFIG_FILENAME = "unbound.config.json";
+const schema = z.object({
+	$schema: z.string().optional(),
+	addons: z.array(z.string()).default(["plugins/*", "themes/*"]),
+	build: z.string().default("bun run build"),
+	output: z.string().default("dist")
+});
+/**
+* @description Walks up from `cwd` looking for an `unbound.config.json`, parsing the first one found
+* against the config schema. When none exists the `cwd` is treated as a single-addon root carrying
+* the schema defaults, so bare addons need no config.
+* @param cwd The directory to start the upward search from.
+* @returns The parsed config and the directory it resolves relative to.
+*/
+function loadConfig(cwd = process.cwd()) {
+	const found = findConfigFile(cwd);
+	if (!found) return {
+		config: schema.parse({}),
+		dir: resolve(cwd),
+		bare: true
+	};
+	const raw = JSON.parse(readFileSync(found, "utf8"));
+	return {
+		config: schema.parse(raw),
+		dir: dirname(found),
+		bare: false
+	};
+}
+function findConfigFile(from) {
+	let dir = resolve(from);
+	while (true) {
+		const candidate = resolve(dir, CONFIG_FILENAME);
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+//#endregion
+//#region src/lib/context.ts
+/** How long a one-shot command waits for the bridge to report a device before giving up. */
+const DEVICE_WAIT_TIMEOUT_MS = 2e3;
+/** How often the device-wait polls the controller's connection state. */
+const DEVICE_WAIT_POLL_MS = 50;
+/**
+* @description Builds a {@link LazyContext} whose controller dials the bridge on the given port on
+* first access to `client`, attaching as a controller through the shared endpoint marker rather than
+* as a device. Commands that never read `client` never connect.
+* @param port The port the bridge listens on.
+* @returns A context that connects on demand.
+*/
+function createContext(port) {
+	const url = `ws://127.0.0.1:${port}?${CONTROLLER_ENDPOINT_MARKER}`;
+	let client;
+	return {
+		get client() {
+			if (client) return client;
+			client = new ControllerClient(url);
+			client.connect();
+			return client;
+		},
+		get connected() {
+			return client !== void 0;
+		},
+		close() {
+			client?.close();
+		}
+	};
+}
+/**
+* @description Waits for the bridge to report a connected device, for one-shot commands that dial in,
+* run, and exit. Resolves early once a device is seen; resolves `false` once the timeout elapses so
+* the caller can surface a connection error rather than hang.
+* @param client The controller dialing the bridge.
+* @param timeoutMs How long to wait before giving up.
+* @returns Whether a device connected within the timeout.
+*/
+function waitForDevice(client, timeoutMs = DEVICE_WAIT_TIMEOUT_MS) {
+	return new Promise((resolve) => {
+		if (client.isDeviceConnected) return resolve(true);
+		const deadline = Date.now() + timeoutMs;
+		const timer = setInterval(() => {
+			if (client.isDeviceConnected) {
+				clearInterval(timer);
+				resolve(true);
+			} else if (Date.now() >= deadline) {
+				clearInterval(timer);
+				resolve(false);
+			}
+		}, DEVICE_WAIT_POLL_MS);
+	});
+}
+//#endregion
+//#region src/lib/zod-flags.ts
+/** The wrappers whose `innerType` carries the underlying type a flag should be built from. */
+const WRAPPER_TYPES = /* @__PURE__ */ new Set([
+	"default",
+	"optional",
+	"nullable"
+]);
+const FLAG_CONSTRUCTORS = {
+	boolean: Boolean,
+	number: Number,
+	string: String
+};
+/**
+* @description Derives a cleye flag descriptor from a zod field, reading its type through zod's own
+* `def` introspection so the flag stays in sync with the schema rather than a hand-kept parallel map.
+* @param field The zod field for a single schema property.
+* @returns The cleye flag descriptor for that field.
+*/
+function fieldToFlag(field) {
+	let def = field.def;
+	let defaultValue;
+	while (WRAPPER_TYPES.has(def.type) && def.innerType) {
+		if (def.type === "default") defaultValue = def.defaultValue;
+		def = def.innerType.def;
+	}
+	return {
+		type: FLAG_CONSTRUCTORS[def.type] ?? String,
+		description: field.description,
+		default: defaultValue
+	};
+}
+//#endregion
+//#region src/adapters/cleye.ts
+/** The value that marks a positional as fed from stdin instead of the command line. */
+const STDIN_MARKER = "-";
+/**
+* @description Builds a cleye command from a registry definition: the fields named in
+* `cli.positionals` become positional parameters, every other schema field becomes a flag whose type
+* is derived from the zod field. The callback reads a stdin-fed positional when piped, validates the
+* assembled input through the definition's schema, runs the handler, and exits `0`/`1`/`2` on
+* success, on-device failure, and connection or usage error respectively.
+* @param definition The command to adapt.
+* @returns A cleye `command()` ready to register on the CLI.
+*/
+function toCleyeCommand(definition) {
+	const positionalNames = (definition.cli?.positionals ?? []).map(String);
+	const flags = { json: {
+		type: Boolean,
+		description: "Print the raw result as JSON instead of the formatted transcript.",
+		default: false
+	} };
+	for (const [name, field] of Object.entries(definition.schema.shape)) {
+		if (positionalNames.includes(name)) continue;
+		flags[name] = fieldToFlag(field);
+	}
+	return command({
+		name: definition.name,
+		description: definition.description,
+		parameters: positionalNames.map((name) => `[${name}]`),
+		flags
+	}, async (parsed) => {
+		const { json, ...flagInput } = parsed.flags;
+		const input = { ...flagInput };
+		for (const name of positionalNames) input[name] = parsed._[name];
+		await run(definition, input, positionalNames[0], Boolean(json));
+	});
+}
+async function run(definition, input, stdinField, json) {
+	if (stdinField && (input[stdinField] === void 0 || input[stdinField] === STDIN_MARKER)) {
+		if (!isStdinPiped()) {
+			process.stderr.write(`Missing required argument: ${stdinField}.\n`);
+			process.exit(2);
+		}
+		input[stdinField] = await readStdin();
+	}
+	const parsed = definition.schema.safeParse(input);
+	if (!parsed.success) {
+		process.stderr.write(`${z.prettifyError(parsed.error)}\n`);
+		process.exit(2);
+	}
+	const port = parsed.data.port;
+	const context = createContext(port ?? NaN);
+	try {
+		const output = await definition.handler(parsed.data, context);
+		if (json) process.stdout.write(`${JSON.stringify(output.data ?? output)}\n`);
+		else if (output.ok) process.stdout.write(`${output.text}\n`);
+		else process.stderr.write(`${output.text}\n`);
+		if (output.ok) process.exit(0);
+		const connectionError = context.connected && !context.client.isDeviceConnected;
+		process.exit(connectionError ? 2 : 1);
+	} catch (error) {
+		if (error instanceof z.ZodError) {
+			process.stderr.write(`Invalid ${CONFIG_FILENAME}:\n${z.prettifyError(error)}\n`);
+			process.exit(2);
+		}
+		throw error;
+	} finally {
+		context.close();
+	}
+}
+//#endregion
+//#region src/adapters/mcp.ts
+/**
+* @description Registers a registry definition as an MCP tool on the given server: the definition's
+* schema is the tool's input schema, and its handler output maps to a tool result — the formatted
+* text as the sole content block, `ok: false` surfacing as `isError`.
+* @param server The MCP server to register the tool on.
+* @param definition The command to expose.
+* @param context The runtime the handler evaluates against.
+*/
+function toMcpTool(server, definition, context) {
+	server.registerTool(definition.name, {
+		description: definition.description,
+		inputSchema: definition.schema
+	}, async (input) => {
+		const output = await definition.handler(input, context);
+		return {
+			isError: !output.ok,
+			content: [{
+				type: "text",
+				text: output.text
+			}]
+		};
+	});
+}
+//#endregion
+//#region src/lib/templates.ts
+/** The base of every documentation link surfaced by `ubd create`. */
+const DOCS_BASE_URL = "https://docs.unbound.rip";
+/**
+* @description Resolves the bundled templates directory, walking up from this module so it works both
+* from `src/` in development and from the built `dist/` on a published install, where `templates/` is
+* shipped alongside via the package `files` field.
+* @returns The absolute path to the `templates` directory.
+*/
+function templatesDir() {
+	let dir = import.meta.dirname;
+	while (true) {
+		const candidate = join(dir, "templates");
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error("Could not locate the bundled templates directory.");
+		dir = parent;
+	}
+}
+/**
+* @description Resolves the absolute path to a single template directory.
+* @param template The template to resolve.
+* @returns The absolute path to that template.
+*/
+function templatePath(template) {
+	return resolve(templatesDir(), template);
+}
+//#endregion
+//#region src/lib/create-prompts.ts
+const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+* @description Runs the interactive `ubd create` flow, prompting only for values the flags left
+* unset so a fully-flagged invocation completes without a single prompt. Exits the process on
+* cancellation.
+* @param input The values supplied via flags.
+* @param workspace The config found in or above the cwd, or `undefined` when none exists.
+* @returns The fully-resolved options to scaffold from.
+*/
+async function resolveOptions(input, workspace) {
+	intro("ubd create");
+	const shape = await resolveShape(input.shape, Boolean(workspace));
+	const kind = await resolveKind(input.kind);
+	const name = await resolveName(input.name);
+	const displayName = await resolveText(input.displayName, "Display name", titleCase(name));
+	const description = await resolveText(input.description, "Description", "An Unbound addon.");
+	const authorName = await resolveText(input.authorName, "Author name", "you");
+	const authorId = await resolveOptionalText(input.authorId, "Author Discord id (optional)", "0");
+	const id = await resolveText(input.id, "Addon id", `${authorName}.${name}`);
+	const dir = shape === "add" ? void 0 : await resolveDir(input.dir, name);
+	const repository = shape === "repository";
+	return {
+		shape,
+		kind,
+		name,
+		displayName,
+		description,
+		authorName,
+		authorId,
+		id,
+		dir,
+		gitInit: repository ? await resolveConfirm(input.gitInit, "Initialize a git repository?") : false,
+		install: repository ? await resolveConfirm(input.install, "Install dependencies with bun?") : false
+	};
+}
+async function resolveShape(flag, hasWorkspace) {
+	if (flag === "repository") return "repository";
+	if (flag === "addon") return hasWorkspace ? "add" : "addon";
+	if (hasWorkspace) return unwrap(await select({
+		message: "This directory is inside an Unbound workspace. What would you like to do?",
+		options: [{
+			value: "add",
+			label: "Add an addon to this workspace"
+		}, {
+			value: "repository",
+			label: "New repository"
+		}]
+	}));
+	return unwrap(await select({
+		message: "What would you like to create?",
+		options: [{
+			value: "repository",
+			label: "Repository",
+			hint: "recommended"
+		}, {
+			value: "addon",
+			label: "Single addon directory"
+		}]
+	}));
+}
+async function resolveKind(flag) {
+	if (flag) return flag;
+	return unwrap(await select({
+		message: "Which kind of addon?",
+		options: [{
+			value: "plugin",
+			label: "Plugin",
+			hint: `patch the client. ${DOCS_BASE_URL}/plugins/introduction`
+		}, {
+			value: "theme",
+			label: "Theme",
+			hint: `recolor the UI. ${DOCS_BASE_URL}/themes/introduction`
+		}]
+	}));
+}
+async function resolveName(flag) {
+	if (flag !== void 0) {
+		if (!KEBAB_CASE.test(flag)) {
+			cancel(`Invalid name "${flag}": must be kebab-case (lowercase, digits, hyphens).`);
+			process.exit(2);
+		}
+		return flag;
+	}
+	return unwrap(await text({
+		message: "Addon name",
+		placeholder: "my-addon",
+		validate(input) {
+			if (!input) return "A name is required.";
+			if (!KEBAB_CASE.test(input)) return "Must be kebab-case (lowercase, digits, hyphens).";
+		}
+	}));
+}
+async function resolveText(flag, message, initialValue) {
+	if (flag !== void 0) return flag;
+	return unwrap(await text({
+		message,
+		initialValue
+	}));
+}
+async function resolveOptionalText(flag, message, fallback) {
+	if (flag !== void 0) return flag;
+	const resolved = unwrap(await text({
+		message,
+		placeholder: fallback
+	}));
+	return resolved === "" ? fallback : resolved;
+}
+async function resolveDir(flag, name) {
+	if (flag !== void 0) return flag;
+	return unwrap(await text({
+		message: "Target directory",
+		initialValue: `./${name}`
+	}));
+}
+async function resolveConfirm(flag, message) {
+	if (flag !== void 0) return flag;
+	return unwrap(await confirm({
+		message,
+		initialValue: true
+	}));
+}
+function unwrap(value) {
+	if (isCancel(value)) {
+		cancel("Cancelled.");
+		process.exit(0);
+	}
+	return value;
+}
+function titleCase(name) {
+	return name.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+//#endregion
+//#region src/lib/scaffold.ts
+/** npm and bun drop dotfiles named `.gitignore` from tarballs, so templates store it undotted. */
+const GITIGNORE_SOURCE = "gitignore";
+/**
+* @description Applies `{{token}}` substitution to a string, replacing every known token with its
+* value and leaving unknown `{{…}}` sequences untouched.
+* @param input The string to substitute over (file contents or a path segment).
+* @param tokens The token values to inject.
+* @returns The substituted string.
+*/
+function substitute(input, tokens) {
+	return input.replace(/\{\{(\w+)\}\}/g, (match, token) => {
+		return token in tokens ? tokens[token] : match;
+	});
+}
+/**
+* @description Recursively copies a template directory into a destination, substituting tokens across
+* both file contents and file/directory names and renaming the undotted `gitignore` to `.gitignore`
+* so it survives publishing yet lands as a real dotfile.
+* @param from The template directory to copy.
+* @param to The destination directory (created if absent).
+* @param tokens The token values to inject.
+*/
+function scaffoldTemplate(from, to, tokens) {
+	mkdirSync(to, { recursive: true });
+	for (const entry of readdirSync(from, { withFileTypes: true })) {
+		const source = join(from, entry.name);
+		const target = join(to, entry.name === GITIGNORE_SOURCE ? ".gitignore" : substitute(entry.name, tokens));
+		if (entry.isDirectory()) {
+			scaffoldTemplate(source, target, tokens);
+			continue;
+		}
+		writeFileSync(target, substitute(readFileSync(source, "utf8"), tokens));
+	}
+}
+//#endregion
+//#region src/lib/create.ts
+/**
+* @description Scaffolds the chosen shape into a validated target directory: a repository stamps the
+* workspace template then the starter addon under `plugins/`/`themes/`; a single addon or an addon
+* added to an existing workspace stamps only the kind's template. Runs `git init` and `bun install`
+* for repositories when confirmed.
+* @param options The fully-resolved create options.
+* @param workspace The config found in or above the cwd, or `undefined` when none exists.
+* @returns Where the addon landed, for the next-step outro.
+*/
+function scaffold(options, workspace) {
+	const tokens = toTokens(options);
+	if (options.shape === "repository") return scaffoldRepository(options, tokens);
+	if (options.shape === "add") return scaffoldWorkspaceAddon(options, tokens, workspace);
+	return scaffoldBareAddon(options, tokens);
+}
+function scaffoldRepository(options, tokens) {
+	const dir = resolve(options.dir ?? `./${options.name}`);
+	assertEmpty(dir);
+	scaffoldTemplate(templatePath("repository"), dir, tokens);
+	const folder = options.kind === "plugin" ? "plugins" : "themes";
+	scaffoldTemplate(templatePath(options.kind), join(dir, folder, options.name), tokens);
+	if (options.gitInit) gitInit(dir);
+	if (options.install) bunInstall(dir);
+	return {
+		dir,
+		kind: options.kind,
+		name: options.name
+	};
+}
+function scaffoldBareAddon(options, tokens) {
+	const dir = resolve(options.dir ?? `./${options.name}`);
+	assertEmpty(dir);
+	scaffoldTemplate(templatePath(options.kind), dir, tokens);
+	return {
+		dir,
+		kind: options.kind,
+		name: options.name
+	};
+}
+function scaffoldWorkspaceAddon(options, tokens, workspace) {
+	if (!workspace) throw new Error("Cannot add an addon: no workspace config was found.");
+	const dir = join(workspaceAddonDir(workspace, options.kind), options.name);
+	assertEmpty(dir);
+	scaffoldTemplate(templatePath(options.kind), dir, tokens);
+	return {
+		dir,
+		kind: options.kind,
+		name: options.name
+	};
+}
+/**
+* @description Picks the workspace directory a new addon of the given kind belongs in, matching the
+* config `addons` glob whose leading segment names the kind and stripping its trailing `*` segment.
+* Falls back to `plugins`/`themes` next to the config when no glob matches.
+* @param workspace The resolved workspace config.
+* @param kind The addon kind being added.
+* @returns The absolute directory the addon folder should be created under.
+*/
+function workspaceAddonDir(workspace, kind) {
+	const keyword = kind === "plugin" ? "plugin" : "theme";
+	const glob = workspace.config.addons.find((pattern) => pattern.includes(keyword));
+	const base = glob ? glob.replace(/\/?\*+.*$/, "") : `${keyword}s`;
+	return resolve(workspace.dir, base);
+}
+function assertEmpty(dir) {
+	if (!existsSync(dir)) return;
+	if (readdirSync(dir).length > 0) throw new Error(`Target directory is not empty: ${dir}`);
+}
+function gitInit(dir) {
+	spawnSync("git", ["init"], {
+		cwd: dir,
+		stdio: "inherit"
+	});
+}
+function bunInstall(dir) {
+	spawnSync("bun", ["install"], {
+		cwd: dir,
+		stdio: "inherit"
+	});
+}
+function toTokens(options) {
+	return {
+		name: options.name,
+		id: options.id,
+		displayName: options.displayName,
+		description: options.description,
+		authorName: options.authorName,
+		authorId: options.authorId,
+		main: options.kind === "theme" ? "theme" : "index.tsx"
+	};
+}
+//#endregion
+//#region src/commands/create.ts
+const createCommand = {
+	name: "create",
+	description: "Scaffold a new Unbound addon or addon workspace. Prompts for anything left unset, so a fully-flagged invocation runs without prompts for use in CI.",
+	surfaces: {
+		cli: true,
+		mcp: false
+	},
+	schema: z.object({
+		kind: z.enum(["plugin", "theme"]).optional().describe("The addon kind to scaffold."),
+		name: z.string().optional().describe("The addon name (kebab-case)."),
+		dir: z.string().optional().describe("The target directory (default ./<name>)."),
+		displayName: z.string().optional().describe("The human-readable addon name."),
+		description: z.string().optional().describe("A one-line description."),
+		authorName: z.string().optional().describe("The author name."),
+		authorId: z.string().optional().describe("The author Discord id."),
+		id: z.string().optional().describe("The manifest id (default <authorName>.<name>)."),
+		shape: z.enum(["repository", "addon"]).optional().describe("Scaffold a repository or a single addon."),
+		gitInit: z.boolean().optional().describe("Initialize a git repository (repository shape only)."),
+		install: z.boolean().optional().describe("Install dependencies with bun (repository shape only).")
+	}),
+	async handler(input) {
+		const config = loadConfig();
+		const workspace = config.bare ? void 0 : config;
+		const options = await resolveOptions(input, workspace);
+		try {
+			printOutro(scaffold(options, workspace));
+			return {
+				ok: true,
+				text: ""
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				text: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+};
+function printOutro(result) {
+	const kindDocs = `${DOCS_BASE_URL}/${result.kind}s/introduction`;
+	const manifestDocs = `${DOCS_BASE_URL}/addons/manifest`;
+	note([
+		`cd ${relative(process.cwd(), result.dir) || "."}`,
+		"ubd dev",
+		`Learn the ${result.kind} API: ${kindDocs}`,
+		`Manifest reference: ${manifestDocs}`
+	].join("\n"), "Next steps");
+	outro(`${result.name} ready.`);
+}
+//#endregion
+//#region src/lib/discovery.ts
+/**
+* @description Discovers every addon reachable through the config's `addons` globs. A directory is an
+* addon iff it contains a `manifest.json`; its kind is derived from the manifest `main` (a `.json`
+* entry point is a theme, anything else a plugin) and it is static when its directory carries no
+* `package.json` with a `build` script.
+* @param resolved The loaded config paired with the directory its globs resolve relative to.
+* @returns Every discovered addon, keyed implicitly by directory.
+*/
+async function discoverAddons(resolved) {
+	const { config, dir, bare } = resolved;
+	const dirs = /* @__PURE__ */ new Set();
+	if (bare) dirs.add(dir);
+	else for (const pattern of config.addons) for await (const match of glob(pattern, { cwd: dir })) dirs.add(resolve(dir, match));
+	const addons = [];
+	for (const addonDir of dirs) {
+		const addon = readAddon(addonDir, config.output);
+		if (addon) addons.push(addon);
+	}
+	return addons;
+}
+/**
+* @description Reads a single directory as an addon, returning `undefined` when it has no
+* `manifest.json` or the manifest lacks the fields discovery needs.
+* @param addonDir The absolute directory to inspect.
+* @param output The config's output directory, relative to the addon.
+* @returns The discovered addon, or `undefined` if the directory is not an addon.
+*/
+function readAddon(addonDir, output) {
+	const manifestPath = join(addonDir, "manifest.json");
+	if (!existsSync(manifestPath)) return void 0;
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+	} catch (error) {
+		process.stderr.write(`Skipping ${addonDir}: its manifest.json could not be read: ${error}\n`);
+		return;
+	}
+	if (typeof manifest.id !== "string" || typeof manifest.main !== "string") return void 0;
+	const kind = manifest.main.endsWith(".json") ? "theme" : "plugin";
+	const isStatic = !hasBuildScript(addonDir);
+	return {
+		id: manifest.id,
+		kind,
+		dir: addonDir,
+		output: isStatic ? addonDir : join(addonDir, output),
+		static: isStatic
+	};
+}
+function hasBuildScript(addonDir) {
+	const packagePath = join(addonDir, "package.json");
+	if (!existsSync(packagePath)) return false;
+	try {
+		const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+		return Boolean(pkg.scripts?.build);
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/lib/build-addon.ts
+/**
+* @description Builds a single addon by running the config's `build` command with cwd set to the
+* addon directory. Static addons carry no build step, so they resolve immediately as successful.
+* stdout and stderr are inherited so the build's own output surfaces live.
+* @param addon The addon to build.
+* @param buildCommand The shell command to run in the addon directory.
+* @returns Whether the build succeeded (always `true` for static addons).
+*/
+function buildAddon(addon, buildCommand) {
+	if (addon.static) return Promise.resolve(true);
+	return new Promise((resolve) => {
+		const child = spawn(buildCommand, {
+			cwd: addon.dir,
+			shell: true,
+			stdio: "inherit"
+		});
+		child.on("error", () => resolve(false));
+		child.on("close", (code) => resolve(code === 0));
+	});
+}
+//#endregion
+//#region src/commands/build.ts
+const buildCommand = {
+	name: "build",
+	description: "Build every addon in the workspace once, reporting per-addon success and failure.",
+	surfaces: {
+		cli: true,
+		mcp: false
+	},
+	schema: z.object({}),
+	async handler() {
+		const resolved = loadConfig();
+		const addons = await discoverAddons(resolved);
+		if (addons.length === 0) return {
+			ok: true,
+			text: "No addons found."
+		};
+		const failed = [];
+		for (const addon of addons) {
+			if (addon.static) {
+				process.stdout.write(`Skipping ${addon.id} (static addon).\n`);
+				continue;
+			}
+			process.stdout.write(`Building ${addon.id}…\n`);
+			if (await buildAddon(addon, resolved.config.build)) process.stdout.write(`Built ${addon.id}.\n`);
+			else {
+				failed.push(addon.id);
+				process.stderr.write(`Failed to build ${addon.id}.\n`);
+			}
+		}
+		if (failed.length > 0) return {
+			ok: false,
+			text: `Failed to build: ${failed.join(", ")}.`
+		};
+		return {
+			ok: true,
+			text: "All addons built."
+		};
+	}
+};
+//#endregion
+//#region src/lib/format.ts
+/**
+* @description Renders an {@link EvalResult} into the human-readable transcript both surfaces print:
+* captured console output first, then the value or error, each under its own header.
+* @param result The device's eval result.
+* @returns The formatted transcript.
+*/
+function formatResult(result) {
+	const parts = [];
+	if (result.logs?.length) parts.push("--- console ---", result.logs.map(formatLog).join("\n"));
+	if (result.ok) parts.push("--- result ---", result.value ?? "undefined");
+	else parts.push("--- error ---", result.error ?? "Unknown error.");
+	return parts.join("\n");
+}
+/**
+* @description Renders a single {@link LogMessage} as a level-tagged line for the console transcript.
+* @param log The captured log line.
+* @returns The `[level] message` line.
+*/
+function formatLog(log) {
+	return `[${log.level === 3 ? "error" : log.level === 2 ? "warn" : "log"}] ${log.message}`;
+}
+//#endregion
+//#region src/commands/eval.ts
+const evalCommand = {
+	name: "eval",
+	description: "Evaluate JavaScript inside the running Unbound client on the connected device and return its result plus any console output the code produced. Use this to inspect the live runtime: read globals (e.g. `unbound.metro`), call APIs, and probe Discord internals. The last expression is the return value; `console.log`/`warn`/`error` are captured separately.",
+	surfaces: {
+		cli: true,
+		mcp: true
+	},
+	schema: z.object({
+		code: z.string().describe("The JavaScript to evaluate on the device."),
+		port: z.number().default(DEFAULT_BRIDGE_PORT).describe("The port the debugger bridge listens on.")
+	}),
+	cli: { positionals: ["code"] },
+	async handler({ code }, { client }) {
+		await waitForDevice(client);
+		if (!client.isDeviceConnected) return {
+			ok: false,
+			text: "No device is connected to the debugger. Launch the app so its debugger dials the bridge, then retry."
+		};
+		const result = await client.evaluate(code);
+		return {
+			ok: result.ok,
+			text: formatResult(result),
+			data: result
+		};
+	}
+};
+//#endregion
+//#region src/lib/reload-transport.ts
+/**
+* The shipped transport: hot reload is not yet wired, so it only reports that the app must be
+* restarted for the rebuild to take effect. The real mechanism swaps this out without touching
+* `ubd dev`.
+*/
+const stubReloadTransport = { async reload(addon) {
+	process.stdout.write(`Rebuilt ${addon.id}, but hot reload is not yet available — restart the app to load it.\n`);
+} };
+//#endregion
+//#region src/lib/dev-server.ts
+/** How long file changes inside one addon settle before that addon rebuilds. */
+const DEBOUNCE_MS = 150;
+/**
+* Watches every discovered addon and rebuilds only the addon whose files changed, debounced per
+* addon. Directory creates and deletes under the workspace re-run discovery so addons added or
+* removed while the server runs are picked up. After each successful build the reload transport is
+* called; static addons skip the build step but still count as a successful build for reload.
+*/
+var DevServer = class {
+	resolved;
+	transport;
+	watcher = null;
+	addons = /* @__PURE__ */ new Map();
+	timers = /* @__PURE__ */ new Map();
+	constructor(resolved, transport) {
+		this.resolved = resolved;
+		this.transport = transport;
+	}
+	/** @description Runs initial discovery, builds every addon once, then watches until {@link stop}ped. */
+	async start() {
+		await this.rediscover();
+		for (const addon of this.addons.values()) await this.rebuild(addon);
+		this.watcher = watch(this.resolved.dir, { recursive: true }, (_event, filename) => {
+			if (!filename) return;
+			this.onChange(resolve(this.resolved.dir, filename));
+		});
+	}
+	/** @description Tears the server down, clearing the watcher and any pending rebuilds. Twin of {@link start}. */
+	stop() {
+		this.watcher?.close();
+		this.watcher = null;
+		for (const timer of this.timers.values()) clearTimeout(timer);
+		this.timers.clear();
+	}
+	onChange(changedPath) {
+		if (isIgnoredPath(changedPath)) return;
+		if (isManifestPath(changedPath)) {
+			this.rediscover();
+			return;
+		}
+		const addon = this.findOwner(changedPath);
+		if (!addon) return;
+		if (!addon.static && isInside(changedPath, addon.output)) return;
+		this.scheduleRebuild(addon);
+	}
+	scheduleRebuild(addon) {
+		const existing = this.timers.get(addon.dir);
+		if (existing) clearTimeout(existing);
+		const timer = setTimeout(() => {
+			this.timers.delete(addon.dir);
+			this.rebuild(addon);
+		}, DEBOUNCE_MS);
+		this.timers.set(addon.dir, timer);
+	}
+	async rebuild(addon) {
+		if (!addon.static) process.stdout.write(`Building ${addon.id}…\n`);
+		if (!await buildAddon(addon, this.resolved.config.build)) {
+			process.stderr.write(`Failed to build ${addon.id}.\n`);
+			return;
+		}
+		if (!addon.static) process.stdout.write(`Built ${addon.id}.\n`);
+		await this.transport.reload(toBuiltAddon(addon));
+	}
+	async rediscover() {
+		const discovered = await discoverAddons(this.resolved);
+		const next = new Map(discovered.map((addon) => [addon.dir, addon]));
+		for (const dir of this.addons.keys()) if (!next.has(dir)) process.stdout.write(`Addon at ${dir} removed.\n`);
+		for (const [dir, addon] of next) if (!this.addons.has(dir)) process.stdout.write(`Discovered addon ${addon.id}.\n`);
+		this.addons = next;
+	}
+	findOwner(changedPath) {
+		for (const addon of this.addons.values()) if (isInside(changedPath, addon.dir)) return addon;
+	}
+};
+/** Directory names whose contents are never source and would otherwise churn the watcher. */
+const IGNORED_SEGMENTS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+function isIgnoredPath(changedPath) {
+	return changedPath.split(sep).some((segment) => IGNORED_SEGMENTS.has(segment));
+}
+function isInside(changedPath, dir) {
+	return changedPath === dir || changedPath.startsWith(dir + sep);
+}
+function isManifestPath(changedPath) {
+	return changedPath.endsWith(join(sep, "manifest.json"));
+}
+function toBuiltAddon(addon) {
+	return {
+		id: addon.id,
+		kind: addon.kind,
+		dir: addon.dir,
+		output: addon.output
+	};
+}
+//#endregion
+//#region src/registry.ts
+/**
+* Every command defined once, from which both surfaces derive: the CLI adapter builds a cleye
+* command per entry, the MCP adapter registers a tool for each entry opted into `surfaces.mcp`.
+*/
+const commands = [
+	evalCommand,
+	buildCommand,
+	{
+		name: "dev",
+		description: "Watch every addon in the workspace and rebuild only the addon whose files change, reloading it in the running client after each successful build. Runs until interrupted.",
+		surfaces: {
+			cli: true,
+			mcp: false
+		},
+		schema: z.object({}),
+		async handler() {
+			const server = new DevServer(loadConfig(), stubReloadTransport);
+			process.on("SIGINT", () => {
+				server.stop();
+				process.exit(0);
+			});
+			await server.start();
+			return new Promise(() => {});
+		}
+	},
+	createCommand
+];
+//#endregion
+//#region src/commands/mcp.ts
+/**
+* @description The `ubd mcp` command: a stdio MCP server exposing every registry entry opted into
+* `surfaces.mcp`, each riding a single long-lived controller connection to the bridge. This is the
+* relocated debugger MCP, now registry-driven.
+*/
+const mcpCommand = command({
+	name: "mcp",
+	description: "Serve the debugger as a stdio MCP server for AI clients.",
+	flags: { port: {
+		type: Number,
+		description: "The port the debugger bridge listens on.",
+		default: DEFAULT_BRIDGE_PORT
+	} }
+}, async (parsed) => {
+	const context = createContext(parsed.flags.port);
+	const server = new McpServer({
+		name: "ubd",
+		version: "1.0.0"
+	});
+	for (const definition of commands) {
+		if (!definition.surfaces.mcp) continue;
+		toMcpTool(server, definition, context);
+	}
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+});
+//#endregion
+//#region src/lib/menu.ts
+/** Concise, menu-friendly summaries keyed by command name; the registry descriptions are tuned for
+* the MCP surface and too long for a tidy list. Presentation copy belongs at the CLI edge. */
+const SUMMARIES = {
+	create: "Scaffold a new addon or workspace.",
+	dev: "Watch addons and rebuild on change.",
+	build: "Build every addon in the workspace.",
+	eval: "Run JavaScript on the connected device.",
+	mcp: "Serve the debugger as an MCP server."
+};
+/** The order commands appear in the menu, most-reached-for first. */
+const ORDER = [
+	"create",
+	"dev",
+	"build",
+	"eval",
+	"mcp"
+];
+/**
+* @description Renders the branded `ubd` menu shown when the CLI runs with no command: a colored
+* banner, every command with a one-line summary, and usage hints. Command names are sourced from the
+* registry (plus the standalone `mcp` command) so a new command surfaces here once it is registered.
+* @returns The menu as a single printable string.
+*/
+function renderMenu() {
+	const names = /* @__PURE__ */ new Set([...commands.map((command) => command.name), "mcp"]);
+	const ordered = [...ORDER.filter((name) => names.has(name)), ...[...names].filter((name) => !ORDER.includes(name))];
+	const width = Math.max(...ordered.map((name) => name.length));
+	const rows = ordered.map((name) => {
+		return `  ${pc.green(name.padEnd(width))}   ${pc.dim(SUMMARIES[name] ?? "")}`;
+	});
+	return [
+		"",
+		`  ${pc.bold(pc.magenta("ubd"))} ${pc.dim("· the Unbound addon toolkit")}`,
+		"",
+		`  ${pc.bold("Usage")}`,
+		`  ${pc.cyan("ubd")} ${pc.yellow("<command>")} ${pc.dim("[flags]")}`,
+		"",
+		`  ${pc.bold("Commands")}`,
+		...rows,
+		"",
+		`  ${pc.dim("Run")} ${pc.cyan("ubd <command> --help")} ${pc.dim("for details.")}`,
+		`  ${pc.dim("New here? Start with")} ${pc.cyan("ubd create")}${pc.dim(".")}`,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/index.ts
+const argv = cli({
+	name: "ubd",
+	commands: [...commands.map(toCleyeCommand), mcpCommand]
+});
+if (!argv.command && argv._.length === 0 && !argv.flags.help && !argv.flags.version) process.stdout.write(`${renderMenu()}\n`);
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@unbound-app/cli",
+	"version": "0.1.0",
+	"description": "The `ubd` command line for the Unbound client: evaluate on-device code and serve the debugger as an MCP.",
+	"author": {
+		"name": "Mario P.",
+		"email": "contact@marioparaschiv.com",
+		"url": "https://github.com/marioparaschiv"
+	},
+	"bin": {
+		"ubd": "./dist/index.mjs"
+	},
+	"files": [
+		"dist",
+		"templates"
+	],
+	"type": "module",
+	"module": "./dist/index.mjs",
+	"scripts": {
+		"build": "tsdown"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.7.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@unbound-app/debugger-protocol": "0.1.0",
+		"cleye": "^1.3.4",
+		"picocolors": "^1.1.1",
+		"zod": "^4.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"tsdown": "^0.22.9"
+	},
+	"peerDependencies": {
+		"typescript": "^5.9.3"
+	}
+}

package/templates/plugin/index.tsx

@@ -0,0 +1,21 @@
+import { metro, patcher } from '@unbound-app/api';
+
+const unpatches: (() => void)[] = [];
+
+export default {
+	start() {
+		const UserStore = metro.findByProps('getCurrentUser', 'getUser');
+
+		unpatches.push(
+			patcher.after(UserStore, 'getCurrentUser', ({ result }) => {
+				console.log('[{{displayName}}] getCurrentUser returned', result?.username);
+			}),
+		);
+	},
+
+	stop() {
+		for (const unpatch of unpatches) unpatch();
+
+		unpatches.length = 0;
+	},
+};

package/templates/plugin/manifest.json

@@ -0,0 +1,13 @@
+{
+	"id": "{{id}}",
+	"name": "{{displayName}}",
+	"description": "{{description}}",
+	"authors": [
+		{
+			"name": "{{authorName}}",
+			"id": "{{authorId}}"
+		}
+	],
+	"version": "1.0.0",
+	"main": "index.tsx"
+}

package/templates/plugin/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "{{name}}",
+	"version": "1.0.0",
+	"description": "{{description}}",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "rollup -c"
+	},
+	"devDependencies": {
+		"@unbound-app/api": "^1.0.0",
+		"@rollup/plugin-json": "^6.1.0",
+		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@types/react": "^19.2.17",
+		"react-native": "^0.86.0",
+		"rollup": "^4.62.2",
+		"rollup-plugin-iife": "^0.8.0",
+		"rollup-plugin-swc3": "^0.12.1"
+	}
+}

package/templates/plugin/rollup.config.mjs

@@ -0,0 +1,27 @@
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import { swc } from 'rollup-plugin-swc3';
+import json from '@rollup/plugin-json';
+import iife from 'rollup-plugin-iife';
+
+const globals = {
+	'@unbound-app/api': 'window.unbound',
+	'react': 'window.React',
+	'react-native': 'window.ReactNative',
+	'react-native-reanimated': 'window.unbound.metro.common.Reanimated',
+	'@react-native-clipboard/clipboard': 'window.unbound.metro.common.Clipboard',
+	'moment': 'window.unbound.metro.common.Moment',
+};
+
+/** @type {import('rollup').RollupOptions} */
+export default {
+	input: 'index.tsx',
+	external: Object.keys(globals),
+	plugins: [nodeResolve(), json(), swc({ tsconfig: false }), iife()],
+	output: {
+		dir: 'dist',
+		format: 'es',
+		compact: true,
+		exports: 'named',
+		globals,
+	},
+};

package/templates/repository/.github/workflows/build.yml

@@ -0,0 +1,15 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bunx ubd build

package/templates/repository/README.md

@@ -0,0 +1,28 @@
+# {{displayName}}
+
+{{description}}
+
+An [Unbound](https://unbound.rip) addon workspace scaffolded with `ubd create`.
+
+## Development
+
+```sh
+bun install
+bun run dev
+```
+
+`ubd dev` watches every addon under `plugins/` and `themes/`, rebuilding the one you change.
+
+## Building
+
+```sh
+bun run build
+```
+
+Builds every addon once into its `dist/` directory.
+
+## Learn more
+
+- Plugins: https://docs.unbound.rip/plugins/introduction
+- Themes: https://docs.unbound.rip/themes/introduction
+- Manifest reference: https://docs.unbound.rip/addons/manifest

package/templates/repository/gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

package/templates/repository/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "{{name}}",
+	"version": "1.0.0",
+	"private": true,
+	"type": "module",
+	"workspaces": [
+		"plugins/*",
+		"themes/*"
+	],
+	"scripts": {
+		"dev": "ubd dev",
+		"build": "ubd build"
+	},
+	"devDependencies": {
+		"@unbound-app/cli": "^1.0.0"
+	}
+}

package/templates/repository/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"lib": ["ESNext"],
+		"jsx": "react-jsx",
+		"strict": true,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"resolveJsonModule": true,
+		"noEmit": true
+	},
+	"include": ["plugins", "themes"]
+}

package/templates/repository/unbound.config.json

@@ -0,0 +1,6 @@
+{
+	"$schema": "https://docs.unbound.rip/schemas/config.json",
+	"addons": ["plugins/*", "themes/*"],
+	"build": "bun run build",
+	"output": "dist"
+}

package/templates/theme/manifest.json

@@ -0,0 +1,13 @@
+{
+	"id": "{{id}}",
+	"name": "{{displayName}}",
+	"description": "{{description}}",
+	"authors": [
+		{
+			"name": "{{authorName}}",
+			"id": "{{authorId}}"
+		}
+	],
+	"version": "1.0.0",
+	"main": "{{main}}.json"
+}

package/templates/theme/{{main}}.json

@@ -0,0 +1,10 @@
+{
+	"type": "darker",
+	"semantic": {
+		"BACKGROUND_PRIMARY": {
+			"type": "color",
+			"value": "#1a1a2e"
+		}
+	},
+	"raw": {}
+}