create-rsc-kit 0.1.0

package/dist/options.js

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const HOSTS = [
+    { value: 'bun', label: 'Bun.serve', hint: 'no framework, fastest to start' },
+    { value: 'hono', label: 'Hono', hint: 'also what a Worker or Deno would use' },
+    { value: 'elysia', label: 'Elysia', hint: 'Bun-first, typed routes of its own' },
+    { value: 'node', label: 'node:http', hint: 'no Bun, no framework' },
+];
+/**
+ * Not asked as a three-way.
+ *
+ * The compiler has a native implementation and a Babel one, and they produce
+ * the same transform — one is just faster to run. Asking which is asking the
+ * user to make a build-performance decision on our behalf, in a project whose
+ * whole argument is performance. So the prompt is yes/no and the answer is
+ * oxc; `--compiler=babel` is there for when the experimental one misbehaves.
+ */
+export const DEFAULT_COMPILER = 'oxc';
+/** The published version range, when there is no checkout to prefer. */
+export const PUBLISHED_CORE = '^0.1.0';
+/**
+ * What to depend on for the engine.
+ *
+ * Run from a checkout — linked, or straight out of the repo — the sibling
+ * package is what the author means, and pointing at npm instead fails the
+ * install on a version that may not exist yet. Installed from npm there is no
+ * sibling and the range is right.
+ */
+export function defaultCore(fromDir) {
+    let dir = fromDir;
+    for (let up = 0; up < 6; up++) {
+        const core = join(dir, 'packages/core/package.json');
+        if (existsSync(core)) {
+            try {
+                const name = JSON.parse(readFileSync(core, 'utf-8')).name;
+                if (name === '@rsc-kit/core')
+                    return 'file:' + join(dir, 'packages/core');
+            }
+            catch {
+                // Unreadable is the same as absent.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return PUBLISHED_CORE;
+}
+export function parseArgs(argv) {
+    const out = {};
+    for (const arg of argv) {
+        if (arg === '--help' || arg === '-h')
+            out.help = true;
+        else if (arg === '--yes' || arg === '-y')
+            out.host ??= 'bun';
+        else if (arg === '--no-install')
+            out.install = false;
+        else if (arg === '--no-git')
+            out.git = false;
+        else if (arg.startsWith('--source-dir='))
+            out.sourceDir = arg.slice(13);
+        else if (arg === '--init')
+            out.init = true;
+        else if (arg === '--lint')
+            out.lint = true;
+        else if (arg === '--no-lint')
+            out.lint = false;
+        else if (arg === '--tailwind')
+            out.tailwind = true;
+        else if (arg === '--no-tailwind')
+            out.tailwind = false;
+        else if (arg.startsWith('--host='))
+            out.host = arg.slice(7);
+        else if (arg.startsWith('--compiler='))
+            out.compiler = arg.slice(11);
+        else if (arg.startsWith('--core='))
+            out.core = arg.slice(7);
+        else if (!arg.startsWith('-'))
+            out.dir ??= arg;
+    }
+    return out;
+}
+/**
+ * A directory name that is safe to be a package name and to interpolate.
+ *
+ * The name reaches a TypeScript string literal, JSX text and a package.json
+ * field. Escaping it differently at each of those is three chances to get one
+ * wrong — an apostrophe alone produced a generated file that would not parse,
+ * and a name containing a template expression produced one that executed. So
+ * it is checked once, against what npm already allows a package to be called.
+ */
+const SAFE_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+export function assertUsableName(name) {
+    if (SAFE_NAME.test(name) && name.length <= 214)
+        return;
+    throw new Error(`Not a usable project name: ${JSON.stringify(name)}. ` +
+        'Use letters, digits, dots, dashes and underscores — it becomes the package name ' +
+        'and is written into generated source.');
+}
+/**
+ * Where the app is written, refusing anywhere that is not below here.
+ *
+ * A generator that writes outside the directory it was pointed at is a
+ * generator nobody can run without reading it first.
+ */
+export function assertInsideCwd(dir, cwd) {
+    const inside = dir === cwd || dir.startsWith(cwd.endsWith('/') ? cwd : cwd + '/');
+    if (inside)
+        return;
+    throw new Error(`Refusing to write outside the current directory: ${dir}. ` +
+        'Change into the directory you want the app in and run it there.');
+}
+export const HELP = `
+  create-rsc-kit — scaffold an RSC app
+
+  Usage
+    create-rsc-kit <dir> [options]
+    bun create rsc-kit <dir> [options]   (once published)
+
+  Options
+    --host=bun|hono|elysia|node   which server to generate
+    --compiler=none|oxc|babel     React Compiler (prompt offers oxc; babel by flag)
+    --tailwind / --no-tailwind    include Tailwind
+    --lint / --no-lint            include oxlint
+    --source-dir <dir>            where app/ lives (default: src)
+    --init                        add to the project here, rather than scaffold
+    --core=<spec>                 engine dependency, e.g. file:../rsc-kit/packages/core
+    --no-install                  skip installing dependencies
+    --no-git                      skip git init
+    -y, --yes                     accept every default, ask nothing
+    -h, --help                    this
+`;

package/dist/prompt.d.ts

@@ -0,0 +1,24 @@
+export declare const dim: (t: string) => string;
+export declare const bold: (t: string) => string;
+export declare const cyan: (t: string) => string;
+export interface Choice<T> {
+    value: T;
+    label: string;
+    hint: string;
+}
+export declare class Prompter {
+    /**
+     * Asked one at a time rather than over one long-lived interface.
+     *
+     * `select` takes stdin into raw mode to read arrow keys, and a readline
+     * interface left open would be consuming the same stream — the two fight
+     * over every keypress. Opening and closing per question keeps exactly one
+     * reader attached at a time.
+     */
+    private ask;
+    text(question: string, fallback: string): Promise<string>;
+    confirm(question: string, fallback: boolean): Promise<boolean>;
+    /** Arrow keys, j/k, or the number — whichever the hands reach for first. */
+    select<T>(question: string, choices: Choice<T>[]): Promise<T>;
+    close(): void;
+}

package/dist/prompt.js

@@ -0,0 +1,129 @@
+// Prompts, with no dependency.
+//
+// A create- package is run through `bunx`/`npm create`, which installs it
+// first — so every dependency is latency the user waits through before being
+// asked anything. readline is in both runtimes and costs nothing.
+import { createInterface, emitKeypressEvents } from 'node:readline';
+import { createInterface as createPromised } from 'node:readline/promises';
+import { exit, stdin, stdout } from 'node:process';
+const tty = stdout.isTTY === true;
+const c = (code, text) => (tty ? code + text + '\x1b[0m' : text);
+export const dim = (t) => c('\x1b[2m', t);
+export const bold = (t) => c('\x1b[1m', t);
+export const cyan = (t) => c('\x1b[36m', t);
+const green = (t) => c('\x1b[32m', t);
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+/** Up n lines, then clear everything below. */
+const rewind = (n) => `\x1b[${n}A\x1b[0J`;
+export class Prompter {
+    /**
+     * Asked one at a time rather than over one long-lived interface.
+     *
+     * `select` takes stdin into raw mode to read arrow keys, and a readline
+     * interface left open would be consuming the same stream — the two fight
+     * over every keypress. Opening and closing per question keeps exactly one
+     * reader attached at a time.
+     */
+    async ask(question) {
+        const rl = createPromised({ input: stdin, output: stdout });
+        try {
+            return (await rl.question(question)).trim();
+        }
+        finally {
+            rl.close();
+        }
+    }
+    async text(question, fallback) {
+        const answer = await this.ask(`${bold(question)} ${dim(`(${fallback})`)} `);
+        return answer === '' ? fallback : answer;
+    }
+    async confirm(question, fallback) {
+        const answer = (await this.ask(`${bold(question)} ${dim(fallback ? '(Y/n)' : '(y/N)')} `)).toLowerCase();
+        if (answer === '')
+            return fallback;
+        return answer.startsWith('y');
+    }
+    /** Arrow keys, j/k, or the number — whichever the hands reach for first. */
+    select(question, choices) {
+        let index = 0;
+        const draw = (first) => {
+            const lines = choices.map((choice, i) => {
+                const on = i === index;
+                const marker = on ? green('●') : dim('○');
+                const label = on ? bold(choice.label) : choice.label;
+                return `  ${marker} ${label}  ${dim(choice.hint)}`;
+            });
+            stdout.write((first ? '' : rewind(choices.length)) + lines.join('\n') + '\n');
+        };
+        stdout.write(`${bold(question)} ${dim('↑↓ then enter')}\n`);
+        stdout.write(HIDE_CURSOR);
+        draw(true);
+        /**
+         * Replace the whole list with the answer.
+         *
+         * Left on screen, every question's options stay in the transcript and the
+         * next question is pushed off the top — by the last one you cannot see
+         * what you picked for the first.
+         */
+        const collapse = (choice) => {
+            stdout.write(rewind(choices.length + 1) + `${green('✓')} ${bold(question)} ${cyan(choice.label)}\n`);
+        };
+        // Its own interface so keypress events are emitted at all; the promised
+        // one above is closed by the time this runs.
+        const rl = createInterface({ input: stdin, escapeCodeTimeout: 50 });
+        emitKeypressEvents(stdin, rl);
+        const wasRaw = stdin.isRaw === true;
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        return new Promise((resolve) => {
+            const done = () => {
+                stdin.off('keypress', onKey);
+                if (stdin.isTTY)
+                    stdin.setRawMode(wasRaw);
+                rl.close();
+                stdout.write(SHOW_CURSOR);
+            };
+            const onKey = (str, key) => {
+                const last = choices.length - 1;
+                // Ctrl-C has to be handled here: raw mode means no SIGINT, so without
+                // this the only way out of the prompt is closing the terminal.
+                if (key?.ctrl && key.name === 'c') {
+                    done();
+                    stdout.write('\n');
+                    exit(130);
+                }
+                if (key?.name === 'up' || key?.name === 'k')
+                    index = index === 0 ? last : index - 1;
+                else if (key?.name === 'down' || key?.name === 'j')
+                    index = index === last ? 0 : index + 1;
+                else if (key?.name === 'home')
+                    index = 0;
+                else if (key?.name === 'end')
+                    index = last;
+                else if (key?.name === 'return' || key?.name === 'enter') {
+                    done();
+                    collapse(choices[index]);
+                    resolve(choices[index].value);
+                    return;
+                }
+                else if (/^[1-9]$/.test(str ?? '')) {
+                    const picked = Number(str) - 1;
+                    if (picked > last)
+                        return;
+                    done();
+                    collapse(choices[picked]);
+                    resolve(choices[picked].value);
+                    return;
+                }
+                else
+                    return;
+                draw(false);
+            };
+            stdin.on('keypress', onKey);
+        });
+    }
+    close() {
+        // Nothing is held open between questions.
+    }
+}

package/dist/templates.d.ts

@@ -0,0 +1,34 @@
+import type { Host, Options } from './options.js';
+export declare function packageJson(o: Options): string;
+/** One server per app, so it needs no qualifier. */
+export declare const serverFile: (_host: Host) => string;
+export declare function viteConfig(o: Options): string;
+export declare const tsconfig: (o: Options) => string;
+export declare function server(host: Host): string;
+export declare function layout(o: Options): string;
+export declare function page(o: Options): string;
+export declare function counter(o: Options): string;
+/**
+ * Tailwind needs @source pointing at the RSC tree.
+ *
+ * Server components never enter the client module graph and Tailwind's
+ * detection roots at the Vite root, so without this the utilities layer holds
+ * only classes scraped from the generated entries. The build still succeeds
+ * and nothing warns — the page just arrives unstyled.
+ */
+export declare const styles = "@import 'tailwindcss';\n\n/* The whole source tree, not just this directory. A client component is found\n   automatically because it enters the browser bundle; a server component never\n   does, so anything it uses has to be declared here or it is silently absent\n   from the stylesheet. */\n@source '../';\n";
+export declare const gitignore = "node_modules\nbuild\n.rsc\ndist\n*.log\n.DS_Store\n\n# Written by the build into the source dir, every run.\nsrc/rsc-env.d.ts\nsrc/rsc-types.d.ts\nsrc/rsc-routes.d.ts\nsrc/rsc-engine.d.ts\n";
+/**
+ * oxlint, with the React Compiler's own rules turned on.
+ *
+ * Those `react/*` rules are the interesting half here: purity, immutability,
+ * set-state-in-render. They describe what the compiler needs in order to
+ * memoise safely, and they are worth running whether or not the compiler is
+ * enabled — a component that breaks them is a component with a bug the
+ * compiler would have made louder.
+ *
+ * `correctness: error` rather than the enumerated list an eslint migration
+ * leaves behind: a new project has nothing to grandfather in.
+ */
+export declare function oxlintConfig(o: Options): string;
+export declare function readme(o: Options): string;