@santi020k/lumen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Molina
+
+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/README.md

@@ -0,0 +1,33 @@
+# @santi020k/lumen
+
+Shared foundation and umbrella package for Lumen UI.
+
+Install the framework package directly:
+
+- `@santi020k/lumen-astro`
+- `@santi020k/lumen-react`
+- `@santi020k/lumen-elements`
+
+Each adapter includes the shared foundation and exposes its own stylesheet entry. Install this
+umbrella package only when you want the framework-neutral CLI or registry APIs:
+
+```bash
+pnpm add @santi020k/lumen
+```
+
+The umbrella package also exposes typed registry metadata and the `lumen` CLI:
+
+```bash
+lumen list
+lumen show Button
+lumen add Button
+lumen add Button --target react
+lumen add Button --target elements
+lumen add scheduler
+lumen add scheduler --target react
+lumen add scheduler --target elements
+```
+
+Use `lumen add <component>` for a local Astro wrapper, `--target react` for a React wrapper, or
+`--target elements` for a custom-elements starter. Bundled recipes support the same Astro, React,
+and Elements targets.

package/bin/lumen.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js'

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,136 @@
+import { addLumenRegistryItem, getLumenRegistryEntries, getLumenRegistryItem, loadLumenRegistry, lumenRegistry } from './registry.js';
+const args = process.argv.slice(2);
+const [command = 'help', name] = args;
+const dryRun = args.includes('--dry-run');
+const failOnConflict = args.includes('--fail-on-conflict');
+const force = args.includes('--force');
+const merge = args.includes('--merge');
+const cwdIndex = args.indexOf('--cwd');
+const cwd = cwdIndex >= 0 ? args[cwdIndex + 1] : undefined;
+const registryIndex = args.indexOf('--registry');
+const registrySource = registryIndex >= 0 ? args[registryIndex + 1] : undefined;
+const registryTokenIndex = args.indexOf('--registry-token');
+const registryToken = registryTokenIndex >= 0 ? args[registryTokenIndex + 1] : process.env.LUMEN_REGISTRY_TOKEN;
+const targetIndex = args.indexOf('--target');
+const targetProvided = targetIndex >= 0;
+const targetValue = targetIndex >= 0 ? args[targetIndex + 1] : undefined;
+let conflict = 'skip';
+const getAddTarget = (value, provided = false) => {
+    if (provided && !value) {
+        throw new Error('Missing Lumen add target. Use astro, react, or elements.');
+    }
+    if (!value || value === 'astro')
+        return 'astro';
+    if (value === 'react' || value === 'elements')
+        return value;
+    throw new Error(`Unknown Lumen add target: ${value}. Use astro, react, or elements.`);
+};
+if (failOnConflict) {
+    conflict = 'error';
+}
+else if (merge) {
+    conflict = 'merge';
+}
+const formatList = (registry = lumenRegistry) => getLumenRegistryEntries(registry)
+    .map(item => `${item.name} (${item.type})`)
+    .join('\n');
+const getRegistryFilePath = (file) => typeof file === 'string' ? file : file.path;
+const getRegistryItemFiles = (item) => {
+    if (!item.files?.length)
+        return undefined;
+    return item.files.map(getRegistryFilePath).join(', ');
+};
+const getRegistryItemDescription = (item) => 'description' in item ? item.description : undefined;
+const getRegistryItemCategory = (item) => 'category' in item ? `category: ${item.category}` : undefined;
+const getRegistryItemComponents = (item) => 'components' in item && Array.isArray(item.components) && item.components.length > 0
+    ? `components: ${item.components.join(', ')}`
+    : undefined;
+const getRegistryItemDependencies = (item) => 'dependencies' in item && item.dependencies.length > 0
+    ? `dependencies: ${item.dependencies.join(', ')}`
+    : undefined;
+const formatItem = (itemName, registry = lumenRegistry) => {
+    const item = getLumenRegistryItem(itemName, registry);
+    if (!item) {
+        process.exitCode = 1;
+        return `Unknown Lumen registry item: ${itemName}`;
+    }
+    const lines = [
+        `${item.name} (${item.type})`,
+        getRegistryItemDescription(item),
+        getRegistryItemCategory(item),
+        getRegistryItemComponents(item),
+        getRegistryItemDependencies(item)
+    ];
+    const files = getRegistryItemFiles(item);
+    if (files) {
+        lines.push(`files: ${files}`);
+    }
+    return lines.filter((line) => Boolean(line)).join('\n');
+};
+const formatAddResult = async (itemName, registry) => {
+    const result = await addLumenRegistryItem(itemName, {
+        ...(cwd ? { cwd } : {}),
+        conflict,
+        dryRun,
+        force,
+        registry,
+        target: getAddTarget(targetValue, targetProvided)
+    });
+    return [
+        `${result.dryRun ? 'Would add' : 'Added'} ${result.item.name}`,
+        ...result.added.map(file => `- ${file}`),
+        ...result.merged.map(file => `- merged existing ${file}`),
+        ...result.skipped.map(file => `- skipped existing ${file}`)
+    ].join('\n');
+};
+const help = [
+    'Lumen registry helper',
+    '',
+    'Commands:',
+    '  lumen list             List registry items',
+    '  lumen show <name>      Show components and files for an item',
+    '  lumen add <name>       Install a recipe or component into the current project',
+    '  lumen install          Print install commands',
+    '',
+    'Options:',
+    '  --cwd <path>           Target directory for lumen add',
+    '  --dry-run              Print files without writing them',
+    '  --fail-on-conflict     Exit if a target recipe file already exists',
+    '  --force                Overwrite existing recipe files',
+    '  --merge                Merge recipe files with existing files',
+    '  --registry <source>    Load list/show data from a local or remote registry JSON file',
+    '  --registry-token <key> Use a bearer token for private remote registries',
+    '  --target <framework>   Generate wrappers or recipe starters for astro, react, or elements',
+    ''
+].join('\n');
+const run = async () => {
+    let output = help;
+    const registry = registrySource
+        ? await loadLumenRegistry(registrySource, registryToken ? { token: registryToken } : {})
+        : lumenRegistry;
+    switch (command) {
+        case 'add': {
+            if (name)
+                output = await formatAddResult(name, registry);
+            break;
+        }
+        case 'install': {
+            output = 'pnpm add @santi020k/lumen-astro\nnpm install @santi020k/lumen-astro\nyarn add @santi020k/lumen-astro';
+            break;
+        }
+        case 'list': {
+            output = formatList(registry);
+            break;
+        }
+        case 'show': {
+            if (name)
+                output = formatItem(name, registry);
+            break;
+        }
+    }
+    process.stdout.write(`${output}\n`);
+};
+run().catch((error) => {
+    process.exitCode = 1;
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+});

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { addLumenRegistryItem, getLumenRegistryEntries, getLumenRegistryItem, loadLumenRegistry, type LumenAddOptions, type LumenAddResult, type LumenAddTarget, type LumenMergeConflict, type LumenRegistry, lumenRegistry, type LumenRegistryComponent, type LumenRegistryEntry, type LumenRegistryFile, type LumenRegistryItem, type LumenRegistryLoadOptions } from './registry.js';
+export { applyDataViewState, canPlaceScheduleEvent, coerceThemeBuilderExportFormat, coerceThemeBuilderMode, coerceThemeBuilderScheme, composeClassName, createDataViewRequestUrl, createDataViewSearchParams, createDataViewServerRequest, createDataViewState, createDataViewStorageKey, createScheduleSlots, createScheduleStorageKey, createThemeBuilderTokens, createThemePalette, expandRecurringScheduleEvent, exportThemeBuilderCss, exportThemeBuilderValue, exportThemeCss, filterDataRecords, getContrastRatio, getScheduleConflicts, getVirtualRange, loadDataViewState, loadScheduleEvents, type LumenCodeToken, lumenCodeTokenClassNames, type LumenCodeTokenKind, lumenColors, type LumenColorTokenName, lumenColorTokenNames, type LumenComponentName, lumenComponentNames, type LumenContrastScore, lumenDarkTheme, type LumenDataRecord, type LumenDataViewServerRequest, type LumenDataViewState, lumenGlass, type LumenGlassColorTokenName, lumenGlassColorTokenNames, type LumenGlassEffectTokenName, lumenGlassEffectTokenNames, type LumenGlassTokenName, lumenGlassTokenNames, type LumenKeyValueReader, type LumenKeyValueStorage, type LumenKeyValueWriter, lumenLightTheme, lumenPackages, type LumenPackageTarget, type LumenScheduleConflict, type LumenScheduleEvent, type LumenScheduleKeyValueReader, type LumenScheduleKeyValueStorage, type LumenScheduleKeyValueWriter, type LumenScheduleResizeEdge, type LumenScheduleResizeOptions, type LumenScheduleResource, type LumenScheduleSlot, type LumenSemanticColorTokenName, lumenSemanticColorTokenNames, type LumenSortDirection, lumenThemeAttribute, type LumenThemeBuilderExportFormat, type LumenThemeBuilderMode, type LumenThemeBuilderOptions, type LumenThemeBuilderResult, type LumenThemeBuilderScheme, type LumenThemeContrastSuggestion, type LumenThemeTokens, lumenTokenNames, mergeThemeTokens, moveScheduleEvent, normalizeLumenCode, normalizeThemeBuilderHex, normalizeThemeBuilderHue, paginateDataRecords, parseDataViewState, parseScheduleEvents, parseThemeCss, pinDataViewColumn, renderLumenCodeHtml, resizeScheduleEvent, resizeScheduleEvents, saveDataViewState, saveScheduleEvents, scheduleEventsOverlap, scoreThemeContrast, serializeDataViewState, serializeScheduleEvents, sortDataRecords, suggestReadableInk, themeBuilderHexToHsl, toggleDataViewSelection, tokenizeLumenCode, tuneThemeContrast, unpinDataViewColumn } from '@santi020k/lumen-core';
+export declare const lumen: {
+    readonly name: "Lumen";
+    readonly packageName: "@santi020k/lumen";
+    readonly scope: "@santi020k";
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,aAAa,EACb,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC9B,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,8BAA8B,EAC9B,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,cAAc,EACnB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,WAAW,EACX,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,UAAU,EACV,KAAK,wBAAwB,EAC7B,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,eAAe,EACf,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,4BAA4B,EAC5B,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,gBAAgB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,uBAAuB,CAAA;AAE9B,eAAO,MAAM,KAAK;;;;CAIR,CAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { addLumenRegistryItem, getLumenRegistryEntries, getLumenRegistryItem, loadLumenRegistry, lumenRegistry } from './registry.js';
+export { applyDataViewState, canPlaceScheduleEvent, coerceThemeBuilderExportFormat, coerceThemeBuilderMode, coerceThemeBuilderScheme, composeClassName, createDataViewRequestUrl, createDataViewSearchParams, createDataViewServerRequest, createDataViewState, createDataViewStorageKey, createScheduleSlots, createScheduleStorageKey, createThemeBuilderTokens, createThemePalette, expandRecurringScheduleEvent, exportThemeBuilderCss, exportThemeBuilderValue, exportThemeCss, filterDataRecords, getContrastRatio, getScheduleConflicts, getVirtualRange, loadDataViewState, loadScheduleEvents, lumenCodeTokenClassNames, lumenColors, lumenColorTokenNames, lumenComponentNames, lumenDarkTheme, lumenGlass, lumenGlassColorTokenNames, lumenGlassEffectTokenNames, lumenGlassTokenNames, lumenLightTheme, lumenPackages, lumenSemanticColorTokenNames, lumenThemeAttribute, lumenTokenNames, mergeThemeTokens, moveScheduleEvent, normalizeLumenCode, normalizeThemeBuilderHex, normalizeThemeBuilderHue, paginateDataRecords, parseDataViewState, parseScheduleEvents, parseThemeCss, pinDataViewColumn, renderLumenCodeHtml, resizeScheduleEvent, resizeScheduleEvents, saveDataViewState, saveScheduleEvents, scheduleEventsOverlap, scoreThemeContrast, serializeDataViewState, serializeScheduleEvents, sortDataRecords, suggestReadableInk, themeBuilderHexToHsl, toggleDataViewSelection, tokenizeLumenCode, tuneThemeContrast, unpinDataViewColumn } from '@santi020k/lumen-core';
+export const lumen = {
+    name: 'Lumen',
+    packageName: '@santi020k/lumen',
+    scope: '@santi020k'
+};

package/dist/installer.d.ts

@@ -0,0 +1,26 @@
+import { type LumenRegistry, type LumenRegistryEntry } from './registry.js';
+export interface LumenAddOptions {
+    conflict?: 'error' | 'merge' | 'overwrite' | 'skip';
+    cwd?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    merge?: (conflict: LumenMergeConflict) => string;
+    registry?: LumenRegistry;
+    target?: LumenAddTarget;
+}
+export type LumenAddTarget = 'astro' | 'elements' | 'react';
+export interface LumenMergeConflict {
+    existing: string;
+    incoming: string;
+    path: string;
+}
+export interface LumenAddResult {
+    added: string[];
+    dryRun: boolean;
+    files: string[];
+    item: LumenRegistryEntry;
+    merged: string[];
+    skipped: string[];
+}
+export declare const addLumenRegistryItem: (name: string, options?: LumenAddOptions) => Promise<LumenAddResult>;
+//# sourceMappingURL=installer.d.ts.map

package/dist/installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAA;AAOtB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAA;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,MAAM,CAAA;IAChD,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAA;AAE3D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,IAAI,EAAE,kBAAkB,CAAA;IACxB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AA4MD,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,EACZ,UAAS,eAAoB,KAC5B,OAAO,CAAC,cAAc,CA2CxB,CAAA"}

package/dist/installer.js

@@ -0,0 +1,181 @@
+import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getLumenRegistryItem, } from './registry.js';
+const templatesRoot = fileURLToPath(new URL('../templates/', import.meta.url));
+const loadRecipeTemplateFiles = async (itemName, target) => {
+    const templateDir = join(templatesRoot, target, itemName);
+    let entries;
+    try {
+        entries = await readdir(templateDir, { recursive: true, withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    const files = await Promise.all(entries
+        .filter(entry => entry.isFile())
+        .map(async (entry) => {
+        const absolutePath = join(entry.parentPath, entry.name);
+        return {
+            path: relative(templateDir, absolutePath).split(sep).join('/'),
+            source: await readFile(absolutePath, 'utf8')
+        };
+    }));
+    files.sort((first, second) => first.path.localeCompare(second.path));
+    return files.length > 0 ? files : undefined;
+};
+const toKebabCase = (name) => name.replaceAll(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+const toCamelCase = (value) => value.replaceAll(/-([a-z])/g, (_match, character) => character.toUpperCase());
+const createAstroComponentFile = (name) => ({
+    path: `src/lumen/${toKebabCase(name)}.astro`,
+    source: `---
+import { ${name} as Lumen${name} } from '@santi020k/lumen-astro'
+
+const props = Astro.props
+---
+
+<Lumen${name} {...props}>
+  <slot />
+</Lumen${name}>
+`
+});
+const createReactComponentFile = (name) => ({
+    path: `src/lumen/${toKebabCase(name)}.tsx`,
+    source: `import type { ComponentPropsWithoutRef } from 'react'
+
+import { ${name} as Lumen${name} } from '@santi020k/lumen-react'
+
+export type ${name}Props = ComponentPropsWithoutRef<typeof Lumen${name}>
+
+export const ${name} = (props: ${name}Props) => <Lumen${name} {...props} />
+`
+});
+const createElementsComponentFile = (name) => {
+    const tagName = `lumen-${toKebabCase(name)}`;
+    const variableName = `${toCamelCase(toKebabCase(name))}TagName`;
+    return {
+        path: `src/lumen/${toKebabCase(name)}.ts`,
+        source: `import {
+  defineLumenElements,
+  Lumen${name}Element
+} from '@santi020k/lumen-elements'
+
+defineLumenElements()
+
+export { Lumen${name}Element }
+
+export const ${variableName} = '${tagName}' as const
+
+declare global {
+  interface HTMLElementTagNameMap {
+    '${tagName}': InstanceType<typeof Lumen${name}Element>
+  }
+}
+`
+    };
+};
+const createComponentFile = (name, target) => {
+    if (target === 'react')
+        return createReactComponentFile(name);
+    if (target === 'elements')
+        return createElementsComponentFile(name);
+    return createAstroComponentFile(name);
+};
+const getFilesForItem = async (item, target) => {
+    if (item.type === 'component')
+        return [createComponentFile(item.name, target)];
+    const targetRecipeFiles = await loadRecipeTemplateFiles(item.name, target);
+    if (targetRecipeFiles) {
+        return targetRecipeFiles;
+    }
+    const inlineFiles = item.files
+        ?.filter((file) => typeof file !== 'string')
+        .map(file => ({
+        path: file.path,
+        source: file.source
+    })) ?? [];
+    if (inlineFiles.length > 0)
+        return inlineFiles;
+    if (item.type === 'recipe') {
+        throw new Error(`Registry recipe "${item.name}" does not have ${target} starter files yet.`);
+    }
+    return [];
+};
+const fileExists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const mergeFileSource = ({ existing, incoming, path }) => {
+    if (existing.includes(incoming.trim()))
+        return existing;
+    return `${existing.trimEnd()}\n\n/* Lumen merge: ${path} */\n${incoming}`;
+};
+const getConflictMode = (options) => options.force ? 'overwrite' : options.conflict ?? 'skip';
+const getInstallSource = async (file, target, exists, options, conflict) => {
+    if (!exists || conflict !== 'merge')
+        return file.source;
+    return (options.merge ?? mergeFileSource)({
+        existing: await readFile(target, 'utf8'),
+        incoming: file.source,
+        path: file.path
+    });
+};
+const writeInstallFile = async (target, source, dryRun) => {
+    if (dryRun)
+        return;
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, source, 'utf8');
+};
+const installRegistryFile = async (file, cwd, options, conflict) => {
+    const target = join(cwd, file.path);
+    const exists = await fileExists(target);
+    if (exists && conflict === 'error') {
+        throw new Error(`Refusing to overwrite existing file: ${file.path}`);
+    }
+    if (exists && conflict === 'skip')
+        return 'skipped';
+    const source = await getInstallSource(file, target, exists, options, conflict);
+    await writeInstallFile(target, source, options.dryRun);
+    return exists && conflict === 'merge' ? 'merged' : 'added';
+};
+export const addLumenRegistryItem = async (name, options = {}) => {
+    const item = getLumenRegistryItem(name, options.registry);
+    if (!item) {
+        throw new Error(`Unknown Lumen registry item: ${name}`);
+    }
+    const files = await getFilesForItem(item, options.target ?? 'astro');
+    const cwd = options.cwd ?? process.cwd();
+    if (!files.length) {
+        throw new Error(`Registry item cannot be installed yet: ${name}`);
+    }
+    const added = [];
+    const conflict = getConflictMode(options);
+    const merged = [];
+    const skipped = [];
+    for (const file of files) {
+        const outcome = await installRegistryFile(file, cwd, options, conflict);
+        if (outcome === 'skipped') {
+            skipped.push(file.path);
+            continue;
+        }
+        if (outcome === 'merged') {
+            merged.push(file.path);
+        }
+        else {
+            added.push(file.path);
+        }
+    }
+    return {
+        added,
+        dryRun: Boolean(options.dryRun),
+        files: files.map(file => file.path),
+        item,
+        merged,
+        skipped
+    };
+};