bref-ui 0.3.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bref contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/cli/commands/add/approve-overwrites.ts

@@ -0,0 +1,17 @@
+import type { PreviewChange } from '../../installation/types.js';
+import { confirm } from './utils.js';
+
+/**
+ * Request an individual approval for each conflicting file in preview order.
+ * @param changes Full preview; additions and identical files need no overwrite approval.
+ * @returns Approved relative paths, or null on the first declined or closed prompt.
+ * No further prompts are shown after cancellation and no files are written.
+ * @throws When reading a confirmation fails.
+ */
+export const approveOverwrites = (changes: PreviewChange[]): string[] | null =>
+	changes
+		.filter(({ status }) => status === 'conflict')
+		.reduce<string[] | null>((approved, { path }) => {
+			if (approved === null) return null;
+			return confirm(`Overwrite ${path}?`) ? [...approved, path] : null;
+		}, []);

package/cli/commands/add/display-changes.ts

@@ -0,0 +1,11 @@
+import type { PreviewChange } from '../../installation/types.js';
+
+/**
+ * Print every preview status and its path relative to the configured UI directory.
+ * @param changes Ordered additions, identical files and conflicts to display.
+ * @throws When writing the terminal output fails.
+ */
+export const displayChanges = (changes: PreviewChange[]): void => {
+	console.log('Planned UI changes:');
+	console.log(changes.map(({ status, path }) => `  ${status}: ${path}`).join('\n'));
+};

package/cli/commands/add/index.ts

@@ -0,0 +1,30 @@
+import { readConfig } from '../../config/read/index.js';
+import { resolveTargetDir } from '../../config/resolve/index.js';
+import { installComponent } from '../../installation/index.js';
+import { loadRegistry } from '../../registry/load/index.js';
+import { planDependencies } from '../../registry/plan/index.js';
+import { reviewChanges } from './review-changes.js';
+
+/**
+ * Install a component and its dependencies after reviewing changes in the terminal.
+ * @param componentId Registry ID of the requested component.
+ * @param projectRoot Consumer project directory containing bref.config.json.
+ * @param sourceRoot Directory containing canonical component folders and manifests.
+ * @param aliases Project alias mappings; supplied values override the default $lib mapping.
+ * @returns installed after accepted changes are copied, or cancelled when any
+ * confirmation is declined or input closes. Cancellation writes no files.
+ * @throws When configuration, alias resolution, registry loading, planning or
+ * installation fails. Copy failures may leave partial writes and are not rolled back.
+ */
+export const addComponent = async (
+	componentId: string,
+	projectRoot: string,
+	sourceRoot: string,
+	aliases: Record<string, string> = {}
+): Promise<'installed' | 'cancelled'> => {
+	const config = await readConfig(projectRoot);
+	const destination = resolveTargetDir(projectRoot, config.ui, aliases);
+	const registry = await loadRegistry(sourceRoot);
+	const entries = planDependencies(componentId, registry);
+	return installComponent(entries, destination, reviewChanges);
+};

package/cli/commands/add/review-changes.ts

@@ -0,0 +1,18 @@
+import type { PreviewChange } from '../../installation/types.js';
+import { approveOverwrites } from './approve-overwrites.js';
+import { displayChanges } from './display-changes.js';
+import { confirm } from './utils.js';
+
+/**
+ * Show the full preview, collect overwrite approvals and confirm installation.
+ * @param changes Prepared source and index.ts changes relative to the UI directory.
+ * @returns Approved conflicting paths, or null if any confirmation is declined
+ * or input closes. An empty list accepts changes that need no overwrites.
+ * @throws When terminal output or prompting fails; destination files remain untouched.
+ */
+export const reviewChanges = async (changes: PreviewChange[]): Promise<string[] | null> => {
+	displayChanges(changes);
+	const overwrites = approveOverwrites(changes);
+	if (overwrites === null) return null;
+	return confirm('Install these changes?') ? overwrites : null;
+};

package/cli/commands/add/utils.ts

@@ -0,0 +1,11 @@
+/**
+ * Read a confirmation using Bun's native terminal prompt, defaulting to refusal.
+ * @param message Question to display before the yes/no hint.
+ * @returns true only for y or yes, ignoring case and surrounding whitespace;
+ * empty input, other answers and closed input return false.
+ * @throws When Bun cannot read terminal input.
+ */
+export const confirm = (message: string): boolean => {
+	const answer = prompt(`${message} [y/N] `);
+	return answer !== null && /^(y|yes)$/i.test(answer.trim());
+};

package/cli/commands/execute.ts

@@ -0,0 +1,39 @@
+import { addComponent } from './add/index.js';
+import { initConfig } from './init.js';
+import type { Command } from './types.js';
+
+/**
+ * Run a validated request and print its outcome using the registry shipped beside the executable.
+ * @param command Parsed help, init or add request.
+ * @param projectRoot Consumer project directory, supplied by the executable's cwd.
+ * @throws When initialization or installation fails; the executable reports the error.
+ */
+export const execute = async (command: Command, projectRoot: string): Promise<void> => {
+	if (command.name === 'help') {
+		console.log(
+			'Usage: bref-ui <command>\n\n' +
+				'Commands:\n' +
+				'  init             Create bref.config.json with the default UI alias\n' +
+				'  add <component>  Preview and install a component and its dependencies\n\n' +
+				'Options:\n' +
+				'  -h, --help       Show this help\n\n' +
+				'Commands use the current directory as the consumer project.'
+		);
+		return;
+	}
+	if (command.name === 'init') {
+		const result = await initConfig(projectRoot);
+		console.log(
+			result === 'created' ? 'Created bref.config.json.' : 'bref.config.json already exists.'
+		);
+		return;
+	}
+
+	const sourceRoot = Bun.fileURLToPath(new URL('../../src/lib/', import.meta.url));
+	const result = await addComponent(command.componentId, projectRoot, sourceRoot);
+	console.log(
+		result === 'installed'
+			? `Installed ${command.componentId} and its dependencies.`
+			: 'Installation cancelled.'
+	);
+};

package/cli/commands/index.ts

@@ -0,0 +1,19 @@
+import { execute } from './execute.js';
+import { parse } from './parse.js';
+
+/**
+ * Parse executable arguments, run the requested command and report failures.
+ * @param args Terminal arguments after the executable filename.
+ * @param projectRoot Consumer project directory supplied by the executable's cwd.
+ * @returns After help, command completion or cancellation; these exit successfully.
+ * Invalid arguments and command failures are reported to stderr and set exit code 1.
+ */
+export const runCommand = async (args: string[], projectRoot: string): Promise<void> => {
+	try {
+		const command = parse(args);
+		await execute(command, projectRoot);
+	} catch (error) {
+		console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+		process.exitCode = 1;
+	}
+};

package/cli/commands/init.ts

@@ -0,0 +1,17 @@
+/**
+ * Create bref.config.json with the default UI alias when the file is absent.
+ * @param projectRoot Existing consumer project directory.
+ * @returns created after writing the default configuration, or exists when a
+ * configuration file is already present. Existing contents are not read or changed.
+ * @throws When checking or writing the configuration fails, including a missing
+ * project directory. The existence check and write are not atomic; concurrent
+ * initialization of the same project is unsupported.
+ */
+export const initConfig = async (projectRoot: string): Promise<'created' | 'exists'> => {
+	const config = Bun.file(`${projectRoot}/bref.config.json`);
+	if (await config.exists()) return 'exists';
+
+	const content = `${JSON.stringify({ ui: '$lib/ui' }, null, '\t')}\n`;
+	await Bun.write(config, content, { createPath: false });
+	return 'created';
+};

package/cli/commands/parse.ts

@@ -0,0 +1,24 @@
+import type { Command } from './types.js';
+
+/**
+ * Validate supported command arguments without reading or writing project files.
+ * @param args Arguments after the executable filename.
+ * @returns A help, init or add request. No arguments also requests help.
+ * @throws When a command is unknown, arguments are missing or extra, or an
+ * unsupported option is supplied.
+ */
+export const parse = (args: string[]): Command => {
+	const [name, componentId] = args;
+	if (
+		args.length === 0 ||
+		(args.length === 1 && ['help', '--help', '-h'].includes(name)) ||
+		(args.length === 2 && ['init', 'add'].includes(name) && ['--help', '-h'].includes(componentId))
+	)
+		return { name: 'help' };
+
+	if (name === 'init' && args.length === 1) return { name: 'init' };
+	if (name === 'add' && args.length === 2 && componentId.length > 0 && !componentId.startsWith('-'))
+		return { name: 'add', componentId };
+
+	throw new Error('Expected init or add <component>. Use --help for usage.');
+};

package/cli/commands/types.ts

@@ -0,0 +1,2 @@
+/** Validated executable request, before accessing the consumer project. */
+export type Command = { name: 'help' } | { name: 'init' } | { name: 'add'; componentId: string };

package/cli/config/read/index.ts

@@ -0,0 +1,15 @@
+import { normalizeConfig } from './normalize-config.js';
+import { readConfigFile } from './read-config-file.js';
+import type { BrefConfig } from '../types.js';
+
+/**
+ * Read bref.config.json, defaulting the UI alias to $lib/ui when omitted.
+ * @param projectRoot Directory containing the consumer project's configuration.
+ * @returns The supported configuration values with defaults applied.
+ * @throws When the file cannot be read or parsed, the root is not an object,
+ * or the supplied UI alias is not a string.
+ */
+export const readConfig = async (projectRoot: string): Promise<BrefConfig> => {
+	const { configPath, config } = await readConfigFile(projectRoot);
+	return normalizeConfig(configPath, config);
+};

package/cli/config/read/normalize-config.ts

@@ -0,0 +1,21 @@
+import type { BrefConfig } from '../types.js';
+
+/**
+ * Validate the supported configuration field and apply its default.
+ * @param configPath Path used to report configuration validation errors.
+ * @param config Parsed configuration JSON value.
+ * @returns The supported configuration values with defaults applied.
+ * @throws When the root is not an object or the supplied UI alias is not a string.
+ */
+export const normalizeConfig = (configPath: string, config: unknown): BrefConfig => {
+	if (typeof config !== 'object' || config === null || Array.isArray(config))
+		throw new Error(`${configPath}: expected a JSON object.`);
+
+	if ('ui' in config) {
+		if (typeof config.ui !== 'string') throw new Error(`${configPath}: "ui" must be a string.`);
+
+		return { ui: config.ui };
+	}
+
+	return { ui: '$lib/ui' };
+};

package/cli/config/read/read-config-file.ts

@@ -0,0 +1,13 @@
+/**
+ * Read and parse the consumer project's bref.config.json file.
+ * @param projectRoot Directory containing the consumer project's configuration.
+ * @returns The configuration file path and parsed JSON value.
+ * @throws When the file cannot be read or contains invalid JSON.
+ */
+export const readConfigFile = async (
+	projectRoot: string
+): Promise<{ configPath: string; config: unknown }> => {
+	const configPath = `${projectRoot}/bref.config.json`;
+	const config: unknown = await Bun.file(configPath).json();
+	return { configPath, config };
+};

package/cli/config/resolve/index.ts

@@ -0,0 +1,20 @@
+import { resolveAlias } from './resolve-alias.js';
+import { resolveAliasTarget } from './resolve-alias-target.js';
+
+/**
+ * Resolve a UI alias using the longest matching alias prefix.
+ * Supplied mappings override the default $lib mapping to src/lib.
+ * @param projectRoot Base directory for relative alias targets.
+ * @param ui Configured UI alias, optionally followed by a subdirectory.
+ * @param aliases Project alias mappings to relative or absolute directories.
+ * @returns The normalized absolute destination path, without accessing the filesystem.
+ * @throws When no alias matches the configured UI location.
+ */
+export const resolveTargetDir = (
+	projectRoot: string,
+	ui: string,
+	aliases: Record<string, string> = {}
+): string => {
+	const [alias, target] = resolveAlias(ui, aliases);
+	return resolveAliasTarget(projectRoot, ui, alias, target);
+};

package/cli/config/resolve/resolve-alias-target.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve an alias match to a normalized absolute filesystem path.
+ * @param projectRoot Base directory for relative alias targets.
+ * @param ui Configured UI alias, optionally followed by a subdirectory.
+ * @param alias Matching alias prefix.
+ * @param target Directory mapped from the alias.
+ * @returns The normalized absolute destination path, without accessing the filesystem.
+ */
+export const resolveAliasTarget = (
+	projectRoot: string,
+	ui: string,
+	alias: string,
+	target: string
+): string => {
+	const directory = target.startsWith('/') ? target : `${projectRoot}/${target}`;
+	return Bun.fileURLToPath(Bun.pathToFileURL(`${directory}${ui.slice(alias.length)}`));
+};

package/cli/config/resolve/resolve-alias.ts

@@ -0,0 +1,17 @@
+/**
+ * Find the longest configured alias prefix matching a UI path.
+ * @param ui Configured UI alias, optionally followed by a subdirectory.
+ * @param aliases Project alias mappings that override the default $lib mapping.
+ * @returns The matching alias and its destination mapping.
+ * @throws When no alias matches the configured UI location.
+ */
+export const resolveAlias = (ui: string, aliases: Record<string, string>): [string, string] => {
+	const mappings = Object.entries({ $lib: 'src/lib', ...aliases }).sort(
+		([left], [right]) => right.length - left.length
+	);
+	const match = mappings.find(([alias]) => ui === alias || ui.startsWith(`${alias}/`));
+
+	if (!match) throw new Error(`Cannot resolve UI alias "${ui}".`);
+
+	return match;
+};

package/cli/config/types.ts

@@ -0,0 +1,5 @@
+/** Supported CLI configuration after defaults have been applied. */
+export interface BrefConfig {
+	/** Destination alias for copied components; defaults to $lib/ui when omitted. */
+	ui: string;
+}

package/cli/index.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCommand } from './commands/index.js';
+
+if (import.meta.main) await runCommand(Bun.argv.slice(2), process.cwd());

package/cli/installation/copy/index.ts

@@ -0,0 +1,25 @@
+import { previewChanges } from '../preview/index.js';
+import type { PreparedFile } from '../types.js';
+import { validateOverwriteApprovals } from './validate-overwrite-approvals.js';
+import { writePreparedFiles } from './write-prepared-files.js';
+
+/**
+ * Copy prepared files after checking every conflict against explicit approvals.
+ * Call only after the user accepts the preview; cancellation must skip this call.
+ * Checks and writes are not atomic; avoid concurrent edits to the destination.
+ * @param files Prepared files with paths relative to the destination directory.
+ * @param destination Consumer project's configured UI directory.
+ * @param overwrites Relative file paths explicitly approved for overwriting.
+ * @returns Completion after all required writes; identical files are skipped.
+ * @throws Before writing when any conflict lacks approval, or when previewing fails.
+ * @throws If an addition appears before its write, or a write fails; some files may be copied.
+ */
+export const copyFiles = async (
+	files: PreparedFile[],
+	destination: string,
+	overwrites: string[] = []
+): Promise<void> => {
+	const changes = await previewChanges(files, destination);
+	validateOverwriteApprovals(changes, overwrites);
+	await writePreparedFiles(files, changes, destination);
+};

package/cli/installation/copy/validate-overwrite-approvals.ts

@@ -0,0 +1,18 @@
+import type { PreviewChange } from '../types.js';
+
+/**
+ * Reject the first conflicting path that has no explicit overwrite approval.
+ * @param changes Preview results in prepared-file order.
+ * @param overwrites Relative paths explicitly approved for overwriting.
+ * @returns Nothing when every conflict is approved.
+ * @throws When a conflict lacks overwrite approval.
+ */
+export const validateOverwriteApprovals = (
+	changes: PreviewChange[],
+	overwrites: string[]
+): void => {
+	const approved = new Set(overwrites);
+	const conflict = changes.find(({ path, status }) => status === 'conflict' && !approved.has(path));
+
+	if (conflict) throw new Error(`Overwrite approval required for "${conflict.path}".`);
+};

package/cli/installation/copy/write-prepared-files.ts

@@ -0,0 +1,26 @@
+import type { PreparedFile, PreviewChange } from '../types.js';
+
+/**
+ * Write additions and approved conflicts, skipping identical destination files.
+ * @param files Prepared files in the same order as changes.
+ * @param changes Preview results for these files.
+ * @param destination Consumer project's configured UI directory.
+ * @returns Completion after all required writes.
+ * @throws If an addition appears before its write or a write fails; some files may be copied.
+ */
+export const writePreparedFiles = async (
+	files: PreparedFile[],
+	changes: PreviewChange[],
+	destination: string
+): Promise<void> =>
+	Promise.all(
+		files.map(async ({ path, content }, index) => {
+			const { status } = changes[index];
+			if (status === 'unchanged') return;
+
+			const target = `${destination}/${path}`;
+			if (status === 'add' && (await Bun.file(target).exists()))
+				throw new Error(`Destination appeared after preview for "${path}".`);
+			await Bun.write(target, content, { createPath: true });
+		})
+	).then(() => undefined);

package/cli/installation/exports/collect-exports.ts

@@ -0,0 +1,19 @@
+import { parseScript } from '../parser/index.js';
+import { readExportedNames } from './read-exported-names.js';
+
+/**
+ * Collect public names and matching direct default re-export module paths.
+ * Null marks a different export form or a duplicate name that cannot be reused.
+ * @param content Existing index.ts content, parsed without changing its formatting.
+ * @returns Export names mapped to their reusable component module or null.
+ * @throws Invalid script syntax or an unresolved wildcard re-export.
+ */
+export const collectExports = (content: string): Map<string, string | null> => {
+	const { statements } = parseScript(content, 'index.ts');
+	return statements.reduce((exports, statement) => {
+		readExportedNames(statement).forEach(({ name, componentPath }) => {
+			exports.set(name, exports.has(name) ? null : componentPath);
+		});
+		return exports;
+	}, new Map<string, string | null>());
+};

package/cli/installation/exports/create-additions.ts

@@ -0,0 +1,26 @@
+import type { RegistryEntry } from '../../registry/types.js';
+
+/**
+ * Build missing default re-exports using each component's source folder name.
+ * @param entries Validated dependency-first registry entries.
+ * @param existing Export names already present; updated as additions are planned.
+ * @returns Missing export statements in entry and manifest order.
+ * @throws When a requested name already refers to another export.
+ */
+export const createAdditions = (
+	entries: RegistryEntry[],
+	existing: Map<string, string | null>
+): string[] => {
+	return entries.flatMap((entry) => {
+		const directory = entry.directory.split('/').filter(Boolean).at(-1);
+		return Object.entries(entry.exports).flatMap(([name, file]) => {
+			const module = `./${directory}/${file}`;
+			if (existing.has(name)) {
+				if (existing.get(name) === module) return [];
+				throw new Error(`index.ts: export "${name}" conflicts with "${module}".`);
+			}
+			existing.set(name, module);
+			return [`export { default as ${name} } from ${JSON.stringify(module)};`];
+		});
+	});
+};

package/cli/installation/exports/index.ts

@@ -0,0 +1,27 @@
+import type { RegistryEntry } from '../../registry/types.js';
+import type { PreparedFile } from '../types.js';
+import { readIndex } from './read-index.js';
+import { collectExports } from './collect-exports.js';
+import { createAdditions } from './create-additions.js';
+import { mergeContent } from './merge-content.js';
+
+/**
+ * Prepare missing component re-exports while preserving the existing index.ts text.
+ * Matching direct default re-exports are skipped; other uses of their names conflict.
+ * @param entries Validated, dependency-first entries returned by planDependencies.
+ * @param destination Absolute consumer UI directory containing index.ts.
+ * @returns The prepared index.ts for the existing preview and copy stages; no writes occur.
+ * @throws When reading or parsing fails, an export name conflicts, or a wildcard
+ * export prevents determining which names are already exported.
+ */
+export const prepareExports = async (
+	entries: RegistryEntry[],
+	destination: string
+): Promise<PreparedFile> => {
+	const content = await readIndex(destination);
+	if (entries.length === 0) return { path: 'index.ts', content };
+
+	const existing = collectExports(content);
+	const additions = createAdditions(entries, existing);
+	return { path: 'index.ts', content: mergeContent(content, additions) };
+};

package/cli/installation/exports/merge-content.ts

@@ -0,0 +1,12 @@
+/**
+ * Append new statements while preserving existing text and its newline style.
+ * @param content Original destination index.ts content.
+ * @param additions Missing export statements to append.
+ * @returns Unchanged content when no exports are missing, otherwise the merged text.
+ */
+export const mergeContent = (content: string, additions: string[]): string => {
+	if (additions.length === 0) return content;
+	const newline = content.includes('\r\n') ? '\r\n' : '\n';
+	const separator = content.length > 0 && !content.endsWith('\n') ? newline : '';
+	return content + separator + additions.join(newline) + newline;
+};

package/cli/installation/exports/read-declared-export-names.ts

@@ -0,0 +1,24 @@
+import type { ScriptStatement } from '../parser/types.js';
+import type { ExistingExport } from './types.js';
+import { readBindingNames, readName } from './utils.js';
+
+/**
+ * Reserve names defined by exported variables, functions, classes and type declarations.
+ * These declarations have no reusable component path; default declarations reserve default.
+ * @param statement Parsed top-level declaration or another statement to ignore.
+ * @returns Declared public names, including destructured variables, or an empty list.
+ */
+export const readDeclaredExportNames = (statement: ScriptStatement): ExistingExport[] => {
+	if (statement.type === 'ExportDefaultDeclaration')
+		return [{ name: 'default', componentPath: null }];
+	if (statement.type !== 'ExportNamedDeclaration' || !statement.declaration) return [];
+
+	const declaration = statement.declaration;
+	if (declaration.type === 'VariableDeclaration')
+		return declaration.declarations.flatMap(({ id }) =>
+			readBindingNames(id).map((name) => ({ name, componentPath: null }))
+		);
+
+	const name = 'id' in declaration ? readName(declaration.id) : null;
+	return name === null ? [] : [{ name, componentPath: null }];
+};

package/cli/installation/exports/read-exported-names.ts

@@ -0,0 +1,21 @@
+import type { ScriptStatement } from '../parser/types.js';
+import { readReExportedNames } from './read-reexported-names.js';
+import { readDeclaredExportNames } from './read-declared-export-names.js';
+import type { ExistingExport } from './types.js';
+
+/**
+ * Identify the public names introduced by one top-level index.ts statement.
+ * A matching component path lets installation reuse an existing default re-export;
+ * a null path reserves the name and prevents installation from replacing it.
+ * @param statement Parsed statement, such as a re-export or an exported declaration.
+ * @returns Named records for its exports, or an empty list when it exports no names.
+ * @throws For export *, whose names cannot be known without inspecting another file.
+ */
+export const readExportedNames = (statement: ScriptStatement): ExistingExport[] => {
+	if (
+		statement.type === 'ExportAllDeclaration' ||
+		(statement.type === 'ExportNamedDeclaration' && !statement.declaration)
+	)
+		return readReExportedNames(statement);
+	return readDeclaredExportNames(statement);
+};

package/cli/installation/exports/read-index.ts

@@ -0,0 +1,14 @@
+/**
+ * Read the destination index, treating only a missing file as empty content.
+ * @param destination Consumer UI directory.
+ * @returns Existing content or an empty string for ENOENT.
+ * @throws Any other filesystem read error.
+ */
+export const readIndex = async (destination: string): Promise<string> => {
+	try {
+		return await Bun.file(`${destination}/index.ts`).text();
+	} catch (error) {
+		if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return '';
+		throw error;
+	}
+};

package/cli/installation/exports/read-reexported-names.ts

@@ -0,0 +1,24 @@
+import type { ExportAllDeclaration, ExportNamedDeclaration } from 'estree';
+import type { ExistingExport } from './types.js';
+import { readDefaultReExportPath, readName } from './utils.js';
+
+/**
+ * Read public aliases from export lists and namespace re-exports.
+ * Direct runtime default re-exports record their module path; other names reserve a null path.
+ * @param declaration Parsed export list, namespace re-export or wildcard re-export.
+ * @returns Export records in source order.
+ * @throws For export * without a namespace, because its names are unknown here.
+ */
+export const readReExportedNames = (
+	declaration: ExportNamedDeclaration | ExportAllDeclaration
+): ExistingExport[] => {
+	if (declaration.type === 'ExportAllDeclaration') {
+		const name = readName(declaration.exported);
+		if (name === null) throw new Error('index.ts: wildcard exports must be made explicit first.');
+		return [{ name, componentPath: null }];
+	}
+	return declaration.specifiers.map((specifier) => ({
+		name: readName(specifier.exported)!,
+		componentPath: readDefaultReExportPath(declaration, specifier)
+	}));
+};

package/cli/installation/exports/types.ts

@@ -0,0 +1,10 @@
+/** One name already exported by the consumer's index.ts. */
+export interface ExistingExport {
+	/** Public name used by consumers, such as Button. */
+	name: string;
+	/**
+	 * Module path for a direct value re-export of default, such as ./button/button.svelte.
+	 * Null means the name is occupied by another export and cannot be reused.
+	 */
+	componentPath: string | null;
+}