@databricks/design-system 2.0.6 → 2.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks/design-system",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "DuBois Design System",
   "keywords": [],
   "license": "ISC",
@@ -55,6 +55,7 @@
   "files": [
     "/AGENTS.md",
     "/CHANGELOG.md",
+    "/setup.mjs",
     "dist",
     "dist-types",
     "test-utils",
@@ -106,7 +107,7 @@
     "@figma/code-connect": "^2.0.0",
     "@jest/globals": "^30.0.2",
     "@svgr/cli": "^8.1.0",
-    "@swc/core": "^1.15.47",
+    "@swc/core": "^1.16.2",
     "@swc/register": "^0.1.10",
     "@tanstack/react-table": "8.21.2",
     "@testing-library/jest-dom": "^6.4.2",
@@ -142,7 +143,6 @@
   },
   "dependencies": {
     "@ant-design/icons": "^4.7.0",
-    "@databricks/testing-library": "1.0.0",
     "@emotion/unitless": "^0.8.1",
     "@floating-ui/dom": "^1.6.12",
     "@floating-ui/react": "^0.26.25",
@@ -186,5 +186,6 @@
     "react-resizable": "^3.0.4",
     "tabbable": "^6.4.0",
     "tslib": "^2.8.1"
-  }
+  },
+  "bin": "./setup.mjs"
 }

package/setup.mjs

@@ -0,0 +1,586 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview `npx @databricks/design-system` — interactive setup for consumers of the dbui
+ * design system. Runs in the user's OWN project, outside the universe monorepo, so it uses only
+ * Node built-ins and shells out to the canonical scaffolders (create-vite, create-next-app)
+ * rather than shipping its own project templates. The wiring it applies (CSS imports, provider,
+ * Emotion JSX runtime, css.d.ts, body font) mirrors the shipped AGENTS.md "Setup" section, which
+ * is the single source of truth for how a consumer wires up the package.
+ *
+ * Shipped as plain ESM JavaScript, not TypeScript: Node refuses type-stripping for files under
+ * node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING) — which is exactly where npx runs a
+ * published bin — so a `.ts`/`.mts` bin would fail to execute.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = '@databricks/design-system';
+
+// Pin the scaffolders instead of `@latest`: the download must be reviewed and reproducible
+// (Databricks supply-chain policy), not a floating fetch of whatever is newest.
+const VITE_SCAFFOLDER = 'create-vite@9.2.1';
+// create-next-app@14 (Next 14) so the project runs on React 18. dbui 2.0.x is built on AntD 4 and
+// only type-checks under React 18; Next 15+ requires React 19, whose types break AntD-derived
+// props (e.g. Typography.Title). The Vite path pins React 18 explicitly (see REACT_18_PINS).
+const NEXT_SCAFFOLDER = 'create-next-app@14.2.35';
+
+// The Vite scaffolder installs React 19, but dbui 2.0.x is typed for React 18 — under React 19's
+// types AntD-derived props resolve as required and `npm run build` fails. Pin the new Vite project
+// back to React 18 so it type-checks.
+const REACT_18_PINS = ['react@^18', 'react-dom@^18', '@types/react@^18', '@types/react-dom@^18'];
+
+// Peers to install on demand when a target project is missing them. react/react-dom are
+// deliberately excluded: new projects get React 18 from pinReact18 / create-next-app@14, and an
+// existing project's React is never touched — adding only the missing half of the react/react-dom
+// pair could leave an incompatible version combination.
+const PEER_RANGES = {
+  '@emotion/react': '^11.11.3',
+  moment: '^2.25.3',
+};
+
+// The exact side-effect imports a consumer needs at their entry point (from AGENTS.md).
+const CSS_IMPORTS = [`import '${PACKAGE_NAME}/index.css';`, `import '${PACKAGE_NAME}/fonts/dm-sans.css';`];
+
+// ApplyGlobalStyles sets the body background and text color but NOT font-family (per AGENTS.md),
+// so the app must apply the DM Sans token itself.
+const BODY_FONT_CSS = 'body {\n  font-family: var(--db-font-family);\n}\n';
+
+// TypeScript rejects the CSS side-effect imports without an ambient declaration; AGENTS.md
+// prescribes this one-liner instead of per-import suppressions.
+const CSS_DECLARATION = "declare module '*.css';\n";
+
+// The version this script shipped inside. Pinning the scaffolded dependency to it keeps a
+// generated project on the same version the user invoked, rather than drifting to a newer
+// `latest` on their next install. Falls back to `latest` if the manifest can't be read.
+function designSystemSpec() {
+  try {
+    // fileURLToPath(import.meta.url), not import.meta.dirname, so pinning works on every ESM Node
+    // (import.meta.dirname is undefined before Node 20.11, which would fall back to @latest).
+    const manifestPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'package.json');
+    const { version } = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    // The in-repo placeholder (0.0.1-0) is never what a real consumer has; only pin a
+    // published-looking version.
+    if (version && version !== '0.0.1-0') return `${PACKAGE_NAME}@${version}`;
+  } catch {
+    // fall through
+  }
+  return `${PACKAGE_NAME}@latest`;
+}
+
+// --mode/--name make the scaffold modes non-interactive (used by tests); omit them and the CLI
+// prompts. There is no --yes: the CLI has no confirmation prompts to skip.
+function parseArgs(argv) {
+  const args = { mode: undefined, name: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--mode') args.mode = argv[++i];
+    else if (arg === '--name') args.name = argv[++i];
+    else if (!arg.startsWith('-') && !args.name) args.name = arg;
+  }
+  return args;
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (answer) => resolve(answer.trim())));
+}
+
+// Runs a command with inherited stdio so the canonical scaffolder's own prompts/output reach the
+// user directly. Exits the process on failure rather than half-finishing a setup.
+function run(command, commandArgs, cwd) {
+  const result = spawnSync(command, commandArgs, { cwd, stdio: 'inherit', shell: false });
+  if (result.status !== 0) {
+    fail(`\`${command} ${commandArgs.join(' ')}\` failed (exit ${result.status}).`);
+  }
+}
+
+function fail(message) {
+  console.error(`\nERROR: ${message}`);
+  process.exit(1);
+}
+
+function readPackageJson(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function allDeps(dir) {
+  const pkg = readPackageJson(dir);
+  if (!pkg) return {};
+  return { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+}
+
+function hasAnyDep(pkg, names) {
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  return names.some((name) => name in deps);
+}
+
+// Picks the package manager from the lockfile a scaffolder or the user already committed to, so
+// we don't cross yarn/pnpm/npm and produce a second lockfile.
+function detectPackageManager(dir) {
+  if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function installCommand(pm, packages) {
+  const verb = pm === 'npm' ? 'install' : 'add';
+  return [pm, [verb, ...packages]];
+}
+
+// Classifies an existing project so "add to existing" applies the right wiring. Order matters: a
+// Next.js project also has react, so check the most specific signal first.
+function detectExistingProject(dir) {
+  const pkg = readPackageJson(dir);
+  if (!pkg) return { type: 'unknown', reason: 'no package.json found' };
+
+  const hasConfig = (names) => names.some((n) => fs.existsSync(path.join(dir, n)));
+
+  if (hasAnyDep(pkg, ['next']) || hasConfig(['next.config.js', 'next.config.ts', 'next.config.mjs'])) {
+    return { type: 'next', pkg };
+  }
+  if (hasAnyDep(pkg, ['vite']) || hasConfig(['vite.config.ts', 'vite.config.js'])) {
+    return { type: 'vite', pkg };
+  }
+  if (hasAnyDep(pkg, ['react-scripts'])) return { type: 'cra', pkg };
+  if (hasAnyDep(pkg, ['react'])) return { type: 'react', pkg };
+  return { type: 'unknown', reason: 'no React dependency detected', pkg };
+}
+
+// Inserts import lines into a source file. A "use client"/"use server" directive is only honored
+// as the first statement, so if one is present the imports go right after it (even when a BOM or a
+// leading license comment sits above it); otherwise they go at the top. Idempotent: lines already
+// present are skipped, so re-running is a no-op.
+function addImports(filePath, lines) {
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const missing = lines.filter((line) => !existing.includes(line));
+  if (missing.length === 0) return false;
+
+  const sourceLines = existing.split('\n');
+  const directiveIndex = sourceLines.findIndex((line) => /^\s*(['"])use (client|server)\1;?\s*$/.test(line));
+  const insertAt = directiveIndex >= 0 ? directiveIndex + 1 : 0;
+  sourceLines.splice(insertAt, 0, ...missing);
+  fs.writeFileSync(filePath, sourceLines.join('\n'));
+  return true;
+}
+
+function writeFileEnsuringDir(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+// A single ambient `declare module '*.css'` so TypeScript accepts the CSS side-effect imports,
+// placed where the project's tsconfig actually includes it (under src/ for Vite/CRA; the repo
+// root is in scope for Next). Never overwrites an existing declaration file.
+function ensureCssDeclaration(dir, type) {
+  const rel = type === 'next' ? 'css.d.ts' : path.join('src', 'css.d.ts');
+  const full = path.join(dir, rel);
+  if (fs.existsSync(full)) return;
+  writeFileEnsuringDir(full, CSS_DECLARATION);
+}
+
+// Emotion's `css` prop needs TypeScript itself to use Emotion's JSX types; the bundler/compiler
+// settings only affect the runtime transform, not type-checking. Set jsxImportSource in the
+// project's tsconfig too (per AGENTS.md). Inserts into the first compilerOptions block; skips if
+// the option is already present or the file is missing.
+function addTsconfigJsxImportSource(tsconfigPath) {
+  if (!fs.existsSync(tsconfigPath)) return;
+  const content = fs.readFileSync(tsconfigPath, 'utf8');
+  if (content.includes('jsxImportSource')) return;
+  const marker = '"compilerOptions": {';
+  if (!content.includes(marker)) return;
+  fs.writeFileSync(tsconfigPath, content.replace(marker, `${marker}\n    "jsxImportSource": "@emotion/react",`));
+}
+
+// Forces a newly scaffolded project onto React 18 (runtime + types), because dbui 2.0.x is typed
+// for React 18. Only for new projects we generate — an existing project's React is never touched.
+function pinReact18(dir, pm) {
+  console.log('\n> Pinning React 18 (dbui is typed for React 18)…\n');
+  const [command, commandArgs] = installCommand(pm, REACT_18_PINS);
+  run(command, commandArgs, dir);
+}
+
+// Installs the pinned design-system version plus any PEER_RANGES peer the project is missing
+// (currently @emotion/react and moment). react/react-dom are handled elsewhere — see PEER_RANGES.
+function installDesignSystem(dir, pm) {
+  const present = allDeps(dir);
+  const missingPeers = Object.entries(PEER_RANGES)
+    .filter(([name]) => !(name in present))
+    .map(([name, range]) => `${name}@${range}`);
+  const packages = [designSystemSpec(), ...missingPeers];
+  console.log(`\n> Installing ${packages.join(', ')} with ${pm}…\n`);
+  const [command, commandArgs] = installCommand(pm, packages);
+  run(command, commandArgs, dir);
+}
+
+function scaffoldVite(name) {
+  console.log(`\n> Scaffolding a Vite + React + TypeScript project via ${VITE_SCAFFOLDER}…\n`);
+  // npx runs the already-`create-`-prefixed package directly (unlike `npm create`, which would
+  // prepend a second `create-`), matching how the Next path invokes create-next-app.
+  run('npx', [VITE_SCAFFOLDER, name, '--template', 'react-ts']);
+
+  const dir = path.resolve(process.cwd(), name);
+  const pm = detectPackageManager(dir);
+  pinReact18(dir, pm);
+  installDesignSystem(dir, pm);
+
+  // Own the entry file wholesale — we generated this project, so there is no user code to
+  // preserve, and a known-good main.tsx is cleaner than surgically editing create-vite's.
+  writeFileEnsuringDir(
+    path.join(dir, 'src', 'main.tsx'),
+    [
+      ...CSS_IMPORTS,
+      "import './dbui.css';",
+      '',
+      "import { StrictMode } from 'react';",
+      "import { createRoot } from 'react-dom/client';",
+      "import { ApplyGlobalStyles, DesignSystemProvider } from '@databricks/design-system';",
+      "import { App } from './App';",
+      '',
+      "createRoot(document.getElementById('root')!).render(",
+      '  <StrictMode>',
+      '    <DesignSystemProvider>',
+      '      <ApplyGlobalStyles />',
+      '      <App />',
+      '    </DesignSystemProvider>',
+      '  </StrictMode>,',
+      ');',
+      '',
+    ].join('\n'),
+  );
+
+  writeFileEnsuringDir(path.join(dir, 'src', 'dbui.css'), BODY_FONT_CSS);
+  writeFileEnsuringDir(path.join(dir, 'src', 'App.tsx'), viteAppFile());
+  ensureCssDeclaration(dir, 'vite');
+  configureViteEmotion(dir);
+  addTsconfigJsxImportSource(path.join(dir, 'tsconfig.app.json'));
+
+  printDone(name, pm, 'vite');
+}
+
+// create-vite's react plugin drives the JSX transform, so the Emotion `css` prop needs its
+// jsxImportSource option — the runtime half of the Emotion setup (the tsconfig half is separate).
+function configureViteEmotion(dir) {
+  writeFileEnsuringDir(
+    path.join(dir, 'vite.config.ts'),
+    [
+      "import { defineConfig } from 'vite';",
+      "import react from '@vitejs/plugin-react';",
+      '',
+      '// jsxImportSource wires up Emotion so the `css` prop dbui components use works.',
+      'export default defineConfig({',
+      "  plugins: [react({ jsxImportSource: '@emotion/react' })],",
+      '});',
+      '',
+    ].join('\n'),
+  );
+}
+
+function scaffoldNext(name) {
+  console.log(`\n> Scaffolding a Next.js (Pages Router) project via ${NEXT_SCAFFOLDER}…\n`);
+  // --no-app selects the Pages Router. dbui is client-only (Emotion + React context) and can't be
+  // server-rendered; Pages Router lets us load the whole app through next/dynamic with ssr:false
+  // so nothing dbui touches the server. App Router's RSC build evaluates every route (even
+  // /_not-found) on the server, which dbui can't survive — hence Pages Router for this prototype.
+  run('npx', [
+    NEXT_SCAFFOLDER,
+    name,
+    '--ts',
+    '--no-app',
+    '--eslint',
+    '--no-tailwind',
+    '--no-src-dir',
+    '--import-alias',
+    '@/*',
+    '--use-npm',
+    '--yes',
+  ]);
+
+  const dir = path.resolve(process.cwd(), name);
+  const pm = detectPackageManager(dir);
+  installDesignSystem(dir, pm);
+
+  // Pages Router requires global CSS to be imported from _app; render the page component plainly.
+  writeFileEnsuringDir(
+    path.join(dir, 'pages', '_app.tsx'),
+    [
+      ...CSS_IMPORTS,
+      "import '../dbui.css';",
+      '',
+      "import type { AppProps } from 'next/app';",
+      '',
+      'export default function App({ Component, pageProps }: AppProps) {',
+      '  return <Component {...pageProps} />;',
+      '}',
+      '',
+    ].join('\n'),
+  );
+
+  writeFileEnsuringDir(
+    path.join(dir, 'pages', 'index.tsx'),
+    [
+      "import dynamic from 'next/dynamic';",
+      '',
+      '// ssr:false renders dbui only on the client, keeping it out of the build-time prerender.',
+      "const DbuiApp = dynamic(() => import('../dbui-app'), { ssr: false });",
+      '',
+      'export default function Home() {',
+      '  return <DbuiApp />;',
+      '}',
+      '',
+    ].join('\n'),
+  );
+
+  writeFileEnsuringDir(path.join(dir, 'dbui-app.tsx'), nextDbuiAppFile());
+  writeFileEnsuringDir(path.join(dir, 'dbui.css'), BODY_FONT_CSS);
+  ensureCssDeclaration(dir, 'next');
+  configureNextEmotion(dir);
+  addTsconfigJsxImportSource(path.join(dir, 'tsconfig.json'));
+  writeVercelReadme(dir, name);
+
+  printDone(name, pm, 'next');
+}
+
+// Next's SWC compiler has first-class Emotion support; enabling it is the idiomatic Next way to
+// get the `css` prop working. create-next-app may emit next.config.ts | .mjs | .js, so write our
+// config into whichever it created rather than adding a second, conflicting config file.
+function configureNextEmotion(dir) {
+  const existing = ['next.config.ts', 'next.config.mjs', 'next.config.js']
+    .map((name) => path.join(dir, name))
+    .find((configPath) => fs.existsSync(configPath));
+  const target = existing ?? path.join(dir, 'next.config.mjs');
+  // Match the export style to the file's module format: a .js config is CommonJS (Next's default
+  // unless the project opts into ESM), while .mjs/.ts are ESM. Writing the wrong one makes Next
+  // fail to load the config.
+  const exportLine = target.endsWith('.js') ? 'module.exports = nextConfig;' : 'export default nextConfig;';
+  writeFileEnsuringDir(
+    target,
+    [
+      "/** @type {import('next').NextConfig} */",
+      'const nextConfig = {',
+      '  // Enables the Emotion `css` prop that dbui components rely on.',
+      '  compiler: { emotion: true },',
+      '};',
+      '',
+      exportLine,
+      '',
+    ].join('\n'),
+  );
+}
+
+// Next.js deploys to Vercel with zero config, so we only leave instructions — no vercel.json is
+// needed, and per the setup we never log in, upload, or deploy anything.
+function writeVercelReadme(dir, name) {
+  writeFileEnsuringDir(
+    path.join(dir, 'DEPLOY.md'),
+    [
+      `# Deploying ${name} to Vercel`,
+      '',
+      'This is a client-only Next.js app, ready to host on Vercel with no extra configuration.',
+      '',
+      '1. Push this project to a Git repository (GitHub/GitLab/Bitbucket).',
+      '2. Import the repo at https://vercel.com/new — Vercel auto-detects Next.js.',
+      '',
+      'Or deploy straight from this directory with the Vercel CLI:',
+      '',
+      '```bash',
+      'npx vercel',
+      '```',
+      '',
+    ].join('\n'),
+  );
+}
+
+function addToExisting(dir) {
+  const detected = detectExistingProject(dir);
+  console.log(`\n> Detected project type: ${detected.type}${detected.reason ? ` (${detected.reason})` : ''}`);
+
+  if (detected.type === 'unknown') {
+    console.log('\nCould not identify a React project here. Set it up manually:');
+    printManualInstructions('generic');
+    return;
+  }
+
+  const pm = detectPackageManager(dir);
+  installDesignSystem(dir, pm);
+  ensureCssDeclaration(dir, detected.type);
+
+  // Wiring the provider into arbitrary existing app code is fragile, so we make only the safe,
+  // idempotent edit (adding the CSS imports where the entry is unambiguous) and print the
+  // provider/font/Emotion steps for the user to apply, rather than rewriting their render.
+  const entry = existingEntryFile(dir, detected.type);
+  if (entry && addImports(entry, CSS_IMPORTS)) {
+    console.log(`> Added the dbui CSS imports to ${path.relative(dir, entry)}`);
+  }
+  printManualInstructions(detected.type);
+}
+
+// Best-effort entry file per framework; undefined when we can't confidently name one.
+function existingEntryFile(dir, type) {
+  const candidatesByType = {
+    next: ['app/layout.tsx', 'app/layout.jsx', 'app/layout.js', 'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.js'],
+    vite: ['src/main.tsx', 'src/main.jsx', 'src/main.ts', 'src/main.js'],
+    cra: ['src/index.tsx', 'src/index.jsx', 'src/index.js'],
+    react: [
+      'src/main.tsx',
+      'src/index.tsx',
+      'src/main.jsx',
+      'src/index.jsx',
+      'src/main.ts',
+      'src/main.js',
+      'src/index.js',
+    ],
+  };
+  for (const rel of candidatesByType[type] ?? []) {
+    const full = path.join(dir, rel);
+    if (fs.existsSync(full)) return full;
+  }
+  return undefined;
+}
+
+function printManualInstructions(type) {
+  const providerNote =
+    type === 'next'
+      ? 'dbui is client-only: put DesignSystemProvider + ApplyGlobalStyles in a "use client" component and render it from your entry — app/layout.tsx (App Router) or pages/_app.tsx (Pages Router). For App Router, load it via next/dynamic with { ssr: false }.'
+      : 'Wrap your root component in <DesignSystemProvider><ApplyGlobalStyles /> … </DesignSystemProvider>.';
+  console.log(
+    [
+      '',
+      'Finish setup:',
+      `  1. Import the styles at your entry point:`,
+      ...CSS_IMPORTS.map((line) => `       ${line}`),
+      `  2. ${providerNote}`,
+      `  3. Set the body font (ApplyGlobalStyles doesn't): body { font-family: var(--db-font-family); }`,
+      `  4. Configure the Emotion JSX runtime (jsxImportSource: '@emotion/react') so the css prop works.`,
+      '',
+      'See the package AGENTS.md for the full setup reference.',
+      '',
+    ].join('\n'),
+  );
+}
+
+function sampleBody() {
+  return [
+    '    <div style={{ padding: theme.spacing.lg }}>',
+    '      <Typography.Title>dbui is set up</Typography.Title>',
+    '      <Button componentId="starter.get_started_button" type="primary">',
+    '        Get started',
+    '      </Button>',
+    '    </div>',
+  ].join('\n');
+}
+
+function viteAppFile() {
+  return [
+    "import { Button, Typography, useDesignSystemTheme } from '@databricks/design-system';",
+    '',
+    'export function App() {',
+    '  const { theme } = useDesignSystemTheme();',
+    '  return (',
+    sampleBody(),
+    '  );',
+    '}',
+    '',
+  ].join('\n');
+}
+
+// The client-only module Next loads with ssr:false: it owns the DesignSystemProvider and the
+// sample, so all dbui usage lives behind the ssr:false boundary and never touches the server.
+function nextDbuiAppFile() {
+  return [
+    "import { ApplyGlobalStyles, Button, DesignSystemProvider, Typography, useDesignSystemTheme } from '@databricks/design-system';",
+    '',
+    'function Sample() {',
+    '  const { theme } = useDesignSystemTheme();',
+    '  return (',
+    sampleBody(),
+    '  );',
+    '}',
+    '',
+    'export default function DbuiApp() {',
+    '  return (',
+    '    <DesignSystemProvider>',
+    '      <ApplyGlobalStyles />',
+    '      <Sample />',
+    '    </DesignSystemProvider>',
+    '  );',
+    '}',
+    '',
+  ].join('\n');
+}
+
+function printDone(name, pm, type) {
+  const runDev = pm === 'npm' ? 'npm run dev' : `${pm} dev`;
+  console.log(
+    [
+      '',
+      `✓ ${name} is ready with @databricks/design-system.`,
+      '',
+      'Next steps:',
+      `  cd ${name}`,
+      `  ${runDev}`,
+      ...(type === 'next' ? ['', 'To host it: see DEPLOY.md (Vercel).'] : []),
+      '',
+    ].join('\n'),
+  );
+}
+
+async function promptMode(rl) {
+  console.log('What would you like to do?\n');
+  console.log('  1) Scaffold a new Vite project (no hosting)');
+  console.log('  2) Scaffold a new Next.js project (Vercel hosting)');
+  console.log('  3) Add @databricks/design-system to an existing project\n');
+  const answer = await ask(rl, 'Enter 1, 2, or 3: ');
+  return { 1: 'vite', 2: 'next', 3: 'existing' }[answer];
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const mode = args.mode ?? (await promptMode(rl));
+    if (!mode || !['vite', 'next', 'existing'].includes(mode)) fail('Please choose 1, 2, or 3.');
+
+    if (mode === 'existing') {
+      addToExisting(process.cwd());
+      return;
+    }
+
+    const name = args.name || (await ask(rl, `\nProject name (new directory): `));
+    if (!name) fail('A project name is required.');
+    if (fs.existsSync(path.resolve(process.cwd(), name))) {
+      fail(`\`${name}\` already exists here. Choose a name that isn't taken.`);
+    }
+
+    if (mode === 'vite') scaffoldVite(name);
+    else scaffoldNext(name);
+  } finally {
+    rl.close();
+  }
+}
+
+// A bin is symlinked into node_modules/.bin, so compare realpaths (not the raw argv path) to tell
+// direct execution from being imported by a test.
+const invokedDirectly = Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  void main();
+}
+
+// Exported for unit testing the network-free logic (detection, wiring, arg parsing).
+export {
+  parseArgs,
+  detectPackageManager,
+  detectExistingProject,
+  existingEntryFile,
+  addImports,
+  designSystemSpec,
+  CSS_IMPORTS,
+};