create-nexwire 4.1.2 → 4.2.0

package/express/src/framework/maker-cli/utils/naming.mjs

@@ -1,32 +1,93 @@
+/**
+ * Name handling for the generators.
+ *
+ * A developer may type a name in any common casing: `game-config`,
+ * `game_config`, `gameConfig` or `GameConfig`. All of them must resolve to the
+ * same thing, because a generator writes the name into four different places
+ * that each need a different shape:
+ *
+ *   file name    game-config.ts      kebab
+ *   SQL table    game_configs        snake
+ *   identifier   gameConfigs         camel
+ *   class name   GameConfigSeeder    pascal
+ *
+ * `normalizeName` produces the single canonical form (kebab). The other three
+ * are derived from it. This has to happen *before* lowercasing, because
+ * lowercasing `gameConfig` to `gameconfig` destroys the word boundary and no
+ * later step can recover it.
+ */
+
 /**
  * A name is safe when it can be used as a folder name, a URL segment, a table
  * name and a TypeScript identifier without further quoting.
  *
- * Kebab-case, snake_case and camelCase all pass: `pascal` already folds `-` and
- * `_`, and names are lowercased before this test. What fails is anything that
- * would produce uncompilable code - spaces and dots break the generated
- * `@/modules/...` import, a leading digit breaks the identifier.
+ * Kebab-case, snake_case, camelCase and PascalCase all pass: they are folded
+ * to one canonical kebab form first. What fails is anything that would produce
+ * uncompilable code - spaces and dots break the generated `@/modules/...`
+ * import, a leading digit breaks the identifier.
+ */
+const RAW_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+/**
+ * Fold any accepted casing to canonical kebab-case.
+ *
+ * `gameConfig` and `GameConfig` split on the lowercase/uppercase boundary;
+ * `game_config` splits on the underscore; repeated separators collapse to one
+ * dash. An all-caps run such as `GAMECONFIG` carries no boundary information
+ * and is deliberately kept as the single word `gameconfig`.
+ */
+export function normalizeName(value) {
+  return String(value)
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+/** Convert a kebab-case or camelCase string to snake_case (the SQL table name). */
+export function snakeCase(input) {
+  return String(input)
+    .trim()
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/_{2,}/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+}
+
+/**
+ * Pluralise an identifier for a table/collection name.
+ *
+ * Deliberately minimal: consonant + `y` becomes `ies` (so `auditEntry` yields
+ * `auditEntries`, matching the export a developer would hand-write), anything
+ * else takes a plain `s`. A word that already ends in `s` is returned
+ * unchanged so the helper is idempotent. English irregulars (`person` ->
+ * `people`) are not modelled; correct those by hand after generating.
  */
-const NAME_PATTERN = /^[a-z][a-z0-9_-]*$/;
+export function plural(word) {
+  const value = String(word);
+  if (!value) return value;
+  if (/[^aeiou]y$/i.test(value)) return `${value.slice(0, -1)}ies`;
+  if (/s$/i.test(value)) return value;
+  return `${value}s`;
+}
 
 /**
  * Best-effort readable repair of a rejected name, used only in error text.
- * Returns "" when no safe suggestion exists (e.g. a leading digit cannot be
+ * Returns "" when no safe suggestion exists (e.g., a leading digit cannot be
  * reordered without guessing the developer's intent).
  */
 function suggestName(value) {
-  const cleaned = value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9_-]+/g, "-")
-    .replace(/-{2,}/g, "-")
-    .replace(/^[-_]+|[-_]+$/g, "");
+  const cleaned = normalizeName(value);
   if (!cleaned || !/^[a-z]/.test(cleaned)) return "";
   return cleaned;
 }
 
 /**
- * Validate that a name value exists and is safe to use.
+ * Validate a name value exists and is safe to use, and return its canonical
+ * form so every generator writes the same name to disk.
  * Throws with the exact command to run instead when the value is unusable.
  */
 export function assertName(value, label) {
@@ -34,14 +95,16 @@ export function assertName(value, label) {
     throw new Error(`${label} is required.`);
   }
 
-  const name = value.trim().toLowerCase();
-  if (NAME_PATTERN.test(name)) return name;
+  const trimmed = value.trim();
+  if (!RAW_PATTERN.test(trimmed)) {
+    const suggestion = suggestName(value);
+    const reason = /^[0-9]/.test(trimmed)
+      ? "must start with a lowercase letter"
+      : "may only contain lowercase letters, numbers, dashes and underscores";
+    throw new Error(`Invalid ${label.toLowerCase()}: "${value}" - a name ${reason}.${suggestion ? ` Use "${suggestion}" instead.` : ""}`);
+  }
 
-  const suggestion = suggestName(value);
-  const reason = /^[0-9]/.test(name)
-    ? "must start with a lowercase letter"
-    : "may only contain lowercase letters, numbers, dashes and underscores";
-  throw new Error(`Invalid ${label.toLowerCase()}: "${value}" - a name ${reason}.${suggestion ? ` Use "${suggestion}" instead.` : ""}`);
+  return normalizeName(trimmed);
 }
 
 /** Convert a kebab-case or snake_case string to PascalCase. */

package/express/src/framework/maker-cli/utils/project-commands.mjs

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { writeFileAlways, writeFileIfMissing } from "./file-ops.mjs";
+import { PROJECT_COMMAND_FLAG } from "./help.mjs";
+
+/**
+ * Where a project keeps its own maker commands.
+ *
+ * Deliberately outside `src/`. Anything under `src/framework/` is copied into
+ * the published package by `scripts/sync-template.mjs`, so a developer edit
+ * there would be overwritten on the next framework update - and `src/modules/`
+ * is swept by the route, job and seeder globs. The project root is the one
+ * place nothing else owns.
+ */
+export const PROJECT_COMMANDS_PATH = "maker/commands.mjs";
+
+const PROJECT_COMMANDS_TEMPLATE = `/**
+ * Your project's maker commands.
+ *
+ * This file is yours. Nothing in nexwire writes to it, and no framework update
+ * will touch it. Whatever you export here is registered on the maker CLI
+ * alongside the built-in commands:
+ *
+ *   maker example:hello          run your command
+ *   maker --help                 every command, yours included
+ *
+ * \`program\` is the same commander object the built-in commands are built with,
+ * so \`.command()\`, \`.description()\`, \`.option()\` and \`.action()\` behave exactly
+ * as they do in nexwire's own commands.
+ *
+ * Three things worth knowing:
+ *
+ *   - A name that collides with a framework command is ignored, and you are told
+ *     which one. Rename yours; the built-in stays.
+ *   - An error in this file is reported, never swallowed. If your commands stop
+ *     appearing, the fault is here rather than in your command code.
+ *   - Import your own code with a normal relative path, e.g.
+ *       import { sendInvoice } from "../src/invoices/send.js";
+ *
+ * Replace or delete the example below once you have a command of your own.
+ */
+
+export default function register(program) {
+  program
+    .command("example:hello <name>")
+    .description("Example command - replace or delete this")
+    .option("--loud", "Shout the greeting")
+    .action((name, options) => {
+      const greeting = \`Hello, \${name}!\`;
+      console.log(options.loud ? greeting.toUpperCase() : greeting);
+    });
+}
+`;
+
+/**
+ * Why: Registers the commands a project defined for itself.
+ * When: Every maker invocation, right after the framework's own registrars.
+ * Where: Maker CLI entry flow, from utils/project-commands.mjs.
+ * How: Imports maker/commands.mjs resolved from process.cwd() - not from
+ *      import.meta.dirname, which points inside node_modules and would find the
+ *      framework's own directory instead of the project. Absent is silent and
+ *      free; broken is loud, because a developer's commands silently not
+ *      existing is a far worse experience than an error message. A name that
+ *      collides with a framework command is refused by commander itself, which
+ *      is the right outcome: the built-in wins and the project cannot shadow a
+ *      command it did not write. That refusal is re-thrown here with the file
+ *      name attached, because commander's own message does not say which file
+ *      asked for the name.
+ */
+export async function registerProjectCommands(program, rawArgs, cwd = process.cwd()) {
+  const file = path.resolve(cwd, PROJECT_COMMANDS_PATH);
+
+  if (!fs.existsSync(file)) {
+    return { loaded: false, file, added: [] };
+  }
+
+  // Not wrapped in a bare try/catch on purpose. A file that exists but fails to
+  // load has to say so, or the developer goes looking for a bug in their own
+  // command that is actually in this loader. The catches below only attach the
+  // file name, because an error from inside the project file otherwise reads as
+  // if it came from the framework.
+  let module;
+  try {
+    module = await import(pathToFileURL(file).href);
+  } catch (error) {
+    throw new Error(`Could not load ${PROJECT_COMMANDS_PATH}: ${error?.message || error}`, { cause: error });
+  }
+
+  const register = module.default ?? module.register;
+
+  if (typeof register !== "function") {
+    throw new TypeError(
+      `${PROJECT_COMMANDS_PATH} must export a default function (program, args) => void. Found: ${typeof register}.`
+    );
+  }
+
+  const before = new Set(program.commands);
+
+  try {
+    await register(program, rawArgs);
+  } catch (error) {
+    throw new Error(`Could not register commands from ${PROJECT_COMMANDS_PATH}: ${error?.message || error}`, {
+      cause: error
+    });
+  }
+
+  const added = [];
+
+  for (const command of program.commands) {
+    if (before.has(command)) continue;
+    // Tagged so `maker --help` files these under "Your commands" beside
+    // `maker:init`, rather than in the section for unclassified commands.
+    command[PROJECT_COMMAND_FLAG] = true;
+    added.push(command.name());
+  }
+
+  return { loaded: true, file, added };
+}
+
+/**
+ * Why: Creates maker/commands.mjs so a project can add its own commands.
+ * When: A developer runs `maker maker:init`.
+ * Where: utils/project-commands.mjs.
+ * How: Writes the template with the same no-clobber default as every other
+ *      generator, so an existing file is left alone unless --force is given.
+ */
+export async function initProjectCommands(cwd = process.cwd(), { force = false } = {}) {
+  const file = path.resolve(cwd, PROJECT_COMMANDS_PATH);
+
+  if (force) {
+    await writeFileAlways(file, PROJECT_COMMANDS_TEMPLATE);
+    return { file, created: false, overwritten: true };
+  }
+
+  await fsPromises.mkdir(path.dirname(file), { recursive: true });
+  const created = await writeFileIfMissing(file, PROJECT_COMMANDS_TEMPLATE);
+  return { file, created, overwritten: false };
+}