@rshono/create 1.0.0-rc.0

package/README.md

@@ -0,0 +1,105 @@
+# @rshono/create
+
+Scaffolds a new [rshono](https://github.com/rshono/rshono) app — Hono + Rspack + React Server Components.
+
+```bash
+npm  create @rshono@latest my-app
+pnpm create @rshono my-app
+yarn create @rshono my-app
+bun  create @rshono my-app
+```
+
+The package manager that ran it is the one the project gets: it is read from `npm_config_user_agent`, used
+for the install, written into `packageManager` for Corepack, and used in every command the closing summary
+prints. Nothing asks you which one you meant.
+
+## The questions
+
+Six, each with a default, and each answerable by a flag instead:
+
+| Question              | Default            | Flag                                                                |
+| --------------------- | ------------------ | ------------------------------------------------------------------- |
+| Where should it go?   | `my-rshono-app`    | first positional argument, or `.`                                   |
+| Where is it deployed? | `node`             | `--deploy node\|bun\|deno\|cloudflare\|vercel\|netlify\|aws-lambda` |
+| Styling               | plain CSS          | `--tailwind` / `--no-tailwind`                                      |
+| Formatting & linting  | Prettier + oxlint  | `--quality prettier-oxlint\|biome\|oxc\|none`                       |
+| Install dependencies? | yes                | `--no-install`                                                      |
+| Initialize git?       | yes, unless nested | `--no-git`                                                          |
+
+Plus `--formatter` and `--linter` to set either half of the quality preset on its own, `--force` to
+scaffold into a directory that is not empty, `--dry-run` to see the file list and write nothing, and `-y`
+to take the defaults for everything not given. **A non-interactive terminal implies `-y`**, so this is one
+command in CI or from an agent:
+
+```bash
+npm create @rshono@latest my-app -y --deploy cloudflare --tailwind --quality biome
+```
+
+The deploy targets, and the deploy command each one prints, are generated from the framework's own
+presets — a target added to rshono appears here with no edit.
+
+## What you get
+
+```
+rshono.config.ts        the chosen deploy target; everything else commented with its default
+tsconfig.json           strict, with @/* → ./src/*
+.env                    committed defaults; secrets go in .env.local
+public/                 favicon.svg, robots.txt
+src/routes.ts           one page, a 404 and a 500, with the other route kinds commented
+src/server.ts           AppEnv, request-id middleware, error reporting, /api/health, redirects, AppType
+src/actions.ts          a 'use server' action, called from a form that works without JavaScript
+src/components/         layout, home, greet-form ('use client'), 404, 500
+src/lib/env.ts          both sides of the PUBLIC_ boundary in one place
+src/styles.css          element-level CSS, or the Tailwind entry
+```
+
+Then, if the dependencies were installed, the scaffold is run through its own formatter — so a fresh
+project passes its own `format:check` rather than reporting a diff nobody made.
+
+`react` and `react-dom` are pinned **exactly**, at the versions the framework is tested against, and those
+pins are generated from rshono's own manifest. That is not tidiness: the RSC runtime reaches into React's
+internals, and an app installed with npm or bun has no workspace overrides to keep a single copy of it.
+
+## Adding an option
+
+Every difference between two scaffolds is a `Feature` — files to overlay, dependencies, scripts,
+`.gitignore` lines, a closing note. Nothing in the generator knows what Tailwind is. So an option is three
+edits and no new machinery:
+
+1. A `Feature` in `src/features/` — `templates/<id>` for the files it brings, plus whatever it adds to the
+   manifest.
+2. The template directory itself, as **real files**. They are copied over the base, so an overlay replaces
+   a file rather than patching it, and template files stay valid TypeScript that an editor can check.
+   `_name` becomes `.name` on write, because npm strips a literal `.gitignore` out of a published tarball.
+3. A prompt in `src/cli.ts`, if it deserves a question of its own — and a flag, which it always does.
+
+`plan(answers)` is pure: answers in, a `Map` of path → contents out, no directory touched. That is what
+makes the whole matrix of options testable in milliseconds (`test/plan.test.mjs`) and `--dry-run` free. It
+is also exported, for a tool that wants to scaffold without the prompts:
+
+```ts
+import { plan, writePlan } from '@rshono/create';
+```
+
+## Two things worth knowing
+
+**There is no ESLint option.** Linting TypeScript with ESLint means `typescript-eslint`, whose peer range is
+`typescript >=4.8.4 <6.1.0`; rshono is built and tested against TypeScript 7. `npm install` fails outright
+on the conflict, and forcing past it would hand you a linter running against a compiler API it was never
+built for. When upstream widens the range, ESLint becomes one more entry in `features/quality.ts`.
+
+**Tailwind is four packages, a `postcss.config.mjs` and one rule in `rshono.config.ts`.** rshono compiles
+CSS natively and has no PostCSS in it — that is deliberate, and it means an app that wants a plugin chain
+brings its own, through the `rspack` hook. The overlay writes all of it, with a comment saying what to
+delete to go back to plain CSS.
+
+## Development
+
+```bash
+pnpm --filter @rshono/create build       # codegen, then one bundled dist/cli.mjs with no runtime deps
+pnpm --filter @rshono/create test        # the plan matrix — fast, no I/O
+CREATE_RSHONO_E2E=1 pnpm --filter @rshono/create test   # also: pack, install and build real apps
+```
+
+`@clack/prompts` (MIT) is bundled rather than depended on, so `npm create` downloads one tarball before it
+can ask its first question.

package/bin/create-rshono.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Thin launcher, kept deliberately old-syntax and dependency-free: it is the one file that has to
+// parse and run on whatever Node the user happens to have. The CLI itself is a bundle — its imports
+// are evaluated before any statement in it, so a version check *inside* it would be too late to
+// produce anything friendlier than a stack trace.
+var MINIMUM = [22, 1, 0];
+
+var current = process.versions.node.split('.').map(Number);
+var older = false;
+for (var i = 0; i < MINIMUM.length; i++) {
+  if (current[i] === MINIMUM[i]) continue;
+  older = current[i] < MINIMUM[i];
+  break;
+}
+
+if (older) {
+  console.error(
+    '\ncreate-rshono needs Node ' +
+      MINIMUM.join('.') +
+      ' or newer — you are on ' +
+      process.versions.node +
+      '.\n' +
+      'rshono itself requires it too (worker threads, process.loadEnvFile, Promise.withResolvers),\n' +
+      'so scaffolding on this version would produce an app that cannot start.\n',
+  );
+  process.exit(1);
+}
+
+import('../dist/cli.mjs');