@stackcraftmx/calcita 0.0.0-stage → 0.23.0

package/cli/packageVersions.js

@@ -0,0 +1,38 @@
+// Las versiones exactas que pide el proyecto nuevo: las mismas con que se probó Calcita. Se leen del package.json del
+// paquete (sus devDependencies), así hay UNA sola lista de versiones y no una copia aquí que se quede vieja.
+//
+// Funciones de node, sin React: function (regla de la casa). Pruebas en packageVersions.test.js.
+import {readFile} from 'node:fs/promises';
+
+// Lo que el paquete no usa, así que no está en sus devDependencies: i18next (su adaptador recibe la instancia del proyecto;
+// versión con más de dos semanas publicada al escogerla, pnpm espera un día antes de instalar una recién salida) y qrcode
+// (el QR de la cuenta de demostración; la misma versión que usan los ejemplos)
+const VERSIONS_NOT_IN_PACKAGE = Object.freeze({i18next: '26.4.2', qrcode: '1.5.4'});
+
+/**
+ * El package.json de Calcita (el del CLI que corre). OJO: por ruta de archivo y no con import: el CLI se publica tal cual,
+ * sin pasar por Vite, y node no lee JSON con import sin una bandera.
+ *
+ * @returns {Promise<{name: string, version: string, devDependencies: Record<string, string>}>}
+ */
+export async function calcitaPackageJson() {
+    return JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+}
+
+/**
+ * La versión exacta de cada librería.
+ *
+ * @param {string[]} packageNames
+ * @param {{devDependencies: Record<string, string>}} calcitaPackage
+ * @returns {Record<string, string>}
+ */
+export function versionsOf(packageNames, calcitaPackage) {
+    return Object.fromEntries(packageNames.map((packageName) => {
+        const version = calcitaPackage.devDependencies?.[packageName] ?? VERSIONS_NOT_IN_PACKAGE[packageName];
+        // guard clause: una librería sin versión es un error del CLI (alguien la quitó del paquete), no algo que se adivine
+        if (!version) {
+            throw new Error(`El CLI no sabe con qué versión de ${packageName} se probó Calcita`);
+        }
+        return [packageName, version];
+    }));
+}

package/cli/projectAnswers.js

@@ -0,0 +1,145 @@
+// Las preguntas de «calcita new»: qué se pregunta, sus opciones (la primera es la recomendada) y cómo cada respuesta
+// prende o apaga partes de las plantillas. Las mismas respuestas se pueden dar con banderas (--forms=react-hook-form) o
+// aceptar todas las recomendadas con --yes.
+//
+// Funciones puras: function (regla de la casa). Pruebas en projectAnswers.test.js.
+import {CliError} from './templateFiles.js';
+
+/** Los colores de fábrica de cada opción (el principal): el tema de la app y el color de la barra del sistema al instalarla. */
+export const PRIMARY_COLOR_OF = Object.freeze({
+    // el naranja Forge de Stackcraft (STACKCRAFT.forge del paquete)
+    stackcraft: '#FF6B1A',
+    // el azul de MUI (su primary.main por omisión)
+    mui: '#1976D2',
+});
+
+const HEX_COLOR = /^#[0-9A-Fa-f]{6}$/;
+// el nombre de la app va en el código (un texto entre comillas), en el HTML y en el manifiesto: sin comillas, sin < ni &
+const APP_TITLE_PATTERN = /^[\p{L}\p{N}][\p{L}\p{N} .,·-]*$/u;
+
+/** Las preguntas, en orden. `options`: [valor, texto]; la primera es la recomendada. */
+export const QUESTIONS = Object.freeze([
+    {key: 'appTitle', text: 'Nombre de la app (en la barra y en la pestaña)'},
+    {key: 'menuPosition', text: '¿Dónde va el menú?', options: [['side', 'A un lado (se encoge a íconos)'], ['top', 'Arriba, en la barra']]},
+    {
+        key: 'style', text: 'Estilo',
+        options: [['glass', 'Vidrio líquido en lo que flota (menús, barra, avisos); en Android, minimalista'], ['plain', 'Sin vidrio'], ['minimal', 'Minimalista: plano, sin bordes ni sombras']],
+    },
+    {key: 'colorModes', text: 'Modos de color', options: [['lightAndDark', 'Claro y oscuro (con su botón)'], ['lightOnly', 'Solo claro']]},
+    {key: 'colors', text: 'Colores', options: [['stackcraft', 'Los de Stackcraft (naranja)'], ['mui', 'Los de MUI (azul)'], ['custom', 'Uno propio']]},
+    {key: 'primaryColor', text: 'Color principal (#RRGGBB)', when: (answers) => answers.colors === 'custom'},
+    {key: 'forms', text: 'Formularios', options: [['formik', 'formik (viene con Calcita)'], ['react-hook-form', 'react-hook-form']]},
+    {key: 'texts', text: 'Textos de la app', options: [['calcita', 'Los de Calcita (archivos JS por módulo)'], ['i18next', 'Con i18next']]},
+    {key: 'auth', text: 'Pantallas de entrar, «¿Olvidó su contraseña?» y Mi perfil, con un servidor de mentira', options: [['yes', 'Sí'], ['no', 'No']]},
+    {key: 'pwa', text: 'Que se pueda instalar como app (PWA, sin modo sin conexión)', options: [['yes', 'Sí'], ['no', 'No']]},
+]);
+
+/**
+ * Las respuestas recomendadas.
+ *
+ * @param {string} folderName el nombre de la carpeta: de ahí sale el nombre de la app por omisión
+ * @returns {Record<string, string>}
+ */
+export function defaultAnswersOf(folderName) {
+    const answers = {appTitle: titleOfFolder(folderName)};
+    for (const question of QUESTIONS) {
+        if (question.options) {
+            answers[question.key] = question.options[0][0];
+        }
+    }
+    return answers;
+}
+
+/** «mi-tienda» → «Mi tienda». */
+function titleOfFolder(folderName) {
+    const words = folderName.split(/[-_\s]+/).filter(Boolean);
+    const title = words.join(' ');
+    return title ? title.charAt(0).toUpperCase() + title.slice(1) : 'Mi app';
+}
+
+/**
+ * ¿La respuesta sirve? Regresa el motivo si no, en palabras de la persona.
+ *
+ * @param {string} key
+ * @param {string} value
+ * @returns {string|null}
+ */
+export function problemWithAnswer(key, value) {
+    const question = QUESTIONS.find((candidate) => candidate.key === key);
+    if (!question) {
+        return `No hay una opción «${key}».`;
+    }
+    if (question.options && !question.options.some(([optionValue]) => optionValue === value)) {
+        return `«${value}» no es una opción de ${key}: use ${question.options.map(([optionValue]) => optionValue).join(', ')}.`;
+    }
+    if (key === 'primaryColor' && !HEX_COLOR.test(value)) {
+        return 'El color va como #RRGGBB, por ejemplo #2563EB.';
+    }
+    if (key === 'appTitle' && !APP_TITLE_PATTERN.test(value)) {
+        return 'El nombre lleva letras, números, espacios, puntos, comas o guiones (sin comillas).';
+    }
+    return null;
+}
+
+/**
+ * Las respuestas recomendadas con lo que vino en banderas encima; truena con el motivo si una no sirve.
+ *
+ * @param {string} folderName
+ * @param {Record<string, string|undefined>} flagValues
+ * @returns {Record<string, string>}
+ */
+export function answersFromFlags(folderName, flagValues) {
+    const answers = defaultAnswersOf(folderName);
+    for (const question of QUESTIONS) {
+        const value = flagValues[question.key];
+        if (value !== undefined) {
+            answers[question.key] = value;
+        }
+    }
+    return checkedAnswers(answers);
+}
+
+/**
+ * Revisa todas: cada valor y que el color propio venga si se eligió.
+ *
+ * @param {Record<string, string>} answers
+ * @returns {Record<string, string>}
+ */
+export function checkedAnswers(answers) {
+    for (const [key, value] of Object.entries(answers)) {
+        const problem = problemWithAnswer(key, value);
+        if (problem) {
+            throw new CliError(problem);
+        }
+    }
+    if (answers.colors === 'custom' && !answers.primaryColor) {
+        throw new CliError('Con colores propios hace falta el color principal: --primaryColor=#2563EB.');
+    }
+    return answers;
+}
+
+/**
+ * Las opciones que leen las plantillas («//#if pwa»), sacadas de las respuestas.
+ *
+ * @param {Record<string, string>} answers
+ * @returns {Record<string, boolean>}
+ */
+export function templateFlagsOf(answers) {
+    return {
+        auth: answers.auth === 'yes',
+        pwa: answers.pwa === 'yes',
+        i18next: answers.texts === 'i18next',
+        hookForm: answers.forms === 'react-hook-form',
+        darkMode: answers.colorModes === 'lightAndDark',
+    };
+}
+
+/**
+ * El color principal elegido.
+ *
+ * @param {Record<string, string>} answers
+ * @returns {string}
+ */
+export function primaryColorOf(answers) {
+    return answers.colors === 'custom' ? answers.primaryColor.toUpperCase() : PRIMARY_COLOR_OF[answers.colors];
+}

package/cli/projectConfig.js

@@ -0,0 +1,38 @@
+// calcita.json: lo que se eligió al crear el proyecto con «calcita new». Los comandos make:* lo leen para armar igual que el
+// resto del proyecto (los formularios con formik o con react-hook-form). Vive en la raíz del proyecto y se sube al repo.
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+
+import {CliError} from './templateFiles.js';
+
+export const PROJECT_CONFIG_FILE = 'calcita.json';
+
+/**
+ * Lo que se guarda: la librería de formularios (la que leen los make:*) y todas las respuestas, para saber cómo se armó.
+ *
+ * @param {Record<string, string>} answers
+ * @param {string} calcitaVersion
+ * @returns {string} el contenido del archivo
+ */
+export function projectConfigOf(answers, calcitaVersion) {
+    return `${JSON.stringify({forms: answers.forms, createdWithCalcita: calcitaVersion, answers}, null, 4)}\n`;
+}
+
+/**
+ * Lee calcita.json de la carpeta donde se corre el comando.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<{forms: string}>}
+ */
+export async function readProjectConfig(projectRoot) {
+    try {
+        return JSON.parse(await readFile(join(projectRoot, PROJECT_CONFIG_FILE), 'utf8'));
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new CliError(`No encontré ${PROJECT_CONFIG_FILE} aquí. Corra el comando en la carpeta del proyecto (la que armó «calcita new»).`);
+        }
+        throw error;
+    }
+}

package/cli/projectFiles.js

@@ -0,0 +1,126 @@
+// Los tres archivos del proyecto nuevo que cambian demasiado según las respuestas para una plantilla con «//#if»: el
+// package.json (qué librerías pide), calcita.json (projectConfig.js) y el tema (colores, modos y estilo).
+//
+// Funciones puras: function (regla de la casa). Pruebas en projectFiles.test.js.
+import {versionsOf} from './packageVersions.js';
+import {primaryColorOf, templateFlagsOf} from './projectAnswers.js';
+
+// lo que pide toda app con Calcita: React, MUI, el router, los avisos y las máquinas de estados que usa su puerta principal
+const BASE_DEPENDENCIES = Object.freeze([
+    '@emotion/react', '@emotion/styled', '@mui/icons-material', '@mui/material', '@xstate/react', 'react', 'react-dom', 'react-router',
+    'sonner', 'xstate',
+]);
+const HOOK_FORM_DEPENDENCIES = Object.freeze(['@hookform/resolvers', 'react-hook-form']);
+// la cuenta: las llaves de acceso (las pide @stackcraftmx/calcita/account) y el QR de la demostración
+const ACCOUNT_DEPENDENCIES = Object.freeze(['@simplewebauthn/browser', 'qrcode']);
+const DEV_DEPENDENCIES = Object.freeze(['@vitejs/plugin-react', 'vite']);
+
+/** Un objeto con sus llaves en orden alfabético (como los escribe npm). */
+const sortedByKey = (record) => Object.fromEntries(Object.entries(record).sort(([first], [second]) => first.localeCompare(second)));
+
+/**
+ * @param {object} options
+ * @param {string} options.packageName
+ * @param {Record<string, string>} options.answers
+ * @param {{version: string, devDependencies: Record<string, string>}} options.calcitaPackage
+ * @returns {string}
+ */
+export function packageJsonOf({packageName, answers, calcitaPackage}) {
+    const flags = templateFlagsOf(answers);
+    const dependencyNames = [
+        ...BASE_DEPENDENCIES,
+        ...(flags.hookForm ? HOOK_FORM_DEPENDENCIES : []),
+        ...(flags.auth ? ACCOUNT_DEPENDENCIES : []),
+        ...(flags.i18next ? ['i18next'] : []),
+    ];
+    const packageJson = {
+        name: packageName,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        scripts: {dev: 'vite', build: 'vite build', preview: 'vite preview'},
+        dependencies: sortedByKey({'@stackcraftmx/calcita': `^${calcitaPackage.version}`, ...versionsOf(dependencyNames, calcitaPackage)}),
+        devDependencies: sortedByKey(versionsOf([...DEV_DEPENDENCIES], calcitaPackage)),
+        engines: {node: '>=22'},
+    };
+    return `${JSON.stringify(packageJson, null, 4)}\n`;
+}
+
+/**
+ * src/app/appTheme.js con lo elegido.
+ *
+ * @param {Record<string, string>} answers
+ * @returns {string}
+ */
+export function appThemeFileOf(answers) {
+    const flags = templateFlagsOf(answers);
+    const usesStackcraftPalettes = answers.colors !== 'mui';
+    // con vidrio también el minimalista: en Android arranca así
+    const imports = [
+        ...(answers.style === 'minimal' || answers.style === 'glass' ? ['THEME_LOOK'] : []),
+        'createToolkitTheme',
+        ...(answers.style === 'glass' ? ['isAndroidDevice'] : []),
+        ...(usesStackcraftPalettes && flags.darkMode ? ['stackcraftDarkPalette'] : []),
+        ...(usesStackcraftPalettes ? ['stackcraftLightPalette'] : []),
+    ];
+
+    const lines = [
+        '// El tema de la app: el del framework (createToolkitTheme), con los ajustes de cada componente de Calcita.',
+        '//',
+        '// Los colores van por modo de color. De cada color basta el «main»: MUI saca su versión clara, la oscura y el',
+        '// color de la letra encima. El configurador de tema de los ejemplos de Calcita arma este archivo con vista previa.',
+        `import {${imports.join(', ')}} from '@stackcraftmx/calcita';`,
+        '',
+    ];
+
+    if (answers.colors === 'custom') {
+        lines.push(
+            '// el color principal de la app; los demás (éxito, aviso, error) se quedan los de Stackcraft',
+            `const PRIMARY_COLOR = '${primaryColorOf(answers)}';`,
+            '',
+        );
+    }
+    lines.push(...colorSchemesLinesOf(answers.colors, flags.darkMode), '');
+
+    if (answers.style === 'glass') {
+        lines.push(
+            '// vidrio líquido en lo que flota (barra, menús, avisos) y en los controles; el contenido, sólido (guía de Apple).',
+            '// En Android, el minimalista: el vidrio es el estilo de Apple (allá se ve ajeno) y el desenfoque pesa en los teléfonos',
+            '// baratos',
+            'export const appTheme = isAndroidDevice()',
+            '    ? createToolkitTheme({colorSchemes, look: THEME_LOOK.minimal})',
+            '    : createToolkitTheme({colorSchemes, glass: true});',
+            '',
+        );
+        return lines.join('\n');
+    }
+    lines.push('export const appTheme = createToolkitTheme({', '    colorSchemes,');
+    if (answers.style === 'minimal') {
+        lines.push('    // plano y tonal: sin bordes ni sombras, las superficies se separan por su tono', '    look: THEME_LOOK.minimal,');
+    }
+    lines.push('});', '');
+    return lines.join('\n');
+}
+
+/** Los renglones de `colorSchemes` según los colores y los modos. */
+function colorSchemesLinesOf(colors, darkMode) {
+    if (colors === 'mui') {
+        return [
+            '// los colores de MUI tal cual (true: su paleta por omisión)',
+            darkMode ? 'const colorSchemes = {light: true, dark: true};' : '// solo claro: sin el modo oscuro\nconst colorSchemes = {light: true};',
+        ];
+    }
+    if (colors === 'custom') {
+        return darkMode
+            ? [
+                'const colorSchemes = {',
+                '    light: {palette: {...stackcraftLightPalette, primary: {main: PRIMARY_COLOR}}},',
+                '    dark: {palette: {...stackcraftDarkPalette, primary: {main: PRIMARY_COLOR}}},',
+                '};',
+            ]
+            : ['// solo claro: sin el modo oscuro', 'const colorSchemes = {light: {palette: {...stackcraftLightPalette, primary: {main: PRIMARY_COLOR}}}};'];
+    }
+    return darkMode
+        ? ['// los colores de Stackcraft', 'const colorSchemes = {light: {palette: stackcraftLightPalette}, dark: {palette: stackcraftDarkPalette}};']
+        : ['// los colores de Stackcraft, solo claro (sin el modo oscuro)', 'const colorSchemes = {light: {palette: stackcraftLightPalette}};'];
+}

package/cli/screenLabels.js

@@ -0,0 +1,41 @@
+// Los nombres en pantalla (español e inglés) de un módulo o de una pantalla nueva: con --label-es y --label-en, o
+// preguntados en la terminal; sin respuesta, el nombre en palabras («Purchase orders»), para cambiarlo después en su
+// archivo de textos.
+//
+// Funciones de node, sin React: function (regla de la casa).
+import {createInterface} from 'node:readline/promises';
+import {stdin, stdout} from 'node:process';
+
+import {CliError} from './templateFiles.js';
+
+// va dentro de un texto entre comillas en el código: sin comillas ni diagonales
+const SCREEN_LABEL_PATTERN = /^[\p{L}\p{N}][\p{L}\p{N} .,·()-]*$/u;
+
+/**
+ * @param {object} options
+ * @param {string} options.defaultLabel el nombre en palabras
+ * @param {string} [options.labelEs] el de la bandera --label-es
+ * @param {string} [options.labelEn] el de la bandera --label-en
+ * @param {boolean} options.canAsk si se puede preguntar (terminal y sin --yes)
+ * @param {string} options.what «el módulo», «la pantalla»: para la pregunta
+ * @returns {Promise<{es: string, en: string}>}
+ */
+export async function screenLabelsOf({defaultLabel, labelEs, labelEn, canAsk, what}) {
+    const labels = {es: labelEs, en: labelEn};
+    if (canAsk && (!labels.es || !labels.en)) {
+        const terminal = createInterface({input: stdin, output: stdout});
+        try {
+            labels.es ??= (await terminal.question(`¿Cómo se llama ${what} en pantalla, en español? [${defaultLabel}]: `)).trim() || undefined;
+            labels.en ??= (await terminal.question(`¿Y en inglés? [${defaultLabel}]: `)).trim() || undefined;
+        } finally {
+            terminal.close();
+        }
+    }
+    const result = {es: labels.es ?? defaultLabel, en: labels.en ?? defaultLabel};
+    for (const label of Object.values(result)) {
+        if (!SCREEN_LABEL_PATTERN.test(label)) {
+            throw new CliError(`«${label}» no sirve como nombre en pantalla: letras, números, espacios, puntos, comas o guiones (sin comillas).`);
+        }
+    }
+    return result;
+}

package/cli/templateFiles.js

@@ -0,0 +1,186 @@
+// Las plantillas del CLI: archivos tal cual en cli/templates, con dos cosas que se cambian al copiarlos.
+//
+//   1. Los valores: __Name__, __APP_TITLE__… se cambian por el valor que toca (ver la lista de cada comando). Si una
+//      plantilla trae uno que el comando no conoce, truena: un «__Name__» olvidado en el proyecto nuevo no compilaría.
+//   2. Los renglones opcionales: lo que va entre «//#if pwa» y «//#endif» solo se queda si la opción está prendida
+//      («//#if !pwa»: si está apagada). Los renglones de las marcas se quitan; se pueden anidar.
+//
+// Así una plantilla se lee como el archivo que va a salir, sin código que la arme. Los archivos que no terminan en .tpl
+// (los íconos) se copian sin tocar.
+//
+// Funciones de node, sin React: function (regla de la casa). Pruebas en templateFiles.test.js.
+import {mkdir, readdir, readFile, writeFile} from 'node:fs/promises';
+import {dirname, join, relative} from 'node:path';
+
+const TEMPLATE_EXTENSION = '.tpl';
+const IF_MARKER = /^\s*\/\/#if (!?)(\w+)\s*$/;
+const END_MARKER = /^\s*\/\/#endif\s*$/;
+const LEFTOVER_VALUE = /__[A-Za-z]+(?:_[A-Za-z]+)*__/;
+// npm no publica los archivos que se llaman .gitignore: en la plantilla van como dot-gitignore.tpl
+const DOT_FILE_PREFIX = 'dot-';
+
+/**
+ * Error que se le explica a la persona (sin el detalle técnico de dónde tronó): un nombre que ya existe, un archivo que no
+ * está. Lo demás es un error del CLI y sale completo.
+ */
+export class CliError extends Error {}
+
+/**
+ * @param {string} text el contenido de la plantilla
+ * @param {{values?: Record<string, string>, flags?: Record<string, boolean>}} [options]
+ * @returns {string}
+ */
+export function renderTemplate(text, {values = {}, flags = {}} = {}) {
+    const keptLines = [];
+    // lo que dice cada «//#if» abierto: si su parte se queda
+    const openConditions = [];
+    for (const line of text.split('\n')) {
+        const ifMatch = IF_MARKER.exec(line);
+        if (ifMatch) {
+            const [, negation, flagName] = ifMatch;
+            if (!(flagName in flags)) {
+                throw new Error(`La plantilla pregunta por «${flagName}», que el comando no conoce`);
+            }
+            openConditions.push(negation ? !flags[flagName] : Boolean(flags[flagName]));
+            continue;
+        }
+        if (END_MARKER.test(line)) {
+            if (openConditions.length === 0) {
+                throw new Error('La plantilla trae un «//#endif» de más');
+            }
+            openConditions.pop();
+            continue;
+        }
+        if (openConditions.every(Boolean)) {
+            keptLines.push(line);
+        }
+    }
+    if (openConditions.length > 0) {
+        throw new Error('A la plantilla le falta un «//#endif»');
+    }
+
+    let rendered = keptLines.join('\n');
+    for (const [name, value] of Object.entries(values)) {
+        rendered = rendered.replaceAll(`__${name}__`, value);
+    }
+    const leftover = LEFTOVER_VALUE.exec(rendered);
+    if (leftover) {
+        throw new Error(`La plantilla trae «${leftover[0]}» y el comando no le dio valor`);
+    }
+    return rendered;
+}
+
+/**
+ * El nombre con que sale un archivo: sin .tpl, con sus valores (__Name__Page.jsx → ContactsPage.jsx) y dot-gitignore
+ * como .gitignore.
+ *
+ * @param {string} relativePath
+ * @param {Record<string, string>} values
+ * @returns {string}
+ */
+export function outputPathOf(relativePath, values) {
+    let outputPath = relativePath.endsWith(TEMPLATE_EXTENSION) ? relativePath.slice(0, -TEMPLATE_EXTENSION.length) : relativePath;
+    for (const [name, value] of Object.entries(values)) {
+        outputPath = outputPath.replaceAll(`__${name}__`, value);
+    }
+    return outputPath.split('/').map((part) => (part.startsWith(DOT_FILE_PREFIX) ? `.${part.slice(DOT_FILE_PREFIX.length)}` : part)).join('/');
+}
+
+/**
+ * Los archivos de una carpeta de plantillas, con su ruta relativa (con «/» también en Windows).
+ *
+ * @param {string} folder
+ * @returns {Promise<string[]>}
+ */
+export async function templateFilesOf(folder) {
+    const entries = await readdir(folder, {recursive: true, withFileTypes: true});
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(folder, join(entry.parentPath, entry.name)).split('\\').join('/'))
+        .sort();
+}
+
+/**
+ * Escribe un archivo nuevo; si ya existe, truena sin tocarlo (el CLI nunca pisa lo que ya escribió alguien).
+ *
+ * @param {string} path
+ * @param {string|Buffer} content
+ */
+export async function writeNewFile(path, content) {
+    await mkdir(dirname(path), {recursive: true});
+    try {
+        await writeFile(path, content, {flag: 'wx'});
+    } catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new CliError(`Ya existe ${path}; no se tocó nada de ese archivo.`);
+        }
+        throw error;
+    }
+}
+
+/**
+ * Copia una carpeta de plantillas a su destino: las .tpl con sus valores y sus renglones opcionales, lo demás tal cual.
+ *
+ * @param {object} options
+ * @param {string} options.templateFolder
+ * @param {string} options.targetFolder
+ * @param {Record<string, string>} options.values
+ * @param {Record<string, boolean>} [options.flags]
+ * @param {(relativePath: string) => boolean} [options.includes] cuáles se copian; por omisión todas
+ * @returns {Promise<string[]>} las rutas escritas, relativas al destino
+ */
+export async function copyTemplateFolder({templateFolder, targetFolder, values, flags = {}, includes = () => true}) {
+    const written = [];
+    for (const relativePath of await templateFilesOf(templateFolder)) {
+        if (!includes(relativePath)) {
+            continue;
+        }
+        const outputPath = outputPathOf(relativePath, values);
+        const source = await readFile(join(templateFolder, relativePath));
+        const content = relativePath.endsWith(TEMPLATE_EXTENSION) ? renderTemplate(source.toString('utf8'), {values, flags}) : source;
+        await writeNewFile(join(targetFolder, outputPath), content);
+        written.push(outputPath);
+    }
+    return written;
+}
+
+/**
+ * Agrega un renglón al final de un arreglo exportado («export const routes = [ … ];»), antes de su «];». Regresa null si no
+ * encuentra el arreglo con esa forma (alguien lo cambió): entonces el comando le dice a la persona qué renglón poner.
+ *
+ * @param {string} text el archivo
+ * @param {string} declaration p. ej. 'export const routes = ['
+ * @param {string} line el renglón completo, con su sangría
+ * @returns {string|null}
+ */
+export function insertIntoArray(text, declaration, line) {
+    const start = text.indexOf(declaration);
+    if (start < 0) {
+        return null;
+    }
+    // el «];» que cierra el arreglo: el primero al inicio de un renglón después de la declaración
+    const end = text.indexOf('\n];', start);
+    if (end < 0) {
+        return null;
+    }
+    return `${text.slice(0, end)}\n${line}${text.slice(end)}`;
+}
+
+/**
+ * Agrega un renglón después del último que cumple la regla (p. ej. después de la última «export const …_PATH»). Regresa null
+ * si ninguno la cumple.
+ *
+ * @param {string} text
+ * @param {RegExp} pattern con la bandera m (renglón por renglón)
+ * @param {string} line
+ * @returns {string|null}
+ */
+export function insertAfterLastMatch(text, pattern, line) {
+    const matches = [...text.matchAll(new RegExp(pattern.source, `${pattern.flags.replace('g', '')}g`))];
+    if (matches.length === 0) {
+        return null;
+    }
+    const lastMatch = matches.at(-1);
+    const lineEnd = lastMatch.index + lastMatch[0].length;
+    return `${text.slice(0, lineEnd)}\n${line}${text.slice(lineEnd)}`;
+}

package/cli/templates/component/core/__ComponentName__.jsx.tpl

@@ -0,0 +1,23 @@
+// __ComponentName__: lo armó el CLI de Calcita (make:component) con un título y su contenido; cámbielo a lo que pida. Vive
+// en core porque lo usan dos o más módulos: se importa de '@/core'.
+//
+// Genérico y sin estado: function (regla de la casa). Recibe los textos ya traducidos.
+import Paper from '@mui/material/Paper';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+
+/**
+ * @param {object} props
+ * @param {string} props.title ya traducido
+ * @param {import('react').ReactNode} [props.children]
+ */
+export function __ComponentName__({title, children}) {
+    return (
+        <Paper variant="outlined" sx={{p: 2}}>
+            <Stack spacing={1}>
+                <Typography variant="subtitle2" component="h3">{title}</Typography>
+                {children}
+            </Stack>
+        </Paper>
+    );
+}

package/cli/templates/component/module/__ComponentName__.jsx.tpl

@@ -0,0 +1,21 @@
+// __ComponentName__ de __module__: lo armó el CLI de Calcita (make:component) con un título y su contenido; cámbielo a lo
+// que pida. Es solo de este módulo; si otro módulo lo necesita, sube a src/core.
+//
+// Lo renderiza la app: arrow (regla de la casa).
+import Paper from '@mui/material/Paper';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+
+/**
+ * @param {object} props
+ * @param {string} props.title ya traducido
+ * @param {import('react').ReactNode} [props.children]
+ */
+export const __ComponentName__ = ({title, children}) => (
+    <Paper variant="outlined" sx={{p: 2}}>
+        <Stack spacing={1}>
+            <Typography variant="subtitle2" component="h3">{title}</Typography>
+            {children}
+        </Stack>
+    </Paper>
+);

package/cli/templates/form/formik/__FormName__.jsx.tpl

@@ -0,0 +1,50 @@
+// __FormName__ (formik + yup): las reglas en __formName__Schema.js y los textos en __formName__Texts.js.
+//
+// La pantalla dice qué hacer con los datos (onSubmit). Si el servidor dice que no (RFC 9457), el aviso sale arriba del
+// formulario y lo de cada campo, en su campo (applyServerProblem). Al guardar, el formulario se vacía y avisa (onSaved).
+//
+// Lo renderiza la app: arrow (regla de la casa).
+import {useMemo} from 'react';
+import Stack from '@mui/material/Stack';
+import {useToolkitTranslation} from '@stackcraftmx/calcita';
+import {Form, FormProblemAlert, FormTextField, Formik, SubmitButton, applyServerProblem} from '@stackcraftmx/calcita/forms';
+
+import {__FORM_NAME___INITIAL_VALUES, build__FormName__Schema} from '@/modules/__module__/__formName__Schema.js';
+
+// los renglones de las notas al abrir
+const NOTES_MIN_ROWS = 3;
+
+/**
+ * @param {object} props
+ * @param {(values: {name: string, notes: string}) => Promise<{message: string}>} props.onSubmit guarda; truena con el
+ *     ApiError si el servidor dice que no
+ * @param {(message: string) => void} [props.onSaved] ya se guardó: el aviso del servidor
+ */
+export const __FormName__ = ({onSubmit, onSaved}) => {
+    const {t} = useToolkitTranslation('__module__');
+    // el esquema se arma al pintar: yup toma sus mensajes al armarlo
+    const schema = useMemo(() => build__FormName__Schema(), []);
+
+    const submit = async (values, formikHelpers) => {
+        try {
+            const response = await onSubmit(values);
+            formikHelpers.resetForm();
+            onSaved?.(response.message);
+        } catch (error) {
+            applyServerProblem(error, {...formikHelpers, values});
+        }
+    };
+
+    return (
+        <Formik initialValues={__FORM_NAME___INITIAL_VALUES} validationSchema={schema} onSubmit={submit}>
+            <Form noValidate>
+                <Stack spacing={2}>
+                    <FormProblemAlert />
+                    <FormTextField name="name" label={t('__formName__.name')} />
+                    <FormTextField name="notes" label={t('__formName__.notes')} helperText={t('__formName__.notesHelp')} multiline minRows={NOTES_MIN_ROWS} />
+                    <SubmitButton sx={{alignSelf: 'flex-start'}}>{t('__formName__.submit')}</SubmitButton>
+                </Stack>
+            </Form>
+        </Formik>
+    );
+};