create-yerd 0.0.0-stage → 0.2.2

package/src/prompt.js

@@ -0,0 +1,284 @@
+// @ts-check
+// Prompts on node:readline. In a terminal: raw mode, arrow keys for selects,
+// y/n for confirms. Anywhere else (a pipe, CI): one plain question per line,
+// and the default for every question once input runs out.
+import { createInterface, emitKeypressEvents } from "node:readline";
+
+/** @typedef {import("./style.js").Style} Style */
+/** @typedef {{ name?: string, ctrl?: boolean, meta?: boolean, sequence?: string }} Key */
+
+/** Ctrl-C or Escape at a prompt. */
+export class CancelError extends Error {
+  name = "CancelError";
+  constructor() {
+    super("Cancelled");
+  }
+}
+
+/**
+ * @template {string} T
+ * @typedef {{ value: T, label: string, hint?: string }} Choice
+ */
+
+/**
+ * @param {object} io
+ * @param {NodeJS.ReadableStream & { isTTY?: boolean, setRawMode?: (on: boolean) => unknown, isRaw?: boolean }} io.input
+ * @param {NodeJS.WritableStream} io.output
+ * @param {Style} io.style
+ * @param {boolean} [io.interactive] raw-mode prompts; default: input and output are both terminals
+ */
+export function createPrompter({ input, output, style, interactive }) {
+  const raw = interactive ?? Boolean(input.isTTY && /** @type {{ isTTY?: boolean }} */ (output).isTTY && input.setRawMode);
+  return raw ? rawPrompter(input, output, style) : linePrompter(input, output, style);
+}
+
+/** @typedef {ReturnType<typeof createPrompter>} Prompter */
+
+/**
+ * The answered question, left on screen: "+ Project name my-app".
+ * @param {Style} style @param {string} message @param {string} answer
+ */
+function answered(style, message, answer) {
+  return `${style.green("+")} ${message} ${style.cyan(answer)}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Terminal: raw mode
+
+/**
+ * @param {NodeJS.ReadableStream & { setRawMode?: (on: boolean) => unknown, isRaw?: boolean }} input
+ * @param {NodeJS.WritableStream} output
+ * @param {Style} style
+ */
+function rawPrompter(input, output, style) {
+  emitKeypressEvents(input);
+
+  /**
+   * Draws `frame()` and redraws it after every key until `onKey` returns a result.
+   * @template R
+   * @param {() => string} frame
+   * @param {(str: string | undefined, key: Key) => { done: R } | void} onKey
+   * @returns {Promise<R>}
+   */
+  function interact(frame, onKey) {
+    return new Promise((resolve, reject) => {
+      const wasRaw = Boolean(input.isRaw);
+      let lines = 0;
+      const draw = () => {
+        // Back to the frame's first line, clear to the end, draw again.
+        const up = lines > 1 ? `\x1b[${lines - 1}A` : "";
+        const text = frame();
+        output.write(`${up}\r\x1b[J${text}`);
+        lines = text.split("\n").length;
+      };
+      const finish = () => {
+        input.off("keypress", onKeypress);
+        input.setRawMode?.(wasRaw);
+        input.pause();
+        const up = lines > 1 ? `\x1b[${lines - 1}A` : "";
+        output.write(`${up}\r\x1b[J\x1b[?25h`);
+      };
+      /** @param {string | undefined} str @param {Key | undefined} key */
+      const onKeypress = (str, key = {}) => {
+        if ((key.ctrl && key.name === "c") || key.name === "escape") {
+          finish();
+          reject(new CancelError());
+          return;
+        }
+        const result = onKey(str, key);
+        if (result) {
+          finish();
+          resolve(result.done);
+        } else draw();
+      };
+      input.setRawMode?.(true);
+      input.on("keypress", onKeypress);
+      input.resume();
+      draw();
+    });
+  }
+
+  return {
+    /**
+     * @param {{ message: string, initial?: string, validate?: (value: string) => string | undefined }} options
+     * @returns {Promise<string>}
+     */
+    async text({ message, initial = "", validate }) {
+      let value = "";
+      /** @type {string | undefined} */
+      let error;
+      const result = await interact(
+        () => {
+          const shown = value === "" && initial ? style.dim(initial) : value;
+          return `${style.cyan("?")} ${style.bold(message)} ${shown}${error ? `\n  ${style.red(error)}` : ""}`;
+        },
+        (str, key) => {
+          if (key.name === "return" || key.name === "enter") {
+            const answer = value.trim() || initial;
+            error = validate?.(answer);
+            return error ? undefined : { done: answer };
+          }
+          if (key.name === "backspace") value = value.slice(0, -1);
+          else if (key.ctrl && key.name === "u") value = "";
+          else if (str && !key.ctrl && !key.meta && !/[\x00-\x1f\x7f]/.test(str)) value += str;
+          error = undefined;
+        },
+      );
+      output.write(answered(style, message, result));
+      return result;
+    },
+
+    /**
+     * @template {string} T
+     * @param {{ message: string, choices: Choice<T>[], initial?: T }} options
+     * @returns {Promise<T>}
+     */
+    async select({ message, choices, initial }) {
+      let index = Math.max(0, choices.findIndex((c) => c.value === initial));
+      const width = Math.max(...choices.map((c) => c.label.length));
+      output.write("\x1b[?25l");
+      const choice = await interact(
+        () =>
+          [
+            `${style.cyan("?")} ${style.bold(message)} ${style.dim("(arrow keys, enter)")}`,
+            ...choices.map((c, i) => {
+              const label = c.hint ? c.label.padEnd(width) : c.label;
+              const hint = c.hint ? `  ${style.dim(c.hint)}` : "";
+              return i === index ? `${style.cyan(">")} ${style.cyan(label)}${hint}` : `  ${label}${hint}`;
+            }),
+          ].join("\n"),
+        (_str, key) => {
+          if (key.name === "up" || key.name === "k") index = (index - 1 + choices.length) % choices.length;
+          else if (key.name === "down" || key.name === "j" || key.name === "tab") index = (index + 1) % choices.length;
+          else if (key.name === "return" || key.name === "enter") return { done: /** @type {Choice<T>} */ (choices[index]) };
+        },
+      );
+      output.write(answered(style, message, choice.label));
+      return choice.value;
+    },
+
+    /**
+     * @param {{ message: string, initial?: boolean }} options
+     * @returns {Promise<boolean>}
+     */
+    async confirm({ message, initial = true }) {
+      const result = await interact(
+        () => `${style.cyan("?")} ${style.bold(message)} ${style.dim(initial ? "(Y/n)" : "(y/N)")}`,
+        (str, key) => {
+          if (key.name === "return" || key.name === "enter") return { done: initial };
+          if (str?.toLowerCase() === "y") return { done: true };
+          if (str?.toLowerCase() === "n") return { done: false };
+        },
+      );
+      output.write(answered(style, message, result ? "yes" : "no"));
+      return result;
+    },
+
+    close() {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pipes and CI: plain lines
+
+/**
+ * @param {NodeJS.ReadableStream} input
+ * @param {NodeJS.WritableStream} output
+ * @param {Style} style
+ */
+function linePrompter(input, output, style) {
+  /** @type {import("node:readline").Interface | undefined} */
+  let rl;
+  /** @type {AsyncIterator<string> | undefined} */
+  let lines;
+  let ended = false;
+
+  /** The next line of input, or undefined once there's no more. */
+  async function nextLine() {
+    if (ended) return undefined;
+    if (!lines) {
+      rl = createInterface({ input, terminal: false });
+      lines = rl[Symbol.asyncIterator]();
+    }
+    const next = await lines.next();
+    if (next.done) {
+      ended = true;
+      return undefined;
+    }
+    return next.value.trim();
+  }
+
+  /**
+   * Asks until `parse` accepts the line; no input left means the default.
+   * `parse` returns `{ value }`, or a message saying what's wrong.
+   * @template T
+   * @param {string} question
+   * @param {T} fallback
+   * @param {(line: string) => { value: T } | string} parse
+   * @returns {Promise<T>}
+   */
+  async function ask(question, fallback, parse) {
+    for (;;) {
+      output.write(question);
+      const line = await nextLine();
+      if (line === undefined) {
+        output.write("\n");
+        return fallback;
+      }
+      if (line === "") return fallback;
+      const result = parse(line);
+      if (typeof result !== "string") return result.value;
+      output.write(`${style.red(result)}\n`);
+    }
+  }
+
+  return {
+    /**
+     * @param {{ message: string, initial?: string, validate?: (value: string) => string | undefined }} options
+     * @returns {Promise<string>}
+     */
+    async text({ message, initial = "", validate }) {
+      const value = await ask(`${message}${initial ? ` (${initial})` : ""}: `, initial, (line) => {
+        const error = validate?.(line);
+        return error ?? { value: line };
+      });
+      const error = validate?.(value);
+      // The default itself failing (no input left) has nobody to ask again.
+      if (error) throw new Error(`${message}: ${error}`);
+      return value;
+    },
+
+    /**
+     * @template {string} T
+     * @param {{ message: string, choices: Choice<T>[], initial?: T }} options
+     * @returns {Promise<T>}
+     */
+    async select({ message, choices, initial }) {
+      const fallback = initial ?? /** @type {Choice<T>} */ (choices[0]).value;
+      const list = choices.map((c, i) => `  ${i + 1}) ${c.label}${c.hint ? ` - ${c.hint}` : ""}`).join("\n");
+      output.write(`${message}\n${list}\n`);
+      return ask(`Choose 1-${choices.length} or a name (${fallback}): `, fallback, (line) => {
+        const byNumber = /^\d+$/.test(line) ? choices[Number(line) - 1] : undefined;
+        const lower = line.toLowerCase();
+        const match = byNumber ?? choices.find((c) => c.value.toLowerCase() === lower || c.label.toLowerCase() === lower);
+        return match ? { value: match.value } : `Pick 1-${choices.length} or one of: ${choices.map((c) => c.value).join(", ")}`;
+      });
+    },
+
+    /**
+     * @param {{ message: string, initial?: boolean }} options
+     * @returns {Promise<boolean>}
+     */
+    async confirm({ message, initial = true }) {
+      return ask(`${message} ${initial ? "(Y/n)" : "(y/N)"}: `, initial, (line) => {
+        if (/^(y|yes)$/i.test(line)) return { value: true };
+        if (/^(n|no)$/i.test(line)) return { value: false };
+        return "Answer y or n";
+      });
+    },
+
+    close() {
+      rl?.close();
+    },
+  };
+}

package/src/render.js

@@ -0,0 +1,159 @@
+// @ts-check
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { commands } from "./pm.js";
+import { VERSIONS } from "./versions.js";
+
+/** @typedef {import("./args.js").Template} Template */
+/** @typedef {import("./args.js").PackageManager} PackageManager */
+
+export const TEMPLATES_DIR = fileURLToPath(new URL("../templates/", import.meta.url));
+
+const own = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+/** This package's version. create-yerd is released with yerd, at the same version. */
+export const VERSION = /** @type {string} */ (own.version);
+
+/**
+ * The @toyz/yerd dependency for generated apps: the matching release, or
+ * CREATE_YERD_YERD_SPEC (`file:/abs/path` to the repo or a packed tarball) for tests.
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function yerdSpec(env = process.env) {
+  return env.CREATE_YERD_YERD_SPEC || `^${VERSION}`;
+}
+
+/**
+ * @typedef {object} Options
+ * @property {string} name the package name
+ * @property {Template} template
+ * @property {boolean} tailwind
+ * @property {PackageManager} pm
+ * @property {string} yerd the @toyz/yerd version range or spec
+ */
+
+/**
+ * Template folders to copy, in order; later ones overwrite earlier files.
+ * @param {Template} template @param {boolean} tailwind
+ */
+export function layers(template, tailwind) {
+  const list = ["_shared", template];
+  if (tailwind) list.push("tailwind/_shared", `tailwind/${template}`);
+  return list;
+}
+
+/**
+ * The values `{{key}}` placeholders in template files are replaced with.
+ * @param {Options} options
+ * @returns {Record<string, string>}
+ */
+export function variables({ name, pm }) {
+  const cmd = commands(pm);
+  return {
+    name,
+    pm,
+    install: cmd.install.join(" "),
+    exec: cmd.exec,
+    run_dev: cmd.run("dev"),
+    run_build: cmd.run("build"),
+    run_start: cmd.run("start"),
+    run_test: cmd.run("test"),
+    run_check: cmd.run("check"),
+    run_e2e: cmd.run("e2e"),
+  };
+}
+
+/**
+ * Replaces `{{key}}` with its value; an unknown key is a bug in the template.
+ * @param {string} text @param {Record<string, string>} vars @param {string} file
+ */
+export function substitute(text, vars, file = "template") {
+  return text.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = vars[key];
+    if (value === undefined) throw new Error(`${file}: unknown placeholder {{${key}}}`);
+    return value;
+  });
+}
+
+/**
+ * `_gitignore` -> `.gitignore`: npm won't publish some dotfiles, so templates name them with `_`.
+ * @param {string} path relative, with `/`
+ */
+export function outputPath(path) {
+  return path.replace(/(^|\/)_([^/]+)$/, "$1.$2");
+}
+
+/**
+ * Every file of the layers, by output path, the last layer winning.
+ * @param {Options} options
+ * @returns {Map<string, string>} output path -> rendered contents
+ */
+export function renderFiles(options) {
+  const vars = variables(options);
+  /** @type {Map<string, string>} */
+  const files = new Map();
+  for (const layer of layers(options.template, options.tailwind)) {
+    const root = join(TEMPLATES_DIR, layer);
+    for (const file of walk(root)) {
+      const rel = relative(root, file).split(sep).join("/");
+      files.set(outputPath(rel), substitute(readFileSync(file, "utf8"), vars, `${layer}/${rel}`));
+    }
+  }
+  files.set("package.json", `${JSON.stringify(packageJson(options), null, 2)}\n`);
+  return new Map([...files].sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/**
+ * Writes the project into `dir` (created if missing). Returns the paths written.
+ * @param {string} dir @param {Options} options
+ */
+export function writeProject(dir, options) {
+  const files = renderFiles(options);
+  for (const [path, contents] of files) {
+    const out = join(dir, path);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, contents);
+  }
+  return [...files.keys()];
+}
+
+/**
+ * The generated package.json.
+ * @param {Options} options
+ */
+export function packageJson({ name, template, tailwind, yerd }) {
+  /** @type {Record<string, string>} */
+  const scripts = {
+    dev: "vite",
+    build: "vite build",
+    start: "node --env-file-if-exists=.env dist/server/server.js",
+    test: "vitest run",
+    check: "tsc --noEmit",
+  };
+  const dev = ["@types/node", "esbuild", "typescript", "vite", "vitest"];
+  if (tailwind) dev.push("@tailwindcss/vite", "tailwindcss");
+  if (template === "full") {
+    scripts.e2e = "playwright test";
+    dev.push("@playwright/test");
+  }
+  return {
+    name,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    engines: { node: ">=24" },
+    scripts,
+    dependencies: { "@toyz/yerd": yerd },
+    devDependencies: Object.fromEntries(dev.sort().map((dep) => [dep, VERSIONS[/** @type {keyof typeof VERSIONS} */ (dep)]])),
+  };
+}
+
+/** @param {string} dir @returns {Generator<string>} */
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(path);
+    else if (entry.isFile()) yield path;
+  }
+}

package/src/style.js

@@ -0,0 +1,33 @@
+// @ts-check
+// Plain ANSI styling. Off for NO_COLOR, TERM=dumb and anything that isn't a terminal.
+
+/**
+ * Whether to color output written to `stream`.
+ * @param {{ isTTY?: boolean }} stream
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function useColor(stream, env = process.env) {
+  if (env.NO_COLOR) return false;
+  if (env.FORCE_COLOR && env.FORCE_COLOR !== "0") return true;
+  if (env.TERM === "dumb") return false;
+  return Boolean(stream.isTTY);
+}
+
+/**
+ * @param {boolean} enabled
+ */
+export function createStyle(enabled) {
+  /** @param {number} open @param {number} close */
+  const wrap = (open, close) => (/** @type {string} */ text) => (enabled ? `\x1b[${open}m${text}\x1b[${close}m` : text);
+  return {
+    enabled,
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    cyan: wrap(36, 39),
+  };
+}
+
+/** @typedef {ReturnType<typeof createStyle>} Style */

package/src/target.js

@@ -0,0 +1,68 @@
+// @ts-check
+import { readdirSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+
+/** Files that don't make a directory "not empty". */
+const IGNORABLE = new Set([".git", ".DS_Store", "Thumbs.db", ".idea", ".vscode"]);
+
+/**
+ * The project directory as typed: `.` is the current folder.
+ * @param {string} dir
+ * @param {string} cwd
+ */
+export function resolveTarget(dir, cwd = process.cwd()) {
+  return resolve(cwd, dir);
+}
+
+/**
+ * A valid npm package name for the folder: lowercased, anything npm refuses
+ * turned into dashes. A scope typed as the directory (`@me/app`) is kept.
+ * @param {string} path the absolute target
+ * @param {string} [typed] what the user typed, for a scoped name
+ */
+export function packageName(path, typed) {
+  if (typed && /^@[^/]+\/[^/]+$/.test(typed.trim())) {
+    const [scope, name] = typed.trim().slice(1).split("/");
+    return `@${slug(scope ?? "")}/${slug(name ?? "") || "yerd-app"}`;
+  }
+  return slug(basename(path)) || "yerd-app";
+}
+
+/** @param {string} text */
+function slug(text) {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/^[._]+/, "")
+    .replace(/[^a-z0-9._~-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 214);
+}
+
+/**
+ * Why `dir` can't be a project directory, or undefined if it can (as typed into the prompt).
+ * @param {string} dir
+ */
+export function validateDir(dir) {
+  if (dir.trim() === "") return "Enter a directory name, or . for this one";
+  if (/[<>:"|?*\x00-\x1f]/.test(dir)) return "That name has characters a folder can't have";
+  return undefined;
+}
+
+/**
+ * What's at the target: nothing, an empty folder, a folder with files, or a file.
+ * @param {string} path
+ * @returns {"missing" | "empty" | "not-empty" | "file"}
+ */
+export function inspectTarget(path) {
+  let stats;
+  try {
+    stats = statSync(path);
+  } catch {
+    return "missing";
+  }
+  if (!stats.isDirectory()) return "file";
+  return readdirSync(path).some((name) => !IGNORABLE.has(name)) ? "not-empty" : "empty";
+}

package/src/versions.js

@@ -0,0 +1,14 @@
+// @ts-check
+// Dev dependency ranges for generated apps. Kept equal to the yerd repo's own
+// devDependencies (a test checks), so templates are built with what yerd is tested with.
+
+export const VERSIONS = {
+  "@playwright/test": "^1.64.1",
+  "@tailwindcss/vite": "^4.3.3",
+  "@types/node": "^26.6.5",
+  esbuild: "^0.28.2",
+  tailwindcss: "^4.3.3",
+  typescript: "^7.0.2",
+  vite: "^8.3.4",
+  vitest: "^5.0.5",
+};

package/templates/_shared/_env.example

@@ -0,0 +1,9 @@
+# Copy to .env for `{{run_start}}`; in production, set these in the environment.
+
+# Signs action tokens and seals session cookies: 32 bytes or more, the same on
+# every instance. Without it, a random one, so sessions and forms break on restart.
+#   node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"
+YERD_SECRET=
+
+# Log filter, e.g. info or info,yerd=debug
+# YERD_LOG=info

package/templates/_shared/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+*.tsbuildinfo
+test-results/
+playwright-report/

package/templates/_shared/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+import { yerdDecorators } from "@toyz/yerd/vite";
+
+export default defineConfig({
+  // Lowers TC39 decorators, which Vite can't yet. Tests don't need the dev server.
+  plugins: [yerdDecorators()],
+  test: { include: ["test/**/*.test.{ts,tsx}"] },
+});

package/templates/api/README.md

@@ -0,0 +1,39 @@
+# {{name}}
+
+A JSON API on [yerd](https://toyz.github.io/yerd/): routes are decorated
+classes, bodies are validated DTOs, errors are classes with a status.
+
+```sh
+{{run_dev}}      # dev server with reloads, on http://localhost:5173
+{{run_test}}     # vitest, in-process: no port
+{{run_check}}    # type-check (Vite doesn't)
+{{run_build}}    # production build: dist/server/server.js
+{{run_start}}    # node dist/server/server.js, on PORT or 3000
+```
+
+```sh
+curl localhost:5173/api/notes
+curl -X POST localhost:5173/api/notes -H 'content-type: application/json' -d '{"title":"Ship it"}'
+curl -X DELETE localhost:5173/api/notes/1
+```
+
+| Route | What |
+| --- | --- |
+| `GET /api/notes` | every note; `?done=true` filters |
+| `POST /api/notes` | 201 with the note; 400 listing every invalid field; 409 for a duplicate title |
+| `GET /api/notes/:id` | the note, or a 404 carrying the id |
+| `PUT /api/notes/:id` | replace it |
+| `DELETE /api/notes/:id` | 204, no body |
+| `GET /api/health` | 204, for load balancers |
+
+| File | What |
+| --- | --- |
+| `src/main.ts` | the Vite entry: the app with every route under `src/routes/` |
+| `src/app.ts` | `createApp()`, shared with the tests |
+| `src/notes.ts` | `NoteInput` DTO, `NoteNotFound`, the `Notes` service |
+| `src/routes/notes.ts` | the routes |
+| `test/notes.test.ts` | `app.request()` tests |
+
+Add `.sessions()` in `src/app.ts` when you need cookies, and see
+[request data](https://toyz.github.io/yerd/#/guide/request-data) and
+[responses](https://toyz.github.io/yerd/#/guide/responses) for the rest.

package/templates/api/src/app.ts

@@ -0,0 +1,9 @@
+import { yerd, type YerdOptions } from "@toyz/yerd";
+
+/**
+ * The app without routes: main.ts discovers them, tests import the ones they need.
+ * No sessions, no layout: every answer is JSON (or a bare status).
+ */
+export function createApp(options?: YerdOptions) {
+  return yerd(options);
+}

package/templates/api/src/main.ts

@@ -0,0 +1,5 @@
+/// <reference types="vite/client" />
+import { createApp } from "./app.js";
+
+// The Vite entry. The plugin serves it in dev and the build's server.js listens: no listen() here.
+export default createApp().discover(import.meta.glob("./routes/**/*.ts", { eager: true }));