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

package/src/generator/embed-config.js

@@ -0,0 +1,431 @@
+const path = require('path');
+const YAML = require('yaml');
+const { stripSecretsForGenerate } = require('../config/auth-config');
+
+/**
+ * Build a config object safe to embed in the generated Fuse root.
+ * Drops secrets, absolute starter pack paths, and dry-run bookkeeping.
+ */
+function buildEmbeddableConfig(config = {}) {
+  const copy = JSON.parse(JSON.stringify(config));
+
+  delete copy.dryRun;
+  if (copy.fuse) {
+    delete copy.fuse.starterPackPath;
+  }
+  if (copy.auth) {
+    copy.auth = stripSecretsForGenerate(copy.auth);
+    delete copy.auth.clientSecret;
+  }
+  if (copy.output && copy.output.directory) {
+    // Generated apps keep config relative to themselves.
+    copy.output.directory = '.';
+  }
+  if (copy.input?.file && path.isAbsolute(copy.input.file)) {
+    copy.input.file = path.relative(config.output.directory, copy.input.file);
+  }
+  if (Array.isArray(copy.input?.sources)) {
+    copy.input.sources = copy.input.sources.map((src) => {
+      if (!src || typeof src !== 'object') return src;
+      const next = { ...src };
+      if (next.file && path.isAbsolute(next.file)) {
+        next.file = path.relative(config.output.directory, next.file);
+      }
+      if (next.path && path.isAbsolute(next.path)) {
+        next.path = path.relative(config.output.directory, next.path);
+      }
+      return next;
+    });
+  }
+  return copy;
+}
+
+function formatLocalTimestamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, '0');
+  const offsetMin = -date.getTimezoneOffset();
+  const sign = offsetMin >= 0 ? '+' : '-';
+  const abs = Math.abs(offsetMin);
+  const offH = pad(Math.floor(abs / 60));
+  const offM = pad(abs % 60);
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())} ` +
+    `(UTC${sign}${offH}:${offM})`
+  );
+}
+
+function pick(source, keys) {
+  const out = {};
+  for (const key of keys) {
+    if (source && Object.prototype.hasOwnProperty.call(source, key) && source[key] !== undefined) {
+      out[key] = source[key];
+    }
+  }
+  return out;
+}
+
+function dumpSection(obj) {
+  if (!obj || !Object.keys(obj).length) {
+    return '';
+  }
+  return YAML.stringify(obj, {
+    lineWidth: 100,
+    singleQuote: false,
+    defaultKeyType: 'PLAIN',
+    defaultStringType: 'QUOTE_DOUBLE',
+  }).trimEnd();
+}
+
+/**
+ * Human-readable embedded config: dated header, section comments, spacing.
+ */
+function formatEmbeddableYaml(config, generatedAt = new Date()) {
+  const iso = generatedAt.toISOString();
+  const local = formatLocalTimestamp(generatedAt);
+  const c = buildEmbeddableConfig(config);
+
+  const lines = [];
+  const push = (...chunks) => {
+    for (const chunk of chunks) {
+      lines.push(chunk);
+    }
+  };
+  const blank = () => lines.push('');
+
+  push(
+    '# =============================================================================',
+    '# CRUDForge configuration (generated under config/)',
+    '# -----------------------------------------------------------------------------',
+    '# Generated by @crudforge/cli (crudforge generate)',
+    `# Generated at : ${local}`,
+    `# ISO / UTC    : ${iso}`,
+    '# Path         : config/crudforge.config.yml',
+    '# Keep this file with the app. Re-run generate to refresh it.',
+    '# Secrets (passwords, client secrets) stay in environment / .env.qa — never here.',
+    '# Agent maps   : AGENT_README.md and docs/ai/ (GO-DUCK-style).',
+    '# =============================================================================',
+    ''
+  );
+
+  push(
+    '# --- Meta --------------------------------------------------------------------',
+    dumpSection({
+      meta: {
+        generatedAt: iso,
+        generatedAtLocal: local,
+        generator: '@crudforge/cli',
+      },
+    })
+  );
+  blank();
+
+  if (c.input) {
+    push('# --- Schema input (relative to project root) ---------------------------------', dumpSection({ input: c.input }));
+    blank();
+  }
+
+  push(
+    '# --- Project -----------------------------------------------------------------',
+    '# name / description appear in the UI. repositoryUrl (optional) triggers',
+    '# git init + origin remote on generate (never pushes).',
+    dumpSection({
+      project: {
+        name: c.project?.name || 'CRUDForge App',
+        description: c.project?.description || '',
+        repositoryUrl: c.project?.repositoryUrl || '',
+      },
+    })
+  );
+  blank();
+
+  push(
+    '# --- Output ------------------------------------------------------------------',
+    '# Canonical config path in the generated app: config/crudforge.config.yml',
+    '# directory "." means the Fuse app root (this file lives under config/).',
+    '# teamPack seeds .cursor/agents, .codex/agents, .agents (Antigravity), and .vscode/extensions.',
+    '# aiDocs seeds AGENT_README.md + docs/ai/* (GO-DUCK-style agent maps).',
+    dumpSection({
+      output: {
+        directory: '.',
+        structure: c.output?.structure || 'entity-folder',
+        overwritePolicy: c.output?.overwritePolicy || 'overwrite',
+        embedConfig: c.output?.embedConfig !== false,
+        teamPack: {
+          enabled: c.output?.teamPack?.enabled !== false,
+          cursorAgents: c.output?.teamPack?.cursorAgents !== false,
+          codexAgents: c.output?.teamPack?.codexAgents !== false,
+          antigravityAgents: c.output?.teamPack?.antigravityAgents !== false,
+          vscodeExtensions: c.output?.teamPack?.vscodeExtensions !== false,
+        },
+        aiDocs: {
+          enabled: c.output?.aiDocs?.enabled !== false,
+        },
+      },
+    })
+  );
+  blank();
+
+  push(
+    '# --- Git ---------------------------------------------------------------------',
+    '# When enabled and project.repositoryUrl is set, generate initializes git + origin.',
+    dumpSection({
+      git: {
+        enabled: c.git?.enabled !== false,
+      },
+    })
+  );
+  blank();
+
+  if (c.fuse) {
+    push(
+      '# --- Fuse --------------------------------------------------------------------',
+      '# Fuse Angular shell. Theme colors flow through root fuseTheme / provideTheming.',
+      dumpSection({
+        fuse: {
+          enabled: !!c.fuse.enabled,
+          cleanLayout: !!c.fuse.cleanLayout,
+          includePrebuilt: c.fuse.includePrebuilt !== false,
+          folderType: c.fuse.folderType || '',
+          routesFile: c.fuse.routesFile || 'src/app/domains/admin/routes.ts',
+          navigationFile: c.fuse.navigationFile || 'src/app/domains/admin/layout/data/navigation.ts',
+          theme: {
+            scheme: c.fuse.theme?.scheme || 'system',
+            primary: c.fuse.theme?.primary || '#0D1E3A',
+            error: c.fuse.theme?.error || '#dc2626',
+          },
+        },
+      })
+    );
+    blank();
+  }
+
+  if (c.ui) {
+    push(
+      '# --- UI ----------------------------------------------------------------------',
+      '# formMode: sidebar | page (new and edit share one mode).',
+      '# searchMode: field (default) | global (only if the API accepts query).',
+      dumpSection({
+        ui: {
+          framework: c.ui.framework || 'material',
+          viewMode: c.ui.viewMode || 'table',
+          formMode: c.ui.formMode || 'sidebar',
+          searchMode: c.ui.searchMode || 'field',
+          useSkeletonLoading: c.ui.useSkeletonLoading !== false,
+          snackbarPositionTop: !!c.ui.snackbarPositionTop,
+          cardBreakpointPx: c.ui.cardBreakpointPx ?? 640,
+          gridCols: c.ui.gridCols || { mobile: 1, tablet: 2, desktop: 3 },
+          styling: c.ui.styling || {
+            snackbarSuccessColor: '#16a34a',
+            snackbarErrorColor: '#dc2626',
+          },
+        },
+      })
+    );
+    blank();
+  }
+
+  if (c.api) {
+    push(
+      '# --- API ---------------------------------------------------------------------',
+      '# api.services: module name → absolute origin (or { prod, dev, pathRewrite }).',
+      '# Written into environment.services (relative /services/{name}) and proxy*.json.',
+      dumpSection({
+        api: {
+          baseUrl: c.api.baseUrl || '/api',
+          microservice: c.api.microservice || '',
+          endpointStyle: c.api.endpointStyle || 'kebab-plural',
+          dateLibrary: c.api.dateLibrary || 'dayjs',
+          responseType: c.api.responseType || 'http-response',
+          services: c.api.services || {},
+        },
+      })
+    );
+    blank();
+  }
+
+  if (c.proxy) {
+    push(
+      '# --- Angular proxy -----------------------------------------------------------',
+      '# write: both | prod (proxy.conf.json) | dev (proxy.dev.conf.json)',
+      dumpSection({
+        proxy: {
+          write: c.proxy.write || 'both',
+          routes: c.proxy.routes || {},
+        },
+      })
+    );
+    blank();
+  }
+
+  if (c.devServer) {
+    push('# --- Development server -----------------------------------------------------', dumpSection({ devServer: c.devServer }));
+    blank();
+  }
+
+  if (c.mock) {
+    push(
+      '# --- Mock data ---------------------------------------------------------------',
+      '# Used by Angular mock interceptors / e2e fixtures. Not Keycloak.',
+      dumpSection({
+        mock: {
+          enabled: !!c.mock.enabled,
+          recordsPerEntity: c.mock.recordsPerEntity ?? 10,
+          values: c.mock.values || {},
+        },
+      })
+    );
+    blank();
+  }
+
+  if (c.auth) {
+    const provision = c.auth.provision || {};
+    push(
+      '# --- Auth (Keycloak) ---------------------------------------------------------',
+      '# provider: none | keycloak',
+      '# useMockAuth: true keeps Playwright deterministic (no remote IdP).',
+      '# provision.enabled: false for generate — use `crudforge bootstrap` to mutate a realm.',
+      '# Admin credentials: KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD (QA: crud / crud).',
+      '# Live sign-in forms never inherit provisioning credentials from environment variables.',
+      '# Admin / user passwords for bootstrap seeds: env refs only (adminUsernameEnv, passwordEnv).',
+      dumpSection({
+        auth: {
+          provider: c.auth.provider || 'none',
+          serverUrl: c.auth.serverUrl || '',
+          realm: c.auth.realm || '',
+          clientId: c.auth.clientId || '',
+          issuerUrl: c.auth.issuerUrl || '',
+          tokenUrl: c.auth.tokenUrl || '',
+          adminBaseUrl: c.auth.adminBaseUrl || '/auth',
+          useMockAuth: !!c.auth.useMockAuth,
+          forwardedProto: c.auth.forwardedProto || '',
+          adminRoles: c.auth.adminRoles || ['ROLE_ADMIN'],
+          sessionIdleTimeoutMs:
+            (c.auth.session && c.auth.session.idleTimeoutMs != null
+              ? c.auth.session.idleTimeoutMs
+              : c.auth.sessionIdleTimeoutMs) || 0,
+          session: {
+            idleTimeoutMs:
+              (c.auth.session && c.auth.session.idleTimeoutMs != null
+                ? c.auth.session.idleTimeoutMs
+                : c.auth.sessionIdleTimeoutMs) || 0,
+            persistAcrossReload: c.auth.session?.persistAcrossReload !== false,
+            crossTabSync: c.auth.session?.crossTabSync !== false,
+            refreshOnFocus: c.auth.session?.refreshOnFocus !== false,
+            statusProbeIntervalMs: c.auth.session?.statusProbeIntervalMs || 60_000,
+          },
+          disabledAccount: {
+            enabled: !!(c.auth.disabledAccount && c.auth.disabledAccount.enabled),
+            countdownSeconds: (c.auth.disabledAccount && c.auth.disabledAccount.countdownSeconds) || 20,
+            message:
+              (c.auth.disabledAccount && c.auth.disabledAccount.message) ||
+              'Your account has been disabled. Please contact your administrator.',
+            sound: !!(c.auth.disabledAccount && c.auth.disabledAccount.sound),
+          },
+          provision: {
+            enabled: !!provision.enabled,
+            dryRun: !!provision.dryRun,
+            adapter: provision.adapter || 'admin-service',
+            adminServiceUrl: provision.adminServiceUrl || '',
+            adminUsernameEnv: provision.adminUsernameEnv || 'KEYCLOAK_ADMIN_USERNAME',
+            adminPasswordEnv: provision.adminPasswordEnv || 'KEYCLOAK_ADMIN_PASSWORD',
+            tokenClientId: provision.tokenClientId || 'admin-cli',
+            clientId: provision.clientId || '',
+            clientName: provision.clientName || '',
+            publicClient: provision.publicClient !== false,
+            directAccessGrantsEnabled: provision.directAccessGrantsEnabled !== false,
+            redirectUris: provision.redirectUris || [],
+            webOrigins: provision.webOrigins || [],
+            roles: provision.roles || [],
+            users: (provision.users || []).map((user) =>
+              pick(user, [
+                'username',
+                'passwordEnv',
+                'email',
+                'firstName',
+                'lastName',
+                'enabled',
+                'temporaryPassword',
+                'roles',
+              ])
+            ),
+            resetExistingPasswords: !!provision.resetExistingPasswords,
+            stateFile: provision.stateFile || '.crudforge/provision-state.json',
+          },
+        },
+      })
+    );
+    blank();
+  }
+
+  if (c.iam) {
+    push(
+      '# --- IAM overlay -------------------------------------------------------------',
+      '# Do not model User / Role as JDL entities. Toggle features with these flags.',
+      dumpSection({
+        iam: {
+          enabled: !!c.iam.enabled,
+          users: c.iam.users !== false,
+          roles: c.iam.roles !== false,
+          rolePermissions: c.iam.rolePermissions !== false,
+          userAccess: c.iam.userAccess !== false,
+          userPermissions: c.iam.userPermissions !== false,
+          inheritance: c.iam.inheritance !== false,
+          screens: c.iam.screens || [],
+        },
+      })
+    );
+    blank();
+  }
+
+  if (c.fields || c.formBehavior || c.namingConventions || c.generate || c.validation !== undefined) {
+    push('# --- Generation preferences -------------------------------------------------');
+    if (c.validation !== undefined) {
+      push(dumpSection({ validation: c.validation }));
+      blank();
+    }
+    if (c.generate) {
+      push('# What the generator emits (models, forms, routes, …).', dumpSection({ generate: c.generate }));
+      blank();
+    }
+    if (c.fields) {
+      push('# Audit fields and display formatting.', dumpSection({ fields: c.fields }));
+      blank();
+    }
+    if (c.formBehavior) {
+      push(dumpSection({ formBehavior: c.formBehavior }));
+      blank();
+    }
+    if (c.namingConventions) {
+      push(dumpSection({ namingConventions: c.namingConventions }));
+      blank();
+    }
+  }
+
+  // Drop trailing blank lines; end with a single newline.
+  while (lines.length && lines[lines.length - 1] === '') {
+    lines.pop();
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Write crudforge.config.yml into the Fuse output root when enabled (default on).
+ */
+function embedConfigInOutput(outputDir, config, writeOrPreview) {
+  const embed = config.output?.embedConfig !== false;
+  if (!embed) {
+    return { written: false, reason: 'output.embedConfig=false' };
+  }
+
+  const yamlText = formatEmbeddableYaml(config, new Date());
+  const target = path.join(outputDir, 'config', 'crudforge.config.yml');
+  writeOrPreview(target, yamlText);
+  return { written: true, path: target };
+}
+
+module.exports = {
+  buildEmbeddableConfig,
+  formatEmbeddableYaml,
+  formatLocalTimestamp,
+  embedConfigInOutput,
+};

package/src/generator/entity-layout.js

@@ -0,0 +1,30 @@
+const path = require('path');
+const { kebabCase } = require('lodash');
+
+// Source folders name service modules; the common container is always micro-functions.
+function serviceFolder(entity, config) {
+  const multiSource = Array.isArray(config.input?.sources) && config.input.sources.length > 0;
+  const module = multiSource
+    ? entity.folderName || kebabCase(entity.sourceName || entity.microservice)
+    : kebabCase(entity.microservice || config.api?.microservice || 'microservice');
+  if (!module || /[\\/]/.test(module) || ['.', '..'].includes(module)) {
+    throw new Error('Microservice module must be a single folder name.');
+  }
+  return `micro-functions/${module}`;
+}
+
+function entityFolder(entity, config) {
+  return `${serviceFolder(entity, config)}/entities`;
+}
+
+function entityPath(entity, config) {
+  return `${entityFolder(entity, config)}/${kebabCase(entity.name)}`;
+}
+
+function relativeEntityPath(from, to, config) {
+  const source = config.fuse?.enabled ? entityPath(from, config) : `entities/${kebabCase(from.name)}`;
+  const target = config.fuse?.enabled ? entityPath(to, config) : `entities/${kebabCase(to.name)}`;
+  return path.posix.relative(source, target) || '.';
+}
+
+module.exports = { serviceFolder, entityFolder, entityPath, relativeEntityPath };

package/src/generator/fuse-build.js

@@ -0,0 +1,57 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/** Make rendering, compilation roots and deployment agree; never weaken compiler checks. */
+function applyFuseBuild({outputDir, config, writeOrPreview}) {
+  if (!config.fuse?.enabled) return;
+  const mode = config.fuse.rendering || 'spa';
+  if (!['spa','ssr'].includes(mode)) throw new Error('fuse.rendering must be spa or ssr.');
+  const read = name => fs.readJsonSync(path.join(outputDir,name));
+  const write = (name,value) => writeOrPreview(path.join(outputDir,name), JSON.stringify(value,null,2)+'\n');
+  const angular=read('angular.json');
+  angular.cli = {...angular.cli, analytics:false, cache:{enabled:true,environment:'local',path:'.angular/cache'}};
+  const targets=angular.projects.fuse.architect;
+  if(mode==='spa') {
+    for(const key of ['server','ssr','prerender','outputMode']) delete targets.build.options[key];
+  } else {
+    Object.assign(targets.build.options,{server:'src/main.server.ts',outputMode:'server',ssr:{entry:'src/server.ts'}});
+  }
+  for(const name of ['development','mock']) if(targets.build.configurations[name]) {
+    targets.build.configurations[name].sourceMap={scripts:true,styles:false,vendor:false};
+    targets.build.configurations[name].optimization=false;
+  }
+  write('angular.json',angular);
+  const tsconfig=JSON.parse(fs.readFileSync(path.join(outputDir,'tsconfig.app.json'),'utf8').replace(/\/\*[\s\S]*?\*\//g,'').replace(/^\/\/.*$/gm,''));
+  tsconfig.files=mode==='ssr'?['src/main.ts','src/main.server.ts','src/server.ts']:['src/main.ts'];
+  tsconfig.include=['src/**/*.d.ts'];
+  tsconfig.compilerOptions.types=mode==='ssr'?['node']:[];
+  write('tsconfig.app.json',tsconfig);
+  const app=path.join(outputDir,'src/app/app.config.ts');
+  let appConfig=fs.readFileSync(app,'utf8');
+  if(mode==='spa') appConfig=appConfig.replace(/import\s*\{\s*provideClientHydration,\s*withIncrementalHydration,?\s*\}\s*from '@angular\/platform-browser';\n/,'').replace(/\s*provideClientHydration\(withIncrementalHydration\(\)\),/,'');
+  else if(!appConfig.includes('provideClientHydration')) appConfig="import { provideClientHydration, withIncrementalHydration } from '@angular/platform-browser';\n"+appConfig.replace('providers: [','providers: [\n    provideClientHydration(withIncrementalHydration()),');
+  writeOrPreview(app,appConfig);
+  const pkg=read('package.json');
+  const dependencies={'@angular/platform-server':pkg.dependencies['@angular/core'],'@angular/ssr':pkg.devDependencies['@angular/build'],express:'5.2.1'};
+  const development={'@types/express':'5.0.6'};
+  for(const [section,values] of [['dependencies',dependencies],['devDependencies',development]]) for(const [name,version] of Object.entries(values)) {
+    if(mode==='spa') delete pkg[section][name];else pkg[section][name] ||= version;
+  }
+  pkg.scripts.start='ng serve --configuration=development';
+  pkg.scripts['start:production']='ng serve --configuration=production';
+  if(mode==='ssr') pkg.scripts['serve:ssr']='node dist/fuse/server/server.mjs'; else delete pkg.scripts['serve:ssr'];
+  write('package.json',pkg);
+  if(fs.existsSync(path.join(outputDir,'package-lock.json'))) {
+    const lock=read('package-lock.json');
+    // Preserve resolved transitive/optional peer entries, keeping root requirements in sync.
+    lock.packages[''].dependencies=pkg.dependencies;lock.packages[''].devDependencies=pkg.devDependencies;
+    write('package-lock.json',lock);
+  }
+  if(mode==='ssr') {
+    const serverPath = path.join(outputDir, 'src/server.ts');
+    const server = fs.readFileSync(serverPath, 'utf8').replace(/allowedHosts: \[[^\]]*\]/, `allowedHosts: ${JSON.stringify(config.fuse.ssrAllowedHosts || ['localhost','127.0.0.1'])}`);
+    writeOrPreview(serverPath, server);
+  }
+  if(mode==='ssr') writeOrPreview(path.join(outputDir,'Dockerfile'),`FROM node:24-alpine AS build\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci\nCOPY . .\nRUN npm run build\n\nFROM node:24-alpine\nWORKDIR /app\nENV NODE_ENV=production\nENV PORT=4000\nCOPY --from=build /app/package*.json ./\nRUN npm ci --omit=dev\nCOPY --from=build /app/dist ./dist\nEXPOSE 4000\nCMD ["node", "dist/fuse/server/server.mjs"]\n`);
+}
+module.exports={applyFuseBuild};