toiljs 0.0.4 → 0.0.6

package/src/cli/create.ts

@@ -3,18 +3,63 @@
  * app to the enforced toiljs presets (tsconfig / eslint / prettier) and file-based routing.
  * Supports a non-interactive path via flags (`--yes`, `--template`, …) for scripting/CI.
  */
-import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-import { intro, outro, text, select, confirm, isCancel, cancel, spinner, note } from '@clack/prompts';
-import { TOIL_ENV_DTS } from 'toiljs/compiler';
+import {
+    intro,
+    outro,
+    text,
+    select,
+    multiselect,
+    confirm,
+    isCancel,
+    cancel,
+    spinner,
+    note,
+} from '@clack/prompts';
+import { AI_HELPERS, AI_HELPER_IDS, aiHelperFiles, TOIL_DOCS, TOIL_ENV_DTS } from 'toiljs/compiler';
 import pc from 'picocolors';
 
+import {
+    PKG_VERSION,
+    PREPROCESSORS,
+    requiredPackages,
+    setStyleImports,
+    styleEntry,
+    styleImportLines,
+    TAILWIND_CSS,
+    TAILWIND_ENTRY,
+    type Preprocessor,
+    type StyleFeatures,
+} from './features.js';
+import { run } from './proc.js';
 import { accent, dim, version } from './ui.js';
+import { isPackageManager, isValidName, resolveProjectDir } from './validate.js';
 
 export type Template = 'app' | 'minimal';
 
+/** Human label for each preprocessor in the styling picker. */
+const PREPROCESSOR_LABEL: Record<Preprocessor, string> = {
+    css: 'Plain CSS',
+    sass: 'Sass (SCSS)',
+    less: 'Less',
+    stylus: 'Stylus',
+};
+
+/** Default global stylesheet contents (palette base styles), shared by every preprocessor. */
+const DEFAULT_STYLE_CONTENT =
+    ':root {\n    color-scheme: dark;\n}\n\n' +
+    'body {\n    margin: 0;\n    background: #080d11;\n    color: #f5f6fa;\n' +
+    '    font-family: system-ui, -apple-system, sans-serif;\n    line-height: 1.6;\n}\n\n' +
+    'a {\n    color: #2563ff;\n    text-decoration: none;\n}\n\n' +
+    'a:hover {\n    color: #22e3ab;\n}\n\n' +
+    'code {\n    background: #11161f;\n    color: #22e3ab;\n    padding: 0.1rem 0.4rem;\n' +
+    '    border-radius: 4px;\n    font-size: 0.9em;\n}\n\n' +
+    'h1 {\n    background: linear-gradient(90deg, #2563ff, #7c3aed, #22e3ab);\n' +
+    '    -webkit-background-clip: text;\n    background-clip: text;\n    color: transparent;\n}\n';
+
 /** A selectable template in the `create` wizard. */
 interface TemplateOption {
     readonly value: Template;
@@ -25,6 +70,10 @@ interface TemplateOption {
 export interface CreateOptions {
     readonly name?: string;
     readonly template?: Template;
+    readonly preprocessor?: Preprocessor;
+    readonly tailwind?: boolean;
+    /** AI assistant files to scaffold: `true` = all, `false` = none, omitted = ask. */
+    readonly ai?: boolean;
     readonly install?: boolean;
     readonly git?: boolean;
     readonly pm?: string;
@@ -40,79 +89,184 @@ function bail<T>(value: T | symbol): asserts value is T {
     }
 }
 
-function isValidName(name: string): true | string {
-    if (!name.trim()) return 'Please enter a project name.';
-    if (!/^[a-z0-9._@/-]+$/i.test(name)) return 'Use letters, numbers, dashes, dots or slashes.';
-    return true;
-}
-
 async function isEmptyDir(dir: string): Promise<boolean> {
     try {
         const entries = await fs.readdir(dir);
         return entries.length === 0;
     } catch {
-        return true; // doesn't exist yet
+        return true;
     }
 }
 
 /** Builds the full file map (relative path → contents) for a scaffolded project. */
-function scaffold(name: string, template: Template): Record<string, string> {
+function scaffold(
+    name: string,
+    template: Template,
+    features: StyleFeatures,
+    aiTools: readonly string[],
+): Record<string, string> {
     const toilVersion = version();
+    const devDependencies: Record<string, string> = {
+        '@types/react': '^19.2.15',
+        '@types/react-dom': '^19.2.3',
+        eslint: '^10.2.0',
+        prettier: '^3.8.1',
+        toilscript: '^0.1.2',
+        typescript: '^6.0.3',
+    };
+    for (const dep of requiredPackages(features).sort()) {
+        devDependencies[dep] = PKG_VERSION[dep] ?? 'latest';
+    }
     const pkg = {
         name: path.basename(name),
         private: true,
         type: 'module',
         scripts: {
             dev: 'toiljs dev',
-            build: 'toiljs build',
+            build: 'toiljs build && toilscript --target release',
+            'build:client': 'toiljs build',
+            'build:server': 'toilscript --target release',
             lint: 'eslint client',
             typecheck: 'tsc --noEmit',
-            format: 'prettier --write "client/**/*.{ts,tsx}"',
+            format: 'prettier --write "client/**/*.{ts,tsx,css,scss,less}" "client/public/**/*.html"',
         },
         dependencies: {
             toiljs: `^${toilVersion}`,
             react: '^19.2.6',
             'react-dom': '^19.2.6',
         },
-        devDependencies: {
-            '@types/react': '^19.2.15',
-            '@types/react-dom': '^19.2.3',
-            eslint: '^10.2.0',
-            prettier: '^3.8.1',
-            typescript: '^6.0.3',
-        },
+        devDependencies,
     };
 
     const files: Record<string, string> = {
         'package.json': JSON.stringify(pkg, null, 4) + '\n',
         'toil.config.ts':
             "import { defineConfig } from 'toiljs/compiler';\n\n" +
-            'export default defineConfig({\n    client: {\n        outDir: \'dist\',\n    },\n});\n',
+            'export default defineConfig({});\n',
         'tsconfig.json':
             '{\n    "extends": "toiljs/tsconfig",\n    "include": ["client", "toil-env.d.ts"]\n}\n',
         'eslint.config.js': "import toiljs from 'toiljs/eslint';\n\nexport default toiljs;\n",
         '.prettierrc': '"toiljs/prettier"\n',
-        '.gitignore': 'node_modules\ndist\n.toil\ntoil-env.d.ts\n',
-        // Written upfront so the project type-checks before its first build; regenerated by build/dev.
+        '.gitignore': 'node_modules\nbuild\n.toil\ntoil-env.d.ts\n',
         'toil-env.d.ts': TOIL_ENV_DTS,
+        'toilconfig.json':
+            JSON.stringify(
+                {
+                    entries: ['server/main.ts'],
+                    targets: {
+                        release: {
+                            outFile: 'build/server/release.wasm',
+                            textFile: 'build/server/release.wat',
+                        },
+                    },
+                    options: {
+                        sourceMap: false,
+                        optimizeLevel: 3,
+                        shrinkLevel: 1,
+                        converge: true,
+                        noAssert: false,
+                        enable: [
+                            'sign-extension',
+                            'mutable-globals',
+                            'nontrapping-f2i',
+                            'bulk-memory',
+                            'simd',
+                            'reference-types',
+                            'multi-value',
+                        ],
+                        runtime: 'stub',
+                        memoryBase: 0,
+                        initialMemory: 1,
+                        debug: false,
+                        trapMode: 'allow',
+                    },
+                },
+                null,
+                4,
+            ) + '\n',
+        'server/tsconfig.json':
+            JSON.stringify(
+                {
+                    extends: 'toilscript/std/assembly.json',
+                    include: ['./**/*.ts'],
+                },
+                null,
+                4,
+            ) + '\n',
+        'server/index.ts': 'export function add(a: i32, b: i32): i32 {\n    return a + b;\n}\n',
+        'server/main.ts':
+            "import { add } from './index';\n\n" +
+            '@main\nfunction run(): i32 {\n    return add(40, 2);\n}\n',
         'README.md': ['# ' + path.basename(name), '', 'A [toiljs](https://toil.org) app.', '', '## Develop', '', '    npm install', '    npm run dev', '', '## Build', '', '    npm run build', ''].join('\n'),
-        'client/layout.tsx': `import { type ReactNode } from 'react';
+    };
+
+    // The `app` template's client UI is copied from templates/app at runtime; `minimal` ships an
+    // inline client here.
+    if (template === 'minimal') Object.assign(files, minimalClient(name, features));
 
-import { Link } from 'toiljs/client';
+    // Selected AI-assistant pointer files at the root (committed). The real docs are always seeded
+    // under .toil/docs (gitignored; regenerated by dev/build) since the framework manages them.
+    Object.assign(files, aiHelperFiles(aiTools));
+    for (const [docName, content] of Object.entries(TOIL_DOCS)) {
+        files[`.toil/docs/${docName}`] = content;
+    }
+
+    return files;
+}
 
-const styles = \`
-  :root { color-scheme: dark; }
-  body { margin: 0; background: #080D11; color: #F5F6FA; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; }
-  a { color: #2563FF; text-decoration: none; }
-  a:hover { color: #22E3AB; }
-  code { background: #11161f; color: #22E3AB; padding: 0.1rem 0.4rem; border-radius: 4px; font-size: 0.9em; }
-  h1 { background: linear-gradient(90deg, #2563FF, #7C3AED, #22E3AB); -webkit-background-clip: text; background-clip: text; color: transparent; }
-\`;
+/** The inline client UI for the `minimal` template (the `app` template copies templates/app). */
+function minimalClient(name: string, features: StyleFeatures): Record<string, string> {
+    const files: Record<string, string> = {
+        'client/public/index.html':
+            '<!doctype html>\n<html lang="en">\n  <head>\n' +
+            '    <meta charset="utf-8" />\n' +
+            '    <meta name="viewport" content="width=device-width, initial-scale=1" />\n' +
+            '    <meta name="theme-color" content="#080D11" />\n' +
+            '    <meta name="description" content="" />\n' +
+            '    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />\n' +
+            '    <link rel="manifest" href="/manifest.webmanifest" />\n' +
+            `    <title>${path.basename(name)}</title>\n` +
+            '  </head>\n  <body>\n    <div id="root"></div>\n  </body>\n</html>\n',
+        'client/public/favicon.svg':
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">\n' +
+            '  <defs>\n' +
+            '    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">\n' +
+            '      <stop offset="0" stop-color="#2563FF" />\n' +
+            '      <stop offset="0.5" stop-color="#7C3AED" />\n' +
+            '      <stop offset="1" stop-color="#22E3AB" />\n' +
+            '    </linearGradient>\n' +
+            '  </defs>\n' +
+            '  <rect width="32" height="32" rx="7" fill="#080D11" />\n' +
+            '  <path d="M9 10h14v3.2h-5.4V24h-3.2V13.2H9z" fill="url(#g)" />\n' +
+            '</svg>\n',
+        'client/public/robots.txt': 'User-agent: *\nAllow: /\n',
+        'client/public/manifest.webmanifest':
+            JSON.stringify(
+                {
+                    name: path.basename(name),
+                    short_name: path.basename(name),
+                    start_url: '/',
+                    display: 'standalone',
+                    background_color: '#080D11',
+                    theme_color: '#080D11',
+                    icons: [{ src: '/favicon.svg', type: 'image/svg+xml', sizes: 'any' }],
+                },
+                null,
+                4,
+            ) + '\n',
+        'client/public/images/.gitkeep': '# Place images and other static assets here; served at /images/*.\n',
+        'client/toil.tsx':
+            "import { routes, layout, notFound } from 'toiljs/routes';\n\n" +
+            styleImportLines(features).join('\n') +
+            '\n\n' +
+            'Toil.mount(routes, layout, notFound);\n',
+        [`client/${styleEntry(features.preprocessor)}`]: DEFAULT_STYLE_CONTENT,
+        'client/components/.gitkeep': '# Place shared React components here.\n',
+        'client/layout.tsx': `import { type ReactNode } from 'react';
 
 export default function Layout({ children }: { children?: ReactNode }) {
     return (
         <div style={{ maxWidth: 680, margin: '0 auto', padding: '3rem 1.5rem' }}>
-            <style>{styles}</style>
             <header
                 style={{
                     display: 'flex',
@@ -124,7 +278,7 @@ export default function Layout({ children }: { children?: ReactNode }) {
                 }}>
                 <strong style={{ color: '#2563FF', fontSize: '1.1rem' }}>${path.basename(name)}</strong>
                 <nav style={{ display: 'flex', gap: '1rem' }}>
-                    <Link href="/">home</Link>${template === 'app' ? '\n                    <Link href="/about">about</Link>' : ''}
+                    <Toil.Link href="/">home</Toil.Link>
                 </nav>
             </header>
             {children}
@@ -133,34 +287,37 @@ export default function Layout({ children }: { children?: ReactNode }) {
 }
 `,
         'client/routes/index.tsx':
-            "import { Link } from 'toiljs/client';\n\n" +
             'export default function Home() {\n' +
             '    return (\n        <main>\n' +
             '            <h1>Welcome to toiljs</h1>\n' +
             '            <p>File-based routing, bundled by Vite, zero config.</p>\n' +
-            (template === 'app'
-                ? '            <p>\n                <Link href="/about">About</Link> · <Link href="/blog/42">Blog post 42</Link>\n            </p>\n'
-                : '') +
             '        </main>\n    );\n}\n',
     };
+    if (features.tailwind) files[`client/${TAILWIND_ENTRY}`] = TAILWIND_CSS;
+    return files;
+}
 
-    if (template === 'app') {
-        files['client/routes/about.tsx'] =
-            "import { Link } from 'toiljs/client';\n\n" +
-            'export default function About() {\n' +
-            '    return (\n        <main>\n            <h1>About</h1>\n' +
-            '            <p>\n                This page is served by <code>client/routes/about.tsx</code>.\n            </p>\n' +
-            '            <Link href="/">Back home</Link>\n        </main>\n    );\n}\n';
-        files['client/routes/blog/[id].tsx'] =
-            "import { Link, useParams } from 'toiljs/client';\n\n" +
-            'export default function BlogPost() {\n' +
-            '    const { id } = useParams();\n' +
-            '    return (\n        <main>\n            <h1>Blog post {id}</h1>\n' +
-            '            <p>\n                Dynamic route from <code>client/routes/blog/[id].tsx</code>.\n            </p>\n' +
-            '            <Link href="/">Back home</Link>\n        </main>\n    );\n}\n';
-    }
+/** Absolute path to a shipped template directory (e.g. `templates/app`). */
+function templateDir(template: Template): string {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates', template);
+}
 
-    return files;
+/**
+ * Applies the chosen styling to a copied template's client dir: renames the stylesheet to the
+ * preprocessor's extension, adds the Tailwind entry, and rewrites `toil.tsx`'s style imports.
+ */
+async function applyStyling(clientDir: string, features: StyleFeatures): Promise<void> {
+    // Plain CSS without Tailwind is exactly what the template ships — leave it byte-for-byte.
+    if (features.preprocessor === 'css' && !features.tailwind) return;
+    const entry = styleEntry(features.preprocessor);
+    if (entry !== 'styles/main.css') {
+        await fs.rename(path.join(clientDir, 'styles', 'main.css'), path.join(clientDir, entry));
+    }
+    if (features.tailwind) {
+        await fs.writeFile(path.join(clientDir, TAILWIND_ENTRY), TAILWIND_CSS, 'utf8');
+    }
+    const toilPath = path.join(clientDir, 'toil.tsx');
+    await fs.writeFile(toilPath, setStyleImports(await fs.readFile(toilPath, 'utf8'), features), 'utf8');
 }
 
 async function writeFiles(dir: string, files: Record<string, string>): Promise<void> {
@@ -171,27 +328,10 @@ async function writeFiles(dir: string, files: Record<string, string>): Promise<v
     }
 }
 
-function run(cmd: string, args: string[], cwd: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-        // On Windows `npm`/`pnpm`/`yarn` are `.cmd` shims that need a shell to launch. Passing an
-        // args array together with `shell: true` is deprecated (DEP0190), so pass the whole command
-        // as one string there (the args are fixed, not user input). POSIX runs it directly.
-        const onWindows = process.platform === 'win32';
-        const child = onWindows
-            ? spawn([cmd, ...args].join(' '), { cwd, stdio: 'ignore', shell: true })
-            : spawn(cmd, args, { cwd, stdio: 'ignore' });
-        child.on('error', reject);
-        child.on('close', (code) =>
-            code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${String(code)}`)),
-        );
-    });
-}
-
 /** Runs the create flow (interactive unless `--yes`). */
 export async function runCreate(opts: CreateOptions): Promise<void> {
     intro(accent(' toiljs create '));
 
-    // 1. Project name
     let name = opts.name;
     if (!name) {
         if (opts.yes) {
@@ -216,10 +356,13 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
         process.exit(1);
     }
 
-    const targetDir = path.resolve(opts.cwd, name);
+    const targetDir = resolveProjectDir(opts.cwd, name);
+    if (targetDir === null) {
+        cancel('Project name must stay inside the current directory (no "..", no absolute paths).');
+        process.exit(1);
+    }
     const rel = path.relative(opts.cwd, targetDir) || '.';
 
-    // 2. Guard against clobbering a non-empty dir
     if (!(await isEmptyDir(targetDir))) {
         if (opts.yes) {
             cancel(`Directory ${pc.cyan(rel)} is not empty.`);
@@ -236,11 +379,10 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
         }
     }
 
-    // 3. Template
     let template: Template = opts.template ?? 'app';
     if (!opts.template && !opts.yes) {
         const templateOptions: TemplateOption[] = [
-            { value: 'app', label: 'App', hint: 'layout + home/about + a dynamic /blog/[id] route' },
+            { value: 'app', label: 'App', hint: 'the full ToilJS starter — landing page, layout, styles, demo routes' },
             { value: 'minimal', label: 'Minimal', hint: 'just a layout and a home route' },
         ];
         const choice = await select({ message: 'Which template?', options: templateOptions, initialValue: 'app' });
@@ -248,10 +390,46 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
         template = choice === 'minimal' ? 'minimal' : 'app';
     }
 
-    // 4. Options: git + install
+    let preprocessor: Preprocessor = opts.preprocessor ?? 'css';
+    let tailwind = opts.tailwind ?? false;
+    if (!opts.yes) {
+        if (opts.preprocessor === undefined) {
+            const choice = await select<Preprocessor>({
+                message: 'Styling',
+                options: PREPROCESSORS.map((value) => ({ value, label: PREPROCESSOR_LABEL[value] })),
+                initialValue: 'css',
+            });
+            bail(choice);
+            preprocessor = choice;
+        }
+        if (opts.tailwind === undefined) {
+            const tw = await confirm({ message: 'Add Tailwind CSS?', initialValue: false });
+            bail(tw);
+            tailwind = tw;
+        }
+    }
+    const features: StyleFeatures = { preprocessor, tailwind };
+
+    // AI assistant files: --ai = all, --no-ai = none, otherwise ask (default: all selected).
+    let aiTools: string[] = opts.ai === false ? [] : [...AI_HELPER_IDS];
+    if (opts.ai === undefined && !opts.yes) {
+        const picked = await multiselect<string>({
+            message: 'AI assistant files (read by Claude, Cursor, Codex, Copilot)',
+            options: AI_HELPERS.map((h) => ({ value: h.id, label: h.label })),
+            initialValues: [...AI_HELPER_IDS],
+            required: false,
+        });
+        bail(picked);
+        aiTools = picked;
+    }
+
     let initGit = opts.git ?? false;
     let install = opts.install ?? false;
     const pm = opts.pm ?? 'npm';
+    if (!isPackageManager(pm)) {
+        cancel(`Unsupported package manager: ${pm} (use npm, pnpm, yarn, or bun).`);
+        process.exit(1);
+    }
     if (!opts.yes) {
         if (opts.git === undefined) {
             const g = await confirm({ message: 'Initialize a git repository?', initialValue: true });
@@ -265,13 +443,22 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
         }
     }
 
-    // 5. Scaffold
     const s = spinner();
     s.start('Scaffolding project');
-    await writeFiles(targetDir, scaffold(name, template));
+    await writeFiles(targetDir, scaffold(name, template, features, aiTools));
+    if (template === 'app') {
+        // Copy the full ToilJS starter UI, set its <title> to the project name, then apply styling.
+        await fs.cp(templateDir('app'), targetDir, { recursive: true });
+        const indexHtml = path.join(targetDir, 'client', 'public', 'index.html');
+        const html = await fs.readFile(indexHtml, 'utf8');
+        await fs.writeFile(
+            indexHtml,
+            html.replace(/<title>[^<]*<\/title>/, `<title>${path.basename(name)}</title>`),
+        );
+        await applyStyling(path.join(targetDir, 'client'), features);
+    }
     s.stop(`Scaffolded ${pc.cyan(rel)}`);
 
-    // 6. git init (best-effort)
     if (initGit) {
         const g = spinner();
         g.start('Initializing git repository');
@@ -284,7 +471,6 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
         }
     }
 
-    // 7. Install (best-effort)
     if (install) {
         const i = spinner();
         i.start(`Installing dependencies with ${pm}`);
@@ -297,7 +483,6 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
         }
     }
 
-    // 8. Next steps
     const steps: string[] = [];
     if (rel !== '.') steps.push(`cd ${rel}`);
     if (!install) steps.push('npm install');

package/src/cli/features.ts

@@ -0,0 +1,128 @@
+/**
+ * Pure description of toiljs's optional client styling features — a CSS preprocessor and Tailwind —
+ * shared by `create` (scaffold) and `configure` (toggle on existing projects). Dependency-light
+ * (no node IO) so it can be unit-tested; the file writes and package-manager calls live in the
+ * commands. Preprocessor and Tailwind are independent: Tailwind lives in its own `.css` entry so
+ * it never passes through (and breaks on) a preprocessor's `@import` resolution.
+ */
+
+/** Supported CSS preprocessor (`css` = none). */
+export type Preprocessor = 'css' | 'sass' | 'less' | 'stylus';
+
+/** The two independently-toggleable styling features of a project. */
+export interface StyleFeatures {
+    readonly preprocessor: Preprocessor;
+    readonly tailwind: boolean;
+}
+
+export const PREPROCESSORS: readonly Preprocessor[] = ['css', 'sass', 'less', 'stylus'];
+
+/** Main stylesheet extension for each preprocessor. */
+export const STYLE_EXT: Record<Preprocessor, string> = {
+    css: 'css',
+    sass: 'scss',
+    less: 'less',
+    stylus: 'styl',
+};
+
+/** npm package that enables each preprocessor in Vite (plain CSS needs none). */
+export const PREPROCESSOR_PKG: Record<Preprocessor, string | null> = {
+    css: null,
+    sass: 'sass',
+    less: 'less',
+    stylus: 'stylus',
+};
+
+/** Tailwind v4 packages. The framework auto-wires the Vite plugin when `@tailwindcss/vite` resolves. */
+export const TAILWIND_PKGS: readonly string[] = ['tailwindcss', '@tailwindcss/vite'];
+
+/** Pinned versions for every package these features may install. */
+export const PKG_VERSION: Record<string, string> = {
+    sass: '^1.83.0',
+    less: '^4.2.1',
+    stylus: '^0.64.0',
+    tailwindcss: '^4.0.0',
+    '@tailwindcss/vite': '^4.0.0',
+};
+
+/** Dedicated Tailwind entry (kept `.css` so no preprocessor touches its `@import`). */
+export const TAILWIND_ENTRY = 'styles/tailwind.css';
+export const TAILWIND_CSS = `@import 'tailwindcss';\n`;
+
+/** Path (relative to `client/`) of the main stylesheet for a preprocessor. */
+export function styleEntry(p: Preprocessor): string {
+    return `styles/main.${STYLE_EXT[p]}`;
+}
+
+/** The preprocessor whose main stylesheet uses `ext` (with or without a leading dot), or null. */
+export function preprocessorForExt(ext: string): Preprocessor | null {
+    const e = ext.replace(/^\./, '');
+    if (e === 'sass') return 'sass';
+    return PREPROCESSORS.find((p) => STYLE_EXT[p] === e) ?? null;
+}
+
+/** Packages required by a feature set (preprocessor package + Tailwind packages). */
+export function requiredPackages(f: StyleFeatures): string[] {
+    const pkgs: string[] = [];
+    const pp = PREPROCESSOR_PKG[f.preprocessor];
+    if (pp) pkgs.push(pp);
+    if (f.tailwind) pkgs.push(...TAILWIND_PKGS);
+    return pkgs;
+}
+
+/** Managed packages to add and remove when moving from `from` to `to`. */
+export function packageDiff(
+    from: StyleFeatures,
+    to: StyleFeatures,
+): { add: string[]; remove: string[] } {
+    const want = new Set(requiredPackages(to));
+    const had = new Set(requiredPackages(from));
+    return {
+        add: [...want].filter((p) => !had.has(p)),
+        remove: [...had].filter((p) => !want.has(p)),
+    };
+}
+
+/** The side-effect style imports for the app entry, Tailwind first so app CSS can override it. */
+export function styleImportLines(f: StyleFeatures): string[] {
+    const lines: string[] = [];
+    if (f.tailwind) lines.push(`import './${TAILWIND_ENTRY}';`);
+    lines.push(`import './${styleEntry(f.preprocessor)}';`);
+    return lines;
+}
+
+/**
+ * Rewrites the `./styles/*` side-effect imports in an app entry (`client/toil.tsx`) to match
+ * `features`, preserving the rest of the file. Existing style imports are removed and the new
+ * block is placed after the `toiljs/routes` import (or the last import, or the top).
+ */
+export function setStyleImports(source: string, f: StyleFeatures): string {
+    const stripped = source.replace(/^[ \t]*import\s+['"]\.\/styles\/[^'"]+['"];?[ \t]*\r?\n/gm, '');
+    const block = styleImportLines(f).join('\n') + '\n';
+
+    const lines = stripped.split('\n');
+    const routesIdx = lines.findIndex((l) => /from\s+['"]toiljs\/routes['"]/.test(l));
+    let insertAt: number;
+    if (routesIdx !== -1) {
+        insertAt = routesIdx + 1;
+    } else {
+        const lastImport = lines.reduce((acc, l, i) => (/^\s*import\s/.test(l) ? i : acc), -1);
+        insertAt = lastImport + 1;
+    }
+    const head = lines.slice(0, insertAt).join('\n');
+    const tail = lines.slice(insertAt).join('\n');
+    return `${head}\n\n${block}\n${tail}`.replace(/\n{3,}/g, '\n\n');
+}
+
+/** Detects the active preprocessor from a project's combined dependency map. */
+export function detectPreprocessor(deps: Record<string, string>): Preprocessor {
+    if ('sass' in deps) return 'sass';
+    if ('less' in deps) return 'less';
+    if ('stylus' in deps) return 'stylus';
+    return 'css';
+}
+
+/** Whether Tailwind is installed in a project's combined dependency map. */
+export function detectTailwind(deps: Record<string, string>): boolean {
+    return '@tailwindcss/vite' in deps || 'tailwindcss' in deps;
+}