@obsidiane/meridiane 0.0.7 → 0.0.11

package/README.md

@@ -19,82 +19,30 @@ npm i -g @obsidiane/meridiane
 ## Usage
 
 ```bash
-# Générer des fichiers d'init (config + snippets)
-npx meridiane init
+# Dev: génère le bridge (+ models par défaut)
+# (build standalone + install local dans node_modules)
+npx meridiane dev <packageName> --spec <url|file> [--preset[=native|all]] [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 
-# Générer une librairie Angular (dans projects/<lib-name>)
-npx meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
-
-# Générer des modèles depuis OpenAPI
-npx meridiane models <SPEC_OPENAPI_URL_OU_FICHIER_JSON> [--out=<dir>] [--item-import=../lib/ports/resource-repository.port] [--required-mode=all-optional|spec] [--preset=all|native] [--include=<substr>] [--exclude=<substr>] [--index=1|0]
-
-# Dev: regen lib + models depuis un backend (localhost par défaut)
-npx meridiane dev-bridge <lib-name> <npm-package-name> [version]
-
-# Dev (repo meridiane): met à jour le bridge du sandbox
-npx meridiane sandbox-bridge
+# CI/CD: génère + build Angular + npm pack (artefact prêt à publier)
+npx meridiane build <packageName> --version <semver> --spec <url|file> [--preset[=native|all]] [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 ```
 
 Options :
 - `--debug` : active des logs supplémentaires (CLI).
 
-`url-registry` est optionnel. Recommandé : gérer le registry via `.npmrc` / variables CI plutôt que de le passer au générateur.
-
 Bonnes pratiques :
-- exécuter `meridiane init` une fois au début du repo du bridge (pour `models.config.js`, `.env.example`, snippets Angular)
-- committer `models.config.js` et `.env.example`, ne pas committer `.env`
-- générer les modèles dans `projects/<lib-name>/src/models` pour publier les types avec le package
-
-## Exemple CI (générer + build + publish)
+- utiliser `--preset=native` si vous voulez des modèles “entity-like” (sans variantes `.jsonld/.jsonMergePatch`)
+- utiliser `--no-models` si vous voulez uniquement le runtime (pas besoin de `--spec`)
+- laisser le registry à la CI (`.npmrc`, variables d’environnement, `npm publish --registry …`)
 
-```bash
-npm ci
-npx -y @obsidiane/meridiane@0.1.0 lib backend-bridge @acme/backend-bridge 0.1.0
-npx -y @obsidiane/meridiane@0.1.0 models http://localhost:8000/api/docs.json --out=projects/backend-bridge/src/models
-npx ng build backend-bridge
-cd dist/backend-bridge
-npm publish
-```
-
-Si votre workspace ne contient pas `ng-packagr` (souvent le cas dans une app Angular “pure”), installez-le :
-
-```bash
-npm i -D ng-packagr
-```
+Note (repo Meridiane) :
+- dans le repo Meridiane, `meridiane dev` peut être exécutée sans `packageName` et se préconfigure pour `apps/sandbox` (`@obsidiane/bridge-sandbox`).
 
-## Configuration (models.config.js)
-
-Le générateur de modèles charge automatiquement un fichier `models.config.js` s’il existe dans le répertoire courant (CWD) ou dans un dossier parent.
-
-Copie rapide (après installation) :
+## Exemple CI (générer + build + publish)
 
 ```bash
-cp node_modules/@obsidiane/meridiane/models.config.example.js ./models.config.js
+npx -y @obsidiane/meridiane@0.1.0 build @acme/backend-bridge --version 0.1.0 --spec https://staging.example/api/docs.json --preset=native
+npm publish dist/backend-bridge
 ```
 
-Exécuter `meridiane init` est généralement plus simple (ça pose aussi `.env.example` et un snippet Angular).
-
-## Configuration via `.env`
-
-Le CLI charge automatiquement un fichier `.env` (CWD ou dossier parent) avant d’exécuter `lib/models`.
-
-Variables utiles :
-- `MERIDIANE_DEBUG=1`
-- `MERIDIANE_LIB_VERSION=0.1.0`
-- `MERIDIANE_NPM_REGISTRY_URL=https://…`
-- `MERIDIANE_MODELS_OUT=projects/<lib>/src/models`
-- `MERIDIANE_MODELS_REQUIRED_MODE=spec`
-- `MERIDIANE_MODELS_ITEM_IMPORT=../lib/ports/resource-repository.port`
-- `MERIDIANE_MODELS_INDEX=1`
-
-Ordre de priorité :
-1) flags CLI
-2) `models.config.js`
-3) `.env`
-4) valeurs par défaut
-
-Sans installation préalable :
-
-```bash
-npx -y @obsidiane/meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
-```
+Note : Meridiane installe le toolchain (`ng-packagr`, `@angular/*`, …) dans `dist/.meridiane-workspace` si nécessaire.

package/cli.js

@@ -1,76 +1,70 @@
 #!/usr/bin/env node
-import {fileURLToPath} from 'node:url';
-import path from 'node:path';
-import {spawn} from 'node:child_process';
+import process from 'node:process';
+import { Command } from 'commander';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+import { runDev } from './tools/dev.js';
+import { runBuild } from './tools/build.js';
+import { createLogger } from './tools/core/logger.js';
 
-function runTool(scriptName, args) {
-  const scriptPath = path.join(__dirname, 'tools', scriptName);
-  const child = spawn(process.execPath, [scriptPath, ...args], {
-    stdio: 'inherit',
-    env: process.env,
-  });
+const program = new Command();
 
-  child.on('exit', (code) => {
-    process.exit(code ?? 0);
-  });
-}
-
-function printHelp() {
-  console.log(`
-Usage:
-  meridiane init [--force]
-  meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
-  meridiane models <SPEC_OPENAPI_URL_OU_FICHIER_JSON> [options]
-  meridiane dev-bridge <lib-name> <npm-package-name> [version] [options]
-  meridiane sandbox-bridge [options]
+program
+  .name('meridiane')
+  .description('Generate an Angular bridge + models from an API Platform OpenAPI spec.')
+  .showHelpAfterError()
+  .showSuggestionAfterError();
 
-Options:
-  --debug  Active les logs (CLI et runtime)
+function presetParser(value, previous) {
+  if (value === undefined && previous === undefined) return true; // `--preset` (no value) => native
+  return value ?? previous;
+}
 
-Examples:
-  npx -y @obsidiane/meridiane init
-  npx -y @obsidiane/meridiane lib backend-bridge @acme/backend-bridge 0.1.0
-  npx -y @obsidiane/meridiane models http://localhost:8000/api/docs.json --out=projects/backend-bridge/src/models
-  npx -y @obsidiane/meridiane dev-bridge bridge-sandbox @obsidiane/bridge-sandbox 0.1.0
-  npx -y @obsidiane/meridiane sandbox-bridge
-`);
+function collect(value, previous = []) {
+  return [...previous, value];
 }
 
-const argv = process.argv.slice(2);
-const debugIndex = argv.indexOf('--debug');
-if (debugIndex >= 0) {
-  argv.splice(debugIndex, 1);
-  process.env.MERIDIANE_DEBUG = process.env.MERIDIANE_DEBUG || '1';
+function commonOptions(cmd) {
+  return cmd
+    .option('--spec <urlOrFile>', 'OpenAPI spec source (URL or local JSON file)')
+    .option('--preset [mode]', 'Preset: native|all (default: all; `--preset` alone => native)', presetParser)
+    .option('--include <substr>', 'Include schema names containing substring (repeatable, supports commas)', collect, [])
+    .option('--exclude <substr>', 'Exclude schema names containing substring (repeatable, supports commas)', collect, [])
+    .option('--no-models', 'Skip models generation (then --spec is not required)')
+    .option('--debug', 'Enable debug logs');
 }
 
-const [cmd, ...rest] = argv;
+commonOptions(
+  program
+    .command('dev')
+    .argument(
+      '[packageName]',
+      'NPM package name of the generated bridge (e.g. @acme/backend-bridge). Optional in this repo (defaults to @obsidiane/bridge-sandbox).'
+    )
+    .action(async (packageName, opts) => {
+      const log = createLogger({ debug: !!opts?.debug });
+      try {
+        await runDev(packageName, opts);
+      } catch (err) {
+        log.error(err);
+        process.exit(1);
+      }
+    })
+);
 
-switch (cmd) {
-  case 'init':
-    runTool('init.js', rest);
-    break;
-  case 'lib':
-    runTool('generate-lib.js', rest);
-    break;
-  case 'models':
-    runTool('generate-models.js', rest);
-    break;
-  case 'dev-bridge':
-    runTool('dev-bridge.js', rest);
-    break;
-  case 'sandbox-bridge':
-    runTool('sandbox-bridge.js', rest);
-    break;
-  case '-h':
-  case '--help':
-  case undefined:
-    printHelp();
-    break;
-  default:
-    console.error(`Unknown command: ${cmd}`);
-    printHelp();
-    process.exit(1);
-}
+commonOptions(
+  program
+    .command('build')
+    .argument('<packageName>', 'NPM package name of the generated bridge (e.g. @acme/backend-bridge)')
+    .requiredOption('--version <semver>', 'Version to write in the generated bridge package.json (CI/CD)')
+    .action(async (packageName, opts) => {
+      const log = createLogger({ debug: !!opts?.debug });
+      try {
+        await runBuild(packageName, opts);
+      } catch (err) {
+        log.error(err);
+        process.exit(1);
+      }
+    })
+);
+
+program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "0.0.7",
+  "version": "0.0.11",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",
@@ -14,21 +14,19 @@
     "pack:check": "npm_config_cache=./.npm-cache npm pack --dry-run"
   },
   "bin": {
-    "meridiane": "cli.js",
-    "meridiane-generate-lib": "tools/generate-lib.js",
-    "meridiane-generate-models": "tools/generate-models.js"
+    "meridiane": "cli.js"
   },
   "files": [
     "cli.js",
     "tools/**",
     "templates/**",
-    "models.config.example.js",
     "README.md"
   ],
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
+    "commander": "^14.0.2",
     "handlebars": "^4.7.8",
     "tslib": "^2.3.0"
   }

package/templates/_lib_template/package.json

@@ -3,7 +3,8 @@
   "version": "0.0.1",
   "peerDependencies": {
     "@angular/common": "^20.1.0",
-    "@angular/core": "^20.1.0"
+    "@angular/core": "^20.1.0",
+    "rxjs": "^7.8.0"
   },
   "dependencies": {
     "tslib": "^2.8.1"

package/templates/_lib_template/src/models/index.ts

@@ -1,2 +1 @@
 export {};
-

package/tools/build.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+import { deriveLibName } from './core/lib-name.js';
+import { normalizePreset, splitListArgs } from './core/paths.js';
+import { readOpenApiSpec } from './core/spec.js';
+import { createLogger } from './core/logger.js';
+import { generateBridgeWorkspace } from './core/generate.js';
+import { ensureStandaloneWorkspace, ensureToolchainInstalled } from './core/standalone.js';
+
+function run(cmd, args, { cwd, env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: 'inherit',
+      cwd: cwd ?? process.cwd(),
+      env: env ?? process.env,
+    });
+    child.on('exit', (code) => resolve(code ?? 0));
+  });
+}
+
+export async function runBuild(packageName, opts) {
+  const cwd = process.cwd();
+  const debug = !!opts.debug;
+  const log = createLogger({ debug });
+
+  const version = opts.version;
+  if (!version) throw new Error('Missing --version');
+
+  const noModels = opts.models === false;
+  const preset = normalizePreset(opts.preset);
+  const include = splitListArgs(opts.include);
+  const exclude = splitListArgs(opts.exclude);
+
+  const libName = deriveLibName(packageName);
+  const requiredMode = 'spec';
+
+  // Standalone mode (native): works from any repo (backend pipeline or otherwise).
+  log.title('build — standalone');
+  log.info(`repo: ${cwd}`);
+  log.info(`package: ${packageName}@${version}`);
+  log.info(`lib: ${libName}`);
+  if (noModels) log.info('models: désactivés (--no-models)');
+  else log.info(`spec: ${opts.spec} | preset: ${preset}`);
+
+  const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot: cwd, log });
+  log.info(`workspace: ${workspaceRoot}`);
+
+  let spec;
+  if (!noModels) {
+    log.step('lecture de la spec OpenAPI');
+    spec = await readOpenApiSpec(opts.spec);
+    log.success('spec chargée');
+  }
+
+  await ensureToolchainInstalled({ workspaceRoot, requireFromWs, npmCacheDir, log });
+
+  await generateBridgeWorkspace({
+    cwd: workspaceRoot,
+    libName,
+    packageName,
+    version,
+    noModels,
+    spec,
+    requiredMode,
+    preset,
+    include,
+    exclude,
+    debug,
+    log,
+    distRoot,
+  });
+
+  const ngPackageJsonPath = path.join(workspaceRoot, 'projects', libName, 'ng-package.json');
+  const tsconfigProdPath = path.join(workspaceRoot, 'projects', libName, 'tsconfig.lib.prod.json');
+
+  log.step('ng-packagr');
+  const ngPackagrPath = requireFromWs.resolve('ng-packagr/src/cli/main.js');
+  const packagrCode = await run(process.execPath, [ngPackagrPath, '-p', ngPackageJsonPath, '-c', tsconfigProdPath], {
+    cwd: workspaceRoot,
+  });
+  if (packagrCode !== 0) process.exit(packagrCode);
+
+  const distDir = path.join(distRoot, libName);
+  log.step(`npm pack (${path.relative(cwd, distDir)})`);
+  const packCode = await run('npm', ['pack'], {
+    cwd: distDir,
+    env: {
+      ...process.env,
+      npm_config_cache: npmCacheDir,
+      npm_config_update_notifier: 'false',
+      npm_config_fund: 'false',
+      npm_config_audit: 'false',
+    },
+  });
+  if (packCode === 0) log.success(`package prêt: ${path.relative(cwd, distDir)}`);
+  process.exit(packCode);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  throw new Error('This module is not meant to be executed directly.');
+}

package/tools/core/generate.js

@@ -0,0 +1,152 @@
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { readJson, writeJsonIfChanged } from './json.js';
+import { renderTemplateToFile } from '../generator/models/handlebars.js';
+import { ensureCleanDir } from '../generator/models/utils.js';
+import { buildModelsFromOpenAPI } from '../generator/models/openapi-to-models.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const pkgRoot = path.resolve(__dirname, '../..'); // packages/meridiane
+
+async function replacePlaceholdersInDir(dir, placeholders) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await replacePlaceholdersInDir(fullPath, placeholders);
+    } else if (entry.isFile()) {
+      let content = await fs.readFile(fullPath, 'utf8');
+      for (const [key, value] of Object.entries(placeholders)) {
+        content = content.replaceAll(key, value);
+      }
+      await fs.writeFile(fullPath, content);
+    }
+  }
+}
+
+async function generateLibrary({ cwd, libName, packageName, version, debug }) {
+  const tplDir = path.resolve(pkgRoot, 'templates/_lib_template');
+  const targetDir = path.resolve(cwd, 'projects', libName);
+
+  if (debug) console.log('[meridiane] generate lib', { libName, packageName, version, targetDir: path.relative(cwd, targetDir) });
+
+  await fs.rm(targetDir, { recursive: true, force: true });
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.cp(tplDir, targetDir, { recursive: true });
+
+  await replacePlaceholdersInDir(targetDir, { '__LIB_NAME__': libName });
+
+  const libPackageJsonPath = path.join(targetDir, 'package.json');
+  if (existsSync(libPackageJsonPath)) {
+    const libPkg = await readJson(libPackageJsonPath);
+    libPkg.name = packageName;
+    libPkg.version = version;
+    await writeJsonIfChanged(libPackageJsonPath, libPkg);
+  }
+
+  // angular.json / workspace patching is intentionally not done here (Meridiane is standalone).
+}
+
+async function generateModels({ cwd, libName, spec, requiredMode, preset, include, exclude, debug }) {
+  const outDir = path.resolve(cwd, 'projects', libName, 'src', 'models');
+  const templatesDir = path.resolve(pkgRoot, 'tools', 'generator', 'models', 'templates');
+
+  if (debug) console.log('[meridiane] generate models', { outDir: path.relative(cwd, outDir), requiredMode, preset, includeCount: include.length, excludeCount: exclude.length });
+
+  await ensureCleanDir(outDir);
+
+  // Write models + index.ts.
+  const { models } = buildModelsFromOpenAPI(spec, {
+    requiredMode,
+    preset,
+    includeSchemaNames: include,
+    excludeSchemaNames: exclude,
+  });
+
+  for (const m of models) {
+    await renderTemplateToFile({
+      templatePath: path.join(templatesDir, 'model.hbs'),
+      outPath: path.join(outDir, `${m.name}.ts`),
+      ctx: {
+        name: m.name,
+        props: m.props,
+        imports: m.imports,
+        extendsTypes: m.extendsTypes || [],
+      },
+    });
+  }
+
+  await renderTemplateToFile({
+    templatePath: path.join(templatesDir, 'index.hbs'),
+    outPath: path.join(outDir, 'index.ts'),
+    ctx: { models: models.map((m) => ({ name: m.name })) },
+  });
+
+  if (debug) console.log(`[meridiane] ${models.length} model(s) generated`);
+}
+
+/**
+ * @param {{
+ *   cwd: string,
+ *   libName: string,
+ *   packageName: string,
+ *   version: string,
+ *   noModels: boolean,
+ *   spec?: any,
+ *   requiredMode: 'all-optional'|'spec',
+ *   preset: 'all'|'native',
+ *   include: string[],
+ *   exclude: string[],
+ *   debug: boolean,
+ *   log?: { step?: (msg: string) => void, info?: (msg: string) => void, success?: (msg: string) => void, debug?: (msg: string, data?: any) => void },
+ *   workspaceMode?: 'angular'|'standalone',
+ *   distRoot?: string,
+ * }} params
+ */
+export async function generateBridgeWorkspace(params) {
+  const {
+    cwd,
+    libName,
+    packageName,
+    version,
+    noModels,
+    spec,
+    requiredMode,
+    preset,
+    include,
+    exclude,
+    debug,
+    log,
+    distRoot,
+  } = params;
+
+  log?.step?.(`génération de la librairie (projects/${libName})`);
+  await generateLibrary({ cwd, libName, packageName, version, debug });
+
+  // If a dist root is provided, force ng-packagr output to that directory.
+  if (distRoot) {
+    const ngPackagePath = path.resolve(cwd, 'projects', libName, 'ng-package.json');
+    const ngPkg = await readJson(ngPackagePath);
+    const desiredDestAbs = path.resolve(distRoot, libName);
+    const projectDir = path.dirname(ngPackagePath);
+    ngPkg.dest = path.relative(projectDir, desiredDestAbs).split(path.sep).join('/');
+    await writeJsonIfChanged(ngPackagePath, ngPkg);
+    log?.debug?.('ng-package.json dest overridden', { dest: ngPkg.dest });
+  }
+
+  if (noModels) {
+    log?.info?.('models ignorés (--no-models)');
+    if (debug) console.log('[meridiane] --no-models enabled, skipping models generation');
+    return;
+  }
+
+  if (!spec) throw new Error('Internal error: spec is required when noModels=false');
+  log?.step?.('génération des models (OpenAPI)');
+  await generateModels({ cwd, libName, spec, requiredMode, preset, include, exclude, debug });
+  log?.success?.('génération terminée');
+}

package/tools/core/json.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+
+function stripJsonComments(input) {
+  let out = '';
+  let i = 0;
+  let inString = false;
+  let stringQuote = '"';
+  while (i < input.length) {
+    const ch = input[i];
+
+    if (inString) {
+      out += ch;
+      if (ch === '\\') {
+        // skip escaped char
+        i += 2;
+        continue;
+      }
+      if (ch === stringQuote) inString = false;
+      i += 1;
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringQuote = ch;
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    // line comment
+    if (ch === '/' && input[i + 1] === '/') {
+      i += 2;
+      while (i < input.length && input[i] !== '\n') i += 1;
+      continue;
+    }
+
+    // block comment
+    if (ch === '/' && input[i + 1] === '*') {
+      i += 2;
+      while (i < input.length && !(input[i] === '*' && input[i + 1] === '/')) i += 1;
+      i += 2;
+      continue;
+    }
+
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+export async function readJson(filePath) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return JSON.parse(stripJsonComments(raw));
+  }
+}
+
+export async function writeJsonIfChanged(filePath, data) {
+  const next = JSON.stringify(data, null, 2) + '\n';
+  try {
+    const prev = await fs.readFile(filePath, 'utf8');
+    if (prev === next) return false;
+  } catch {
+    // ignore (file missing / unreadable)
+  }
+  await fs.writeFile(filePath, next, 'utf8');
+  return true;
+}

package/tools/core/lib-name.js

@@ -0,0 +1,15 @@
+export function deriveLibName(packageName) {
+  const raw = String(packageName || '').trim();
+  if (!raw) throw new Error('Missing packageName');
+
+  const base = raw.startsWith('@') ? (raw.split('/')[1] || '') : raw;
+  const normalized = base
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  if (!normalized) throw new Error(`Invalid packageName: ${packageName}`);
+  return normalized;
+}
+

package/tools/core/logger.js

@@ -0,0 +1,51 @@
+import process from 'node:process';
+
+function color(code, text) {
+  if (!process.stdout.isTTY) return text;
+  return `\u001b[${code}m${text}\u001b[0m`;
+}
+
+function line(prefix, text) {
+  return `${prefix} ${text}`;
+}
+
+export function createLogger({ debug = false } = {}) {
+  const prefix = color('35', 'meridiane');
+
+  return {
+    debugEnabled: debug,
+
+    title(text) {
+      console.log(line('🌙', `${prefix} ${text}`));
+    },
+
+    step(text) {
+      console.log(line('🔧', `${prefix} ${text}`));
+    },
+
+    info(text) {
+      console.log(line('ℹ️', `${prefix} ${text}`));
+    },
+
+    success(text) {
+      console.log(line('✅', `${prefix} ${text}`));
+    },
+
+    warn(text) {
+      console.warn(line('⚠️', `${prefix} ${text}`));
+    },
+
+    debug(text, data) {
+      if (!debug) return;
+      if (data === undefined) console.log(line('🐛', `${prefix} ${text}`));
+      else console.log(line('🐛', `${prefix} ${text} ${JSON.stringify(data, null, 2)}`));
+    },
+
+    error(err) {
+      const msg = err?.message ?? String(err);
+      console.error(line('❌', `${prefix} ${msg}`));
+      if (debug && err?.stack) console.error(err.stack);
+    },
+  };
+}
+