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

package/cli.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+const yargs = require('yargs');
+const colors = require('./src/utils/colors');
+const { generateCommand } = require('./src/commands/generate');
+const { initConfig, initProject } = require('./src/commands/init-config');
+const { validate } = require('./src/commands/validate');
+const { bootstrapCommand } = require('./src/commands/bootstrap');
+
+const argv = yargs
+  .command('doctor', 'Read-only project diagnostics (network checks are opt-in)', y => y.option('json',{type:'boolean'}).option('live',{type:'boolean',default:false}).option('preferences',{alias:'p',type:'string'}), async options => { try { await require('./src/commands/doctor').doctorCommand(options); } catch { const message='Doctor could not complete local checks. Check project permissions.'; if(options.json)console.log(JSON.stringify({ok:false,checks:[{id:'doctor',status:'fail',message,next:'Check project permissions.'}]}));else console.error(message); process.exitCode=1; } })
+  .usage('Usage: $0 <command> [options]')
+  // Default legacy fallback command mapping to 'generate'
+  .command(
+    ['generate [jdlFile] [outputFolder]', '$0 <jdlFile> [outputFolder]'],
+    'Generate from project config, or an explicit JDL/GDL file',
+    (yargs) => {
+      yargs
+        .positional('jdlFile', { describe: 'JDL/GDL file (defaults to input.file in project config)', type: 'string' })
+        .positional('outputFolder', { describe: 'Target output folder for the Angular files', type: 'string' })
+        .option('microservice', { alias: 'm', describe: 'Name of the microservice for URL paths', type: 'string' })
+        .option('preferences', { alias: 'p', describe: 'Path to custom crudforge config', type: 'string' })
+        .option('json', { type: 'boolean', default: false, describe: 'JSON outcome/diagnostics on stdout; progress on stderr' })
+        .option('dry-run', { alias: 'd', describe: 'Preview modifications without writing', type: 'boolean', default: false })
+        .option('overwrite-policy', { alias: 'w', describe: 'Overwrite policy: overwrite, skip, fail, ask, merge', type: 'string', choices: ['overwrite', 'skip', 'fail', 'ask', 'merge'] })
+        .option('fuse', { describe: 'Scaffold and generate into Fuse Angular project layout', type: 'boolean', default: false })
+        .option('fuse-path', { describe: 'Path to local Fuse starter pack directory', type: 'string' })
+        .option('clean-layout', { describe: 'Hide all pre-built Fuse pages and layouts', type: 'boolean', default: false })
+        .option('sidebar-theme', { describe: 'Configures sidebar navigation theme style', type: 'string', choices: ['white', 'dark'], default: 'white' })
+        .option('folder-type', { describe: 'Folder name mapping for apps modules', type: 'string' })
+        .option('keycloak', { describe: 'Enable Keycloak auth + IAM for this generate', type: 'boolean', default: false })
+        .option('kc-server-url', { describe: 'Keycloak base URL (e.g. http://host:30080)', type: 'string' })
+        .option('kc-admin-service-url', {
+          describe: 'Keycloak middleware / admin service URL (e.g. http://host:31740/)',
+          type: 'string',
+        })
+        .option('kc-client-id', { describe: 'Application Keycloak client ID', type: 'string' })
+        .option('kc-realm', { describe: 'Keycloak realm name', type: 'string' })
+        .option('kc-username', { describe: 'Keycloak admin username (written to output .env only)', type: 'string' })
+        .option('kc-password', { describe: 'Keycloak admin password (written to output .env only)', type: 'string' })
+        .option('kc-forwarded-proto', { describe: 'X-Forwarded-Proto when Keycloak requires HTTPS', type: 'string' })
+        .option('proxy-write', {
+          describe: 'Which Fuse proxy file(s) to update: both | prod | dev',
+          type: 'string',
+          choices: ['both', 'prod', 'dev'],
+        })
+        .option('yes', { alias: 'y', describe: 'Skip interactive prompts', type: 'boolean', default: false });
+    },
+    async (argv) => {
+      const log = console.log;
+      if (argv.json) console.log = (...args) => console.error(...args);
+      try {
+        const result = await generateCommand(argv.jdlFile, argv.outputFolder, argv);
+        if (argv.json) log(JSON.stringify({ok:true, diagnostics:result.diagnostics, dryRun:!!result.stats.dryRun}));
+      } catch (err) {
+        if (argv.json) log(JSON.stringify({ok:false,diagnostics:err.diagnostics || [{severity:'error',code:'generation',message:err.message,suggestion:'Correct the input or conflict policy and retry.'}]}));
+        else console.error(colors.red(`❌ Generator execution failed:`), err);
+        process.exitCode = 1;
+      } finally { console.log = log; }
+    }
+  )
+  .command(
+    'init <directory>',
+    'Create only config/crudforge.config.yml and gdl/example.gdl; edit them before generate',
+    yargs => yargs.positional('directory', { type: 'string', describe: 'New or empty project directory' })
+      .option('preset', { type: 'string', choices: ['pmb-test'], describe: 'Optional reusable testing preset' })
+      .option('source', { type: 'string', describe: 'Read-only PMB project path; import preset on first use' }),
+    async argv => {
+      try { await initProject(argv.directory, argv); }
+      catch (error) { console.error(error.message); process.exitCode = 1; }
+    }
+  )
+  .command(
+    'preset <action> <name>',
+    'Refresh a saved testing preset from its source, keeping a backup',
+    yargs => yargs.positional('action', { choices: ['refresh'] })
+      .positional('name', { choices: ['pmb-test'] })
+      .option('source', { type: 'string', demandOption: true, describe: 'PMB source project (read-only)' }),
+    async argv => {
+      try { await require('./src/presets/store').importPreset(argv.name, argv.source, { refresh: true }); }
+      catch (error) { console.error(error.message); process.exitCode = 1; }
+    }
+  )
+  .command(
+    'init-config',
+    'Initializes a default crudforge.config.yml and example schema files',
+    () => {},
+    async (argv) => {
+      try {
+        await initConfig();
+      } catch (err) {
+        console.error(colors.red(`❌ Failed to initialize configuration:`), err);
+        process.exit(1);
+      }
+    }
+  )
+  .command(
+    'validate <file>',
+    'Validate a JDL or GDL file syntax and rules',
+    (yargs) => {
+      yargs.positional('file', { describe: 'Path to the schema file', type: 'string' }).option('json', {type:'boolean',default:false}).option('preferences', {alias:'p',type:'string'});
+    },
+    async (argv) => {
+      try {
+        await validate(argv.file, argv);
+      } catch (err) {
+        console.error(colors.red(`❌ Validation command failed:`), err);
+        process.exit(1);
+      }
+    }
+  )
+  .command(
+    'validate-jdl <file>',
+    'Validate a JDL file syntax and rules explicitly',
+    (yargs) => {
+      yargs.positional('file', { describe: 'Path to the schema file', type: 'string' }).option('json', {type:'boolean',default:false}).option('preferences', {alias:'p',type:'string'});
+    },
+    async (argv) => {
+      try {
+        await validate(argv.file, argv, 'jdl');
+      } catch (err) {
+        process.exit(1);
+      }
+    }
+  )
+  .command(
+    'validate-gdl <file>',
+    'Validate a GDL file syntax and rules explicitly',
+    (yargs) => {
+      yargs.positional('file', { describe: 'Path to the schema file', type: 'string' }).option('json', {type:'boolean',default:false}).option('preferences', {alias:'p',type:'string'});
+    },
+    async (argv) => {
+      try {
+        await validate(argv.file, argv, 'gdl');
+      } catch (err) {
+        process.exit(1);
+      }
+    }
+  )
+  .command(
+    'bootstrap',
+    'Provision Keycloak realm resources from auth.provision (never runs during generate)',
+    (yargs) => {
+      yargs
+        .option('preferences', { alias: 'p', describe: 'Path to custom crudforge config', type: 'string' })
+        .option('dry-run', { alias: 'd', describe: 'Preview provisioning without remote mutations', type: 'boolean', default: false })
+        .option('env-file', { describe: 'Path to dotenv file loaded before validation', type: 'string' })
+        .option('cleanup', { describe: 'Delete only resources tracked in auth.provision.stateFile', type: 'boolean', default: false });
+    },
+    async (argv) => {
+      try {
+        await bootstrapCommand(argv);
+      } catch (err) {
+        console.error(colors.red('❌ Bootstrap failed:'), err.message || err);
+        process.exit(1);
+      }
+    }
+  )
+  .example('crudforge init my-app', 'Initialize editable project inputs')
+  .example('crudforge init my-app --preset pmb-test --source /path/to/pmb-admin', 'Import PMB dev settings and initialize inputs')
+  .example('crudforge init my-app --preset pmb-test', 'Reuse saved PMB settings after deleting an app')
+  .example('crudforge preset refresh pmb-test --source /path/to/pmb-admin', 'Refresh the saved preset; existing apps are untouched')
+  .example('crudforge generate', 'Run inside my-app after editing config/ and gdl/')
+  .example('crudforge generate schema.gdl ./output -p prefs.yml', 'Legacy explicit generation')
+  .help()
+  .alias('help', 'h')
+  .argv;

package/config/default-config.yml

@@ -0,0 +1,245 @@
+# CRUDForge Default Configuration
+# All options correspond to safe fallbacks matching TW-Hipster behaviors.
+
+project:
+  name: CRUDForge App
+  description: Angular Material CRUD generated by CRUDForge
+  repositoryUrl: ""              # if set, generated Fuse root gets git init + origin remote
+
+input:
+  type: gdl                       # default for sources[] / single file when unset
+  # --- Single schema (legacy) ---
+  # file: ./GDL/app.gdl
+  file: ""
+  # --- Multiple GDL/JDL files per service (preferred for multi-backend apps) ---
+  # Each entry is a named service module: generates under apps/<folder>/…,
+  # nav group labeled by name, and API paths use microservice.
+  # Leave sources empty and set file: above for one schema.
+  sources: []
+  # sources:
+  #   - name: identity-access              # nav group label + default folder
+  #     file: ./GDL/identity-access.gdl
+  #     microservice: identity-access-module
+  #     type: gdl                          # optional; inferred from .gdl / .jdl
+  #     # folder: identity-access          # optional override (kebab folder under apps/)
+  #   - name: inventory
+  #     file: ./GDL/inventory.gdl
+  #     microservice: inventory-service
+  #   - name: book-catalog
+  #     file: ./jdl/books.jdl
+  #     type: jdl
+  #     microservice: book-service
+
+output:
+  directory: "./generated-app"
+  structure: entity-folder        # Entity layout; shared utilities are emitted once for either value
+  embedConfig: true               # write config/crudforge.config.yml into the Fuse app
+  teamPack:
+    enabled: true                 # seed .cursor/agents, .codex/agents, .agents (Antigravity), .vscode/extensions
+    cursorAgents: true
+    codexAgents: true
+    antigravityAgents: true       # .agents/agents + .agents/rules (model_decision)
+    vscodeExtensions: true
+  aiDocs:
+    enabled: true                 # AGENT_README.md + docs/ai/* + .crudforge/ (GO-DUCK-style)
+
+git:
+  enabled: true                   # honor project.repositoryUrl when true
+
+fuse:
+  enabled: false
+  rendering: spa # spa (Nginx) | ssr (Node server)
+  cleanLayout: false
+  includePrebuilt: true
+  folderType: ""
+  sidebarTheme: white             # white | dark
+  routesFile: "src/app/domains/admin/routes.ts"
+  navigationFile: "src/app/domains/admin/layout/data/navigation.ts"
+  ssrAllowedHosts:
+    - localhost
+    - 127.0.0.1
+  # Root Material accents → generated src/app/app.ts fuseTheme / provideTheming.
+  # Override primary/error/scheme here; do not hardcode entity button colors.
+  theme:
+    scheme: system                # system | light | dark
+    primary: "#0D1E3A"            # default navy (matrix / app accents)
+    error: "#dc2626"
+
+preset: crud
+
+generate:
+  model: true
+  service: true
+  enums: true
+  routes: true
+  components:
+    list: true
+    card: true
+    detail: true
+    filter: true
+    form: true
+    formPage: true
+    actions: true
+  globals:
+    tests: false
+
+ui:
+  framework: material
+  useSkeletonLoading: true
+  viewMode: table                 # 'table' or 'card'
+  cardBreakpointPx: 640
+  gridCols:
+    mobile: 1
+    tablet: 2
+    desktop: 3
+  styling:
+    snackbarSuccessColor: '#16a34a'
+    snackbarErrorColor: '#dc2626'
+
+api:
+  baseUrl: /api
+  microservice: ""
+  endpointStyle: kebab-plural
+  dateLibrary: dayjs
+  responseType: http-response
+  # Backend modules for environment.services + proxy*.json
+  # identityaccessmodule: http://62.84.188.166:30084
+  # book-service:
+  #   prod: http://62.84.188.166:30084
+  #   dev: http://62.84.188.166:31704
+  #   pathRewrite: /book-service
+  services: {}
+
+# Which Angular proxy file(s) to update for Keycloak + api.services
+# both | prod (proxy.conf.json) | dev (proxy.dev.conf.json)
+proxy:
+  write: both
+
+fields:
+  # Exact entity and field names from your GDL/JDL. Only String/TextBlob fields.
+  # entities:
+  #   Province:
+  #     fields:
+  #       referenceCode: { inputFormat: uppercase }
+  #       email: { inputFormat: lowercase }
+  #       description: { inputFormat: none }
+  entities: {}
+  audit:
+    enabled: true
+    hideInForms: true
+    hideInFilters: true
+    hideInSearch: true
+    # Table view: hide createdBy / createdDate / lastModified* by default.
+    # Set hideInLists: false if you want those columns visible in the list initially
+    # (users can still toggle them via Column Preferences either way).
+    hideInLists: true
+    showInDetail: true
+    names:
+      - createdBy
+      - createdDate
+      - lastModifiedBy
+      - lastModifiedDate
+  # Backend plumbing columns (debug / refType / refId). Kept on the model for API
+  # payloads; never rendered in list, form, detail, card, filter, or search UI.
+  # Set enabled: false (or clear names) to show them.
+  technical:
+    enabled: true
+    names:
+      - debug
+      - refType
+      - refId
+  formatting:
+    dateMediumFormat: 'medium'
+    numberFormat: '1.0-2'
+    stringCase: default
+
+formBehavior:
+  uppercaseInputs: false
+  updateOn: change
+  showErrorMessages: true
+  autoFocusFirstInput: true
+
+mock:
+  enabled: false
+  recordsPerEntity: 10
+  values:
+    stringPrefix: 'Mock '
+    numberMin: 1
+    numberMax: 1000
+    booleanDefault: true
+
+# Keycloak — set provider: keycloak and fill the fields below for developer generate.
+# Username/password never go in this file: put them in a local .env as
+# KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD (names below).
+auth:
+  provider: none                  # none | keycloak
+  serverUrl: ""                   # e.g. http://62.84.188.166:30080 (not the /admin console link)
+  realm: CRUD-FORDGE
+  clientId: ""                    # application public SPA client ID
+  clientSecret: ""
+  issuerUrl: ""
+  tokenUrl: ""
+  adminBaseUrl: /auth
+  useMockAuth: false
+  adminRoles:
+    - ROLE_ADMIN
+    - ADMIN
+    - ROLE_SUPER_ADMIN
+  sessionIdleTimeoutMs: 0       # legacy; prefer auth.session.idleTimeoutMs (0 = stay signed in)
+  session:
+    idleTimeoutMs: 0            # 0 = never idle-logout; set e.g. 900000 for 15m like PMB
+    persistAcrossReload: true
+    crossTabSync: true
+    refreshOnFocus: true
+    statusProbeIntervalMs: 60000
+  disabledAccount:
+    enabled: false              # true → countdown overlay then sign-out when Keycloak says disabled
+    countdownSeconds: 20
+    message: "Your account has been disabled. Please contact your administrator."
+    sound: false
+  forwardedProto: ""              # set to https when Keycloak requires HTTPS behind HTTP
+  provision:
+    enabled: false                # true only for `crudforge bootstrap`
+    dryRun: false
+    adapter: admin-service        # or keycloak-admin-rest
+    adminServiceUrl: ""           # Keycloak middleware, e.g. http://62.84.188.166:31740/
+    adminUsernameEnv: KEYCLOAK_ADMIN_USERNAME
+    adminPasswordEnv: KEYCLOAK_ADMIN_PASSWORD
+    tokenClientId: admin-cli
+    clientId: ""                  # defaults to auth.clientId when empty
+    clientName: ""
+    publicClient: true
+    directAccessGrantsEnabled: true
+    redirectUris: []
+    webOrigins: []
+    roles: []
+    users: []
+    resetExistingPasswords: false
+    stateFile: ".crudforge/provision-state.json"
+
+iam:
+  enabled: false
+  users: true
+  roles: true
+  rolePermissions: true
+  userAccess: true
+  userPermissions: true
+  inheritance: true
+  screens: []
+
+namingConventions:
+  entityPrefix: ''
+  entitySuffix: ''
+  modelInterfacePrefix: 'I'
+  kebabCaseFiles: true
+  enumValueCasing: uppercase
+
+# Optional application smoke suite and GitHub Actions (npm lockfile).
+testing:
+  ci: false
+  fixtures: {}
+backend:
+  kind: custom # informational: custom, go-duck, jhipster; never implies verified support
+doctor:
+  timeoutMs: 3000
+  endpoints: [] # explicit documented read-only URLs; requested only with doctor --live

package/docs/performance/README.md

@@ -0,0 +1,217 @@
+# CRUDForge performance investigation
+
+Measured on 2026-10-09. Baseline generator commit: `5699fab319ff600e2e19e8bd85b23219e1adf26a`.
+Changes apply to the generator and Fuse starter, not to PMB business code. PMB was read only.
+
+## Audit checked against implementation
+
+Reference: `/Users/abdulla/Work/PMB/pmb-admin/AUDIT_README.md`, plus PMB's
+`angular.json`, app/bootstrap configuration, package manifests, Dockerfile, routes,
+HTTP imports and component implementations.
+
+The audit mixes historical findings with completed work. Its action matrix correctly
+marks SPA conversion, shared-asset consolidation and removal of component-level
+`HttpClientModule` as completed. PMB currently has no SSR build targets or hydration
+provider and deploys browser assets with Nginx. A source scan found three classes
+named `ConfirmationDialogComponent`, one `ResizableDirective`, and no
+`HttpClientModule` references; the introductory counts of hundreds of copies no
+longer describe current source.
+
+Other recommendations remain outstanding or only partly applied: PMB still includes
+`src/**/*.ts` as compilation roots. The scan counted 2,027 TypeScript files / 504,681
+lines, 1,164 files containing `@Component(`, 34 containing OnPush and 23 containing
+`takeUntilDestroyed`. These are textual counts, not a runtime profile or a count of
+confirmed leaks. PMB's large custom report screens and business services are not
+CRUDForge templates and were not copied or rewritten. The heap setting exists, but
+the audit's claimed GC stalls have no accompanying heap/CPU measurement; this work
+does not claim to confirm them or increase the heap limit.
+
+The starter uses Angular 21.2.6 without Zone.js. Angular 21 defaults to zoneless
+change detection ([Angular documentation](https://angular.dev/guide/zoneless)), so
+Zone.js-wide change-detection claims do not explain this fixture. Generated entity
+components already used OnPush; asynchronous updates needed correct notifications,
+not a blanket change-detection conversion.
+
+## Confirmed generator causes and changes
+
+- The starter built browser and SSR bundles even though its Dockerfile served only
+  browser assets. The baseline produced `index.csr.html`, whereas Nginx expects
+  `index.html`. `src/generator/fuse-build.js` now coordinates `fuse.rendering: spa`
+  (default) or `ssr`, build targets, compiler roots, hydration, direct dependencies,
+  lockfile root requirements, start scripts, allowed hosts and deployment files.
+  SPA omits server sources in fresh projects. Strict TypeScript/template checks stay
+  enabled. Angular's local disk cache is explicit; Tailwind scans the source tree.
+- Fuse already generated canonical shared assets; non-Fuse output duplicated them
+  per entity. Both layouts now share confirmation, resize, base and style files.
+  Shared list CSS is scoped to `.cforge-entity-list`; entity SCSS remains an extension
+  hook. Existing CLI conflict/overwrite rules protect customizations. Legacy copies
+  in existing projects are not silently deleted.
+- Domain/entity routing already used lazy route boundaries, but each entity route
+  eagerly imported its screens. Screens now use `loadComponent`; related collection
+  and form dialogs use dynamic imports, avoiding relationship chains pulling screens
+  into a feature chunk. Related collection dialogs also receive a definite height
+  and explicit maximum width; browser tests caught collapsed content in the old layout.
+- Pagination had two listeners: the paginator observable and a template `(page)`
+  handler. Browser traces measured two GET requests per page change. One remains.
+  Save/delete/filter paths also had both a refresh event and direct `loadData()`;
+  redundant calls were removed. Superseded reads are cancelled and reads/dialog
+  subscriptions end with component destruction. Server page/size parameters remain.
+- Relationship option responses now notify OnPush and bind to lifecycle cleanup;
+  selects request page 0 / size 50. A remote searchable/paged relationship selector
+  remains necessary for larger option sets. Table tracking uses row IDs. ACL template
+  conditions use `@if`; existing `@for` tracking and Material table directives remain.
+- Generated components had no `HttpClientModule` imports to remove. Root HTTP providers
+  and authentication interceptors are retained and regression-tested. No blanket
+  subscription or signal rewrite was made.
+
+Optional chart screens are already route-lazy. The measured clean app excludes
+prebuilt dashboards; its build graph contains no ApexCharts, spreadsheet or PDF
+library. These dependencies were not indiscriminately removed from the starter
+because optional features use them. No global route preloading was found. Backend
+latency and PMB's custom initialization were not measured; required authentication
+checks were preserved.
+
+## Measurements
+
+See `before.json` and `after.json` for exact values, commands and three browser
+observations per fixture. The small fixture has one audited Province; the large
+fixture has Province plus 24 independent catalog entities. They use the same schema,
+configuration, dependency directory, Node 24.19.0, macOS arm64 / 11 logical CPUs and
+`NG_BUILD_MAX_WORKERS=2`. Relationship behavior is tested separately with Book/Author.
+
+Cold build means deleting Angular's disk cache and build output, not flushing OS
+caches. Warm build reruns the same production command. Each build/start/rebuild has
+one sample; these results are observations, not statistically established guarantees.
+Development startup ends when the server prints its local URL. Browser bootstrap
+is measured separately because Vite transforms code on first request. Its readiness
+marker is Angular's sign-in component instance, not a standardized TTI metric.
+Browser/API timings use local mocked authentication and backend responses. Initial
+bundle bytes sum unique JS/CSS files referenced by production HTML, including
+modulepreloads; they are raw bytes, not compressed transfer size or all lazy chunks.
+FCP was sampled too early in SPA runs and is null; no FCP comparison is claimed.
+
+### One entity
+- Cold production build: 7.52s → 4.33s (42.5% lower in this run).
+- Warm production build: 5.61s → 2.78s (50.4% lower in this run).
+- Cold dev startup: 3.03s → 2.12s (30.0% lower in this run).
+- Template rebuild: 1.61s → 1.11s (31.1% lower in this run).
+- Initial JS/CSS: 1,002,588 → 655,268 bytes (34.6% smaller).
+- First browser bootstrap (cold dev transforms): 3775 → 955 ms.
+- Warm bootstrap (mean of runs 2–3): 184 → 132 ms.
+- Province rendered (median of 3): 346 → 275 ms.
+- Province refresh (median of 3): 429 → 301 ms.
+- Pagination GET requests: 2 → 1 in all three browser runs.
+
+### 25 entities
+- Cold production build: 14.04s → 8.92s (36.5% lower in this run).
+- Warm production build: 9.63s → 7.08s (26.5% lower in this run).
+- Cold dev startup: 8.38s → 6.97s (16.9% lower in this run).
+- Template rebuild: 6.98s → 6.06s (13.1% lower in this run).
+- Initial JS/CSS: 1,004,796 → 657,476 bytes (34.6% smaller).
+- First browser bootstrap (cold dev transforms): 4752 → 1121 ms.
+- Warm bootstrap (mean of runs 2–3): 177 → 136 ms.
+- Province rendered (median of 3): 522 → 296 ms.
+- Province refresh (median of 3): 481 → 333 ms.
+- Pagination GET requests: 2 → 1 in all three browser runs.
+
+
+## Verification
+
+Passed generator/config/workflow/PMB-preset, field-preference, list-state,
+auth-interceptor and new performance-generation tests. The 25-entity regression
+asserts single shared assets, lazy screens, strict compilation, root HTTP providers,
+SPA/SSR coherence and protection of customized shared components.
+
+Fresh apps passed production builds for both rendering modes and the Book/Author
+relationship fixture. SSR returned HTTP 200 with server-rendered sign-in content.
+Both generated manifest/lock pairs passed offline `npm ci --dry-run --ignore-scripts`;
+full builds used the same existing dependency directory. Docker images were not built.
+
+Browser checks passed: 25 existing demo/navigation/list/filter/form/detail/card/state
+checks; one related-list/create-dialog check; three profile/field/performance checks
+covering mocked login, current identity, refresh, logout/account switch, create/update
+payloads, deletion, single pagination/deletion refresh requests, and persistent column
+resizing. These tests use synthetic accounts and responses. Real PMB login, permissions,
+network latency and backend writes were NOT verified in this performance pass. Earlier
+manual login success is not evidence for the newly generated output.
+
+Existing unused-import warnings remain in some relationship components; optional SSR
+also warns about the 1 MB initial budget. Neither warning was suppressed or the budget
+raised. No runtime page errors occurred in the measured fixture browser runs.
+
+## Reproduce
+
+From the repository root (Node 24 and Chrome installed):
+
+```bash
+npm ci
+npm run test:performance
+# Install app dependencies once in an isolated fixture location if needed:
+CRUDFORGE_E2E_APP_DIR=/tmp/crudforge-perf-dependencies npm run e2e:prepare
+export CRUDFORGE_BENCH_MODULES=/tmp/crudforge-perf-dependencies/node_modules
+
+git worktree add --detach /tmp/crudforge-perf-baseline-source 5699fab319ff600e2e19e8bd85b23219e1adf26a
+npm ci --prefix /tmp/crudforge-perf-baseline-source
+CRUDFORGE_GENERATOR_ROOT=/tmp/crudforge-perf-baseline-source node scripts/performance/generate.js /tmp/crudforge-perf-before
+node scripts/performance/measure.js /tmp/crudforge-perf-before
+node scripts/performance/generate.js /tmp/crudforge-perf-after
+node scripts/performance/measure.js /tmp/crudforge-perf-after
+```
+
+Use fresh output paths, stop competing builds, and leave port 4301 free. The harness
+runs production builds, cold dev startup, three Chrome sessions and one template-edit
+rebuild serially, writes logs and `measurements.json`, then stops its server. The
+`CRUDFORGE_GENERATOR_ROOT` option lets the same current harness/fixtures use the baseline
+implementation and starter. Never regenerate the baseline with the changed generator.
+
+For your PMB project:
+
+```bash
+cd /Users/abdulla/Work/CRUD-FORDGE-SETUP/crud-fordge-testing-area
+crudforge init crudforge-app --preset pmb-test
+cd crudforge-app
+# Edit config/crudforge.config.yml and gdl/example.gdl as needed; rendering defaults to spa.
+crudforge generate
+npm ci
+npm start
+# Production validation:
+npm run build
+```
+
+For an existing project, skip init and run `crudforge generate --dry-run` first.
+Review conflicts and preserve custom work before selecting the existing overwrite
+option. Do not delete a customized project merely to benchmark. The reusable preset
+remains outside the app; no PMB source path is compiled into the application.
+
+Browser regression commands (run each server in a separate terminal):
+
+```bash
+npm run e2e:prepare:field-profile
+(cd e2e/.field-profile && NG_BUILD_MAX_WORKERS=2 npm start -- --host 127.0.0.1 --port 4202)
+CRUDFORGE_BROWSER_CHANNEL=chrome CRUDFORGE_UI_TEST_URL=http://127.0.0.1:4202 npx playwright test --config=playwright.field-profile.config.js
+
+CRUDFORGE_E2E_APP_DIR=/tmp/crudforge-perf-relationships npm run e2e:prepare
+(cd /tmp/crudforge-perf-relationships && NG_BUILD_MAX_WORKERS=2 npx ng serve --configuration mock --host 127.0.0.1 --port 4203)
+npx playwright test --config=playwright.performance.config.js
+```
+
+## Changed source files
+
+Build integration: `src/generator/fuse-build.js`, `src/generator/index.js`,
+`src/config/default-values.js`, `src/config/load-config.js`,
+`src/commands/init-config.js`, `config/default-config.yml`.
+
+Starter: `fuse-starter-pack/fuse-v21.1/{angular.json,tsconfig.app.json,package.json,package-lock.json}`,
+`src/app/app.config.ts` and `src/styles/styles.css` within that starter.
+
+Templates under `src/templates/angular/`: `entity/_entity_.routes.ts.ejs`,
+`shared/list-styles.css.ejs`, `shared/base/base-list.component.ts.ejs`, entity list
+TS/HTML/SCSS, form and form-page TS, form-service TS, detail/card TS, filter TS,
+entity service TS, and actions/card HTML. The service/filter/form-service changes
+correct relative imports for the centralized non-Fuse shared directory.
+
+Verification: `test/performance-generation.js`, `test/verify.js`,
+`test/fixtures/performance/*`, `scripts/performance/{generate,measure}.js`,
+`e2e/tests/{field-profile,generated-crud}.spec.js`,
+`playwright.performance.config.js`, and the root npm test script. Documentation and
+raw observations are in this directory and the root README.