create-yerd 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 toyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# create-yerd
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffold a [yerd](https://toyz.github.io/yerd/) app.
+
+```sh
+npm create yerd@latest my-app
+pnpm create yerd my-app
+yarn create yerd my-app
+bun create yerd my-app
+```
+
+It asks for anything the flags leave out: the directory, a template,
+Tailwind, the package manager, git, and whether to install. Then it prints
+what to run next. Node 24 or newer; no dependencies.
+
+## Templates
+
+| Template | What you get |
+| --- | --- |
+| `full` | A small shop: a catalog with search, product pages with a 404, a session cart updated by actions that answer with `<Region>`s, sign-in with `createAuth`, a validated checkout form, a JSON API, a health check. Unit tests with `app.request()` / `app.client()` and one Playwright test. |
+| `minimal` | One page and a layout, a session counter updated by an action, a stylesheet, a test. |
+| `api` | JSON routes for notes: DTO-validated bodies, `NotFound` / `Conflict` errors, `@status(HttpStatus.Created)`, `HttpStatus.NoContent` for deletes. No pages, no client runtime. Tests. |
+
+Every template runs with Vite in dev (`vite`) and builds to a plain Node
+server (`vite build`, then `node dist/server/server.js`), with
+`tsconfig.json` set up for TC39 decorators and yerd's JSX, vitest, and a
+`.env.example` for `YERD_SECRET`.
+
+`--tailwind` adds Tailwind CSS v4 to `full` or `minimal`: `@tailwindcss/vite`
+in `vite.config.ts` and a stylesheet that starts with `@import "tailwindcss"`,
+linked with `<Stylesheet>` like any other.
+
+## Options
+
+| Flag | Meaning |
+| --- | --- |
+| `[directory]` | where to create the app; `.` for the current folder |
+| `-t, --template <name>` | `full`, `minimal` or `api` |
+| `--tailwind`, `--no-tailwind` | add Tailwind CSS (`full` and `minimal` only) |
+| `--pm <name>` | `npm`, `pnpm`, `yarn` or `bun`; default: the one running create-yerd |
+| `--git`, `--no-git` | `git init` and a first commit (default: yes; skipped inside a repository) |
+| `--install`, `--no-install` | install dependencies (default: yes) |
+| `-y, --yes` | take the defaults for everything not given: `yerd-app`, `minimal`, no Tailwind, git, install |
+| `-f, --force` | write into a directory that isn't empty, overwriting files with the same names |
+| `-h, --help` | show the options |
+| `-v, --version` | show the version |
+
+With npm, flags go after `--`:
+
+```sh
+npm create yerd@latest my-app -- --template full --tailwind
+pnpm create yerd my-api --template api --yes
+npm create yerd@latest . -- --yes --no-install
+```
+
+Without a terminal (a pipe, CI), each question is one line on stdin, and
+every question takes its default once input runs out. `NO_COLOR` turns off
+colors.
+
+## Versions
+
+create-yerd is released together with yerd, at the same version:
+`create-yerd@X.Y.Z` writes `"@toyz/yerd": "^X.Y.Z"`.
+
+## Working on it
+
+From the repository root:
+
+```sh
+npm ci && npm run build                                # the integration test installs this build
+npm test --prefix packages/create-yerd                  # unit tests
+npm run test:integration --prefix packages/create-yerd  # every template: install, tsc, test, build, serve
+npm run check --prefix packages/create-yerd             # type-check the JS
+```
+
+Templates live in `templates/`: `_shared` goes into every app, then the
+template's folder, then for Tailwind `tailwind/_shared` and
+`tailwind/<template>`; later files replace earlier ones. `{{name}}`,
+`{{run_dev}}` and the other placeholders in `src/render.js` are filled in,
+and `_gitignore` becomes `.gitignore`. `package.json` is written by
+`src/render.js`.
+
+## License
+
+MIT

package/bin/create-yerd.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+try {
+  process.exitCode = await main({
+    argv: process.argv.slice(2),
+    env: process.env,
+    cwd: process.cwd(),
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+  });
+} catch (error) {
+  // Anything unexpected (a folder it can't write to...): the message, not a stack trace.
+  process.stderr.write(`error ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "create-yerd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Scaffold a yerd app: npm create yerd@latest",
+  "keywords": [
+    "yerd",
+    "create",
+    "scaffold",
+    "template",
+    "typescript",
+    "tsx",
+    "ssr"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "toyz",
+  "homepage": "https://github.com/Toyz/yerd/tree/main/packages/create-yerd#readme",
+  "bugs": {
+    "url": "https://github.com/Toyz/yerd/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Toyz/yerd.git",
+    "directory": "packages/create-yerd"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "create-yerd": "bin/create-yerd.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc -p .",
+    "test": "node --test test/*.test.js",
+    "test:integration": "CREATE_YERD_INTEGRATION=1 node --test test/integration.test.js"
+  }
+}

package/src/args.js

@@ -0,0 +1,140 @@
+// @ts-check
+import { parseArgs as parseNodeArgs } from "node:util";
+
+export const TEMPLATES = /** @type {const} */ (["full", "minimal", "api"]);
+export const PACKAGE_MANAGERS = /** @type {const} */ (["npm", "pnpm", "yarn", "bun"]);
+
+/** @typedef {(typeof TEMPLATES)[number]} Template */
+/** @typedef {(typeof PACKAGE_MANAGERS)[number]} PackageManager */
+
+/**
+ * What the command line said. `undefined` means "ask, or use the default".
+ * @typedef {object} Args
+ * @property {string} [dir]
+ * @property {Template} [template]
+ * @property {boolean} [tailwind]
+ * @property {PackageManager} [pm]
+ * @property {boolean} [git]
+ * @property {boolean} [install]
+ * @property {boolean} yes
+ * @property {boolean} force
+ * @property {boolean} help
+ * @property {boolean} version
+ */
+
+/** A bad command line: printed without a stack trace, exit code 1. */
+export class UsageError extends Error {
+  name = "UsageError";
+}
+
+/** Templates that render pages, so Tailwind applies. */
+export const PAGE_TEMPLATES = /** @type {readonly Template[]} */ (["full", "minimal"]);
+
+/**
+ * @param {string[]} argv the arguments after the script
+ * @returns {Args}
+ */
+export function parseArgs(argv) {
+  /** @type {ReturnType<typeof parse>} */
+  let parsed;
+  try {
+    parsed = parse(argv);
+  } catch (error) {
+    throw new UsageError(cleanMessage(/** @type {Error} */ (error).message));
+  }
+  const { values, positionals } = parsed;
+  if (positionals.length > 1) throw new UsageError(`Expected one project directory, got ${positionals.length}: ${positionals.join(" ")}`);
+
+  const template = values.template;
+  if (template !== undefined && !includes(TEMPLATES, template)) {
+    throw new UsageError(`Unknown template "${template}". Use one of: ${TEMPLATES.join(", ")}`);
+  }
+  const pm = values.pm;
+  if (pm !== undefined && !includes(PACKAGE_MANAGERS, pm)) {
+    throw new UsageError(`Unknown package manager "${pm}". Use one of: ${PACKAGE_MANAGERS.join(", ")}`);
+  }
+  if (template === "api" && values.tailwind === true) {
+    throw new UsageError("--tailwind needs a template with pages (full or minimal); api has none");
+  }
+  const dir = positionals[0];
+  if (dir !== undefined && dir.trim() === "") throw new UsageError("The project directory can't be empty");
+
+  return {
+    dir,
+    template,
+    tailwind: values.tailwind,
+    pm,
+    git: values.git,
+    install: values.install,
+    yes: values.yes ?? false,
+    force: values.force ?? false,
+    help: values.help ?? false,
+    version: values.version ?? false,
+  };
+}
+
+/** @param {string[]} args */
+function parse(args) {
+  return parseNodeArgs({
+    args,
+    allowPositionals: true,
+    allowNegative: true,
+    strict: true,
+    options: {
+      template: { type: "string", short: "t" },
+      tailwind: { type: "boolean" },
+      pm: { type: "string" },
+      git: { type: "boolean" },
+      install: { type: "boolean" },
+      yes: { type: "boolean", short: "y" },
+      force: { type: "boolean", short: "f" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+  });
+}
+
+/**
+ * @template {string} T
+ * @param {readonly T[]} list
+ * @param {string} value
+ * @returns {value is T}
+ */
+export function includes(list, value) {
+  return /** @type {readonly string[]} */ (list).includes(value);
+}
+
+/** node:util's messages end with advice about "--" that doesn't fit here. @param {string} message */
+function cleanMessage(message) {
+  return message.split(". To specify a positional")[0]?.replace(/\.$/, "") ?? message;
+}
+
+export const HELP = `Usage: create-yerd [directory] [options]
+
+Scaffold a yerd app. Asks for anything the flags leave out.
+
+Options:
+  -t, --template <name>   full | minimal | api
+      --tailwind          add Tailwind CSS (full and minimal)
+      --no-tailwind       plain CSS
+      --pm <name>         npm | pnpm | yarn | bun (default: the one running this)
+      --git, --no-git     initialize a git repository (default: yes)
+      --install, --no-install
+                          install dependencies (default: yes)
+  -y, --yes               accept the defaults for everything not given
+  -f, --force             write into a directory that isn't empty
+  -h, --help              show this help
+  -v, --version           show the version
+
+Templates:
+  full      catalog, product pages, a session cart, sign-in, a validated form,
+            a JSON API, unit tests and a Playwright test
+  minimal   one page, a layout, one action, a test
+  api       JSON routes, DTO validation, errors, tests; no pages
+
+Examples:
+  npm create yerd@latest my-app
+  npm create yerd@latest my-app -- --template full --tailwind
+  pnpm create yerd my-api --template api --yes
+  npm create yerd@latest . -- --yes --no-install
+`;

package/src/cli.js

@@ -0,0 +1,180 @@
+// @ts-check
+import { spawnSync } from "node:child_process";
+import { relative } from "node:path";
+import { HELP, PAGE_TEMPLATES, UsageError, parseArgs } from "./args.js";
+import { commands, detectPackageManager } from "./pm.js";
+import { CancelError, createPrompter } from "./prompt.js";
+import { VERSION, writeProject, yerdSpec } from "./render.js";
+import { createStyle, useColor } from "./style.js";
+import { inspectTarget, packageName, resolveTarget, validateDir } from "./target.js";
+
+/** @typedef {import("./args.js").Template} Template */
+/** @typedef {import("./args.js").PackageManager} PackageManager */
+
+/** Defaults for --yes and for questions nobody answers. */
+export const DEFAULTS = { dir: "yerd-app", template: /** @type {Template} */ ("minimal"), tailwind: false, git: true, install: true };
+
+/** @type {{ value: Template, label: string, hint: string }[]} */
+const TEMPLATE_CHOICES = [
+  { value: "full", label: "Full app", hint: "catalog, cart, sign-in, forms, JSON API, tests" },
+  { value: "minimal", label: "Minimal", hint: "one page and a layout" },
+  { value: "api", label: "API only", hint: "JSON routes and validation, no pages" },
+];
+
+/**
+ * @typedef {object} Io
+ * @property {string[]} argv
+ * @property {NodeJS.ProcessEnv} env
+ * @property {string} cwd
+ * @property {NodeJS.ReadableStream & { isTTY?: boolean, setRawMode?: (on: boolean) => unknown }} stdin
+ * @property {NodeJS.WritableStream & { isTTY?: boolean }} stdout
+ * @property {NodeJS.WritableStream & { isTTY?: boolean }} stderr
+ * @property {(cmd: string, args: string[], cwd: string, quiet?: boolean) => boolean} [exec] runs a command; true on success
+ */
+
+/**
+ * The whole command. Returns the exit code.
+ * @param {Io} io
+ */
+export async function main(io) {
+  const style = createStyle(useColor(io.stdout, io.env));
+  const err = createStyle(useColor(io.stderr, io.env));
+  const exec = io.exec ?? run;
+  const say = (/** @type {string} */ text = "") => io.stdout.write(`${text}\n`);
+
+  let args;
+  try {
+    args = parseArgs(io.argv);
+  } catch (error) {
+    if (!(error instanceof UsageError)) throw error;
+    io.stderr.write(`${err.red("error")} ${error.message}\nRun create-yerd --help for the options.\n`);
+    return 1;
+  }
+  if (args.help) {
+    io.stdout.write(HELP);
+    return 0;
+  }
+  if (args.version) {
+    say(VERSION);
+    return 0;
+  }
+
+  const prompter = createPrompter({ input: io.stdin, output: io.stdout, style });
+  try {
+    say(`${style.bold("create-yerd")} ${style.dim(`v${VERSION}`)}\n`);
+    const ask = !args.yes;
+
+    const dir = args.dir ?? (ask ? await prompter.text({ message: "Project directory:", initial: DEFAULTS.dir, validate: validateDir }) : DEFAULTS.dir);
+    const target = resolveTarget(dir, io.cwd);
+    const state = inspectTarget(target);
+    if (state === "file") throw new UsageError(`${dir} is a file`);
+    if (state === "not-empty" && !args.force) {
+      if (!ask) throw new UsageError(`${dir === "." ? "This directory" : dir} is not empty. Use --force to write into it anyway`);
+      const proceed = await prompter.confirm({
+        message: `${dir === "." ? "This directory" : dir} is not empty. Write into it, overwriting files with the same names?`,
+        initial: false,
+      });
+      if (!proceed) throw new CancelError();
+    }
+
+    const template =
+      args.template ?? (ask ? await prompter.select({ message: "Template:", choices: TEMPLATE_CHOICES, initial: DEFAULTS.template }) : DEFAULTS.template);
+    const pages = PAGE_TEMPLATES.includes(template);
+    if (!pages && args.tailwind) throw new UsageError("--tailwind needs a template with pages (full or minimal); api has none");
+    const tailwind = pages && (args.tailwind ?? (ask ? await prompter.confirm({ message: "Add Tailwind CSS?", initial: DEFAULTS.tailwind }) : DEFAULTS.tailwind));
+
+    const detected = detectPackageManager(io.env.npm_config_user_agent);
+    /** @type {PackageManager} */
+    const pm =
+      args.pm ??
+      (ask
+        ? await prompter.select({
+            message: "Package manager:",
+            choices: /** @type {PackageManager[]} */ ([detected, ...["npm", "pnpm", "yarn", "bun"].filter((p) => p !== detected)]).map((p) => ({
+              value: p,
+              label: p,
+            })),
+            initial: detected,
+          })
+        : detected);
+    const git = args.git ?? (ask ? await prompter.confirm({ message: "Initialize a git repository?", initial: DEFAULTS.git }) : DEFAULTS.git);
+    const install = args.install ?? (ask ? await prompter.confirm({ message: "Install dependencies?", initial: DEFAULTS.install }) : DEFAULTS.install);
+    prompter.close();
+
+    const name = packageName(target, dir);
+    const shown = relative(io.cwd, target) || ".";
+    const asked = ask && (state === "not-empty" || [args.dir, args.template, args.pm, args.git, args.install, pages ? args.tailwind : false].includes(undefined));
+    if (asked) say();
+    say(`Scaffolding ${style.bold(name)} ${style.dim(`(${template}${tailwind ? ", tailwind" : ""})`)} in ${style.cyan(target)}`);
+    writeProject(target, { name, template, tailwind, pm, yerd: yerdSpec(io.env) });
+
+    const cmd = commands(pm);
+    let installed = false;
+    if (install) {
+      say(`Installing dependencies with ${pm}...`);
+      installed = exec(/** @type {string} */ (cmd.install[0]), cmd.install.slice(1), target);
+      if (!installed) io.stderr.write(`${err.yellow("warning")} ${cmd.install.join(" ")} failed; run it yourself in ${shown}\n`);
+    }
+
+    if (git) {
+      const result = initGit(target, exec);
+      if (result === "missing") io.stderr.write(`${err.yellow("warning")} git isn't installed; skipped the repository\n`);
+      else if (result === "inside") say(style.dim("Already inside a git repository; skipped git init."));
+      else if (result === "no-commit") io.stderr.write(`${err.yellow("warning")} git init ran, but the first commit failed (is user.name set?)\n`);
+      else say("Initialized a git repository.");
+    }
+
+    say();
+    say(style.bold("Next steps:"));
+    say();
+    if (shown !== ".") say(`  cd ${shown.includes(" ") ? JSON.stringify(shown) : shown}`);
+    if (!installed) say(`  ${cmd.install.join(" ")}`);
+    say(`  ${cmd.run("dev")}`.padEnd(24) + style.dim(`# http://localhost:5173${pages ? "" : "/api/notes"}`));
+    say();
+    say(`  ${cmd.run("test")}`.padEnd(24) + style.dim("# unit tests"));
+    say(`  ${cmd.run("build")}`.padEnd(24) + style.dim("# production build"));
+    say(`  ${cmd.run("start")}`.padEnd(24) + style.dim("# serve it, on PORT or http://localhost:3000"));
+    say();
+    say(`Docs: ${style.cyan("https://toyz.github.io/yerd/")}`);
+    return install && !installed ? 1 : 0;
+  } catch (error) {
+    prompter.close();
+    if (error instanceof CancelError) {
+      io.stderr.write(`\n${err.red("Cancelled.")} Nothing was written.\n`);
+      return 130;
+    }
+    if (error instanceof UsageError) {
+      io.stderr.write(`${err.red("error")} ${error.message}\n`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+/**
+ * git init and a first commit, unless the folder is already in a repository.
+ * @param {string} dir
+ * @param {NonNullable<Io["exec"]>} exec
+ * @returns {"done" | "missing" | "inside" | "no-commit"}
+ */
+function initGit(dir, exec) {
+  if (!exec("git", ["--version"], dir, true)) return "missing";
+  if (exec("git", ["rev-parse", "--is-inside-work-tree"], dir, true)) return "inside";
+  if (!exec("git", ["init", "-q"], dir, true)) return "missing";
+  if (!exec("git", ["add", "-A"], dir, true)) return "no-commit";
+  return exec("git", ["commit", "-q", "-m", "Initial commit from create-yerd"], dir, true) ? "done" : "no-commit";
+}
+
+/**
+ * Runs a command and waits. `quiet` swallows its output.
+ * @type {NonNullable<Io["exec"]>}
+ */
+function run(cmd, args, cwd, quiet = false) {
+  const result = spawnSync(cmd, args, {
+    cwd,
+    stdio: quiet ? "ignore" : "inherit",
+    // npm, pnpm and yarn are .cmd shims on Windows.
+    shell: process.platform === "win32",
+  });
+  return result.status === 0;
+}

package/src/pm.js

@@ -0,0 +1,33 @@
+// @ts-check
+import { includes, PACKAGE_MANAGERS } from "./args.js";
+
+/** @typedef {import("./args.js").PackageManager} PackageManager */
+
+/**
+ * The package manager that ran us, from npm_config_user_agent
+ * ("pnpm/10.4.1 npm/? node/v24.0.0 linux x64"). npm when there's none.
+ * @param {string | undefined} userAgent
+ * @returns {PackageManager}
+ */
+export function detectPackageManager(userAgent) {
+  const name = userAgent?.split(" ")[0]?.split("/")[0];
+  return name && includes(PACKAGE_MANAGERS, name) ? name : "npm";
+}
+
+/**
+ * The commands to print and run for one package manager.
+ * @param {PackageManager} pm
+ */
+export function commands(pm) {
+  return {
+    /** argv for installing dependencies */
+    install: pm === "yarn" ? ["yarn"] : [pm, "install"],
+    /** `npm run dev`, `pnpm dev`... for a script. Not `bun test`: that's bun's own runner. */
+    run: (/** @type {string} */ script) => {
+      if (pm === "npm") return script === "test" || script === "start" ? `npm ${script}` : `npm run ${script}`;
+      return pm === "bun" ? `bun run ${script}` : `${pm} ${script}`;
+    },
+    /** `npx`, `pnpm exec`... for a binary from node_modules */
+    exec: pm === "npm" ? "npx" : pm === "bun" ? "bunx" : pm === "pnpm" ? "pnpm exec" : "yarn",
+  };
+}