@stackcraftmx/calcita 0.0.0-stage → 0.23.0

package/cli/askQuestions.js

@@ -0,0 +1,63 @@
+// Las preguntas de «calcita new» en la terminal: cada una con sus opciones numeradas y la recomendada marcada; Enter acepta
+// la recomendada. Una respuesta que no sirve se vuelve a preguntar con su motivo.
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {createInterface} from 'node:readline/promises';
+import {stdin, stdout} from 'node:process';
+
+import {QUESTIONS, problemWithAnswer} from './projectAnswers.js';
+
+/**
+ * @param {Record<string, string>} recommendedAnswers las de defaultAnswersOf
+ * @param {Record<string, string>} [presetAnswers] las que ya llegaron como opciones: esas no se preguntan
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function askQuestions(recommendedAnswers, presetAnswers = {}) {
+    const terminal = createInterface({input: stdin, output: stdout});
+    const answers = {...presetAnswers};
+    try {
+        for (const question of QUESTIONS) {
+            if (question.key in presetAnswers || (question.when && !question.when(answers))) {
+                continue;
+            }
+            answers[question.key] = question.options
+                ? await askOption(terminal, question, recommendedAnswers[question.key])
+                : await askText(terminal, question, recommendedAnswers[question.key]);
+        }
+    } finally {
+        terminal.close();
+    }
+    return answers;
+}
+
+/** Una pregunta de opciones: se contesta con su número; Enter, la recomendada. */
+async function askOption(terminal, question, recommendedValue) {
+    stdout.write(`\n${question.text}\n`);
+    question.options.forEach(([value, label], index) => {
+        stdout.write(`  ${index + 1}) ${label}${value === recommendedValue ? '  ← recomendada' : ''}\n`);
+    });
+    for (;;) {
+        const reply = (await terminal.question('Número (Enter = recomendada): ')).trim();
+        if (reply === '') {
+            return recommendedValue;
+        }
+        const option = question.options[Number(reply) - 1];
+        if (option) {
+            return option[0];
+        }
+        stdout.write(`Escriba un número del 1 al ${question.options.length}.\n`);
+    }
+}
+
+/** Una pregunta de texto; Enter, la recomendada (si hay). */
+async function askText(terminal, question, recommendedValue) {
+    for (;;) {
+        const hint = recommendedValue ? ` [${recommendedValue}]` : '';
+        const reply = (await terminal.question(`\n${question.text}${hint}: `)).trim() || recommendedValue || '';
+        const problem = problemWithAnswer(question.key, reply);
+        if (!problem) {
+            return reply;
+        }
+        stdout.write(`${problem}\n`);
+    }
+}

package/cli/calcita.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// El CLI de Calcita: arma un proyecto nuevo con preguntas y el esqueleto de módulos, pantallas, formularios y componentes,
+// con la forma de los ejemplos (un módulo por carpeta, con su menú, sus rutas, sus textos y su API).
+//
+//   npx @stackcraftmx/calcita new mi-tienda          (o: pnpm dlx @stackcraftmx/calcita new mi-tienda)
+//   pnpm exec calcita make:module purchase-orders    (dentro del proyecto)
+//
+// Solo node, sin dependencias: corre antes de que el proyecto tenga nada instalado. Los textos para la persona van en
+// español; los nombres que escribe (módulos, pantallas…), en inglés y sin acentos, como el resto del código.
+//
+// OJO: los imports del CLI van con «./» y no con el alias @/: el CLI se publica tal cual y node no conoce el alias.
+import {basename, resolve} from 'node:path';
+import {argv, cwd, exit, stdin, stdout} from 'node:process';
+import {parseArgs} from 'node:util';
+
+import {askQuestions} from './askQuestions.js';
+import {makeComponent} from './makeComponent.js';
+import {makeForm} from './makeForm.js';
+import {makeModule} from './makeModule.js';
+import {makePage} from './makePage.js';
+import {namesOf} from './names.js';
+import {newProject} from './newProject.js';
+import {QUESTIONS, answersFromFlags, checkedAnswers, defaultAnswersOf} from './projectAnswers.js';
+import {screenLabelsOf} from './screenLabels.js';
+import {CliError} from './templateFiles.js';
+
+const HELP = `Calcita: proyectos y esqueletos con la forma de los ejemplos.
+
+  calcita new <carpeta>                      un proyecto nuevo (pregunta cómo lo quiere)
+  calcita init                               lo mismo, en la carpeta actual (vacía)
+  calcita make:module <módulo>               un módulo: menú, ruta, pantalla, formulario, API, textos y servidor de mentira
+  calcita make:page <módulo> <Pantalla>      otra pantalla en un módulo, con su ruta
+  calcita make:form <módulo> <Formulario>    un formulario con sus reglas y sus textos
+  calcita make:component <Componente>        un componente en src/core (lo usan varios módulos)
+       --module <módulo>                     … o solo de un módulo
+
+Opciones:
+  -y, --yes                 sin preguntas: lo recomendado, más lo que diga cada opción
+  --label-es, --label-en    el nombre en pantalla de un módulo o una pantalla nueva
+${QUESTIONS.map((question) => `  --${namesOf(question.key).kebab}=${question.options ? question.options.map(([value]) => value).join('|') : '…'}`).join('\n')}
+
+Los nombres van en inglés y sin acentos (purchase-orders, OrderDetail); el texto en pantalla, con --label-es y --label-en.`;
+
+// las respuestas de «new» también llegan como opciones: --menu-position=top
+const ANSWER_OPTIONS = Object.fromEntries(QUESTIONS.map((question) => [namesOf(question.key).kebab, {type: 'string'}]));
+
+const {values: options, positionals} = parseArgs({
+    args: argv.slice(2),
+    allowPositionals: true,
+    options: {
+        'yes': {type: 'boolean', short: 'y'},
+        'help': {type: 'boolean', short: 'h'},
+        'module': {type: 'string'},
+        'label-es': {type: 'string'},
+        'label-en': {type: 'string'},
+        ...ANSWER_OPTIONS,
+    },
+});
+const [command, ...commandArguments] = positionals;
+// se pregunta solo en una terminal de verdad y sin --yes (en un script se usa lo recomendado)
+const canAsk = Boolean(stdin.isTTY) && !options.yes;
+
+/** Las respuestas que llegaron como opciones, con la llave de su pregunta (menuPosition). */
+function answersInOptions() {
+    return Object.fromEntries(QUESTIONS
+        .map((question) => [question.key, options[namesOf(question.key).kebab]])
+        .filter(([, value]) => value !== undefined));
+}
+
+/** Imprime lo escrito, una ruta por renglón. */
+function printWritten(written) {
+    stdout.write(`${written.map((path) => `  + ${path}`).join('\n')}\n`);
+}
+
+async function runNew(folder) {
+    if (!folder) {
+        throw new CliError('Falta la carpeta del proyecto: calcita new mi-tienda');
+    }
+    const folderName = basename(resolve(folder));
+    const presetAnswers = answersInOptions();
+    const answers = canAsk
+        ? checkedAnswers({...defaultAnswersOf(folderName), ...presetAnswers, ...await askQuestions({...defaultAnswersOf(folderName), ...presetAnswers}, presetAnswers)})
+        : answersFromFlags(folderName, presetAnswers);
+    const {projectRoot, written} = await newProject({folder, answers});
+    stdout.write(`\nListo: ${projectRoot}\n`);
+    printWritten(written);
+    const enterFolder = folder === '.' ? '' : `  cd ${folder}\n`;
+    stdout.write(`\nPara arrancar:\n${enterFolder}  pnpm install\n  pnpm dev\n`);
+    if (answers.auth === 'yes') {
+        stdout.write('\nEn la pantalla de entrar, «Entrar con la cuenta de ejemplo» entra sin escribir nada (servidor de mentira).\n');
+    }
+}
+
+async function runMakeModule(moduleName) {
+    const labels = await screenLabelsOf({
+        defaultLabel: namesOf(moduleName ?? 'module').human, labelEs: options['label-es'], labelEn: options['label-en'], canAsk, what: 'el módulo',
+    });
+    const {written, path} = await makeModule({projectRoot: cwd(), moduleName, labels});
+    printWritten(written);
+    stdout.write(`\nListo: ya sale en el menú y en ${path}.\n`);
+}
+
+async function runMakePage(moduleName, pageName) {
+    const labels = await screenLabelsOf({
+        defaultLabel: namesOf(pageName ?? 'page').human, labelEs: options['label-es'], labelEn: options['label-en'], canAsk, what: 'la pantalla',
+    });
+    const {written, path, manualLines} = await makePage({projectRoot: cwd(), moduleName, pageName, labels});
+    printWritten(written);
+    if (manualLines) {
+        stdout.write(`\nNo reconocí la forma de routes.js del módulo: agregue a mano estos renglones (la constante y la ruta):\n${manualLines.join('\n')}\n`);
+    }
+    stdout.write(`\nListo: la pantalla está en ${path}.\n`);
+}
+
+async function runMakeForm(moduleName, formName) {
+    const written = await makeForm({projectRoot: cwd(), moduleName, formName});
+    printWritten(written);
+    // el componente es el .jsx que se escribió: la pantalla le dice qué hacer con los datos
+    const componentName = written.find((path) => path.endsWith('.jsx'))?.split('/').at(-1).replace('.jsx', '');
+    stdout.write(`\nListo. En una pantalla del módulo: <${componentName} onSubmit={addRecord} onSaved={showSaved} /> (las funciones de su *Api.js).\n`);
+}
+
+async function runMakeComponent(componentName) {
+    printWritten(await makeComponent({projectRoot: cwd(), componentName, moduleName: options.module}));
+    stdout.write('\nListo.\n');
+}
+
+const COMMANDS = Object.freeze({
+    'new': runNew,
+    'init': () => runNew('.'),
+    'make:module': runMakeModule,
+    'make:page': runMakePage,
+    'make:form': runMakeForm,
+    'make:component': runMakeComponent,
+});
+
+try {
+    const run = COMMANDS[command];
+    if (options.help || !command) {
+        stdout.write(`${HELP}\n`);
+    } else if (!run) {
+        throw new CliError(`No conozco el comando «${command}». Vea: calcita --help`);
+    } else {
+        await run(...commandArguments);
+    }
+} catch (error) {
+    // un error que se le explica a la persona sale solo con su mensaje; uno del CLI, completo (para reportarlo)
+    stdout.write(error instanceof CliError ? `\n${error.message}\n` : `\n${error.stack}\n`);
+    exit(1);
+}

package/cli/makeComponent.js

@@ -0,0 +1,50 @@
+// calcita make:component <Componente> [--module <módulo>]: un componente nuevo.
+//
+//   - Sin --module va a src/core (lo usan dos o más módulos) y se agrega a la puerta de core (src/core/index.js): se
+//     importa de '@/core'. Es genérico y sin estado: function.
+//   - Con --module va a src/modules/<módulo>/components (solo de ese módulo): arrow.
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {access, appendFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {existingModuleOf} from './makeForm.js';
+import {isValidName, namesOf} from './names.js';
+import {CliError, copyTemplateFolder} from './templateFiles.js';
+
+const COMPONENT_TEMPLATES = fileURLToPath(new URL('templates/component/', import.meta.url));
+
+/**
+ * @param {object} options
+ * @param {string} options.projectRoot
+ * @param {string} options.componentName
+ * @param {string} [options.moduleName] sin él, a core
+ * @returns {Promise<string[]>} las rutas escritas, relativas al proyecto
+ */
+export async function makeComponent({projectRoot, componentName, moduleName}) {
+    if (!isValidName(componentName ?? '')) {
+        throw new CliError('Falta el nombre del componente, en inglés y sin acentos (p. ej. StatusBadge).');
+    }
+    const componentNames = namesOf(componentName);
+
+    if (moduleName) {
+        const {folder, names: moduleNames} = await existingModuleOf(projectRoot, moduleName);
+        const written = await copyTemplateFolder({
+            templateFolder: join(COMPONENT_TEMPLATES, 'module'), targetFolder: join(folder, 'components'),
+            values: {ComponentName: componentNames.pascal, module: moduleNames.camel},
+        });
+        return written.map((path) => `src/modules/${moduleNames.camel}/components/${path}`);
+    }
+
+    const coreFolder = join(projectRoot, 'src', 'core');
+    const coreIndex = join(coreFolder, 'index.js');
+    await access(coreIndex).catch(() => {
+        throw new CliError('No encontré src/core/index.js (la puerta de core).');
+    });
+    const written = await copyTemplateFolder({
+        templateFolder: join(COMPONENT_TEMPLATES, 'core'), targetFolder: coreFolder, values: {ComponentName: componentNames.pascal},
+    });
+    await appendFile(coreIndex, `export {${componentNames.pascal}} from '@/core/${componentNames.pascal}.jsx';\n`);
+    return [...written.map((path) => `src/core/${path}`), 'src/core/index.js (se agregó a la puerta de core)'];
+}

package/cli/makeForm.js

@@ -0,0 +1,68 @@
+// calcita make:form <módulo> <Formulario>: un formulario dentro de un módulo, con la librería del proyecto (formik o
+// react-hook-form, la de calcita.json): el componente, sus reglas (yup) y sus textos.
+//
+//   calcita make:form contacts ContactForm
+//     → src/modules/contacts/ContactForm.jsx, contactFormSchema.js, contactFormTexts.js
+//
+// El formulario no sabe del servidor: la pantalla le pasa qué hacer con los datos (onSubmit).
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {access} from 'node:fs/promises';
+import {join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {isValidName, namesOf, withoutSuffixWord} from './names.js';
+import {readProjectConfig} from './projectConfig.js';
+import {CliError, copyTemplateFolder} from './templateFiles.js';
+
+const FORM_TEMPLATES = fileURLToPath(new URL('templates/form/', import.meta.url));
+// la carpeta de plantillas de cada librería de formularios
+const TEMPLATE_FOLDER_OF_LIBRARY = Object.freeze({'formik': 'formik', 'react-hook-form': 'hookForm'});
+
+/**
+ * La carpeta del módulo, que ya debe existir.
+ *
+ * @param {string} projectRoot
+ * @param {string} moduleName como lo escribió la persona
+ * @returns {Promise<{folder: string, names: ReturnType<typeof namesOf>}>}
+ */
+export async function existingModuleOf(projectRoot, moduleName) {
+    if (!isValidName(moduleName ?? '')) {
+        throw new CliError('Falta el módulo, en inglés y sin acentos (p. ej. contacts).');
+    }
+    const names = namesOf(moduleName);
+    const folder = join(projectRoot, 'src', 'modules', names.camel);
+    try {
+        await access(folder);
+    } catch {
+        throw new CliError(`No existe el módulo src/modules/${names.camel}. Créelo antes con: calcita make:module ${names.kebab}`);
+    }
+    return {folder, names};
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.projectRoot
+ * @param {string} options.moduleName
+ * @param {string} options.formName «ContactForm» o «contact» (se le agrega Form)
+ * @returns {Promise<string[]>} las rutas escritas, relativas al proyecto
+ */
+export async function makeForm({projectRoot, moduleName, formName}) {
+    const {folder, names: moduleNames} = await existingModuleOf(projectRoot, moduleName);
+    if (!isValidName(formName ?? '')) {
+        throw new CliError('Falta el nombre del formulario, en inglés y sin acentos (p. ej. ContactForm).');
+    }
+    const {forms} = await readProjectConfig(projectRoot);
+    const libraryFolder = TEMPLATE_FOLDER_OF_LIBRARY[forms];
+    if (!libraryFolder) {
+        throw new CliError(`calcita.json dice forms: «${forms}»; use formik o react-hook-form.`);
+    }
+
+    const formNames = namesOf(`${withoutSuffixWord(formName, 'form')} form`);
+    const values = {module: moduleNames.camel, FormName: formNames.pascal, formName: formNames.camel, FORM_NAME: formNames.constant};
+    const written = [
+        ...await copyTemplateFolder({templateFolder: join(FORM_TEMPLATES, 'shared'), targetFolder: folder, values}),
+        ...await copyTemplateFolder({templateFolder: join(FORM_TEMPLATES, libraryFolder), targetFolder: folder, values}),
+    ];
+    return written.map((path) => `src/modules/${moduleNames.camel}/${path}`);
+}

package/cli/makeModule.js

@@ -0,0 +1,78 @@
+// calcita make:module <nombre>: un módulo nuevo con la forma de los demás, en su carpeta y sin tocar ningún otro archivo:
+// su entrada en el menú (menu.js), su ruta (routes.js), su pantalla con la lista y el formulario para agregar, su API (la
+// única puerta al servidor), sus textos en español e inglés y su servidor de mentira (src/fakeServer).
+//
+//   calcita make:module purchase-orders
+//     → src/modules/purchaseOrders/… y src/fakeServer/purchaseOrdersServer.js, en /purchase-orders
+//
+// El menú, las rutas y los textos se descubren solos (import.meta.glob): el módulo sale en la app sin más ediciones.
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {access, readFile, readdir} from 'node:fs/promises';
+import {join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {makeForm} from './makeForm.js';
+import {isValidName, namesOf} from './names.js';
+import {CliError, copyTemplateFolder} from './templateFiles.js';
+
+const MODULE_TEMPLATES = fileURLToPath(new URL('templates/module/', import.meta.url));
+const MODULE_SERVER_TEMPLATES = fileURLToPath(new URL('templates/moduleServer/', import.meta.url));
+// el orden de un módulo nuevo: después del último, con espacio para meter otros en medio
+const ORDER_STEP = 10;
+const ORDER_PATTERN = /export const order = (\d+);/;
+
+/**
+ * El lugar en el menú para el módulo nuevo: el siguiente múltiplo de 10 después del mayor que ya hay.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<number>}
+ */
+async function nextMenuOrderOf(projectRoot) {
+    const modulesFolder = join(projectRoot, 'src', 'modules');
+    const orders = [];
+    for (const moduleFolder of await readdir(modulesFolder)) {
+        try {
+            const match = ORDER_PATTERN.exec(await readFile(join(modulesFolder, moduleFolder, 'menu.js'), 'utf8'));
+            if (match) {
+                orders.push(Number(match[1]));
+            }
+        } catch {
+            // un módulo sin menu.js (las pantallas de entrar): no cuenta
+        }
+    }
+    return (Math.floor(Math.max(0, ...orders) / ORDER_STEP) + 1) * ORDER_STEP;
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.projectRoot
+ * @param {string} options.moduleName como lo escribió la persona
+ * @param {{es: string, en: string}} options.labels su nombre en pantalla
+ * @returns {Promise<{written: string[], path: string}>} las rutas escritas (relativas al proyecto) y su dirección en la app
+ */
+export async function makeModule({projectRoot, moduleName, labels}) {
+    if (!isValidName(moduleName ?? '')) {
+        throw new CliError('Falta el nombre del módulo, en inglés y sin acentos (p. ej. purchase-orders).');
+    }
+    const names = namesOf(moduleName);
+    const moduleFolder = join(projectRoot, 'src', 'modules', names.camel);
+    const exists = await access(moduleFolder).then(() => true, () => false);
+    if (exists) {
+        throw new CliError(`Ya existe src/modules/${names.camel}; no se tocó nada.`);
+    }
+
+    const values = {
+        name: names.camel, Name: names.pascal, NAME: names.constant, kebab: names.kebab,
+        LABEL_ES: labels.es, LABEL_EN: labels.en, ORDER: String(await nextMenuOrderOf(projectRoot)),
+    };
+    const moduleFiles = await copyTemplateFolder({templateFolder: MODULE_TEMPLATES, targetFolder: moduleFolder, values});
+    const serverFiles = await copyTemplateFolder({templateFolder: MODULE_SERVER_TEMPLATES, targetFolder: join(projectRoot, 'src', 'fakeServer'), values});
+    // su formulario, con la librería del proyecto: el mismo que arma «calcita make:form»
+    const formFiles = await makeForm({projectRoot, moduleName: names.camel, formName: `${names.pascal}Form`});
+
+    return {
+        written: [...moduleFiles.map((path) => `src/modules/${names.camel}/${path}`), ...serverFiles.map((path) => `src/fakeServer/${path}`), ...formFiles],
+        path: `/${names.kebab}`,
+    };
+}

package/cli/makePage.js

@@ -0,0 +1,62 @@
+// calcita make:page <módulo> <Pantalla>: otra pantalla dentro de un módulo: el componente, sus textos y su ruta (se agrega
+// a routes.js del módulo, con su constante _PATH).
+//
+//   calcita make:page contacts ContactDetail
+//     → src/modules/contacts/ContactDetailPage.jsx y contactDetailPageTexts.js, en /contacts/contact-detail
+//
+// Si routes.js ya no tiene la forma de la plantilla (alguien lo cambió), no se adivina: se dice qué renglones agregar.
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {readFile, writeFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {existingModuleOf} from './makeForm.js';
+import {isValidName, namesOf, withoutSuffixWord} from './names.js';
+import {CliError, copyTemplateFolder, insertAfterLastMatch, insertIntoArray} from './templateFiles.js';
+
+const PAGE_TEMPLATES = fileURLToPath(new URL('templates/page/', import.meta.url));
+const PATH_CONSTANT_LINE = /^export const \w+_PATH = '([^']*)';$/m;
+const ROUTES_DECLARATION = 'export const routes = [';
+
+/**
+ * @param {object} options
+ * @param {string} options.projectRoot
+ * @param {string} options.moduleName
+ * @param {string} options.pageName «ContactDetail» o «ContactDetailPage»
+ * @param {{es: string, en: string}} options.labels su título en pantalla
+ * @returns {Promise<{written: string[], path: string, manualLines: string[]|null}>} manualLines: los renglones que hay
+ *     que agregar a mano a routes.js si no se pudo
+ */
+export async function makePage({projectRoot, moduleName, pageName, labels}) {
+    const {folder, names: moduleNames} = await existingModuleOf(projectRoot, moduleName);
+    if (!isValidName(pageName ?? '')) {
+        throw new CliError('Falta el nombre de la pantalla, en inglés y sin acentos (p. ej. ContactDetail).');
+    }
+    const pageNames = namesOf(withoutSuffixWord(pageName, 'page'));
+    const routesFile = join(folder, 'routes.js');
+    const routesText = await readFile(routesFile, 'utf8').catch(() => {
+        throw new CliError(`El módulo ${moduleNames.camel} no tiene routes.js.`);
+    });
+    // la dirección del módulo (su primera constante _PATH) y la de la pantalla, debajo
+    const modulePath = PATH_CONSTANT_LINE.exec(routesText)?.[1] ?? `/${moduleNames.kebab}`;
+    const pagePath = `${modulePath.replace(/\/$/, '')}/${pageNames.kebab}`;
+
+    const values = {
+        module: moduleNames.camel, PageName: pageNames.pascal, pageName: pageNames.camel, PAGE_NAME: pageNames.constant,
+        PAGE_LABEL_ES: labels.es, PAGE_LABEL_EN: labels.en,
+    };
+    const written = (await copyTemplateFolder({templateFolder: PAGE_TEMPLATES, targetFolder: folder, values}))
+        .map((path) => `src/modules/${moduleNames.camel}/${path}`);
+
+    const pathLine = `export const ${pageNames.constant}_PATH = '${pagePath}';`;
+    const routeLine = `    {path: ${pageNames.constant}_PATH, lazy: async () => ({Component: (await import('@/modules/${moduleNames.camel}/${pageNames.pascal}Page.jsx')).${pageNames.pascal}Page})},`;
+    const withPath = insertAfterLastMatch(routesText, PATH_CONSTANT_LINE, pathLine);
+    const withRoute = withPath && insertIntoArray(withPath, ROUTES_DECLARATION, routeLine);
+    if (!withRoute) {
+        return {written, path: pagePath, manualLines: [pathLine, routeLine]};
+    }
+    await writeFile(routesFile, withRoute);
+    written.push(`src/modules/${moduleNames.camel}/routes.js (se agregó su ruta)`);
+    return {written, path: pagePath, manualLines: null};
+}

package/cli/names.js

@@ -0,0 +1,64 @@
+// Los nombres que salen de lo que escribe la persona («purchase-orders», «PurchaseOrders», «purchase orders»). Cada parte
+// del proyecto pide el suyo: la carpeta y el namespace de textos en camelCase, el componente en PascalCase, la ruta en
+// kebab-case y la constante en MAYÚSCULAS. Se arman aquí, en un solo lugar, para que no salgan distintos de un archivo a otro.
+//
+// Funciones puras: function (regla de la casa). Pruebas en names.test.js.
+
+// una palabra: minúsculas con números («orders2»), una con mayúscula inicial («Orders») o unas siglas («PDF»)
+const WORD_PATTERN = /[A-Z]?[a-z0-9]+|[A-Z]+(?![a-z])/g;
+// lo que se acepta: letras sin acentos, números, espacios, guiones; empieza con letra. Los nombres van en inglés (regla de
+// la casa) y un acento en el nombre de un archivo o de una variable da problemas entre sistemas
+const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9 _-]*$/;
+
+/**
+ * Las palabras del nombre, en minúsculas: «PurchaseOrders» y «purchase-orders» dan ['purchase', 'orders'].
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function wordsOf(text) {
+    return (text.match(WORD_PATTERN) ?? []).map((word) => word.toLowerCase());
+}
+
+/**
+ * ¿Se puede usar como nombre de módulo, pantalla, formulario o componente?
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isValidName(text) {
+    return typeof text === 'string' && NAME_PATTERN.test(text.trim()) && wordsOf(text).length > 0;
+}
+
+const capitalized = (word) => word.charAt(0).toUpperCase() + word.slice(1);
+
+/**
+ * Todas las formas del nombre.
+ *
+ * @param {string} text
+ * @returns {{camel: string, pascal: string, kebab: string, constant: string, human: string}} human: «Purchase orders»,
+ *     para un texto de pantalla por omisión
+ */
+export function namesOf(text) {
+    const words = wordsOf(text);
+    return {
+        camel: words[0] + words.slice(1).map(capitalized).join(''),
+        pascal: words.map(capitalized).join(''),
+        kebab: words.join('-'),
+        constant: words.join('_').toUpperCase(),
+        human: capitalized(words.join(' ')),
+    };
+}
+
+/**
+ * El nombre sin una palabra del final que el CLI ya agrega: «OrderDetailPage» con 'page' da «OrderDetail» (si no, el
+ * componente saldría «OrderDetailPagePage»).
+ *
+ * @param {string} text
+ * @param {string} suffixWord en minúsculas
+ * @returns {string}
+ */
+export function withoutSuffixWord(text, suffixWord) {
+    const words = wordsOf(text);
+    return words.length > 1 && words.at(-1) === suffixWord ? words.slice(0, -1).join('-') : text;
+}

package/cli/newProject.js

@@ -0,0 +1,103 @@
+// calcita new <carpeta>: un proyecto nuevo de Vite + React + MUI con Calcita, armado con lo que se contestó (projectAnswers.js):
+// el marco con su menú, el tema, los textos en español e inglés, las rutas que se descubren solas, el servidor de
+// mentira, las pantallas de entrar (si se pidieron) y un módulo de ejemplo (contacts) hecho con «make:module».
+//
+// Nunca escribe en una carpeta con archivos: si ya existe y no está vacía, se detiene sin tocar nada.
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {mkdir, readdir} from 'node:fs/promises';
+import {basename, join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {makeModule} from './makeModule.js';
+import {isValidName, namesOf} from './names.js';
+import {calcitaPackageJson} from './packageVersions.js';
+import {primaryColorOf, templateFlagsOf} from './projectAnswers.js';
+import {projectConfigOf, PROJECT_CONFIG_FILE} from './projectConfig.js';
+import {appThemeFileOf, packageJsonOf} from './projectFiles.js';
+import {CliError, copyTemplateFolder, writeNewFile} from './templateFiles.js';
+
+const PROJECT_TEMPLATES = fileURLToPath(new URL('templates/project/', import.meta.url));
+// los archivos (o carpetas, con «/» al final) que solo van con una opción prendida
+const FILES_ONLY_WITH = Object.freeze({
+    'public/manifest.webmanifest.tpl': 'pwa',
+    'public/icons/': 'pwa',
+    'src/app/i18n.js.tpl': 'i18next',
+    'src/core/accountConnector.js.tpl': 'auth',
+    'src/modules/auth/': 'auth',
+    'src/modules/profile/': 'auth',
+});
+// lo que puede haber en una carpeta «vacía» (la de un repo recién clonado)
+const IGNORED_IN_EMPTY_FOLDER = new Set(['.git', '.DS_Store']);
+// el módulo de ejemplo
+const SAMPLE_MODULE = Object.freeze({name: 'contacts', labels: {es: 'Contactos', en: 'Contacts'}});
+
+/**
+ * ¿Va este archivo de la plantilla con estas opciones?
+ *
+ * @param {string} relativePath
+ * @param {Record<string, boolean>} flags
+ * @returns {boolean}
+ */
+export function isTemplateFileIncluded(relativePath, flags) {
+    for (const [pathOrFolder, flagName] of Object.entries(FILES_ONLY_WITH)) {
+        const matches = pathOrFolder.endsWith('/') ? relativePath.startsWith(pathOrFolder) : relativePath === pathOrFolder;
+        if (matches) {
+            return Boolean(flags[flagName]);
+        }
+    }
+    return true;
+}
+
+/** Falla si la carpeta tiene algo (se permite que no exista). */
+async function checkEmptyFolder(folder) {
+    const entries = await readdir(folder).catch((error) => {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    });
+    if (entries.some((entry) => !IGNORED_IN_EMPTY_FOLDER.has(entry))) {
+        throw new CliError(`La carpeta ${folder} ya tiene archivos; use una nueva o vacía.`);
+    }
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.folder donde se crea (relativa a donde se corre, o «.» para la actual)
+ * @param {Record<string, string>} options.answers ya revisadas (checkedAnswers)
+ * @returns {Promise<{projectRoot: string, written: string[]}>}
+ */
+export async function newProject({folder, answers}) {
+    const projectRoot = resolve(folder);
+    const folderName = basename(projectRoot);
+    if (!isValidName(folderName)) {
+        throw new CliError(`«${folderName}» no sirve como nombre del proyecto: letras sin acentos, números y guiones (p. ej. mi-tienda).`);
+    }
+    await checkEmptyFolder(projectRoot);
+    await mkdir(projectRoot, {recursive: true});
+
+    const calcitaPackage = await calcitaPackageJson();
+    const flags = templateFlagsOf(answers);
+    const packageName = namesOf(folderName).kebab;
+    const values = {
+        APP_TITLE: answers.appTitle,
+        APP_SLUG: packageName,
+        PRIMARY_COLOR: primaryColorOf(answers),
+        MENU_POSITION: answers.menuPosition,
+        FORMS_LIBRARY: answers.forms,
+    };
+
+    const written = await copyTemplateFolder({
+        templateFolder: PROJECT_TEMPLATES, targetFolder: projectRoot, values, flags,
+        includes: (relativePath) => isTemplateFileIncluded(relativePath, flags),
+    });
+    await writeNewFile(join(projectRoot, 'package.json'), packageJsonOf({packageName, answers, calcitaPackage}));
+    await writeNewFile(join(projectRoot, PROJECT_CONFIG_FILE), projectConfigOf(answers, calcitaPackage.version));
+    await writeNewFile(join(projectRoot, 'src', 'app', 'appTheme.js'), appThemeFileOf(answers));
+    written.push('package.json', PROJECT_CONFIG_FILE, 'src/app/appTheme.js');
+
+    const sample = await makeModule({projectRoot, moduleName: SAMPLE_MODULE.name, labels: SAMPLE_MODULE.labels});
+    written.push(...sample.written);
+    return {projectRoot, written};
+}