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

package/docs/performance/after.json

@@ -0,0 +1,111 @@
+{
+  "machine": {
+    "platform": "darwin",
+    "arch": "arm64",
+    "cpus": 11,
+    "node": "v24.19.0"
+  },
+  "commands": {
+    "build": "node node_modules/@angular/cli/bin/ng.js build --configuration production --stats-json",
+    "serve": "node node_modules/@angular/cli/bin/ng.js serve --host 127.0.0.1 --port 4301",
+    "workers": 2
+  },
+  "fixtures": {
+    "small": {
+      "coldBuildSeconds": 4.325572875,
+      "warmBuildSeconds": 2.783962625,
+      "initialBytes": 655268,
+      "initialFiles": [
+        "styles-3TRNVMYE.css",
+        "chunk-NDOSOM7F.js",
+        "chunk-BWAQPUGJ.js",
+        "chunk-NSEZI5HP.js",
+        "chunk-2CGR3MGZ.js",
+        "chunk-JKJ4OYD6.js",
+        "chunk-UTORK2V4.js",
+        "chunk-QWS5T5GV.js",
+        "chunk-KWCZCL72.js",
+        "chunk-O7K3GK2S.js",
+        "chunk-SFBWYKT6.js",
+        "main-CFTZP4TH.js"
+      ],
+      "serverBundle": false,
+      "coldDevStartupSeconds": 2.122047791000001,
+      "browser": [
+        {
+          "interactiveMs": 954.5875830000004,
+          "fcpMs": null,
+          "entityLoadMs": 296.59912500000064,
+          "reloadMs": 314.25275000000147,
+          "paginationReads": 1,
+          "errors": []
+        },
+        {
+          "interactiveMs": 132.7291669999995,
+          "fcpMs": null,
+          "entityLoadMs": 274.55783299999894,
+          "reloadMs": 282.9455419999995,
+          "paginationReads": 1,
+          "errors": []
+        },
+        {
+          "interactiveMs": 132.1135830000003,
+          "fcpMs": null,
+          "entityLoadMs": 270.77529200000026,
+          "reloadMs": 300.5688339999997,
+          "paginationReads": 1,
+          "errors": []
+        }
+      ],
+      "rebuildSeconds": 1.1119830419999999
+    },
+    "large": {
+      "coldBuildSeconds": 8.916114916,
+      "warmBuildSeconds": 7.083413082999999,
+      "initialBytes": 657476,
+      "initialFiles": [
+        "styles-3TRNVMYE.css",
+        "chunk-NDOSOM7F.js",
+        "chunk-BWAQPUGJ.js",
+        "chunk-KES7LWDN.js",
+        "chunk-2CGR3MGZ.js",
+        "chunk-JKJ4OYD6.js",
+        "chunk-UTORK2V4.js",
+        "chunk-QWS5T5GV.js",
+        "chunk-KWCZCL72.js",
+        "chunk-O7K3GK2S.js",
+        "chunk-SFBWYKT6.js",
+        "main-PW4HZ76G.js"
+      ],
+      "serverBundle": false,
+      "coldDevStartupSeconds": 6.968824999999997,
+      "browser": [
+        {
+          "interactiveMs": 1120.5042499999981,
+          "fcpMs": null,
+          "entityLoadMs": 317.80737500000396,
+          "reloadMs": 333.49874999999884,
+          "paginationReads": 1,
+          "errors": []
+        },
+        {
+          "interactiveMs": 134.8382500000007,
+          "fcpMs": null,
+          "entityLoadMs": 296.3120409999974,
+          "reloadMs": 381.8153749999983,
+          "paginationReads": 1,
+          "errors": []
+        },
+        {
+          "interactiveMs": 137.86237499999697,
+          "fcpMs": null,
+          "entityLoadMs": 295.4111669999984,
+          "reloadMs": 291.98920799999905,
+          "paginationReads": 1,
+          "errors": []
+        }
+      ],
+      "rebuildSeconds": 6.060445290999996
+    }
+  }
+}

package/docs/performance/before.json

@@ -0,0 +1,111 @@
+{
+  "machine": {
+    "platform": "darwin",
+    "arch": "arm64",
+    "cpus": 11,
+    "node": "v24.19.0"
+  },
+  "commands": {
+    "build": "node node_modules/@angular/cli/bin/ng.js build --configuration production --stats-json",
+    "serve": "node node_modules/@angular/cli/bin/ng.js serve --host 127.0.0.1 --port 4301",
+    "workers": 2
+  },
+  "fixtures": {
+    "small": {
+      "coldBuildSeconds": 7.520871584,
+      "warmBuildSeconds": 5.613279083,
+      "initialBytes": 1002588,
+      "initialFiles": [
+        "styles-4E7FUNNQ.css",
+        "chunk-BYVIJEIQ.js",
+        "chunk-XDBVZKKQ.js",
+        "chunk-7EHZJMZS.js",
+        "chunk-RTKC6PBC.js",
+        "chunk-CO7JMNBJ.js",
+        "chunk-DCCJNBDI.js",
+        "chunk-G523QTT6.js",
+        "chunk-P5WENFS4.js",
+        "chunk-CGQZTJAX.js",
+        "chunk-CBEDY7LG.js",
+        "main-5LKUABOL.js"
+      ],
+      "serverBundle": true,
+      "coldDevStartupSeconds": 3.029542209000001,
+      "browser": [
+        {
+          "interactiveMs": 3774.997625,
+          "fcpMs": 3612,
+          "entityLoadMs": 442.23766700000124,
+          "reloadMs": 428.81758400000035,
+          "paginationReads": 2,
+          "errors": []
+        },
+        {
+          "interactiveMs": 190.69912499999919,
+          "fcpMs": 92,
+          "entityLoadMs": 345.5164999999979,
+          "reloadMs": 373.8043749999997,
+          "paginationReads": 2,
+          "errors": []
+        },
+        {
+          "interactiveMs": 177.2548330000027,
+          "fcpMs": 76,
+          "entityLoadMs": 342.033958,
+          "reloadMs": 519.2770000000019,
+          "paginationReads": 2,
+          "errors": []
+        }
+      ],
+      "rebuildSeconds": 1.6145452910000022
+    },
+    "large": {
+      "coldBuildSeconds": 14.040262583000004,
+      "warmBuildSeconds": 9.634600542,
+      "initialBytes": 1004796,
+      "initialFiles": [
+        "styles-4E7FUNNQ.css",
+        "chunk-BYVIJEIQ.js",
+        "chunk-XDBVZKKQ.js",
+        "chunk-334JRSXR.js",
+        "chunk-RTKC6PBC.js",
+        "chunk-CO7JMNBJ.js",
+        "chunk-DCCJNBDI.js",
+        "chunk-G523QTT6.js",
+        "chunk-P5WENFS4.js",
+        "chunk-CGQZTJAX.js",
+        "chunk-CBEDY7LG.js",
+        "main-AX5WANX6.js"
+      ],
+      "serverBundle": true,
+      "coldDevStartupSeconds": 8.382417332999998,
+      "browser": [
+        {
+          "interactiveMs": 4752.308290999994,
+          "fcpMs": 4576,
+          "entityLoadMs": 695.3545000000013,
+          "reloadMs": 480.5537089999998,
+          "paginationReads": 2,
+          "errors": []
+        },
+        {
+          "interactiveMs": 171.2327920000098,
+          "fcpMs": 84,
+          "entityLoadMs": 521.7752499999915,
+          "reloadMs": 488.31937499999185,
+          "paginationReads": 2,
+          "errors": []
+        },
+        {
+          "interactiveMs": 182.0655839999963,
+          "fcpMs": 76,
+          "entityLoadMs": 469.2784580000007,
+          "reloadMs": 405.61333300000115,
+          "paginationReads": 2,
+          "errors": []
+        }
+      ],
+      "rebuildSeconds": 6.975476750000001
+    }
+  }
+}

package/docs/quality/README.md

@@ -0,0 +1,276 @@
+# Generated tests, validation, and doctor
+
+These features are optional additions to initialize → edit → generate. They do not
+create backend infrastructure, change authentication providers, or infer backend
+capabilities from a product name.
+
+## Project configuration
+
+Add this to `config/crudforge.config.yml` before generation:
+
+```yaml
+generate:
+  globals:
+    tests: true
+
+testing:
+  ci: true
+  fixtures:
+    Farmer:
+      referenceCode: AB12
+
+backend:
+  kind: custom
+
+doctor:
+  timeoutMs: 3000
+  endpoints: []
+```
+
+`generate.globals.tests` defaults to false; previously it emitted no tests. The
+older example's `generate.tests` is not the supported setting. `testing.ci` defaults
+to false and requires test generation. Tests currently target complete Fuse apps,
+with generated list components, forms and routes. Component-only output has no
+standalone application to start, so requesting tests for that output is rejected.
+
+`testing.fixtures` supplies synthetic field values, particularly for pattern rules
+that cannot be safely guessed. Omit this mapping when unnecessary. Do not store real
+passwords, tokens, or customer records in fixtures. Primitive fields and enums get
+sample values; relationships reference records in the related entity's mock collection.
+
+`backend.kind` is informational and can identify GO-DUCK, JHipster, or a custom backend.
+It never changes naming conventions or certifies a live contract. Configure the
+existing `api.microservice`, `api.baseUrl`, `api.services`, proxy, and auth settings
+for the actual deployment. Current generated services use zero-based page/size,
+array responses and `X-Total-Count`, with kebab-plural paths and Dayjs dates. A backend
+with different behavior needs a tested adapter; unsupported service modes produce
+explicit diagnostics instead of being silently ignored.
+
+## Run the application tests
+
+```bash
+crudforge generate --dry-run
+# Review conflicts; use the existing explicit overwrite policy when appropriate.
+crudforge generate
+npm ci
+npm run test:smoke:install
+npm run build
+npm run test:smoke
+```
+
+The generated app declares its required Node version in `package.json`; the bundled
+Angular 21 starter requires Node 24+. Playwright is pinned in both the generated
+manifest and lockfile. Generation itself does not install packages or browsers.
+
+The test server uses port **4297** on `127.0.0.1`. It starts its own server and refuses
+to reuse an existing one. Tests use a separate Angular build configuration, an empty
+proxy configuration, and SSR disabled. HTTP/API/auth requests are intercepted in the
+browser; unknown requests are blocked. Service workers are disabled and external
+WebSocket connections are blocked. Only local application assets and the local dev
+server's WebSocket are allowed. Production environments and normal `npm start` are
+not switched to mock mode.
+
+The suite covers startup, each entity's navigation and pagination, required text or
+numeric fields when present, create/edit submissions, failed-save recovery, loading
+and failed-list recovery. Authentication-enabled apps also check the synthetic user
+identity across refresh. Generated tests verify UI and HTTP behavior against mocks;
+they do **not** verify real credentials, server-side permissions, database persistence,
+production routing, or full backend compatibility.
+
+Tests use a development build for observable loading behavior; CI separately runs
+the unchanged strict production build. They are smoke tests, not exhaustive
+business-rule coverage. Advanced custom controls/workflows need custom tests.
+
+## Add a developer-owned test
+
+Generator-managed files are in `tests/generated/`. Create your own file at
+`tests/custom/dashboard.spec.cjs`:
+
+```js
+const { test, expect } = require('../generated/mock.cjs');
+
+test('my dashboard opens', async ({ page, backend }) => {
+  await backend.login(page);
+  await page.goto('/admin/my-dashboard');
+  await expect(page.getByRole('heading', { name: 'My Dashboard' })).toBeVisible();
+});
+```
+
+Replace the route and heading with your screen. Both folders run through
+`npm run test:smoke`. The generator never emits files into `tests/custom/`.
+Normal conflict policies apply to generated tests, package files, and the generated
+CI workflow. Changes to generator-managed files are not silently accepted or overwritten
+by the project generation command. Prefer custom tests for application-specific assertions.
+
+## CI
+
+`testing.ci: true` emits `.github/workflows/crudforge-smoke.yml`. It checks out source,
+selects Node using package.json, installs dependencies, runs the strict production
+build, installs Chromium, and runs the smoke suite. Failure artifacts include the
+HTML report and screenshots, retained for seven days. Tracing/video are disabled.
+Fixtures are synthetic; do not introduce live secrets or live requests into custom tests
+whose screenshots may be uploaded.
+
+The underlying commands also work outside GitHub Actions:
+
+```bash
+node tests/generated/ci.cjs install
+node tests/generated/ci.cjs build
+node tests/generated/ci.cjs browsers
+node tests/generated/ci.cjs test
+```
+
+The helper requires exactly one lockfile matching `package.json.packageManager`
+when that field is declared. It uses npm ci, pnpm frozen-lockfile, Yarn 1 frozen-lockfile,
+or modern Yarn immutable installs. Fresh CRUDForge apps use npm and package-lock.json.
+Changing package managers and converting the lockfile is a deliberate developer action,
+not something the generator or doctor does automatically. Pin non-npm manager versions
+in `packageManager`; the workflow installs Corepack to make those managers available.
+
+The test server working directory is explicit, as documented by
+[Playwright](https://playwright.dev/docs/test-webserver). Service-worker isolation follows
+[Playwright's routing guidance](https://playwright.dev/docs/service-workers).
+Node selection follows [setup-node's version-file support](https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md).
+
+## Shared schema validation
+
+```bash
+crudforge validate gdl/example.gdl --preferences config/crudforge.config.yml
+crudforge validate gdl/example.gdl --preferences config/crudforge.config.yml --json
+crudforge generate --json --yes
+```
+
+`validate-gdl` and `validate-jdl` accept the same options. The CLI validate and generate
+commands and `generateFromSource` use one diagnostic/parse pipeline. It checks syntax,
+duplicate declarations/fields, known types, enum values, rule applicability and ranges,
+relationship targets, display-field references, relationship/scalar/FK collisions,
+audit-field collisions, TypeScript-safe identifiers, output filename collisions,
+unsupported annotations, and configured field preferences. Balanced blocks are parsed
+without truncating regex quantifier braces in fields.
+
+Diagnostics have `severity`, `code`, `file`, `line`, `column`, optional `entity`/`field`,
+`message`, and `suggestion`. JSON output is a single object with `ok`, `diagnostics`,
+and entity count. Generate also accepts `--json` (progress goes to stderr). Errors exit 1; warnings alone exit 0. Configuration/read failures
+also exit 1. Backend contract checks are kept separate from general schema checks.
+
+Unknown annotations and unimplemented behavior are errors. The frontend supports
+`@Audited` in GDL and `@EnableAudit` in JDL. Backend-only annotations such as SoftDelete
+are not silently discarded. Custom relationship display-field arguments are currently
+rejected: selectors use name, title or id. Plain relationship fields are supported.
+Naming styles are not forced to GO-DUCK or JHipster conventions.
+
+**Compatibility change:** `validation: false` no longer bypasses the fail-fast gate.
+Invalid schemas stop generation before application files are written. The existing
+low-level parser exports remain available, but generation uses the validated structure.
+
+## Doctor: local checks
+
+```bash
+cd crudforge-app
+crudforge doctor
+crudforge doctor --json
+crudforge doctor --preferences config/crudforge.config.yml
+```
+
+Local checks make no HTTP requests. They check CLI version, project/config discovery,
+schema diagnostics, Node engine compatibility, starter/output paths, dependency
+presence, package-manager/lockfile consistency, npm root dependency drift, development
+port availability, and API/proxy/auth configuration. Port checks briefly bind and close
+an IPv4 loopback socket; an occupied or unbindable port is a warning, never a reason to
+kill a process. Yarn PnP resolution is reported as unverified rather than executed.
+
+Doctor never installs dependencies, modifies files, provisions services, or sends
+write requests. It prints pass/warning/fail results and next steps. Known sensitive
+configuration values are redacted. Malformed configuration is reported without dumping
+its contents. Exit 0 means no failed checks; warnings remain visible. Exit 1 means a
+failed check or inability to complete diagnosis. It is not proof that CRUD works.
+
+## Optional live checks
+
+Only configure endpoints that your backend documents as read-only:
+
+```yaml
+doctor:
+  timeoutMs: 2000
+  endpoints:
+    - url: http://127.0.0.1:8080/documented-read-only-status
+      description: Replace this URL with the service's documented read-only status endpoint.
+```
+
+```bash
+crudforge doctor --live
+crudforge doctor --live --json
+```
+
+Doctor does not invent a health endpoint or attach credentials. Endpoints must use
+HTTP(S), with no URL credentials, query parameters or fragments. It sends GET only,
+does not follow redirects, and applies a 100–10000 ms deadline per endpoint. Responses
+are categorized as reachable, authentication required (401), access denied (403),
+endpoint/client failure, server failure, transport failure, or timeout. Authentication
+requirements/denials are warnings, not proof of a broken server. No response bodies
+or tokens are printed.
+
+## If `crudforge` is not found
+
+A shell PATH problem occurs before doctor can run. Use the repository entry point:
+
+```bash
+node /Users/abdulla/Work/crud-fordge/cli.js doctor \
+  --preferences /path/to/crudforge-app/config/crudforge.config.yml
+```
+
+If dependencies are missing, run `npm ci` in the CRUDForge repository yourself. To
+make the short command available, run `npm link` there, then `command -v crudforge`.
+Check that your active Node installation's npm global bin directory is on PATH.
+Doctor does not perform installation or change shell settings.
+
+## Maintainer verification
+
+```bash
+npm test
+npm run test:quality
+npm run test:field-preferences
+npm run test:auth
+npm run test:ui-state
+npm run test:performance
+node scripts/prepare-quality-apps.js /tmp/crudforge-quality-check
+```
+
+The last command requires a new output directory and generates GO-DUCK-labelled,
+JHipster-labelled and custom configurations with different API prefixes and auth
+modes. Each uses the same documented HTTP response contract; the labels do not claim
+live vendor integration. In each generated directory, run the CI commands above.
+The representative GDL includes enums, required values, dates, booleans, a regex pattern,
+and a relationship. No live backend is involved.
+
+## Verification results (October 11, 2026)
+
+The repository test suite and the field-preference, authentication, UI-state, and
+performance regressions passed. The quality regression suite also passed after
+final validation changes. It covers malformed schemas, structured CLI failures,
+custom-test preservation, local doctor failures, HTTP status classification and
+timeouts, and package-manager command selection.
+
+Fresh generated applications passed these checks on this machine:
+
+- A clean `npm ci` and strict production build in the representative application.
+- GO-DUCK-labelled configuration: 8 mocked browser tests passed.
+- JHipster-labelled configuration: 9 mocked browser tests and production build passed.
+- Custom API-prefix configuration: 8 mocked browser tests and production build passed.
+- SSR-configured application: 8 browser tests passed using the isolated browser-only
+  smoke configuration. Its normal SSR production build was not run in this task.
+
+Browser verification used installed Chrome through
+`CRUDFORGE_BROWSER_CHANNEL=chrome npm run test:smoke`. Generated CI instead installs
+Playwright Chromium. The GitHub-hosted workflow was not executed; npm installation
+was exercised locally, while pnpm/Yarn command selection was regression-tested.
+No real backend, real account, or production record was used. These results verify
+frontend behavior against configured mock contracts, not GO-DUCK/JHipster server
+compatibility or live authentication.
+
+The implementation is concentrated in `src/generator/application-tests.js` and
+`src/templates/testing/`, the shared `src/validator/diagnostics.js` pipeline and
+backend/pattern helpers, and `src/commands/doctor.js`. CLI wiring, configuration
+schemas/defaults, generation/validation entry points, and the form-validation
+template integrate these features. Fixtures and regressions live in
+`test/fixtures/quality/` and `test/quality-features.js`.

package/e2e/crudforge.e2e.yml

@@ -0,0 +1,47 @@
+project:
+  name: CRUDForge E2E
+  description: Generated Fuse app used by Playwright
+
+output:
+  # Overridden by scripts/e2e-prepare*.js → $CRUDFORGE_TESTING_AREA/crudforge-app
+  directory: "./e2e/.app"
+  structure: "entity-folder"
+  overwritePolicy: "overwrite"
+  embedConfig: true
+  teamPack:
+    enabled: true
+
+validation: true
+
+fuse:
+  enabled: true
+  cleanLayout: true
+  includePrebuilt: false
+  folderType: ""
+  theme:
+    scheme: "light"
+    primary: "#0f766e"
+    error: "#b91c1c"
+
+ui:
+  framework: "material"
+  viewMode: "table"
+  formMode: "sidebar"
+  searchMode: "field"
+  snackbarPositionTop: false
+
+api:
+  baseUrl: "/api"
+  microservice: "book-service"
+  endpointStyle: "kebab-plural"
+  dateLibrary: "dayjs"
+  responseType: "http-response"
+
+mock:
+  enabled: true
+  recordsPerEntity: 12
+  values:
+    stringPrefix: "Mock "
+    numberMin: 1
+    numberMax: 1000
+    booleanDefault: true

package/e2e/crudforge.field-profile.yml

@@ -0,0 +1,33 @@
+project:
+  name: Field and profile regression fixture
+output:
+  directory: ./e2e/.field-profile
+  overwritePolicy: overwrite
+fuse:
+  enabled: true
+  cleanLayout: true
+  includePrebuilt: false
+api:
+  microservice: pmb-reference-module
+  baseUrl: /api
+mock:
+  enabled: false
+fields:
+  entities:
+    Province:
+      fields:
+        provinceCode: { inputFormat: uppercase }
+        provinceName: { inputFormat: lowercase }
+        index: { inputFormat: none }
+auth:
+  provider: keycloak
+  realm: test
+  clientId: test-client
+  # Deliberately non-live: Playwright intercepts every auth and API request.
+  serverUrl: http://127.0.0.1:9999
+  useMockAuth: false
+  provision:
+    enabled: false
+    adminServiceUrl: http://127.0.0.1:9999
+iam:
+  enabled: false