create-nudge-ui 0.1.2

package/README.md

@@ -0,0 +1,24 @@
+# `create-nudge-ui`
+
+`create-nudge-ui` detects an application's host framework, installs the
+corresponding Nudge UI adapter, and updates the host configuration.
+
+Run the initializer from the application root:
+
+```sh
+npm create nudge-ui@latest
+```
+
+The initializer supports Next.js, Astro, Vite with React, and static HTML. Host
+frameworks take precedence over their underlying tools, so an Astro project
+with React islands receives `@nudge-ui/astro`, not `@nudge-ui/vite-react`.
+
+Use an explicit framework when automatic detection is ambiguous:
+
+```sh
+npm create nudge-ui@latest -- --framework astro
+```
+
+Use `--dry-run` to print the package installation and configuration change
+without modifying the project. Run `npm create nudge-ui@latest -- --help` for
+the complete command reference.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Smart
+
+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/dist/arguments.d.ts

@@ -0,0 +1,10 @@
+import { type Framework, type PackageManager } from "./types.js";
+export interface CliOptions {
+    readonly framework?: Framework;
+    readonly packageManager?: PackageManager;
+    readonly dryRun: boolean;
+    readonly help: boolean;
+}
+/** Parses the initializer command line. */
+export declare function parseArguments(args: readonly string[]): CliOptions;
+export declare const helpText = "Set up Nudge UI in the current project.\n\nUsage: npm create nudge-ui@latest -- [options]\n\nOptions:\n  --framework <nextjs|astro|vite-react|standalone>\n  --package-manager <pnpm|npm|yarn|bun>\n  --dry-run\n  -h, --help";

package/dist/arguments.js

@@ -0,0 +1,55 @@
+import { frameworks, packageManagers } from "./types.js";
+/** Parses the initializer command line. */
+export function parseArguments(args) {
+    let framework;
+    let packageManager;
+    let dryRun = false;
+    let help = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--")
+            continue;
+        if (argument === "--dry-run")
+            dryRun = true;
+        else if (argument === "--help" || argument === "-h")
+            help = true;
+        else if (argument === "--framework")
+            framework = parseFramework(requiredValue(args, ++index, argument));
+        else if (argument.startsWith("--framework="))
+            framework = parseFramework(argument.slice("--framework=".length));
+        else if (argument === "--package-manager") {
+            packageManager = parsePackageManager(requiredValue(args, ++index, argument));
+        }
+        else if (argument.startsWith("--package-manager=")) {
+            packageManager = parsePackageManager(argument.slice("--package-manager=".length));
+        }
+        else
+            throw new Error(`Unknown option: ${argument}`);
+    }
+    return { framework, packageManager, dryRun, help };
+}
+function requiredValue(args, index, option) {
+    const value = args[index];
+    if (!value || value.startsWith("-"))
+        throw new Error(`${option} requires a value.`);
+    return value;
+}
+export const helpText = `Set up Nudge UI in the current project.
+
+Usage: npm create nudge-ui@latest -- [options]
+
+Options:
+  --framework <nextjs|astro|vite-react|standalone>
+  --package-manager <pnpm|npm|yarn|bun>
+  --dry-run
+  -h, --help`;
+function parseFramework(value) {
+    if (value === "nextjs" || value === "astro" || value === "vite-react" || value === "standalone")
+        return value;
+    throw new Error(`--framework must be one of: ${frameworks.join(", ")}.`);
+}
+function parsePackageManager(value) {
+    if (value === "pnpm" || value === "npm" || value === "yarn" || value === "bun")
+        return value;
+    throw new Error(`--package-manager must be one of: ${packageManagers.join(", ")}.`);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+/** Runs the Nudge UI project initializer. */
+export declare function runCli(args?: string[], projectRoot?: string): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,91 @@
+import { rmSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { basename, relative } from "node:path";
+import { parseArguments, helpText } from "./arguments.js";
+import { planConfiguration } from "./configuration.js";
+import { adapterPackage, detectFrameworks, detectPackageManager, detectStaticRoot, frameworkDisplayName, readProjectManifest, } from "./detection.js";
+import { formatCommand, installCommand, installPackage } from "./installer.js";
+import { frameworks } from "./types.js";
+/** Runs the Nudge UI project initializer. */
+export async function runCli(args = process.argv.slice(2), projectRoot = process.cwd()) {
+    const options = parseArguments(args);
+    if (options.help) {
+        stdout.write(`${helpText}\n`);
+        return;
+    }
+    const manifest = readProjectManifest(projectRoot);
+    const detected = detectFrameworks(projectRoot, manifest);
+    const framework = options.framework ?? await selectFramework(detected);
+    const packageManager = options.packageManager ?? detectPackageManager(projectRoot, manifest);
+    const packageName = adapterPackage(framework);
+    const command = installCommand(packageManager, packageName);
+    const change = planConfiguration(projectRoot, framework);
+    const staticRoot = framework === "standalone" ? detectStaticRoot(projectRoot) : undefined;
+    const serveDirectory = staticRoot ? relative(projectRoot, staticRoot) || "." : ".";
+    stdout.write(`Nudge UI detected ${frameworkDisplayName(framework)} in ${basename(projectRoot)}.\n`);
+    if (options.dryRun) {
+        stdout.write(`Would run: ${formatCommand(command)}\n`);
+        if (change)
+            stdout.write(`Would ${change.created ? "create" : "update"}: ${change.path}\n`);
+        if (framework === "standalone")
+            stdout.write(`After installation, run: nudge-ui serve ${serveDirectory}\n`);
+        return;
+    }
+    if (change) {
+        writeFileSync(change.path, change.content);
+    }
+    try {
+        installPackage(command, projectRoot);
+    }
+    catch (error) {
+        if (change)
+            rollbackConfiguration(change);
+        throw error;
+    }
+    if (change) {
+        stdout.write(`${change.created ? "Created" : "Updated"} ${change.path}.\n`);
+    }
+    if (framework === "standalone") {
+        stdout.write(`Run \`nudge-ui serve ${serveDirectory}\` to start the instrumented development server.\n`);
+    }
+    stdout.write(`Nudge UI is configured with ${packageName}.\n`);
+}
+async function selectFramework(detected) {
+    if (detected.length === 1)
+        return detected[0];
+    if (!stdin.isTTY || !stdout.isTTY)
+        throw detectionError(detected);
+    const choices = detected.length > 1 ? detected : frameworks;
+    stdout.write("Select the host framework:\n");
+    choices.forEach((framework, index) => stdout.write(`  ${index + 1}. ${frameworkDisplayName(framework)}\n`));
+    const reader = createInterface({ input: stdin, output: stdout });
+    try {
+        while (true) {
+            const answer = await reader.question("Framework: ");
+            const selected = choices[Number(answer) - 1];
+            if (selected)
+                return selected;
+            stdout.write(`Enter a number from 1 to ${choices.length}.\n`);
+        }
+    }
+    finally {
+        reader.close();
+    }
+}
+function rollbackConfiguration(change) {
+    if (change.created) {
+        rmSync(change.path, { force: true });
+        return;
+    }
+    if (change.originalContent === undefined) {
+        throw new Error(`Could not restore ${change.path}: original content was not recorded.`);
+    }
+    writeFileSync(change.path, change.originalContent);
+}
+function detectionError(detected) {
+    if (detected.length > 1) {
+        return new Error(`Detected multiple host frameworks (${detected.join(", ")}). Pass --framework explicitly.`);
+    }
+    return new Error("Could not detect a supported host framework. Pass --framework explicitly.");
+}

package/dist/configuration.d.ts

@@ -0,0 +1,5 @@
+import type { ConfigurationChange, Framework } from "./types.js";
+/** Plans an idempotent host-configuration edit without writing to the project. */
+export declare function planConfiguration(projectRoot: string, framework: Framework): ConfigurationChange | undefined;
+/** Adds the selected adapter to a conventional host configuration source. */
+export declare function configureSource(source: string, framework: Exclude<Framework, "standalone">, fileName: string): string;

package/dist/configuration.js

@@ -0,0 +1,269 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import ts from "typescript";
+const nextConfigNames = ["next.config.ts", "next.config.mts", "next.config.mjs", "next.config.js", "next.config.cjs"];
+const astroConfigNames = ["astro.config.ts", "astro.config.mts", "astro.config.mjs", "astro.config.js"];
+const viteConfigNames = ["vite.config.ts", "vite.config.mts", "vite.config.mjs", "vite.config.js"];
+/** Plans an idempotent host-configuration edit without writing to the project. */
+export function planConfiguration(projectRoot, framework) {
+    if (framework === "standalone")
+        return undefined;
+    const existingName = configurationNames(framework).find((name) => existsSync(join(projectRoot, name)));
+    const name = existingName ?? defaultConfigName(framework);
+    const path = join(projectRoot, name);
+    const originalContent = existingName ? readFileSync(path, "utf8") : undefined;
+    const original = originalContent ?? defaultConfiguration(framework);
+    const content = configureSource(original, framework, name);
+    if (content === original)
+        return undefined;
+    return { path, content, created: !existingName, originalContent };
+}
+/** Adds the selected adapter to a conventional host configuration source. */
+export function configureSource(source, framework, fileName) {
+    const sourceFile = parseSource(source, fileName);
+    if (framework === "astro") {
+        return configureArrayHost(source, sourceFile, "@nudge-ui/astro", "nudgeUiAstro", "integrations", "nudgeUiAstro()");
+    }
+    if (framework === "vite-react") {
+        return configureArrayHost(source, sourceFile, "@nudge-ui/vite-react", "nudgeUi", "plugins", "...nudgeUi()");
+    }
+    return configureNextSource(source, sourceFile);
+}
+function configureArrayHost(source, sourceFile, packageName, importName, propertyName, expression) {
+    const bindings = importedBindings(sourceFile, packageName, importName);
+    const callableBindings = new Set([...bindings, importName]);
+    const configObject = findDefineConfigObject(sourceFile, propertyName);
+    const matchingProperties = configObject.properties.filter((property) => propertyText(property.name) === propertyName);
+    if (matchingProperties.length > 1) {
+        throw new Error(`Could not update ${propertyName}: the configuration contains duplicate ${propertyName} properties.`);
+    }
+    const property = matchingProperties[0];
+    let configurationEdit;
+    if (property) {
+        if (!ts.isPropertyAssignment(property) || !ts.isArrayLiteralExpression(property.initializer)) {
+            throw new Error(`Could not update ${propertyName}: expected ${propertyName} to be an array.`);
+        }
+        if (!containsCall(property.initializer, callableBindings)) {
+            configurationEdit = insertArrayElement(source, sourceFile, property, expression);
+        }
+    }
+    else {
+        configurationEdit = insertObjectProperty(source, sourceFile, configObject, propertyName, expression);
+    }
+    const edits = configurationEdit ? [configurationEdit] : [];
+    if (bindings.length === 0) {
+        edits.push(importEdit(sourceFile, `import { ${importName} } from "${packageName}";`, false));
+    }
+    return applyEdits(source, edits);
+}
+function configureNextSource(source, sourceFile) {
+    const target = findNextExport(sourceFile);
+    const bindings = target.commonJs
+        ? requiredBindings(sourceFile, "@nudge-ui/nextjs", "withNudgeUi")
+        : importedBindings(sourceFile, "@nudge-ui/nextjs", "withNudgeUi");
+    const callableBindings = new Set([...bindings, "withNudgeUi"]);
+    const edits = [];
+    if (!containsCall(target.expression, callableBindings)) {
+        const start = target.expression.getStart(sourceFile);
+        const end = target.expression.getEnd();
+        edits.push({ start, end, text: `withNudgeUi(${source.slice(start, end)})` });
+    }
+    if (bindings.length === 0) {
+        const statement = target.commonJs
+            ? 'const { withNudgeUi } = require("@nudge-ui/nextjs");'
+            : 'import { withNudgeUi } from "@nudge-ui/nextjs";';
+        edits.push(importEdit(sourceFile, statement, target.commonJs));
+    }
+    return applyEdits(source, edits);
+}
+function parseSource(source, fileName) {
+    const scriptKind = fileName.endsWith(".ts") || fileName.endsWith(".mts")
+        ? ts.ScriptKind.TS
+        : ts.ScriptKind.JS;
+    return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind);
+}
+function findDefineConfigObject(sourceFile, propertyName) {
+    const candidates = [];
+    visit(sourceFile, (node) => {
+        if (ts.isCallExpression(node)
+            && ts.isIdentifier(node.expression)
+            && node.expression.text === "defineConfig"
+            && node.arguments[0]
+            && ts.isObjectLiteralExpression(node.arguments[0]))
+            candidates.push(node.arguments[0]);
+    });
+    if (candidates.length !== 1) {
+        throw new Error(`Could not update ${propertyName}: expected exactly one defineConfig({ ... }) call.`);
+    }
+    return candidates[0];
+}
+function findNextExport(sourceFile) {
+    const exports = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            exports.push({ expression: statement.expression, commonJs: false });
+            continue;
+        }
+        if (!ts.isExpressionStatement(statement) || !ts.isBinaryExpression(statement.expression))
+            continue;
+        const assignment = statement.expression;
+        if (assignment.operatorToken.kind !== ts.SyntaxKind.EqualsToken || !isModuleExports(assignment.left))
+            continue;
+        exports.push({ expression: assignment.right, commonJs: true });
+    }
+    if (exports.length !== 1) {
+        throw new Error("Could not update the Next.js configuration: expected exactly one default or module.exports assignment.");
+    }
+    return exports[0];
+}
+function isModuleExports(expression) {
+    return ts.isPropertyAccessExpression(expression)
+        && ts.isIdentifier(expression.expression)
+        && expression.expression.text === "module"
+        && expression.name.text === "exports";
+}
+function importedBindings(sourceFile, packageName, importName) {
+    const bindings = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement)
+            || !ts.isStringLiteral(statement.moduleSpecifier)
+            || statement.moduleSpecifier.text !== packageName
+            || !statement.importClause?.namedBindings
+            || !ts.isNamedImports(statement.importClause.namedBindings))
+            continue;
+        for (const element of statement.importClause.namedBindings.elements) {
+            if ((element.propertyName?.text ?? element.name.text) === importName)
+                bindings.push(element.name.text);
+        }
+    }
+    return bindings;
+}
+function requiredBindings(sourceFile, packageName, importName) {
+    const bindings = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!declaration.initializer || !isRequireCall(declaration.initializer, packageName))
+                continue;
+            if (!ts.isObjectBindingPattern(declaration.name))
+                continue;
+            for (const element of declaration.name.elements) {
+                const importedName = element.propertyName && ts.isIdentifier(element.propertyName)
+                    ? element.propertyName.text
+                    : element.name.getText(sourceFile);
+                if (importedName === importName && ts.isIdentifier(element.name))
+                    bindings.push(element.name.text);
+            }
+        }
+    }
+    return bindings;
+}
+function isRequireCall(expression, packageName) {
+    if (!ts.isCallExpression(expression) || expression.arguments.length !== 1)
+        return false;
+    const argument = expression.arguments[0];
+    if (!argument)
+        return false;
+    return ts.isCallExpression(expression)
+        && ts.isIdentifier(expression.expression)
+        && expression.expression.text === "require"
+        && ts.isStringLiteral(argument)
+        && argument.text === packageName;
+}
+function containsCall(root, bindingNames) {
+    let found = false;
+    visit(root, (node) => {
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && bindingNames.has(node.expression.text)) {
+            found = true;
+        }
+    });
+    return found;
+}
+function visit(root, visitor) {
+    visitor(root);
+    ts.forEachChild(root, (child) => visit(child, visitor));
+}
+function propertyText(name) {
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    if (ts.isComputedPropertyName(name) && ts.isStringLiteral(name.expression))
+        return name.expression.text;
+    return undefined;
+}
+function insertArrayElement(source, sourceFile, property, expression) {
+    const array = property.initializer;
+    if (!ts.isArrayLiteralExpression(array))
+        throw new Error("Expected an array property.");
+    const start = array.getStart(sourceFile) + 1;
+    const end = array.getEnd() - 1;
+    const indentation = lineIndentation(source, property.getStart(sourceFile));
+    const elementIndentation = `${indentation}  `;
+    const interior = source.slice(start, end);
+    if (interior.trim() === "") {
+        return { start, end, text: `\n${elementIndentation}${expression},\n${indentation}` };
+    }
+    const text = interior.startsWith("\n")
+        ? `\n${elementIndentation}${expression},`
+        : `\n${elementIndentation}${expression},\n${elementIndentation}`;
+    return { start, end: start, text };
+}
+function insertObjectProperty(source, sourceFile, object, propertyName, expression) {
+    const start = object.getStart(sourceFile) + 1;
+    const indentation = lineIndentation(source, object.getStart(sourceFile));
+    const propertyIndentation = `${indentation}  `;
+    const empty = object.properties.length === 0;
+    const text = empty
+        ? `\n${propertyIndentation}${propertyName}: [${expression}],\n${indentation}`
+        : `\n${propertyIndentation}${propertyName}: [${expression}],`;
+    return { start, end: start, text };
+}
+function importEdit(sourceFile, statement, commonJs) {
+    const imports = sourceFile.statements.filter(ts.isImportDeclaration);
+    const lastImport = imports.at(-1);
+    if (!commonJs && lastImport)
+        return { start: lastImport.end, end: lastImport.end, text: `\n${statement}` };
+    if (commonJs) {
+        const directives = sourceFile.statements.filter((candidate) => ts.isExpressionStatement(candidate) && ts.isStringLiteral(candidate.expression));
+        const lastDirective = directives.at(-1);
+        if (lastDirective)
+            return { start: lastDirective.end, end: lastDirective.end, text: `\n${statement}` };
+    }
+    const firstStatement = sourceFile.statements[0];
+    const start = firstStatement?.getStart(sourceFile) ?? sourceFile.getEnd();
+    return { start, end: start, text: `${statement}\n` };
+}
+function lineIndentation(source, position) {
+    const lineStart = source.lastIndexOf("\n", position - 1) + 1;
+    const match = /^[ \t]*/.exec(source.slice(lineStart, position));
+    return match?.[0] ?? "";
+}
+function applyEdits(source, edits) {
+    return [...edits]
+        .sort((left, right) => right.start - left.start)
+        .reduce((result, edit) => `${result.slice(0, edit.start)}${edit.text}${result.slice(edit.end)}`, source);
+}
+function configurationNames(framework) {
+    if (framework === "nextjs")
+        return nextConfigNames;
+    if (framework === "astro")
+        return astroConfigNames;
+    return viteConfigNames;
+}
+function defaultConfigName(framework) {
+    if (framework === "nextjs")
+        return "next.config.mjs";
+    if (framework === "astro")
+        return "astro.config.mjs";
+    return "vite.config.mjs";
+}
+function defaultConfiguration(framework) {
+    if (framework === "nextjs")
+        return "const nextConfig = {};\n\nexport default nextConfig;\n";
+    if (framework === "astro") {
+        return 'import { defineConfig } from "astro/config";\n\nexport default defineConfig({});\n';
+    }
+    return 'import { defineConfig } from "vite";\n\nexport default defineConfig({});\n';
+}

package/dist/detection.d.ts

@@ -0,0 +1,11 @@
+import type { Framework, PackageManager, ProjectManifest } from "./types.js";
+/** Reads only the package metadata needed for framework and package-manager detection. */
+export declare function readProjectManifest(projectRoot: string): ProjectManifest;
+/** Detects viable host adapters without treating React or Vite as host frameworks. */
+export declare function detectFrameworks(projectRoot: string, manifest?: ProjectManifest): Framework[];
+/** Detects the project's package manager, preferring its declared package manager. */
+export declare function detectPackageManager(projectRoot: string, manifest?: ProjectManifest): PackageManager;
+/** Finds an HTML document root without recursively scanning dependency or build output. */
+export declare function detectStaticRoot(projectRoot: string): string | undefined;
+export declare function frameworkDisplayName(framework: Framework): string;
+export declare function adapterPackage(framework: Framework): string;

package/dist/detection.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+const nextConfigNames = ["next.config.ts", "next.config.mts", "next.config.mjs", "next.config.js", "next.config.cjs"];
+const astroConfigNames = ["astro.config.ts", "astro.config.mts", "astro.config.mjs", "astro.config.js"];
+const viteConfigNames = ["vite.config.ts", "vite.config.mts", "vite.config.mjs", "vite.config.js"];
+/** Reads only the package metadata needed for framework and package-manager detection. */
+export function readProjectManifest(projectRoot) {
+    const manifestPath = join(projectRoot, "package.json");
+    if (!existsSync(manifestPath)) {
+        return { dependencies: new Set() };
+    }
+    let source;
+    try {
+        source = readFileSync(manifestPath, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read ${manifestPath}: ${message}`, { cause: error });
+    }
+    let parsed;
+    try {
+        // SAFETY: The object shape is validated before any property is consumed.
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not parse ${manifestPath}: ${message}`, { cause: error });
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${manifestPath} must contain a JSON object.`);
+    }
+    return {
+        type: stringProperty(parsed, "type"),
+        packageManager: stringProperty(parsed, "packageManager"),
+        dependencies: new Set([
+            ...dependencyNames(parsed, "dependencies"),
+            ...dependencyNames(parsed, "devDependencies"),
+            ...dependencyNames(parsed, "peerDependencies"),
+            ...dependencyNames(parsed, "optionalDependencies"),
+        ]),
+    };
+}
+/** Detects viable host adapters without treating React or Vite as host frameworks. */
+export function detectFrameworks(projectRoot, manifest = readProjectManifest(projectRoot)) {
+    const hasNext = manifest.dependencies.has("next") || hasAnyFile(projectRoot, nextConfigNames);
+    const hasAstro = manifest.dependencies.has("astro") || hasAnyFile(projectRoot, astroConfigNames);
+    const hosts = [];
+    if (hasNext)
+        hosts.push("nextjs");
+    if (hasAstro)
+        hosts.push("astro");
+    if (hosts.length > 0)
+        return hosts;
+    const hasVite = manifest.dependencies.has("vite") || hasAnyFile(projectRoot, viteConfigNames);
+    const hasReact = manifest.dependencies.has("react") || manifest.dependencies.has("@vitejs/plugin-react");
+    if (hasVite && hasReact)
+        return ["vite-react"];
+    if (hasVite)
+        return [];
+    if (manifest.dependencies.has("@nudge-ui/standalone") || detectStaticRoot(projectRoot))
+        return ["standalone"];
+    return [];
+}
+/** Detects the project's package manager, preferring its declared package manager. */
+export function detectPackageManager(projectRoot, manifest = readProjectManifest(projectRoot)) {
+    const declared = manifest.packageManager?.split("@")[0];
+    if (declared === "pnpm" || declared === "npm" || declared === "yarn" || declared === "bun")
+        return declared;
+    let directory = projectRoot;
+    while (true) {
+        if (existsSync(join(directory, "pnpm-lock.yaml")))
+            return "pnpm";
+        if (existsSync(join(directory, "yarn.lock")))
+            return "yarn";
+        if (existsSync(join(directory, "bun.lock")) || existsSync(join(directory, "bun.lockb")))
+            return "bun";
+        if (existsSync(join(directory, "package-lock.json")))
+            return "npm";
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return "npm";
+}
+/** Finds an HTML document root without recursively scanning dependency or build output. */
+export function detectStaticRoot(projectRoot) {
+    const entries = readDirectory(projectRoot);
+    if (entries.some((entry) => entry.isFile() && entry.name.endsWith(".html")))
+        return projectRoot;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith(".") || ignoredStaticDirectories.has(entry.name))
+            continue;
+        const directory = join(projectRoot, entry.name);
+        const children = readDirectory(directory);
+        if (children.some((child) => child.isFile() && child.name.endsWith(".html")))
+            return directory;
+    }
+    return undefined;
+}
+export function frameworkDisplayName(framework) {
+    if (framework === "nextjs")
+        return "Next.js";
+    if (framework === "astro")
+        return "Astro";
+    if (framework === "vite-react")
+        return "Vite with React";
+    return "static HTML";
+}
+export function adapterPackage(framework) {
+    if (framework === "nextjs")
+        return "@nudge-ui/nextjs";
+    if (framework === "astro")
+        return "@nudge-ui/astro";
+    if (framework === "vite-react")
+        return "@nudge-ui/vite-react";
+    return "@nudge-ui/standalone";
+}
+function hasAnyFile(projectRoot, names) {
+    return names.some((name) => existsSync(join(projectRoot, name)));
+}
+const ignoredStaticDirectories = new Set(["node_modules", "dist", "build", "coverage", "test-results"]);
+function stringProperty(value, key) {
+    const property = key === "type" ? value.type : value.packageManager;
+    return typeof property === "string" ? property : undefined;
+}
+function dependencyNames(value, key) {
+    const dependencies = value[key];
+    if (typeof dependencies !== "object" || dependencies === null || Array.isArray(dependencies))
+        return [];
+    return Object.keys(dependencies);
+}
+function readDirectory(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not inspect ${path}: ${message}`, { cause: error });
+    }
+}

package/dist/entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/entry.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+runCli().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : "Nudge UI setup failed."}\n`);
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { parseArguments, helpText, type CliOptions } from "./arguments.js";
+export { configureSource, planConfiguration } from "./configuration.js";
+export { adapterPackage, detectFrameworks, detectPackageManager, detectStaticRoot, frameworkDisplayName, readProjectManifest, } from "./detection.js";
+export { formatCommand, installCommand, type InstallCommand } from "./installer.js";
+export { frameworks, packageManagers, type Framework, type PackageManager } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { parseArguments, helpText } from "./arguments.js";
+export { configureSource, planConfiguration } from "./configuration.js";
+export { adapterPackage, detectFrameworks, detectPackageManager, detectStaticRoot, frameworkDisplayName, readProjectManifest, } from "./detection.js";
+export { formatCommand, installCommand } from "./installer.js";
+export { frameworks, packageManagers } from "./types.js";

package/dist/installer.d.ts

@@ -0,0 +1,10 @@
+import type { PackageManager } from "./types.js";
+export interface InstallCommand {
+    readonly executable: string;
+    readonly args: readonly string[];
+}
+/** Returns the native development-dependency command for a package manager. */
+export declare function installCommand(packageManager: PackageManager, packageName: string): InstallCommand;
+/** Runs a package-manager command with the user's terminal attached. */
+export declare function installPackage(command: InstallCommand, projectRoot: string): void;
+export declare function formatCommand(command: InstallCommand): string;

package/dist/installer.js

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+/** Returns the native development-dependency command for a package manager. */
+export function installCommand(packageManager, packageName) {
+    if (packageManager === "pnpm")
+        return { executable: "pnpm", args: ["add", "-D", packageName] };
+    if (packageManager === "yarn")
+        return { executable: "yarn", args: ["add", "-D", packageName] };
+    if (packageManager === "bun")
+        return { executable: "bun", args: ["add", "--dev", packageName] };
+    return { executable: "npm", args: ["install", "--save-dev", packageName] };
+}
+/** Runs a package-manager command with the user's terminal attached. */
+export function installPackage(command, projectRoot) {
+    const executable = process.platform === "win32" ? `${command.executable}.cmd` : command.executable;
+    const result = spawnSync(executable, command.args, { cwd: projectRoot, stdio: "inherit" });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`${command.executable} exited with status ${result.status ?? "unknown"}.`);
+    }
+}
+export function formatCommand(command) {
+    return [command.executable, ...command.args].join(" ");
+}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export declare const frameworks: readonly ["nextjs", "astro", "vite-react", "standalone"];
+export type Framework = typeof frameworks[number];
+export declare const packageManagers: readonly ["pnpm", "npm", "yarn", "bun"];
+export type PackageManager = typeof packageManagers[number];
+export interface ProjectManifest {
+    readonly type?: string;
+    readonly packageManager?: string;
+    readonly dependencies: ReadonlySet<string>;
+}
+export interface ConfigurationChange {
+    readonly path: string;
+    readonly content: string;
+    readonly created: boolean;
+    readonly originalContent?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export const frameworks = ["nextjs", "astro", "vite-react", "standalone"];
+export const packageManagers = ["pnpm", "npm", "yarn", "bun"];

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "create-nudge-ui",
+  "version": "0.1.2",
+  "description": "Framework-detecting installer for Nudge UI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/charlessmart/nudge-ui.git",
+    "directory": "packages/create-nudge-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/charlessmart/nudge-ui/issues"
+  },
+  "homepage": "https://github.com/charlessmart/nudge-ui#readme",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "create-nudge-ui": "./dist/entry.js"
+  },
+  "dependencies": {
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  }
+}