@unbound-app/cli 0.11.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unbound-app/cli",
-	"version": "0.11.0",
+	"version": "1.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.",
@@ -21,20 +21,51 @@
 	],
 	"type": "module",
 	"module": "./dist/index.mjs",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs"
+		},
+		"./rollup": {
+			"types": "./dist/rollup/index.d.mts",
+			"import": "./dist/rollup/index.mjs"
+		},
+		"./oxlint": {
+			"types": "./dist/oxlint/plugin.d.mts",
+			"import": "./dist/oxlint/plugin.mjs"
+		}
+	},
 	"scripts": {
 		"build": "tsdown",
 		"typecheck": "bun run --filter @unbound-app/web build:types && tsc --noEmit -p ."
 	},
 	"dependencies": {
-		"@clack/prompts": "^1.7.0",
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@unbound-app/debugger-protocol": "0.9.0",
-		"better-auth": "1.7.12",
+		"@babel/core": "^7.29.7",
+		"@babel/plugin-syntax-jsx": "^8.0.1",
+		"@babel/plugin-transform-block-scoping": "^8.0.10",
+		"@babel/preset-typescript": "^8.0.7",
+		"@clack/prompts": "^1.8.1",
+		"@modelcontextprotocol/sdk": "^1.32.2",
+		"@rollup/plugin-commonjs": "^29.0.3",
+		"@rollup/plugin-json": "^6.1.0",
+		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@unbound-app/debugger-protocol": "0.11.0",
+		"@unbound-app/rollup-plugin-hermes": "2.0.0",
+		"better-auth": "1.7.16",
 		"cleye": "^2.7.0",
+		"magic-string": "^1.4.5",
+		"marked": "^18.1.3",
 		"picocolors": "^1.1.1",
-		"zod": "^4.0.0"
+		"rolldown": "^1.2.16",
+		"rollup": "^4.67.5",
+		"rollup-plugin-iife": "^0.8.0",
+		"rollup-plugin-swc3": "^0.12.1",
+		"sharp": "^0.35.5",
+		"thumbhash": "^0.1.1",
+		"typebox": "^1.4.4",
+		"typescript-api": "npm:typescript@5.9.3"
 	},
 	"peerDependencies": {
-		"typescript": "^5.9.3"
+		"typescript": "^7.0.2"
 	}
 }

package/templates/plugin/ADDON.md

@@ -0,0 +1,9 @@
+---
+banner: media/banner.png
+---
+
+{{description}}
+
+## Settings
+
+- **Greet on start**. Shows a greeting when the plugin starts. On by default.

package/templates/plugin/bunfig.toml

@@ -0,0 +1,3 @@
+[test]
+# Serves the plugin's manifest, translations, settings and a fake Unbound API to every test.
+preload = ["@unbound-app/api/testing/preset"]

package/templates/plugin/gitignore

@@ -0,0 +1,2 @@
+node_modules
+# src/unbound-i18n.d.ts and src/unbound-settings.d.ts are generated, but committed so the editor works before a build.

package/templates/plugin/i18n/en-US.json

@@ -0,0 +1,5 @@
+{
+	"GREETING_BODY": "{name} is running.",
+	"GREET_ON_START": "Greet on start",
+	"GREET_ON_START_SUBTITLE": "Show a greeting when the plugin starts."
+}

package/templates/plugin/oxlintrc.json

@@ -0,0 +1,9 @@
+{
+	"jsPlugins": [{ "name": "unbound", "specifier": "@unbound-app/cli/oxlint" }],
+	"ignorePatterns": ["dist", "src/unbound-i18n.d.ts", "src/unbound-settings.d.ts"],
+	"rules": {
+		"unbound/no-window-unbound": "error",
+		"unbound/platform-check-only-in-platform-file": "error",
+		"unbound/no-module-scope-lookup": ["error", { "lazyByDefault": true }]
+	}
+}

package/templates/plugin/package.json

@@ -5,15 +5,19 @@
 	"private": true,
 	"type": "module",
 	"scripts": {
-		"build": "rollup -c"
+		"build": "rollup -c",
+		"lint": "oxlint",
+		"test": "bun test"
 	},
 	"devDependencies": {
-		"@unbound-app/api": "latest",
-		"@rollup/plugin-json": "^6.1.0",
-		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@types/bun": "latest",
 		"@types/react": "^19.2.7",
-		"react-native": "^0.83.0",
-		"rollup": "^4.62.2",
-		"rollup-plugin-swc3": "^0.12.1"
+		"@unbound-app/api": "latest",
+		"@unbound-app/cli": "latest",
+		"oxlint": "^1.91.0",
+		"react": "^19.3.1",
+		"react-native": "^0.86.0",
+		"rollup": "^4.67.5",
+		"typescript": "^7.0.2"
 	}
 }

package/templates/plugin/rollup.config.mjs

@@ -1,43 +1,3 @@
-import { nodeResolve } from '@rollup/plugin-node-resolve';
-import { swc } from 'rollup-plugin-swc3';
-import json from '@rollup/plugin-json';
+import { unbound } from '@unbound-app/cli/rollup';
 
-const globals = {
-	'@unbound-app/api': 'window.unbound',
-	// The bare name reaches the React Unbound passes the bundle, which keeps components' state on hot refresh.
-	'react': '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',
-};
-
-const hot = process.env.UNBOUND_HOT === '1';
-
-function keepIifeUnnamedForUnbound(level, log, handler) {
-	if (log.code !== 'MISSING_NAME_OPTION_FOR_IIFE_EXPORT') {
-		handler(level, log);
-	}
-}
-
-/** @type {import('rollup').RollupOptions} */
-export default {
-	input: 'index.tsx',
-	external: Object.keys(globals),
-	plugins: [
-		nodeResolve(),
-		json(),
-		swc({
-			tsconfig: false,
-			jsc: { transform: { react: { refresh: hot, development: hot } } },
-		}),
-	],
-	onLog: keepIifeUnnamedForUnbound,
-	output: {
-		dir: 'dist',
-		format: 'iife',
-		compact: true,
-		exports: 'named',
-		globals,
-	},
-};
+export default unbound(import.meta.url);

package/templates/plugin/settings.ts

@@ -0,0 +1,9 @@
+import { defineSettings, setting } from '@unbound-app/settings/schema';
+
+export default defineSettings({
+	greetOnStart: setting.boolean({
+		default: true,
+		title: 'GREET_ON_START',
+		subtitle: 'GREET_ON_START_SUBTITLE',
+	}),
+});

package/templates/plugin/src/index.tsx

@@ -0,0 +1,11 @@
+import { settings } from '@unbound-app/settings';
+import { toasts } from '@unbound-app/api';
+
+import icon from '../assets/icon.png';
+
+/** Greets the user, unless they turned the greeting off. */
+export function start() {
+	if (!settings.greetOnStart) return;
+
+	toasts.success('GREETING_BODY', { name: addon.name }, { icon });
+}

package/templates/plugin/src/unbound-i18n.d.ts

@@ -0,0 +1,39 @@
+// Generated by ubd from i18n/en-US.json. Do not edit: `ubd build` and `ubd dev` rewrite it.
+
+declare module '@unbound-app/i18n' {
+	/** Every en-US message, read in the user's locale. */
+	export type Messages = {
+		/** {name} is running. */
+		readonly GREETING_BODY: string;
+		/** Greet on start */
+		readonly GREET_ON_START: string;
+		/** Show a greeting when the plugin starts. */
+		readonly GREET_ON_START_SUBTITLE: string;
+	};
+
+	/** The placeholder values each message that has placeholders takes. */
+	export type FormatVars = {
+		GREETING_BODY: { name: string | number };
+	};
+
+	/** Each message in the user's locale, falling back to en-US. */
+	export const messages: Messages;
+	/** Formats a message that has no placeholders. */
+	export function format(key: Exclude<keyof Messages, keyof FormatVars>): string;
+	/** Formats a message, filling its placeholders from `vars`. */
+	export function format<K extends keyof FormatVars>(key: K, vars: FormatVars[K]): string;
+	/**
+	 * Re-renders the component when the user's locale changes or its translation loads, and returns the locale code.
+	 * The build adds it to components and hooks that read `messages` or `format`.
+	 */
+	export function useMessages(): string;
+
+	/** Every key of the plugin's en-US.json. */
+	export type MessageKey = keyof Messages;
+
+	global {
+		/** Gives the plugin's commands, toasts and dialogs its message keys. */
+		// oxlint-disable-next-line typescript/consistent-type-definitions -- merging needs an interface.
+		interface UnboundMessageKeys extends Record<MessageKey, true> {}
+	}
+}

package/templates/plugin/src/unbound-settings.d.ts

@@ -0,0 +1,174 @@
+// Generated by ubd from settings.ts and i18n/en-US.json. Do not edit: `ubd build` and `ubd dev` rewrite it.
+
+declare module '@unbound-app/settings/schema' {
+	/** A message key of this plugin's i18n/en-US.json. */
+	export type MessageKey = import('@unbound-app/i18n').MessageKey;
+	type HexColor = import('@unbound-app/settings').HexColor;
+	type HttpUrl = import('@unbound-app/settings').HttpUrl;
+	type Snowflake = import('@unbound-app/settings').Snowflake;
+	type EmojiString = import('@unbound-app/settings').EmojiString;
+	type Settings = import('@unbound-app/settings').Settings;
+	type ActionName = import('@unbound-app/settings').ActionName;
+	type Never<K extends string> = { [P in K]?: never };
+
+	const stored: unique symbol;
+	const item: unique symbol;
+	const section: unique symbol;
+	const button: unique symbol;
+	const notice: unique symbol;
+	const definition: unique symbol;
+
+	/** A stored setting, from one of the `setting` builders. */
+	export type Setting = { readonly [stored]: true };
+	/** An `array` item, from `setting.string()` or `setting.choice({ options })`; `T` is its value. */
+	export type Item<T> = { readonly [item]: T };
+	/** A section from `setting.section`. */
+	export type Section = { readonly [section]: true };
+	/** A button row from `setting.button`; it stores nothing. */
+	export type Button = { readonly [button]: true };
+	/** A notice row from `setting.notice`; it stores nothing. */
+	export type Notice = { readonly [notice]: true };
+	/** What `defineSettings` returns: the default export of settings.ts. */
+	export type SettingsDefinition = { readonly [definition]: true };
+
+	/** Shows the row only while it holds: a predicate of every setting, defaults applied, or a boolean setting's key. */
+	export type Condition = ((settings: Settings) => boolean) | import('@unbound-app/settings').BooleanSettingKey;
+
+	/** What every setting, section and button takes. A hidden setting needs no title. */
+	export type Common = {
+		/** The row's sub-label. */
+		subtitle?: MessageKey;
+		visibleWhen?: Condition;
+		disabledWhen?: Condition;
+		/** Changing it shows a hint to restart Discord. */
+		requiresRestart?: boolean;
+	} & (
+		| { /** Stored and typed, but not drawn. */ hidden: true; title?: MessageKey }
+		| { hidden?: false; /** The row's label or the section's title. */ title: MessageKey }
+	);
+
+	type Range = { min?: number; max?: number };
+	type NumberDisplay<Step> =
+		| ({ displayAs?: 'input' } & Range & Never<'step' | 'units'>)
+		| ({ /** The default when `min` and `max` are set. */ displayAs?: 'slider'; min: number; max: number; step?: number } & Never<'units'>)
+		| ({ displayAs: 'stepper' } & Range & Step & Never<'units'>)
+		| ({ displayAs: 'duration'; /** The units offered, smallest first. */ units?: ('ms' | 's' | 'm' | 'h' | 'd')[] } & Range & Never<'step'>);
+
+	type TextOptions = { minLength?: number; maxLength?: number; placeholder?: MessageKey };
+	type ColorOptions = { alpha?: boolean; default: HexColor } & (
+		| { palette?: false; presets?: HexColor[] }
+		| { /** Draws `presets` inline. */ palette: true; presets: [HexColor, ...HexColor[]] }
+	);
+	type StringDisplay =
+		| ({ displayAs?: 'input' | 'multiline'; default: string } & TextOptions & Never<'alpha' | 'presets' | 'palette' | 'maxSize'>)
+		| ({ displayAs: 'secret'; default: string; placeholder?: MessageKey } & Never<'minLength' | 'maxLength' | 'alpha' | 'presets' | 'palette' | 'maxSize'>)
+		| ({ displayAs: 'url'; default: HttpUrl | ''; placeholder?: MessageKey } & Never<'minLength' | 'maxLength' | 'alpha' | 'presets' | 'palette' | 'maxSize'>)
+		| ({ displayAs: 'color' } & ColorOptions & Never<'minLength' | 'maxLength' | 'placeholder' | 'maxSize'>)
+		| ({ displayAs: 'image'; default?: string; /** The largest file, in bytes. */ maxSize?: number } & Never<'minLength' | 'maxLength' | 'placeholder' | 'alpha' | 'presets' | 'palette'>)
+		| ({ displayAs: 'font'; default?: string } & Never<'minLength' | 'maxLength' | 'placeholder' | 'alpha' | 'presets' | 'palette' | 'maxSize'>)
+		| ({ /** `name`, or `name:id` for a custom emoji. */ displayAs: 'emoji'; default?: EmojiString } & Never<'minLength' | 'maxLength' | 'placeholder' | 'alpha' | 'presets' | 'palette' | 'maxSize'>)
+		| ({ displayAs: 'user' | 'channel' | 'guild' | 'role'; default?: Snowflake | '' } & Never<'minLength' | 'maxLength' | 'placeholder' | 'alpha' | 'presets' | 'palette' | 'maxSize'>);
+
+	/** An option's label: a message key, or a title and a subtitle a radio group shows under it. */
+	export type OptionLabel = MessageKey | { title: MessageKey; subtitle?: MessageKey };
+	type Options = Record<string, OptionLabel>;
+
+	/** The builders, one per stored primitive; `displayAs` picks the widget. */
+	export const setting: {
+		/** A `boolean`: a switch, or a checkbox. */
+		boolean(options: Common & { default: boolean; displayAs?: 'switch' | 'checkbox' }): Setting;
+		/** A `number`: an input; a slider with `min` and `max`; a stepper, which needs `step`; or a duration in milliseconds. */
+		number(options: Common & { default: number } & NumberDisplay<{ step: number }>): Setting;
+		/** A whole `number`: an input; a slider with `min` and `max`; a stepper; or a duration in milliseconds. */
+		integer(options: Common & { default: number } & NumberDisplay<{ step?: number }>): Setting;
+		/** A `string` item of an `array`. */
+		string(): Item<string>;
+		/** A `string`: an input, a multiline input, a secret, a URL, a color, an image, a font, an emoji or a Discord entity. */
+		string(options: Common & StringDisplay): Setting;
+		/** A choice item of an `array`. */
+		choice<const O extends Options>(options: { options: O }): Item<keyof O & string>;
+		/** One of `options`' keys: a radio group (up to 5 options), a picker sheet (more), or a segmented control (up to 4). */
+		choice<const O extends Options>(
+			options: Common & { options: O; default: NoInfer<keyof O & string>; displayAs?: 'radio' | 'picker' | 'segmented' },
+		): Setting;
+		/** A list of `of`: strings as an editable list or a Discord entity picker, choices as checkboxes. */
+		array<const T>(
+			options: Common & { of: Item<T>; default?: NoInfer<T>[]; minItems?: number; maxItems?: number } & (string extends T
+				? { displayAs?: 'list' | 'user' | 'channel' | 'guild' | 'role' }
+				: { displayAs?: 'checkboxes' }),
+		): Setting;
+		/** A section of settings, titled by `title`. */
+		section(
+			options: Common & { displayAs?: 'group' | 'collapsible' },
+			properties: Record<string, Setting | Button | Notice>,
+		): Section;
+		/** A button row that calls `action`, a function src/actions.ts exports, asking `confirm` first when set. */
+		button(
+			options: Common & { action: ActionName; confirm?: MessageKey; displayAs?: 'button' | 'danger' },
+		): Button;
+		/** A message row, shown while `visibleWhen` holds; it stores nothing. `tone` is `info` unless set. */
+		notice(options: {
+			title: MessageKey;
+			subtitle?: MessageKey;
+			tone?: 'info' | 'warning' | 'danger';
+			visibleWhen?: Condition;
+		}): Notice;
+	};
+
+	/** Declares the plugin's settings; `title` names the section holding the top-level ones. */
+	export function defineSettings(
+		properties: Record<string, Setting | Section | Button | Notice>,
+		options?: { title?: MessageKey },
+	): SettingsDefinition;
+}
+
+declare module '@unbound-app/settings' {
+	/** A `color` setting: `#RRGGBB`, or `#RRGGBBAA` with `alpha`. */
+	export type HexColor = import('@unbound-app/api/types').HexColor;
+	/** A `url` setting: an http or https URL. */
+	export type HttpUrl = import('@unbound-app/api/types').HttpUrl;
+	/** A Discord id, as an entity setting holds it. */
+	export type Snowflake = import('@unbound-app/api/types').Snowflake;
+	/** An `emoji` setting: a Unicode emoji or a custom emoji's name, then `:` and its id when custom. */
+	export type EmojiString = import('@unbound-app/api/types').EmojiString;
+
+	/** The plugin's settings: reads apply defaults, and writes are validated and saved to its Bucket. */
+	export type Settings = {
+		/**
+		 * Greet on start
+		 *
+		 * Show a greeting when the plugin starts.
+		 */
+		greetOnStart: boolean;
+	};
+
+	/** Each setting and section by its dot-separated key. */
+	type SettingValues = {
+		/**
+		 * Greet on start
+		 *
+		 * Show a greeting when the plugin starts.
+		 */
+		"greetOnStart": boolean;
+	};
+
+	/** Every setting and section by its dot-separated key; buttons and notices are not settings. */
+	export type SettingKey = keyof SettingValues;
+	/** The value of the setting or section at `K`. */
+	export type SettingsEntry<K extends SettingKey> = SettingValues[K];
+
+	/** The functions src/actions.ts exports, which a `setting.button` can run. */
+	export type ActionName = never;
+
+	/** The keys of the boolean settings, which `visibleWhen` and `disabledWhen` can name. */
+	export type BooleanSettingKey = "greetOnStart";
+
+	/** The plugin's settings. Assign a property, a section's too, to save it. */
+	export const settings: Settings;
+	/** Reads a setting or a whole section, and re-renders the component when it changes. */
+	export function useSetting<K extends SettingKey>(key: K): SettingsEntry<K>;
+	/** Puts every setting back to its default. */
+	export function resetSettings(): void;
+	/** The settings panel generated from settings.ts; a custom `getSettingsPanel` can render it too. */
+	export function SettingsPanel(): import('react').ReactElement;
+}

package/templates/plugin/tests/index.test.ts

@@ -0,0 +1,22 @@
+import { startPlugin, stopPlugin, toasts } from '@unbound-app/api/testing';
+import { settings } from '@unbound-app/settings';
+import { describe, expect, test } from 'bun:test';
+
+describe('start', () => {
+	test('greets with the plugin name', async () => {
+		await startPlugin();
+
+		expect(toasts.shown).toMatchObject([
+			{ key: 'GREETING_BODY', title: '{{displayName}} is running.' },
+		]);
+		await stopPlugin();
+	});
+
+	test('stays quiet when greetOnStart is off', async () => {
+		settings.greetOnStart = false;
+		await startPlugin();
+
+		expect(toasts.shown).toEqual([]);
+		await stopPlugin();
+	});
+});

package/templates/plugin/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"lib": ["ESNext"],
+		"jsx": "react-jsx",
+		"strict": true,
+		"skipLibCheck": true,
+		"resolveJsonModule": true,
+		"noEmit": true,
+		"types": ["bun", "@unbound-app/api/global"],
+		"paths": {
+			"~/*": ["./src/*"]
+		}
+	},
+	"include": ["src", "tests", "settings.ts"]
+}

package/templates/plugin/index.tsx

@@ -1,21 +0,0 @@
-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;
-	},
-};