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

package/scripts/performance/measure.js

@@ -0,0 +1,55 @@
+// Serial measurements. Cold means empty Angular disk cache, not an OS cache flush.
+const fs=require('fs-extra'),path=require('path'),os=require('os');
+const {spawn}=require('child_process');
+const {performance}=require('perf_hooks');
+const {chromium}=require('@playwright/test');
+const root=path.resolve(process.argv[2]);
+const results={machine:{platform:os.platform(),arch:os.arch(),cpus:os.cpus().length,node:process.version},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:{}};
+function command(cwd,args,log){return new Promise((resolve,reject)=>{const start=performance.now();const stream=fs.createWriteStream(log);const child=spawn(process.execPath,['node_modules/@angular/cli/bin/ng.js',...args],{cwd,env:{...process.env,NG_BUILD_MAX_WORKERS:'2'},stdio:['ignore','pipe','pipe']});child.stdout.pipe(stream);child.stderr.pipe(stream);child.on('error',reject);child.on('exit',code=>{stream.end();code===0?resolve((performance.now()-start)/1000):reject(new Error(`Command failed (${code}), see ${log}`));});});}
+async function browserMetrics(url){
+ const browser=await chromium.launch({channel:process.env.CRUDFORGE_BROWSER_CHANNEL||'chrome'});
+ const runs=[];
+ try { for(let i=0;i<3;i++) {
+  const context=await browser.newContext();const page=await context.newPage();let reads=0;const errors=[];page.on('pageerror',e=>errors.push(e.message));
+  await page.route('**/*',async route=>{const u=new URL(route.request().url());
+   if(u.pathname.endsWith('/token')){const token='test.'+Buffer.from(JSON.stringify({sub:'benchmark',name:'Benchmark User',email:'benchmark@example.test',exp:Math.floor(Date.now()/1000)+3600,realm_access:{roles:['ROLE_ADMIN']}})).toString('base64url')+'.test';return route.fulfill({json:{access_token:token,refresh_token:'benchmark-refresh',expires_in:3600}});}
+   if(u.pathname.includes('/services/keycloak-admin/')) return route.fulfill({json:{id:'benchmark',attributes:{province:['VIEW']}}});
+   if(u.pathname.includes('/api/provinces')){reads++;return route.fulfill({headers:{'X-Total-Count':'100'},json:[{id:1,index:'1',provinceCode:'AB',provinceName:'Benchmark Province',isActive:true}]});}
+   if(u.hostname!=='127.0.0.1')return route.abort();return route.continue();
+  });
+  let t=performance.now();await page.goto(url+'/auth/sign-in',{waitUntil:'domcontentloaded'});
+  await page.waitForFunction(()=>{const e=document.querySelector('auth-sign-in');return !!e&&!!window.ng?.getComponent(e);});
+  const interactiveMs=performance.now()-t;
+  const fcpMs=await page.evaluate(()=>performance.getEntriesByName('first-contentful-paint')[0]?.startTime??null);
+  await page.getByLabel('Username or email').fill('benchmark');await page.getByLabel('Password',{exact:true}).fill('test');await page.getByRole('button',{name:'Sign in',exact:true}).click();await page.waitForURL(/\/admin/);
+  t=performance.now();await page.goto(url+'/admin/province');await page.getByRole('cell',{name:'Benchmark Province',exact:true}).waitFor();const entityLoadMs=performance.now()-t;
+  const firstReads=reads;await page.getByRole('button',{name:'Next page'}).click();await page.waitForTimeout(500);const paginationReads=reads-firstReads;
+  t=performance.now();await page.reload();await page.getByRole('cell',{name:'Benchmark Province',exact:true}).waitFor();const reloadMs=performance.now()-t;
+  runs.push({interactiveMs,fcpMs,entityLoadMs,reloadMs,paginationReads,errors});await context.close();
+ }}finally{await browser.close();}return runs;
+}
+(async()=>{
+ for(const size of ['small','large']){
+  const cwd=path.join(root,size),metric={};results.fixtures[size]=metric;
+  await fs.remove(path.join(cwd,'.angular/cache'));await fs.remove(path.join(cwd,'dist'));
+  metric.coldBuildSeconds=await command(cwd,['build','--configuration','production','--stats-json'],path.join(root,size+'-cold.log'));
+  metric.warmBuildSeconds=await command(cwd,['build','--configuration','production','--stats-json'],path.join(root,size+'-warm.log'));
+  const browserDir=path.join(cwd,'dist/fuse/browser');const html=await fs.readFile(path.join(browserDir,fs.existsSync(path.join(browserDir,'index.html'))?'index.html':'index.csr.html'),'utf8');
+  const entries=[...new Set([...html.matchAll(/(?:src|href)="([^"?#]+\.(?:js|css))"/g)].map(m=>m[1]))];
+  metric.initialBytes=entries.reduce((n,f)=>n+fs.statSync(path.join(browserDir,f)).size,0);
+  metric.initialFiles=entries;metric.serverBundle=await fs.pathExists(path.join(cwd,'dist/fuse/server'));
+  await fs.remove(path.join(cwd,'.angular/cache'));
+  const started=performance.now();let output='';const log=fs.createWriteStream(path.join(root,size+'-serve.log'));
+  const server=spawn(process.execPath,['node_modules/@angular/cli/bin/ng.js','serve','--host','127.0.0.1','--port','4301'],{cwd,env:{...process.env,NG_BUILD_MAX_WORKERS:'2'},stdio:['ignore','pipe','pipe']});
+  server.stdout.on('data',b=>{output+=b.toString();log.write(b);});server.stderr.on('data',b=>{output+=b.toString();log.write(b);});
+  const wait=async predicate=>{const deadline=Date.now()+180000;while(!predicate()){if(server.exitCode!==null||Date.now()>deadline)throw new Error('Serve/rebuild failed: '+output.slice(-2000));await new Promise(r=>setTimeout(r,100));}};
+  try{
+   await wait(()=>output.includes('Local:'));metric.coldDevStartupSeconds=(performance.now()-started)/1000;
+   metric.browser=await browserMetrics('http://127.0.0.1:4301');
+   const apps=path.join(cwd,'src/app/domains/admin/modules/apps');const folder=fs.existsSync(path.join(apps,'micro-functions'))?'micro-functions':'microservice';const file=path.join(apps,folder,'province/components/presentation/list/province-list.component.html');const original=await fs.readFile(file,'utf8');
+   output='';const rebuild=performance.now();await fs.writeFile(file,original.replace('Province Management','Province Management Benchmark'));
+   try{await wait(()=>output.includes('Application bundle generation complete'));metric.rebuildSeconds=(performance.now()-rebuild)/1000;}finally{await fs.writeFile(file,original);}
+  }finally{server.kill('SIGTERM');await new Promise(resolve=>server.once('exit',resolve));log.end();}
+  await fs.writeJson(path.join(root,'measurements.json'),results,{spaces:2});console.log(size,JSON.stringify(metric));
+ }
+})().catch(e=>{console.error(e);process.exitCode=1;});

package/scripts/postinstall.js

@@ -0,0 +1,9 @@
+const path = require('path');
+
+try {
+  const branding = require('../src/utils/branding');
+  branding.printBanner();
+} catch (e) {
+  // Gracefully suppress any exceptions to avoid breaking or blocking npm install
+}
+process.exit(0);

package/scripts/prepare-quality-apps.js

@@ -0,0 +1,34 @@
+const fs = require("fs-extra"),
+  path = require("path");
+const { generateFromSource } = require("../src");
+(async () => {
+  if (!process.argv[2])
+    throw Error(
+      "Usage: node scripts/prepare-quality-apps.js <new-output-directory>",
+    );
+  const root = path.resolve(process.argv[2]);
+  if (await fs.pathExists(root))
+    throw Error("Use a new output directory to preserve existing work.");
+  const fixture = path.resolve(
+    __dirname,
+    "../test/fixtures/quality/representative.gdl",
+  );
+  for (const kind of ["go-duck", "jhipster", "custom"]) {
+    const output = path.join(root, kind);
+    await generateFromSource(await fs.readFile(fixture, "utf8"), {
+      filePath: fixture,
+      outputDirectory: output,
+      configPath: path.resolve(
+        __dirname,
+        "../test/fixtures/quality/" + kind + ".yml",
+      ),
+    });
+    await fs.outputFile(
+      path.join(output, "gdl/example.gdl"),
+      await fs.readFile(fixture, "utf8"),
+    );
+  }
+})().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/scripts/run-config-tests.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const YAML = require('yaml');
+
+const root = path.resolve(__dirname, '..');
+const mode = process.argv[2] || 'ci';
+const area = path.resolve(process.env.CRUDFORGE_TESTING_AREA ||
+  '/Users/abdulla/Work/CRUD-FORDGE-SETUP/crud-fordge-testing-area');
+
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} failed (${result.signal || result.status})`);
+}
+
+async function main() {
+  if (mode === '--help' || mode === '-h') {
+    console.log('Usage: ./run-config-tests.sh [validate|generate|ci]\n' +
+      'Default ci: validate GDL, run generator tests, generate app, install dependencies, build development.\n' +
+      'Set CRUDFORGE_TESTING_AREA to override the testing directory.\n' +
+      'New projects: <testing-area>/crudforge-app/config/crudforge.config.yml.\n' +
+      'Set CRUDFORGE_PROJECT_DIR to select another initialized project.');
+    return;
+  }
+  if (!['validate', 'generate', 'ci'].includes(mode)) throw new Error(`Unknown mode: ${mode}`);
+  const project = path.resolve(process.env.CRUDFORGE_PROJECT_DIR || path.join(area, 'crudforge-app'));
+  const { loadConfig } = require('../src/config/load-config');
+  const { configPath } = await loadConfig(project, null, { required: true, projectPaths: true });
+  // Require the explicit input and output settings for this QA workflow.
+  const config = YAML.parse(fs.readFileSync(configPath, 'utf8'));
+  if (!config?.input?.file || !config?.output?.directory || !config?.api?.microservice) {
+    throw new Error('Config requires input.file, output.directory, and api.microservice.');
+  }
+  if (config.dryRun || config.validation === false || config.fuse?.enabled !== true) {
+    throw new Error('Testing requires dryRun: false, validation: true, and fuse.enabled: true.');
+  }
+  const input = fs.realpathSync(path.resolve(project, config.input.file));
+  const output = path.resolve(project, config.output.directory);
+  if (output !== project) throw new Error('Project testing requires output.directory: ".".');
+  if (fs.lstatSync(project).isSymbolicLink()) throw new Error('The project directory must not be a symbolic link.');
+  const { parseGdl } = require('../src/parser/gdl-parser');
+  if (!input.endsWith('.gdl') || !parseGdl(fs.readFileSync(input, 'utf8'), config).entities.length) {
+    throw new Error('input.file must be a GDL file containing at least one entity.');
+  }
+  console.log(`Testing area: ${area}\nConfig: ${configPath}\nSchema: ${input}\nOutput: ${output}`);
+  run(process.execPath, [path.join(root, 'cli.js'), 'validate', input], project);
+  if (mode === 'validate') return;
+  if (mode === 'ci') run('npm', ['test'], root);
+  run(process.execPath, [path.join(root, 'cli.js'), 'generate', '--preferences', configPath, '--yes',
+    ...(process.env.CRUDFORGE_OVERWRITE_POLICY ? ['--overwrite-policy', process.env.CRUDFORGE_OVERWRITE_POLICY] : [])], project);
+  if (mode === 'ci') {
+    if (!fs.existsSync(path.join(output, 'node_modules/.bin/ng'))) {
+      run('npm', [fs.existsSync(path.join(output, 'package-lock.json')) ? 'ci' : 'install',
+        '--no-audit', '--no-fund'], output);
+    }
+    run('npm', ['run', 'build:dev'], output);
+  }
+  console.log(`${mode} passed. Generated app: ${output}`);
+}
+
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/src/commands/bootstrap.js

@@ -0,0 +1,92 @@
+const path = require('path');
+const colors = require('../utils/colors');
+const { loadConfig } = require('../config/load-config');
+const { loadEnvFile } = require('../config/env-refs');
+const { deriveAuthUrls, validateAuthConfig } = require('../config/auth-config');
+
+function loadRunBootstrap() {
+  try {
+    return require('../provision/bootstrap');
+  } catch (err) {
+    const message = err && err.message ? String(err.message) : '';
+    const missingProvision =
+      err &&
+      err.code === 'MODULE_NOT_FOUND' &&
+      (message.includes('provision/bootstrap') || message.includes('provision\\bootstrap'));
+    if (missingProvision) {
+      throw new Error(
+        'Keycloak provisioning is not available: src/provision/bootstrap.js is missing. Implement the provision module before running `crudforge bootstrap`.'
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Thin CLI wrapper: load env + config, validate, then delegate to provision.
+ * Does not implement Keycloak mutations itself.
+ */
+async function bootstrapCommand(options = {}) {
+  const cwd = process.cwd();
+
+  if (options.envFile) {
+    const envPath = path.isAbsolute(options.envFile)
+      ? options.envFile
+      : path.resolve(cwd, options.envFile);
+    loadEnvFile(envPath);
+  }
+
+  const { config, configPath } = await loadConfig(cwd, options.preferences);
+  if (configPath) {
+    console.log(colors.cyan(`🔵 Loaded configuration preferences from: ${configPath}`));
+  } else {
+    console.log(colors.dim('🔵 No configuration file found. Using default developer preferences.'));
+  }
+
+  config.auth = config.auth || {};
+  config.auth.provision = config.auth.provision || {};
+  if (process.env.CRUDFORGE_KC_SERVER_URL) {
+    config.auth.serverUrl = process.env.CRUDFORGE_KC_SERVER_URL;
+  }
+  if (process.env.CRUDFORGE_KC_REALM) {
+    config.auth.realm = process.env.CRUDFORGE_KC_REALM;
+  }
+  if (process.env.CRUDFORGE_KC_CLIENT_ID) {
+    config.auth.clientId = process.env.CRUDFORGE_KC_CLIENT_ID;
+    config.auth.provision.clientId = config.auth.provision.clientId || process.env.CRUDFORGE_KC_CLIENT_ID;
+  }
+  if (process.env.CRUDFORGE_KC_ADMIN_SERVICE_URL) {
+    config.auth.provision.adminServiceUrl = process.env.CRUDFORGE_KC_ADMIN_SERVICE_URL;
+  }
+  if (process.env.CRUDFORGE_KC_FORWARDED_PROTO) {
+    config.auth.forwardedProto = process.env.CRUDFORGE_KC_FORWARDED_PROTO;
+  }
+  if (options.dryRun) {
+    config.auth.provision.dryRun = true;
+  }
+
+  deriveAuthUrls(config.auth);
+  validateAuthConfig(config, { requireProvision: true });
+
+  const provision = loadRunBootstrap();
+  if (options.cleanup) {
+    if (typeof provision.runCleanup !== 'function') {
+      throw new Error('src/provision/bootstrap.js must export runCleanup(config, options).');
+    }
+    await provision.runCleanup(config, { preferences: options.preferences });
+    return;
+  }
+
+  if (typeof provision.runBootstrap !== 'function') {
+    throw new Error(
+      'Keycloak provisioning is not available: src/provision/bootstrap.js must export runBootstrap(config, options).'
+    );
+  }
+
+  await provision.runBootstrap(config, {
+    dryRun: !!options.dryRun,
+    preferences: options.preferences,
+  });
+}
+
+module.exports = { bootstrapCommand };

package/src/commands/doctor.js

@@ -0,0 +1,403 @@
+const fs = require("fs-extra");
+const path = require("path");
+const net = require("net");
+const http = require("http");
+const https = require("https");
+const { loadConfig } = require("../config/load-config");
+const { analyzeSchema } = require("../validator/diagnostics");
+
+function safeUrl(raw) {
+  try {
+    const u = new URL(raw);
+    return u.origin + u.pathname;
+  } catch {
+    return "[invalid URL]";
+  }
+}
+function probe(raw, timeoutMs = 3000) {
+  return new Promise((resolve) => {
+    let url;
+    try {
+      url = new URL(raw);
+      if (
+        !["http:", "https:"].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash
+      )
+        throw Error();
+    } catch {
+      return resolve({
+        status: "fail",
+        message:
+          "Use an HTTP(S) endpoint without credentials, query parameters or fragments.",
+      });
+    }
+    const req = (url.protocol === "https:" ? https : http).request(
+      url,
+      { method: "GET", headers: { Accept: "application/json" } },
+      (res) => {
+        res.resume();
+        const code = res.statusCode;
+        resolve({
+          status:
+            code < 400
+              ? "pass"
+              : code === 401 || code === 403
+                ? "warning"
+                : "fail",
+          message: `HTTP ${code}: ${code === 401 ? "authentication required" : code === 403 ? "access denied" : code >= 500 ? "server error" : code >= 400 ? "endpoint unavailable" : code >= 300 ? "redirect returned (not followed)" : "endpoint reachable; CRUD behavior unverified"}.`,
+        });
+      },
+    );
+    const timer = setTimeout(
+      () => req.destroy(new Error("timeout")),
+      timeoutMs,
+    );
+    req.on("error", (error) =>
+      resolve({
+        status: "fail",
+        message:
+          error.message === "timeout"
+            ? "Connection timed out."
+            : `Connection failed (${error.code || "transport error"}).`,
+      }),
+    );
+    req.on("close", () => clearTimeout(timer));
+    req.end();
+  });
+}
+function portAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.listen({ port, host: "127.0.0.1" }, () =>
+      server.close(() => resolve(true)),
+    );
+  });
+}
+async function diagnose({
+  cwd = process.cwd(),
+  preferences,
+  live = false,
+  nodeVersion = process.versions.node,
+} = {}) {
+  const checks = [];
+  const add = (id, status, message, next = "") =>
+    checks.push({ id, status, message, next });
+  const cli = require("../../package.json");
+  add("cli", "pass", `CRUDForge ${cli.version}; Node ${nodeVersion}.`);
+  let loaded;
+  try {
+    loaded = await loadConfig(cwd, preferences, {
+      required: true,
+      projectPaths: true,
+    });
+    add("config", "pass", `Configuration: ${loaded.configPath}`);
+  } catch {
+    add(
+      "config",
+      "fail",
+      "Configuration is missing or malformed.",
+      "Run init or correct --preferences and YAML/JSON syntax; use validate for schema diagnostics.",
+    );
+    return { ok: false, checks };
+  }
+  const { config, projectRoot } = loaded;
+  const pkgPath = path.join(projectRoot, "package.json");
+  let pkg = null;
+  try {
+    if (await fs.pathExists(pkgPath)) pkg = await fs.readJson(pkgPath);
+  } catch {
+    add(
+      "package",
+      "fail",
+      "package.json is malformed.",
+      "Correct the JSON before installing dependencies.",
+    );
+  }
+  const requirement =
+    pkg?.engines?.node ||
+    (config.fuse?.enabled
+      ? require("../../fuse-starter-pack/fuse-v21.1/package.json").engines.node
+      : cli.engines.node);
+  const semver = require("semver");
+  if (!semver.validRange(requirement))
+    add(
+      "node",
+      "fail",
+      `Invalid Node requirement in package.json engines.`,
+      "Set a valid semver range.",
+    );
+  else {
+    const compatible = semver.satisfies(nodeVersion, requirement);
+    add(
+      "node",
+      compatible ? "pass" : "fail",
+      `Project requires Node ${requirement}; installed ${nodeVersion}.`,
+      compatible ? "" : "Select a compatible Node version and rerun doctor.",
+    );
+  }
+
+  try {
+    const { resolveInputSources } = require("../config/input-sources");
+    const sources = resolveInputSources(config, projectRoot);
+    if (!sources.length) throw Error();
+    for (const source of sources) {
+      const { diagnostics } = analyzeSchema(await fs.readFile(source.file, "utf8"), {
+        file: source.file,
+        isGdl: source.type === "gdl" || path.extname(source.file) === ".gdl",
+        config,
+      });
+      for (const d of diagnostics)
+        add(
+          "schema:" + d.code,
+          d.severity === "error" ? "fail" : "warning",
+          `${d.file}:${d.line}:${d.column}: ${d.message}`,
+          d.suggestion,
+        );
+      if (!diagnostics.length) {
+        add("schema", "pass", `Schema [${source.name}]: ${source.file}`);
+      }
+    }
+  } catch {
+    add(
+      "schema",
+      "fail",
+      "Configured schema cannot be read.",
+      "Correct input.file or input.sources[].file relative to the project root.",
+    );
+  }
+  if (config.fuse?.enabled)
+    add(
+      "starter",
+      (await fs.pathExists(config.fuse.starterPackPath)) ? "pass" : "fail",
+      "Fuse starter path checked.",
+      "Correct fuse.starterPackPath if the template directory is missing.",
+    );
+  if (!pkg)
+    add(
+      "application",
+      "warning",
+      "No generated package.json yet.",
+      "Run crudforge generate after validation passes.",
+    );
+  else {
+    const locks = [];
+    for (const name of ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"])
+      if (await fs.pathExists(path.join(projectRoot, name))) locks.push(name);
+    const lockFor = {
+      npm: "package-lock.json",
+      pnpm: "pnpm-lock.yaml",
+      yarn: "yarn.lock",
+    };
+    const expected = pkg.packageManager?.split("@")[0] ||
+      Object.keys(lockFor).find((manager) => locks.length === 1 && lockFor[manager] === locks[0]) || "npm";
+    add(
+      "lockfile",
+      locks.length === 1 && locks[0] === lockFor[expected] ? "pass" : "fail",
+      `Package manager ${expected}; lockfiles: ${locks.join(", ") || "none"}.`,
+      "Keep the matching lockfile and use the declared package manager.",
+    );
+    if (locks.includes("package-lock.json"))
+      try {
+        const lock = await fs.readJson(
+          path.join(projectRoot, "package-lock.json"),
+        );
+        const root = lock.packages?.[""];
+        for (const section of ["dependencies", "devDependencies"])
+          if (
+            JSON.stringify(Object.entries(root?.[section] || {}).sort()) !==
+            JSON.stringify(Object.entries(pkg[section] || {}).sort())
+          )
+            add(
+              "lockfile-drift",
+              "fail",
+              `${section} differ between package.json and package-lock.json.`,
+              "Refresh the lockfile deliberately with npm install, then use npm ci.",
+            );
+      } catch {
+        add(
+          "lockfile",
+          "fail",
+          "package-lock.json is malformed.",
+          "Repair the lockfile.",
+        );
+      }
+    const pnp = await fs.pathExists(path.join(projectRoot, ".pnp.cjs"));
+    const missing = [];
+    for (const name of Object.keys({
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+    }))
+      if (
+        !(await fs.pathExists(
+          path.join(projectRoot, "node_modules", name, "package.json"),
+        ))
+      )
+        missing.push(name);
+    add(
+      "dependencies",
+      pnp ? "warning" : missing.length ? "fail" : "pass",
+      pnp
+        ? "Yarn PnP manifest exists; package resolution was not executed during read-only diagnosis."
+        : missing.length
+          ? `${missing.length} declared dependencies are missing.`
+          : "Declared dependency directories exist.",
+      "Run the project package manager install command; doctor never installs packages.",
+    );
+  }
+  let target = config.output?.directory || ".";
+  while (!(await fs.pathExists(target)) && path.dirname(target) !== target)
+    target = path.dirname(target);
+  try {
+    if (!(await fs.stat(target)).isDirectory()) throw Error();
+    await fs.access(target, fs.constants.W_OK);
+    add(
+      "output-path",
+      "pass",
+      "Output directory or its nearest parent is writable.",
+    );
+  } catch {
+    add(
+      "output-path",
+      "fail",
+      "Output directory cannot be created or written.",
+      "Correct output.directory or its directory permissions.",
+    );
+  }
+  const port = config.devServer?.port || 4200;
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    add(
+      "port",
+      "fail",
+      "devServer.port must be an integer from 1 to 65535.",
+      "Correct devServer.port.",
+    );
+  else {
+    const available = await portAvailable(port);
+    add(
+      "port",
+      available ? "pass" : "warning",
+      `Development port ${port} ${available ? "is available" : "is occupied or binding is not permitted"} on IPv4 loopback.`,
+      "If occupied, use another configured port or stop your own server manually.",
+    );
+  }
+  for (const [name, value] of Object.entries(config.api?.services || {})) {
+    for (const target of typeof value === "string"
+      ? [value]
+      : [value.dev, value.prod].filter(Boolean))
+      if (!/^https?:\/\//.test(target) || safeUrl(target) === "[invalid URL]")
+        add(
+          "api-target",
+          "fail",
+          `Service ${name} has an invalid target.`,
+          "Use an absolute HTTP(S) service URL.",
+        );
+  }
+  if (
+    config.api?.microservice &&
+    !config.api?.services?.[config.api.microservice] &&
+    !Object.keys(config.proxy?.routes || {}).length
+  )
+    add(
+      "api-routing",
+      "warning",
+      "No explicit proxy target for the configured microservice.",
+      "Verify same-origin deployment routing or configure api.services/proxy.routes.",
+    );
+  if (config.auth?.provider === "keycloak") {
+    const missing = ["realm", "clientId", "serverUrl"].filter(
+      (k) => !config.auth[k],
+    );
+    add(
+      "auth",
+      missing.length ? "fail" : "pass",
+      missing.length
+        ? `Missing Keycloak settings: ${missing.join(", ")}.`
+        : "Keycloak settings present; credentials and login are unverified.",
+      "Configure frontend authentication without embedding client secrets.",
+    );
+  }
+  for (const [route, value] of Object.entries(config.proxy?.routes || {})) {
+    const target = typeof value === "string" ? value : value.target;
+    if (target && !/^https?:\/\//.test(target))
+      add(
+        "proxy-target",
+        "fail",
+        `Proxy route ${route} needs an HTTP(S) target.`,
+        "Correct proxy.routes.",
+      );
+  }
+  if (
+    config.auth?.provider === "keycloak" &&
+    config.auth.serverUrl &&
+    !/^https?:\/\//.test(config.auth.serverUrl)
+  )
+    add(
+      "auth-url",
+      "fail",
+      "Keycloak server URL must be absolute HTTP(S).",
+      "Correct auth.serverUrl.",
+    );
+  const endpoints = config.doctor?.endpoints || [];
+  if (live) {
+    if (!endpoints.length)
+      add(
+        "live",
+        "warning",
+        "No documented read-only endpoints configured.",
+        "Set doctor.endpoints with explicit URLs and descriptions; no universal health endpoint is assumed.",
+      );
+    for (const endpoint of endpoints) {
+      const result = await probe(endpoint.url, config.doctor.timeoutMs);
+      add(
+        "live",
+        result.status,
+        `${safeUrl(endpoint.url)}: ${result.message}`,
+        endpoint.description,
+      );
+    }
+  } else
+    add(
+      "live",
+      "pass",
+      "Live requests disabled; local checks made no HTTP requests.",
+    );
+  const secrets = [];
+  function collect(value) {
+    if (value && typeof value === "object")
+      for (const [key, item] of Object.entries(value)) {
+        if (
+          /password|secret|token|credential|authorization/i.test(key) &&
+          typeof item === "string" &&
+          item.length
+        )
+          secrets.push(item);
+        else collect(item);
+      }
+  }
+  collect(config);
+  for (const check of checks)
+    for (const key of ["message", "next"])
+      for (const secret of secrets)
+        check[key] = check[key].split(secret).join("[REDACTED]");
+  return { ok: !checks.some((c) => c.status === "fail"), checks };
+}
+async function doctorCommand(options = {}) {
+  const result = await diagnose(options);
+  console.log(
+    options.json
+      ? JSON.stringify(result, null, 2)
+      : result.checks
+          .map(
+            (c) =>
+              `[${c.status.toUpperCase()}] ${c.message}${c.next ? "\n  Next: " + c.next : ""}`,
+          )
+          .join("\n"),
+  );
+  process.exitCode = result.ok ? 0 : 1;
+  return result;
+}
+module.exports = { doctorCommand, diagnose, probe };