@team-codeme/crud-forge 0.0.0-stage → 1.0.0

package/src/config/env-refs.js

@@ -0,0 +1,71 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read a named environment variable. Never log the value.
+ * @param {string} name
+ * @returns {string|undefined}
+ */
+function resolveEnv(name) {
+  if (name == null || name === '') {
+    return undefined;
+  }
+  const value = process.env[String(name)];
+  return value;
+}
+
+/**
+ * Parse KEY=VALUE lines from a dotenv-style file.
+ * Existing process.env keys are not overridden. Values are never logged.
+ * @param {string} filePath
+ */
+function loadEnvFile(filePath) {
+  if (filePath == null || String(filePath).trim() === '') {
+    throw new Error('loadEnvFile requires a file path.');
+  }
+
+  const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Env file not found: ${resolved}`);
+  }
+
+  const content = fs.readFileSync(resolved, 'utf8');
+  const lines = content.split(/\r?\n/);
+
+  for (const rawLine of lines) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    if (line.startsWith('export ')) {
+      line = line.slice('export '.length).trim();
+    }
+
+    const eq = line.indexOf('=');
+    if (eq <= 0) {
+      continue;
+    }
+
+    const key = line.slice(0, eq).trim();
+    if (!key) {
+      continue;
+    }
+
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+      (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+module.exports = {
+  resolveEnv,
+  loadEnvFile,
+};

package/src/config/field-preferences.js

@@ -0,0 +1,99 @@
+const TEXT_TYPES = new Set(['String', 'TextBlob']);
+const FORMATS = new Set(['uppercase', 'lowercase', 'none']);
+const AUDIT_NAMES = ['createdBy', 'createdDate', 'lastModifiedBy', 'lastModifiedDate'];
+/** Backend plumbing columns — never rendered in generated UI by default. */
+const TECHNICAL_NAMES = ['debug', 'refType', 'refId'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function auditFieldNames(config) {
+  return config?.fields?.audit?.names || AUDIT_NAMES;
+}
+
+function technicalFieldNames(config) {
+  if (config?.fields?.technical?.enabled === false) {
+    return [];
+  }
+  return config?.fields?.technical?.names || TECHNICAL_NAMES;
+}
+
+function isTechnicalField(fieldName, config) {
+  return technicalFieldNames(config).includes(fieldName);
+}
+
+function isNonEditableSystemField(fieldName, config) {
+  return auditFieldNames(config).includes(fieldName) || isTechnicalField(fieldName, config);
+}
+
+/**
+ * Whether a field should be omitted from a generated UI surface.
+ * Technical fields are always hidden when enabled. Audit fields follow
+ * fields.audit.hideIn* / showInDetail (lists keep separate defaultHidden handling).
+ */
+function isHiddenFromUi(fieldName, config, surface = 'lists') {
+  if (isTechnicalField(fieldName, config)) {
+    return true;
+  }
+  const audit = config?.fields?.audit || {};
+  if (!auditFieldNames(config).includes(fieldName)) {
+    return false;
+  }
+  switch (surface) {
+    case 'forms':
+      return audit.hideInForms !== false;
+    case 'filters':
+      return audit.hideInFilters !== false;
+    case 'search':
+      return audit.hideInSearch !== false;
+    case 'detail':
+      return audit.showInDetail === false;
+    case 'cards':
+    case 'lists':
+      // Cards show audit; lists emit audit as defaultHidden columns.
+      // Technical fields are already excluded above.
+      return false;
+    default:
+      return false;
+  }
+}
+
+function validateFieldPreferences(config, entities, file = 'fields configuration') {
+  const fail = (key, message) => { throw new Error(`Invalid configuration "${file}": ${key} ${message}`); };
+  const configured = config.fields?.entities;
+  if (configured === undefined) return;
+  if (!object(configured)) fail('fields.entities', 'must be an object keyed by GDL/JDL entity name.');
+  for (const [entityName, entityOptions] of Object.entries(configured)) {
+    const prefix = `fields.entities.${entityName}`;
+    if (!object(entityOptions) || !object(entityOptions.fields)) fail(prefix, 'must contain a fields object.');
+    const entity = entities?.find(item => item.name === entityName);
+    if (entities && !entity) fail(prefix, 'references an unknown entity. Use its exact GDL/JDL name.');
+    for (const [fieldName, options] of Object.entries(entityOptions.fields)) {
+      const key = `${prefix}.fields.${fieldName}.inputFormat`;
+      if (!object(options) || !FORMATS.has(options.inputFormat)) fail(key, 'must be uppercase, lowercase, or none.');
+      if (entity) {
+        const field = entity.fields.find(item => item.fieldName === fieldName);
+        if (!field) fail(key, 'references an unknown field. Check the GDL/JDL field name.');
+        if (!TEXT_TYPES.has(field.fieldType) || field.fieldTypeIsEnum || fieldName === 'id' || isNonEditableSystemField(fieldName, config)) {
+          fail(key, `is incompatible with ${field.fieldType} field ${fieldName}. Configure only editable String or TextBlob fields, excluding IDs, audit, and technical fields.`);
+        }
+      }
+    }
+  }
+}
+
+function entityFieldSettings(config, entity) {
+  return Object.fromEntries(entity.fields.filter(field => TEXT_TYPES.has(field.fieldType) && !field.fieldTypeIsEnum && !isNonEditableSystemField(field.fieldName, config)).map(field => [field.fieldName, {
+    inputFormat: config.fields?.entities?.[entity.name]?.fields?.[field.fieldName]?.inputFormat ?? (config.formBehavior?.uppercaseInputs ? 'uppercase' : 'none'),
+  }]));
+}
+
+module.exports = {
+  AUDIT_NAMES,
+  TECHNICAL_NAMES,
+  auditFieldNames,
+  technicalFieldNames,
+  isTechnicalField,
+  isHiddenFromUi,
+  isNonEditableSystemField,
+  validateFieldPreferences,
+  entityFieldSettings,
+};

package/src/config/input-sources.js

@@ -0,0 +1,104 @@
+const path = require('path');
+const _ = require('lodash');
+
+/**
+ * Resolve schema input(s) from config.
+ *
+ * Supports:
+ *   input.file              — legacy single GDL/JDL
+ *   input.sources[]         — multiple files, each with a service name
+ *
+ * @returns {{ name: string, file: string, type: string, microservice: string, folder: string }[]}
+ */
+function resolveInputSources(config = {}, projectRoot = process.cwd()) {
+  const input = config.input || {};
+  const defaultType = String(input.type || '').toLowerCase();
+  const globalMs = String(config.api?.microservice || '').trim();
+  const sources = Array.isArray(input.sources) ? input.sources : [];
+
+  if (sources.length) {
+    return sources.map((raw, index) => {
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`input.sources[${index}] must be an object with name and file.`);
+      }
+      const name = String(raw.name || raw.service || '').trim();
+      const fileRaw = String(raw.file || raw.path || '').trim();
+      if (!name) {
+        throw new Error(`input.sources[${index}].name is required (service / module label).`);
+      }
+      if (!fileRaw) {
+        throw new Error(`input.sources[${index}].file is required.`);
+      }
+      const file = path.isAbsolute(fileRaw) ? fileRaw : path.resolve(projectRoot, fileRaw);
+      const ext = path.extname(file).slice(1).toLowerCase();
+      const type = String(raw.type || ext || defaultType || 'gdl').toLowerCase();
+      if (!['gdl', 'jdl'].includes(type)) {
+        throw new Error(`input.sources[${index}].type must be gdl or jdl (got "${type}").`);
+      }
+      if (ext && ext !== type) {
+        throw new Error(`input.sources[${index}]: file extension .${ext} does not match type ${type}.`);
+      }
+      const microservice = String(raw.microservice || raw.serviceId || globalMs || '').trim();
+      const folder = String(raw.folder || _.kebabCase(name)).trim();
+      if (!folder || /[\\/]/.test(folder) || ['.', '..'].includes(folder)) {
+        throw new Error(`input.sources[${index}].folder must be a single folder name.`);
+      }
+      return { name, file, type, microservice, folder };
+    });
+  }
+
+  const fileRaw = String(input.file || '').trim();
+  if (!fileRaw) {
+    return [];
+  }
+  const file = path.isAbsolute(fileRaw) ? fileRaw : path.resolve(projectRoot, fileRaw);
+  const ext = path.extname(file).slice(1).toLowerCase();
+  const type = String(defaultType || ext || 'jdl').toLowerCase();
+  const isGdl = type === 'gdl' || ext === 'gdl';
+  const folder =
+    String(config.fuse?.folderType || '').trim() || (isGdl ? 'micro-functions' : 'microservice');
+  return [
+    {
+      name: folder === 'micro-functions' ? 'Micro Functions' : folder === 'microservice' ? 'Microservice' : folder,
+      file,
+      type,
+      microservice: globalMs,
+      folder,
+    },
+  ];
+}
+
+function validateInputSourcesConfig(config, fail) {
+  const sources = config?.input?.sources;
+  if (sources === undefined) {
+    return;
+  }
+  if (!Array.isArray(sources)) {
+    fail('input.sources must be an array of { name, file, microservice? } objects.');
+  }
+  const names = new Set();
+  const folders = new Set();
+  sources.forEach((src, index) => {
+    if (!src || typeof src !== 'object' || Array.isArray(src)) {
+      fail(`input.sources[${index}] must be an object.`);
+      return;
+    }
+    const name = String(src.name || src.service || '').trim();
+    const file = String(src.file || src.path || '').trim();
+    if (!name) fail(`input.sources[${index}].name is required.`);
+    if (!file) fail(`input.sources[${index}].file is required.`);
+    if (names.has(name.toLowerCase())) fail(`input.sources[${index}].name "${name}" is duplicated.`);
+    names.add(name.toLowerCase());
+    const folder = String(src.folder || _.kebabCase(name)).trim();
+    if (folders.has(folder.toLowerCase())) fail(`input.sources[${index}] folder "${folder}" collides with another source.`);
+    folders.add(folder.toLowerCase());
+    if (src.type != null && !['gdl', 'jdl'].includes(String(src.type).toLowerCase())) {
+      fail(`input.sources[${index}].type must be gdl or jdl.`);
+    }
+  });
+}
+
+module.exports = {
+  resolveInputSources,
+  validateInputSourcesConfig,
+};

package/src/config/load-config.js

@@ -0,0 +1,166 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { parse: parseYaml } = require('yaml');
+const _ = require('lodash');
+const defaultValues = require('./default-values');
+const { deriveAuthUrls } = require('./auth-config');
+
+/**
+ * Searches for a configuration file in the project.
+ * Priority: 
+ * 1. Custom path if provided
+ * 2. config/crudforge.config.yml (generated Fuse apps)
+ * 3. crudforge.config.yml / crudforge.config.yaml (repo root)
+ * 4. config/config.yml
+ * 5. crudforge.config.json
+ */
+async function loadConfig(cwd = process.cwd(), customPath = null, options = {}) {
+  let rawConfig = {};
+  let matchedPath = null;
+
+  const candidates = customPath 
+    ? [customPath]
+    : [
+        'config/crudforge.config.yml',
+        'config/crudforge.config.yaml',
+        'crudforge.config.yml',
+        'crudforge.config.yaml',
+        'config/config.yml',
+        'crudforge.config.json'
+      ];
+
+  for (const candidate of candidates) {
+    const resolved = path.isAbsolute(candidate) ? candidate : path.join(cwd, candidate);
+    if (await fs.pathExists(resolved)) {
+      matchedPath = resolved;
+      try {
+        const fileContent = await fs.readFile(resolved, 'utf8');
+        if (resolved.endsWith('.json')) {
+          rawConfig = JSON.parse(fileContent);
+        } else {
+          rawConfig = parseYaml(fileContent);
+        }
+      } catch (err) {
+        throw new Error(`Invalid configuration "${resolved}": ${err.message}. Fix this file and retry.`);
+      }
+      validateConfig(rawConfig, resolved);
+      break;
+    }
+  }
+
+  if (!matchedPath && (customPath || options.required)) {
+    throw new Error(`Configuration not found: ${path.resolve(cwd, customPath || 'config/crudforge.config.yml')}. Run "crudforge init <directory>" or specify --preferences <file>.`);
+  }
+  const projectRoot = options.projectPaths && matchedPath
+    ? (path.basename(path.dirname(matchedPath)) === 'config' ? path.dirname(path.dirname(matchedPath)) : path.dirname(matchedPath))
+    : cwd;
+
+  // Deep merge default configurations with custom ones
+  const config = _.mergeWith({}, defaultValues, rawConfig, (_current, incoming) =>
+    Array.isArray(incoming) ? incoming.slice() : undefined);
+
+  if (config.auth) {
+    deriveAuthUrls(config.auth);
+  }
+
+  // Normalize absolute paths (single file + multi-source list)
+  if (config.input && config.input.file) {
+    config.input.file = path.isAbsolute(config.input.file)
+      ? config.input.file
+      : path.resolve(projectRoot, config.input.file);
+  }
+  if (Array.isArray(config.input?.sources)) {
+    config.input.sources = config.input.sources.map((src) => {
+      if (!src || typeof src !== 'object') return src;
+      const next = { ...src };
+      if (next.file && !path.isAbsolute(next.file)) {
+        next.file = path.resolve(projectRoot, next.file);
+      }
+      if (next.path && !path.isAbsolute(next.path)) {
+        next.path = path.resolve(projectRoot, next.path);
+      }
+      return next;
+    });
+  }
+
+  if (config.output && config.output.directory) {
+    config.output.directory = path.isAbsolute(config.output.directory)
+      ? config.output.directory
+      : path.resolve(projectRoot, config.output.directory);
+  }
+
+  if (rawConfig.fuse?.starterPackPath) config.fuse.starterPackPath = path.resolve(projectRoot, rawConfig.fuse.starterPackPath);
+
+  Object.defineProperty(config, '_configPath', { value: matchedPath, enumerable: false });
+  return {
+    config,
+    configPath: matchedPath,
+    projectRoot
+  };
+}
+
+function validateConfig(config, file) {
+  const fail = message => { throw new Error(`Invalid configuration "${file}": ${message}`); };
+  if (config?.doctor?.timeoutMs !== undefined && (!Number.isInteger(config.doctor.timeoutMs) || config.doctor.timeoutMs < 100 || config.doctor.timeoutMs > 10000)) fail('doctor.timeoutMs must be 100–10000 milliseconds.');
+  if (config?.doctor?.endpoints !== undefined && (!Array.isArray(config.doctor.endpoints) || config.doctor.endpoints.some(e => !e || typeof e.url !== 'string' || typeof e.description !== 'string' || !e.description.trim()))) fail('doctor.endpoints requires url and a description of each documented read-only endpoint.');
+  const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (!isObject(config)) fail('expected a YAML/JSON object.');
+  function check(values, defaults, prefix = '') {
+    for (const [key, value] of Object.entries(values)) {
+      const name = prefix + key;
+      if (!(key in defaults)) continue;
+      const expected = defaults[key];
+      if (Array.isArray(expected)) {
+        if (!Array.isArray(value)) fail(`${name} must be an array.`);
+      } else if (isObject(expected)) {
+        if (!isObject(value)) fail(`${name} must be an object.`);
+        check(value, expected, name + '.');
+      } else if (expected !== null && typeof value !== typeof expected) {
+        fail(`${name} must be ${typeof expected}.`);
+      }
+    }
+  }
+  check(config, defaultValues);
+  require('./input-sources').validateInputSourcesConfig(config, fail);
+  require('./field-preferences').validateFieldPreferences(config, undefined, file);
+  if (config.proxy?.routes !== undefined) {
+    require('./proxy-routes').validateProxyRoutes(config.proxy.routes, `${file}: proxy.routes`);
+  }
+  if (config.devServer?.port !== undefined && (!Number.isInteger(config.devServer.port) || config.devServer.port < 1 || config.devServer.port > 65535)) {
+    fail('devServer.port must be an integer between 1 and 65535.');
+  }
+  const enums = [
+    ['input', 'type', ['gdl', 'jdl']],
+    ['output', 'overwritePolicy', ['fail', 'ask', 'skip', 'merge', 'overwrite']],
+    ['output', 'structure', ['entity-folder', 'shared-central']],
+    ['fuse', 'rendering', ['spa', 'ssr']],
+    ['auth', 'provider', ['none', 'keycloak']],
+    ['proxy', 'write', ['both', 'dev', 'prod', 'development', 'production']],
+  ];
+  for (const [section, key, choices] of enums) {
+    if (config[section]?.[key] !== undefined && !choices.includes(config[section][key])) {
+      fail(`${section}.${key} must be one of: ${choices.join(', ')}.`);
+    }
+  }
+  if (config.output?.directory !== undefined && !config.output.directory.trim()) fail('output.directory must not be empty.');
+  if (config.fuse?.starterPackPath !== undefined && typeof config.fuse.starterPackPath !== 'string') fail('fuse.starterPackPath must be a string.');
+  if (config.fuse?.includePrebuilt !== undefined && typeof config.fuse.includePrebuilt !== 'boolean') fail('fuse.includePrebuilt must be a boolean.');
+  if (config.fuse?.ssrAllowedHosts !== undefined && (!Array.isArray(config.fuse.ssrAllowedHosts) || config.fuse.ssrAllowedHosts.some(host => typeof host !== 'string' || !host.trim()))) fail('fuse.ssrAllowedHosts must be an array of non-empty host strings.');
+  if (config.fuse?.folderType && (/[\\/]/.test(config.fuse.folderType) || ['.', '..'].includes(config.fuse.folderType))) {
+    fail('fuse.folderType must be a single folder name.');
+  }
+  for (const [name, service] of Object.entries(config.api?.services || {})) {
+    if (typeof service !== 'string' && !isObject(service)) fail(`api.services.${name} must be a URL or service configuration object.`);
+    if (isObject(service)) {
+      for (const key of ['prod', 'dev', 'target', 'url', 'pathRewrite']) {
+        if (service[key] !== undefined && typeof service[key] !== 'string') fail(`api.services.${name}.${key} must be a string.`);
+      }
+      if (!['prod', 'dev', 'target', 'url'].some(key => service[key]?.trim())) fail(`api.services.${name} needs a prod, dev, target, or url target.`);
+    }
+  }
+}
+
+module.exports = {
+  loadConfig,
+  validateConfig
+};

package/src/config/proxy-routes.js

@@ -0,0 +1,44 @@
+const ALLOWED = new Set(['target', 'secure', 'changeOrigin', 'ws', 'logLevel', 'pathRewrite']);
+
+function validateProxyRoutes(routes, label = 'proxy.routes') {
+  if (!routes || typeof routes !== 'object' || Array.isArray(routes)) throw new Error(`${label} must be an object.`);
+  for (const [route, entry] of Object.entries(routes)) {
+    if (!route.startsWith('/') || /[\s?#]/.test(route)) throw new Error(`${label}: invalid route ${route}.`);
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error(`${label}.${route} must be an object.`);
+    for (const key of Object.keys(entry)) {
+      if (!ALLOWED.has(key)) throw new Error(`${label}.${route}: unsupported option ${key}.`);
+    }
+    let url;
+    try { url = new URL(entry.target); } catch { throw new Error(`${label}.${route}: target must be an absolute HTTP(S) URL.`); }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+      throw new Error(`${label}.${route}: target must be an HTTP(S) URL without credentials, query, or fragment.`);
+    }
+    for (const key of ['secure', 'changeOrigin', 'ws']) {
+      if (entry[key] !== undefined && typeof entry[key] !== 'boolean') throw new Error(`${label}.${route}.${key} must be boolean.`);
+    }
+    if (entry.logLevel !== undefined && !['debug', 'info', 'warn', 'error', 'silent'].includes(entry.logLevel)) throw new Error(`${label}.${route}: invalid logLevel.`);
+    if (entry.pathRewrite !== undefined) {
+      if (!entry.pathRewrite || typeof entry.pathRewrite !== 'object' || Array.isArray(entry.pathRewrite)) throw new Error(`${label}.${route}.pathRewrite must be an object.`);
+      for (const [pattern, replacement] of Object.entries(entry.pathRewrite)) {
+        try { new RegExp(pattern); } catch { throw new Error(`${label}.${route}: invalid rewrite pattern.`); }
+        if (typeof replacement !== 'string' || (replacement !== '' && !replacement.startsWith('/')) || /[?#\r\n]/.test(replacement)) {
+          throw new Error(`${label}.${route}: rewrite must be an empty string or a URL path.`);
+        }
+      }
+    }
+  }
+}
+
+// Do not import auth headers, cookies, credentials, bypass code, or other proxy hooks.
+function sanitizeProxyRoutes(routes, label) {
+  const clean = {};
+  if (!routes || typeof routes !== 'object' || Array.isArray(routes)) throw new Error(`${label}: expected a proxy object.`);
+  for (const [route, entry] of Object.entries(routes)) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error(`${label}: invalid entry ${route}.`);
+    clean[route] = Object.fromEntries(Object.entries(entry).filter(([key]) => ALLOWED.has(key)));
+  }
+  validateProxyRoutes(clean, label);
+  return clean;
+}
+
+module.exports = { validateProxyRoutes, sanitizeProxyRoutes };