@databricks/design-system 2.0.9 → 2.0.10

package/processes/spawn-process-runner.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpawnProcessRunner = void 0;
+const node_child_process_1 = require("node:child_process");
+class SpawnProcessRunner {
+    run(request) {
+        return new Promise((resolve) => {
+            const output = request.output ?? 'capture';
+            const childProcess = (0, node_child_process_1.spawn)(request.binary, request.args, {
+                cwd: request.cwd,
+                env: { ...process.env, ...request.env },
+                shell: false,
+                stdio: ['pipe', output === 'inherit' ? 'inherit' : 'pipe', output === 'inherit' ? 'inherit' : 'pipe'],
+            });
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            let hasResolved = false;
+            let timeout;
+            const complete = (exitCode, timedOut = false, error) => {
+                if (hasResolved) {
+                    return;
+                }
+                hasResolved = true;
+                clearTimeout(timeout);
+                resolve({
+                    stdout: stdoutChunks.join(''),
+                    stderr: error?.message ?? stderrChunks.join(''),
+                    exitCode,
+                    timedOut,
+                });
+            };
+            if (request.timeoutMs !== undefined) {
+                timeout = setTimeout(() => {
+                    terminateProcess(childProcess);
+                    complete(-1, true);
+                }, request.timeoutMs);
+            }
+            childProcess.stdout?.setEncoding('utf8').on('data', (chunk) => {
+                stdoutChunks.push(chunk);
+                request.onOutput?.(chunk, 'stdout');
+            });
+            childProcess.stderr?.setEncoding('utf8').on('data', (chunk) => {
+                stderrChunks.push(chunk);
+                request.onOutput?.(chunk, 'stderr');
+            });
+            childProcess.on('error', (error) => {
+                complete(-1, false, error);
+            });
+            childProcess.on('close', (exitCode) => {
+                complete(exitCode ?? -1);
+            });
+            childProcess.stdin?.on('error', (error) => {
+                terminateProcess(childProcess);
+                complete(-1, false, error);
+            });
+            childProcess.stdin?.end(request.input);
+        });
+    }
+}
+exports.SpawnProcessRunner = SpawnProcessRunner;
+function terminateProcess(childProcess) {
+    childProcess.kill('SIGKILL');
+    // Descendants can keep the pipes open after the direct child exits.
+    childProcess.stdin?.destroy();
+    childProcess.stdout?.destroy();
+    childProcess.stderr?.destroy();
+}

package/scaffold_tool/src/dependency-installer.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyInstaller = void 0;
+const package_manifest_1 = require("./package-manifest");
+const process_runner_1 = require("../../processes/process-runner");
+class DependencyInstaller {
+    config;
+    fileSystem;
+    processRunner;
+    progress;
+    projectInspector;
+    constructor(dependencies) {
+        this.config = dependencies.config;
+        this.fileSystem = dependencies.fileSystem;
+        this.processRunner = dependencies.processRunner;
+        this.progress = dependencies.progress;
+        this.projectInspector = dependencies.projectInspector;
+    }
+    async install(projectDirectory, packageManager, additionalPackages = []) {
+        const packages = await this.progress.run('Dependencies > Select package version and missing peers', () => this.getPackagesToInstall(projectDirectory, additionalPackages));
+        const installVerb = packageManager === 'npm' ? 'install' : 'add';
+        await this.progress.run(`Dependencies > Run ${packageManager} ${installVerb}`, async (reportOutput) => {
+            reportOutput(`Installing ${packages.join(', ')}…\n`);
+            await (0, process_runner_1.runSuccessfulProcess)(this.processRunner, {
+                binary: packageManager,
+                args: [installVerb, ...packages],
+                cwd: projectDirectory,
+                env: { npm_config_loglevel: 'error' },
+                onOutput: reportOutput,
+            });
+        });
+    }
+    async getPackagesToInstall(projectDirectory, additionalPackages) {
+        const projectManifest = await this.projectInspector.readManifest(projectDirectory);
+        const missingPeerPackages = Object.entries(this.config.peerRanges)
+            .filter(([dependencyName]) => !projectManifest?.dependencyNames.has(dependencyName))
+            .map(([dependencyName, versionRange]) => `${dependencyName}@${versionRange}`);
+        return [...additionalPackages, await this.getDesignSystemPackageSpec(), ...missingPeerPackages];
+    }
+    async getDesignSystemPackageSpec() {
+        if (this.config.localPackagePath) {
+            return `file:${this.config.localPackagePath}`;
+        }
+        const packageManifest = await (0, package_manifest_1.readPackageManifest)(this.fileSystem, this.config.packageManifestPath);
+        const packageVersion = packageManifest?.version;
+        if (packageVersion && packageVersion !== '0.0.1-0') {
+            return `${this.config.packageName}@${packageVersion}`;
+        }
+        return `${this.config.packageName}@latest`;
+    }
+}
+exports.DependencyInstaller = DependencyInstaller;

package/scaffold_tool/src/file-system.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/scaffold_tool/src/get-progress-reporter.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProgressReporter = getProgressReporter;
+const listr_progress_reporter_1 = require("./listr-progress-reporter");
+const terminal_progress_reporter_1 = require("./terminal-progress-reporter");
+function getProgressReporter(terminal) {
+    return process.stdout.isTTY && process.stderr.isTTY && !process.env['CI'] && process.env['TERM'] !== 'dumb'
+        ? new listr_progress_reporter_1.ListrProgressReporter()
+        : new terminal_progress_reporter_1.TerminalProgressReporter(terminal);
+}

package/scaffold_tool/src/listr-progress-reporter.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListrProgressReporter = void 0;
+const node_util_1 = require("node:util");
+const listr2_1 = require("listr2");
+class ListrProgressReporter {
+    activePhases = new Set();
+    pending = new Set();
+    reportOutput;
+    async run(phase, operation) {
+        if (!this.reportOutput) {
+            return this.runSession(phase, operation);
+        }
+        const result = this.runPhase(phase, operation);
+        const settled = result.then(() => { }, () => { });
+        this.pending.add(settled);
+        void settled.then(() => this.pending.delete(settled));
+        return result;
+    }
+    async runSession(phase, operation) {
+        const tasks = new listr2_1.Listr([
+            {
+                title: phase,
+                rendererOptions: { persistentOutput: true },
+                task: async (context, task) => {
+                    this.reportOutput = (output) => {
+                        task.output = output;
+                    };
+                    const timer = setInterval(() => this.renderPhases(), 1000);
+                    timer.unref();
+                    try {
+                        context.value = await operation((output) => {
+                            task.output = output;
+                        });
+                    }
+                    finally {
+                        // Promise.all can reject while sibling phases still own child processes.
+                        while (this.pending.size > 0) {
+                            await Promise.all(this.pending);
+                        }
+                        clearInterval(timer);
+                        this.reportOutput = undefined;
+                        this.activePhases.clear();
+                    }
+                },
+            },
+        ], {
+            rendererOptions: { timer: listr2_1.PRESET_TIMER, collapseErrors: false },
+            // listr2 7's signal listener is never removed; Node retains its normal SIGINT behavior.
+            registerSignalListeners: false,
+        });
+        return (await tasks.run()).value;
+    }
+    async runPhase(title, operation) {
+        const phase = {
+            title,
+            startedAt: performance.now(),
+            output: '',
+            unfinishedLines: { stdout: '', stderr: '' },
+            failed: false,
+        };
+        this.activePhases.add(phase);
+        this.renderPhases();
+        try {
+            return await operation((output, stream = 'stdout') => {
+                const lines = (phase.unfinishedLines[stream] + (0, node_util_1.stripVTControlCharacters)(output)).split(/\r\n|[\r\n]/);
+                phase.unfinishedLines[stream] = lines.pop() ?? '';
+                phase.output = phase.unfinishedLines[stream] || lines.reverse().find((line) => line.trim()) || phase.output;
+                this.renderPhases();
+            });
+        }
+        catch (error) {
+            phase.failed = true;
+            throw error;
+        }
+        finally {
+            if (!phase.failed) {
+                this.activePhases.delete(phase);
+            }
+            this.renderPhases();
+        }
+    }
+    renderPhases() {
+        const lines = [...this.activePhases].map((phase) => {
+            const seconds = Math.floor((performance.now() - phase.startedAt) / 1000);
+            const status = phase.failed ? '[failed] ' : '';
+            const output = phase.output ? `\n  ${phase.output}` : '';
+            return `${status}${phase.title} (${seconds}s)${output}`;
+        });
+        this.reportOutput?.(lines.join('\n'));
+    }
+}
+exports.ListrProgressReporter = ListrProgressReporter;

package/scaffold_tool/src/local-main.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const local_package_builder_1 = require("./local-package-builder");
+const main_1 = require("./main");
+const node_file_system_1 = require("./node-file-system");
+const scaffold_config_1 = require("./scaffold-config");
+const terminal_progress_reporter_1 = require("./terminal-progress-reporter");
+const spawn_process_runner_1 = require("../../processes/spawn-process-runner");
+async function getLocalConfig(args) {
+    const packageDirectory = (0, node_path_1.resolve)(__dirname, '../..');
+    const config = (0, scaffold_config_1.getScaffoldToolConfig)(packageDirectory);
+    const { values } = (0, node_util_1.parseArgs)({
+        args: [...args],
+        options: {
+            'local-package': { type: 'boolean' },
+            mode: { type: 'string' },
+            name: { type: 'string' },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    if (!values['local-package']) {
+        return config;
+    }
+    const progress = new terminal_progress_reporter_1.TerminalProgressReporter({
+        write: (message) => {
+            process.stdout.write(message);
+        },
+        writeError: (message) => {
+            process.stderr.write(message);
+        },
+    });
+    const packageBuilder = new local_package_builder_1.LocalPackageBuilder({
+        packageDirectory,
+        processRunner: new spawn_process_runner_1.SpawnProcessRunner(),
+        fileSystem: new node_file_system_1.NodeFileSystem(),
+        progress,
+    });
+    return { ...config, localPackagePath: await packageBuilder.build() };
+}
+async function run(args) {
+    await (0, main_1.main)(args, await getLocalConfig(args));
+}
+void run(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`\nERROR: ${message}\n`);
+    process.exitCode = 1;
+});

package/scaffold_tool/src/local-package-builder.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalPackageBuilder = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const process_runner_1 = require("../../processes/process-runner");
+const PREPUBLISH_FILES = ['package.json', 'README.md', 'AGENTS.md', 'package.json.bak', 'README_bak.md'];
+class LocalPackageBuilder {
+    packageDirectory;
+    processRunner;
+    fileSystem;
+    progress;
+    constructor(dependencies) {
+        this.packageDirectory = dependencies.packageDirectory;
+        this.processRunner = dependencies.processRunner;
+        this.fileSystem = dependencies.fileSystem;
+        this.progress = dependencies.progress;
+    }
+    async build() {
+        const originalFiles = await this.progress.run('Local package > Save source files', () => this.snapshotSourceFiles());
+        const outputDirectory = (0, node_path_1.join)(this.packageDirectory, '.local-packages');
+        await (0, promises_1.mkdir)(outputDirectory, { recursive: true });
+        // Keep each archive at a unique, persistent path for lockfiles and package-manager caches.
+        const buildDirectory = await (0, promises_1.mkdtemp)((0, node_path_1.join)(outputDirectory, 'build-'));
+        const tarballPath = (0, node_path_1.join)(buildDirectory, 'design-system.tgz');
+        const errors = [];
+        try {
+            await this.createArchive(tarballPath);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            // Restore the working copies, not HEAD: local component and manifest edits are what we're testing.
+            await this.progress.run('Local package > Restore source files', () => this.restoreSourceFiles(originalFiles));
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0) {
+            try {
+                await this.progress.run('Local package > Remove unusable archive', () => this.fileSystem.remove(buildDirectory));
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            throwCollectedErrors(errors);
+        }
+        return tarballPath;
+    }
+    async createArchive(tarballPath) {
+        await this.progress.run('Local package > Run publishing build', () => (0, process_runner_1.runSuccessfulProcess)(this.processRunner, {
+            binary: 'yarn',
+            args: ['prepublish'],
+            cwd: this.packageDirectory,
+            output: 'inherit',
+        }));
+        await this.progress.run('Local package > Pack archive', () => (0, process_runner_1.runSuccessfulProcess)(this.processRunner, {
+            binary: 'yarn',
+            args: ['pack', '--out', tarballPath],
+            cwd: this.packageDirectory,
+            output: 'inherit',
+        }));
+    }
+    async snapshotSourceFiles() {
+        return Promise.all(PREPUBLISH_FILES.map(async (name) => {
+            const path = (0, node_path_1.join)(this.packageDirectory, name);
+            const contents = (await this.fileSystem.pathExists(path))
+                ? await this.fileSystem.readTextFile(path)
+                : undefined;
+            return { path, contents };
+        }));
+    }
+    async restoreSourceFiles(files) {
+        const outcomes = await Promise.allSettled(files.map(async ({ path, contents }) => {
+            if (contents === undefined) {
+                await this.fileSystem.remove(path);
+            }
+            else {
+                await this.fileSystem.writeTextFile(path, contents);
+            }
+        }));
+        const errors = [];
+        for (const outcome of outcomes) {
+            if (outcome.status === 'rejected') {
+                errors.push(outcome.reason);
+            }
+        }
+        if (errors.length > 0) {
+            throwCollectedErrors(errors);
+        }
+    }
+}
+exports.LocalPackageBuilder = LocalPackageBuilder;
+function throwCollectedErrors(errors) {
+    if (errors.length === 1) {
+        throw errors[0];
+    }
+    const messages = errors.map((error) => (error instanceof Error ? error.message : String(error)));
+    throw new AggregateError(errors, messages.join('\n'));
+}

package/scaffold_tool/src/main.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const node_path_1 = require("node:path");
+const dependency_installer_1 = require("./dependency-installer");
+const get_progress_reporter_1 = require("./get-progress-reporter");
+const node_file_system_1 = require("./node-file-system");
+const project_configurator_1 = require("./project-configurator");
+const project_inspector_1 = require("./project-inspector");
+const readline_terminal_1 = require("./readline-terminal");
+const scaffold_config_1 = require("./scaffold-config");
+const scaffold_tool_1 = require("./scaffold-tool");
+const spawn_process_runner_1 = require("../../processes/spawn-process-runner");
+async function main(args, config = (0, scaffold_config_1.getScaffoldToolConfig)((0, node_path_1.resolve)(__dirname, '../..'))) {
+    const fileSystem = new node_file_system_1.NodeFileSystem();
+    const processRunner = new spawn_process_runner_1.SpawnProcessRunner();
+    const terminal = new readline_terminal_1.ReadlineTerminal();
+    const progress = (0, get_progress_reporter_1.getProgressReporter)(terminal);
+    const projectInspector = new project_inspector_1.ProjectInspector(fileSystem);
+    const dependencyInstaller = new dependency_installer_1.DependencyInstaller({
+        config,
+        fileSystem,
+        processRunner,
+        progress,
+        projectInspector,
+    });
+    const projectConfigurator = new project_configurator_1.ProjectConfigurator({ config, fileSystem, projectInspector, terminal, progress });
+    const scaffoldTool = new scaffold_tool_1.ScaffoldTool({
+        config,
+        dependencyInstaller,
+        fileSystem,
+        processRunner,
+        progress,
+        projectConfigurator,
+        projectInspector,
+        terminal,
+    });
+    await scaffoldTool.main(args, process.cwd());
+}
+if (require.main === module) {
+    void main(process.argv.slice(2)).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`\nERROR: ${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/scaffold_tool/src/node-file-system.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeFileSystem = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+class NodeFileSystem {
+    async pathExists(filePath) {
+        try {
+            await (0, promises_1.access)(filePath);
+            return true;
+        }
+        catch (error) {
+            if (isMissingPathError(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async readTextFile(filePath) {
+        return (0, promises_1.readFile)(filePath, 'utf8');
+    }
+    async remove(filePath) {
+        await (0, promises_1.rm)(filePath, { force: true, recursive: true });
+    }
+    async writeTextFile(filePath, content) {
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(filePath), { recursive: true });
+        await (0, promises_1.writeFile)(filePath, content);
+    }
+}
+exports.NodeFileSystem = NodeFileSystem;
+function isMissingPathError(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}

package/scaffold_tool/src/package-manifest.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPackageManifest = readPackageManifest;
+exports.parsePackageManifest = parsePackageManifest;
+async function readPackageManifest(fileSystem, manifestPath) {
+    try {
+        const content = await fileSystem.readTextFile(manifestPath);
+        return parsePackageManifest(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parsePackageManifest(content) {
+    try {
+        const parsedManifest = JSON.parse(content);
+        if (!isStringKeyedObject(parsedManifest)) {
+            return undefined;
+        }
+        const dependencyNames = new Set();
+        addDependencyNames(dependencyNames, parsedManifest['dependencies']);
+        addDependencyNames(dependencyNames, parsedManifest['devDependencies']);
+        const version = parsedManifest['version'];
+        return typeof version === 'string' ? { dependencyNames, version } : { dependencyNames };
+    }
+    catch {
+        return undefined;
+    }
+}
+function addDependencyNames(dependencyNames, dependencyGroup) {
+    if (!isStringKeyedObject(dependencyGroup)) {
+        return;
+    }
+    for (const dependencyName of Object.keys(dependencyGroup)) {
+        dependencyNames.add(dependencyName);
+    }
+}
+function isStringKeyedObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/scaffold_tool/src/progress-reporter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/scaffold_tool/src/project-configurator.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectConfigurator = void 0;
+const node_path_1 = require("node:path");
+const project_templates_1 = require("./project-templates");
+const theme_picker_templates_1 = require("./theme-picker-templates");
+const theme_templates_1 = require("./theme-templates");
+class ProjectConfigurator {
+    config;
+    fileSystem;
+    projectInspector;
+    progress;
+    terminal;
+    constructor(dependencies) {
+        this.config = dependencies.config;
+        this.fileSystem = dependencies.fileSystem;
+        this.projectInspector = dependencies.projectInspector;
+        this.progress = dependencies.progress;
+        this.terminal = dependencies.terminal;
+    }
+    async configureVite(projectDirectory, themeName = 'dubois') {
+        await Promise.all([
+            this.writeProjectFile(projectDirectory, 'src/main.tsx', (0, project_templates_1.createViteMainFile)()),
+            this.writeProjectFile(projectDirectory, 'src/dbui.css', project_templates_1.BODY_FONT_CSS),
+            this.writeProjectFile(projectDirectory, 'src/app-theme.tsx', (0, theme_picker_templates_1.createThemeProviderFile)(themeName)),
+            this.writeProjectFile(projectDirectory, 'src/app-themes.ts', (0, theme_templates_1.createThemeRegistryFile)()),
+            this.writeProjectFile(projectDirectory, 'src/theme-picker.tsx', (0, theme_picker_templates_1.createThemePickerFile)()),
+            this.writeProjectFile(projectDirectory, 'THEME.md', (0, theme_templates_1.createThemeReadme)(themeName, 'src')),
+            this.writeProjectFile(projectDirectory, 'src/App.tsx', (0, project_templates_1.createViteAppFile)()),
+            this.progress.run('Configuration > Add CSS declarations', () => this.ensureCssDeclaration(projectDirectory, 'vite')),
+            this.writeProjectFile(projectDirectory, 'vite.config.ts', (0, project_templates_1.createViteConfigFile)()),
+            this.progress.run('Configuration > Configure TypeScript JSX', () => this.addTsconfigJsxImportSource((0, node_path_1.join)(projectDirectory, 'tsconfig.app.json'))),
+            this.progress.run('Configuration > Remove Vite demo files', () => this.removeViteDemoFiles(projectDirectory)),
+            this.progress.run('Configuration > Set up agent instructions', () => this.writeAgentInstructions(projectDirectory)),
+        ]);
+    }
+    async configureNext(projectDirectory, projectName, themeName = 'dubois') {
+        const nextConfigPath = await this.progress.run('Configuration > Find Next.js config', () => this.findNextConfigPath(projectDirectory));
+        const nextConfig = nextConfigPath.endsWith('.js') ? (0, project_templates_1.createCommonJsNextConfigFile)() : (0, project_templates_1.createEsmNextConfigFile)();
+        await Promise.all([
+            this.writeProjectFile(projectDirectory, 'pages/_app.tsx', (0, project_templates_1.createNextAppFile)()),
+            this.writeProjectFile(projectDirectory, 'pages/index.tsx', (0, project_templates_1.createNextIndexFile)()),
+            this.writeProjectFile(projectDirectory, 'dbui-app.tsx', (0, project_templates_1.createNextDbuiAppFile)()),
+            this.writeProjectFile(projectDirectory, 'dbui.css', project_templates_1.BODY_FONT_CSS),
+            this.writeProjectFile(projectDirectory, 'app-theme.tsx', (0, theme_picker_templates_1.createThemeProviderFile)(themeName)),
+            this.writeProjectFile(projectDirectory, 'app-themes.ts', (0, theme_templates_1.createThemeRegistryFile)()),
+            this.writeProjectFile(projectDirectory, 'theme-picker.tsx', (0, theme_picker_templates_1.createThemePickerFile)()),
+            this.writeProjectFile(projectDirectory, 'THEME.md', (0, theme_templates_1.createThemeReadme)(themeName, '.')),
+            this.progress.run('Configuration > Add CSS declarations', () => this.ensureCssDeclaration(projectDirectory, 'next')),
+            this.progress.run('Configuration > Write Next.js config', () => this.fileSystem.writeTextFile(nextConfigPath, nextConfig)),
+            this.progress.run('Configuration > Configure TypeScript JSX', () => this.addTsconfigJsxImportSource((0, node_path_1.join)(projectDirectory, 'tsconfig.json'))),
+            this.writeProjectFile(projectDirectory, 'DEPLOY.md', (0, project_templates_1.createVercelReadme)(projectName)),
+            this.progress.run('Configuration > Set up agent instructions', () => this.writeAgentInstructions(projectDirectory)),
+        ]);
+    }
+    async configureExisting(projectDirectory, projectType) {
+        const [addedImportsTo, wroteAgentInstructions] = await Promise.all([
+            this.progress.run('Configuration > Add CSS imports to entry point', () => this.configureExistingEntryFile(projectDirectory, projectType)),
+            this.progress.run('Configuration > Set up agent instructions', () => this.writeAgentInstructions(projectDirectory)),
+            this.progress.run('Configuration > Add CSS declarations', () => this.ensureCssDeclaration(projectDirectory, projectType)),
+        ]);
+        return addedImportsTo ? { addedImportsTo, wroteAgentInstructions } : { wroteAgentInstructions };
+    }
+    async configureExistingEntryFile(projectDirectory, projectType) {
+        const entryFile = await this.projectInspector.findExistingEntryFile(projectDirectory, projectType);
+        return entryFile && (await this.addImports(entryFile, project_templates_1.CSS_IMPORTS)) ? entryFile : undefined;
+    }
+    async writeProjectFile(projectDirectory, relativePath, content) {
+        await this.progress.run(`Configuration > Write ${relativePath}`, () => this.fileSystem.writeTextFile((0, node_path_1.join)(projectDirectory, relativePath), content));
+    }
+    async addImports(filePath, imports) {
+        const existingContent = (await this.fileSystem.pathExists(filePath))
+            ? await this.fileSystem.readTextFile(filePath)
+            : '';
+        const missingImports = imports.filter((importStatement) => !existingContent.includes(importStatement));
+        if (missingImports.length === 0) {
+            return false;
+        }
+        const sourceLines = existingContent.split('\n');
+        const directiveIndex = sourceLines.findIndex((line) => /^\s*(['"])use (client|server)\1;?\s*$/.test(line));
+        const insertionIndex = directiveIndex >= 0 ? directiveIndex + 1 : 0;
+        sourceLines.splice(insertionIndex, 0, ...missingImports);
+        await this.fileSystem.writeTextFile(filePath, sourceLines.join('\n'));
+        return true;
+    }
+    async addTsconfigJsxImportSource(tsconfigPath) {
+        if (!(await this.fileSystem.pathExists(tsconfigPath))) {
+            return;
+        }
+        const content = await this.fileSystem.readTextFile(tsconfigPath);
+        if (content.includes('jsxImportSource')) {
+            return;
+        }
+        const compilerOptionsMarker = '"compilerOptions": {';
+        if (!content.includes(compilerOptionsMarker)) {
+            return;
+        }
+        const updatedContent = content.replace(compilerOptionsMarker, `${compilerOptionsMarker}\n    "jsxImportSource": "@emotion/react",`);
+        await this.fileSystem.writeTextFile(tsconfigPath, updatedContent);
+    }
+    async ensureCssDeclaration(projectDirectory, projectType) {
+        const relativePath = projectType === 'next' ? 'css.d.ts' : 'src/css.d.ts';
+        const declarationPath = (0, node_path_1.join)(projectDirectory, relativePath);
+        if (!(await this.fileSystem.pathExists(declarationPath))) {
+            await this.fileSystem.writeTextFile(declarationPath, project_templates_1.CSS_DECLARATION);
+        }
+    }
+    async findNextConfigPath(projectDirectory) {
+        for (const fileName of ['next.config.ts', 'next.config.mjs', 'next.config.js']) {
+            const configPath = (0, node_path_1.join)(projectDirectory, fileName);
+            if (await this.fileSystem.pathExists(configPath)) {
+                return configPath;
+            }
+        }
+        return (0, node_path_1.join)(projectDirectory, 'next.config.mjs');
+    }
+    async removeViteDemoFiles(projectDirectory) {
+        await Promise.all(['src/App.css', 'src/index.css', 'src/assets'].map((relativePath) => this.fileSystem.remove((0, node_path_1.join)(projectDirectory, relativePath))));
+    }
+    async writeAgentInstructions(projectDirectory) {
+        const agentInstructionsPath = (0, node_path_1.join)(projectDirectory, 'AGENTS.md');
+        const claudeInstructionsPath = (0, node_path_1.join)(projectDirectory, 'CLAUDE.md');
+        let wroteAgentInstructions = false;
+        if (!(await this.fileSystem.pathExists(agentInstructionsPath))) {
+            if (!(await this.fileSystem.pathExists(this.config.agentInstructionsPath))) {
+                this.terminal.writeError('> Skipping AGENTS.md/CLAUDE.md (bundled scaffold-agents.md not found).\n');
+                return false;
+            }
+            const instructions = await this.fileSystem.readTextFile(this.config.agentInstructionsPath);
+            await this.fileSystem.writeTextFile(agentInstructionsPath, instructions);
+            wroteAgentInstructions = true;
+        }
+        if (!(await this.fileSystem.pathExists(claudeInstructionsPath))) {
+            await this.fileSystem.writeTextFile(claudeInstructionsPath, '@AGENTS.md\n');
+        }
+        return wroteAgentInstructions;
+    }
+}
+exports.ProjectConfigurator = ProjectConfigurator;