@obsidiane/meridiane 2.0.3 → 2.0.4

package/README.md

@@ -23,12 +23,17 @@ npm i -g @obsidiane/meridiane
 # (build standalone + install local dans node_modules)
 npx meridiane dev <packageName> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 
+# Monorepo: génère uniquement les fichiers (pas de npm pack)
+npx meridiane generate <packageName> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--out <dir>] [--debug]
+
 # CI/CD: génère + build Angular + npm pack (artefact prêt à publier)
-npx meridiane build <packageName> --version <semver> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
+npx meridiane build <packageName> [--version <semver>] --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 ```
 
 Options :
 - `--debug` : active des logs supplémentaires (CLI).
+- `--version` : pour `build` et `generate` ; par défaut `0.0.0` si omis (déconseillé pour publier).
+- `--out` : uniquement pour `generate` ; répertoire de sortie (défaut `projects/<libName>`).
 - `--formats` : peut être répété ou fourni en liste séparée par virgules :
   - `--formats application/ld+json`
   - `--formats application/ld+json,application/json`
@@ -40,6 +45,7 @@ Bonnes pratiques :
   - pas de modèles `*.jsonMergePatch` (PATCH = `Partial<...>`)
   - noms normalisés (pas de suffixe `.jsonld`)
 - utiliser `--no-models` si vous voulez uniquement le runtime (pas besoin de `--spec`)
+- le `README.md` du projet (si présent à la racine) est ajouté à la fin du README du bridge
 - laisser le registry à la CI (`.npmrc`, variables d’environnement, `npm publish --registry …`)
 
 Note (repo Meridiane) :
@@ -53,3 +59,11 @@ npm publish dist/backend-bridge
 ```
 
 Note : Meridiane installe le toolchain (`ng-packagr`, `@angular/*`, …) dans `dist/.meridiane-workspace` si nécessaire.
+
+## Structure interne (mainteneurs)
+
+- `tools/app/` : orchestration des commandes (use-cases).
+- `tools/domain/` : logique pure (options, naming).
+- `tools/infra/` : I/O (spec, workspace, exec, logs) + génération.
+- `tools/generator/` : génération des modèles TypeScript.
+- `templates/_lib_template/` : runtime Angular du bridge.

package/cli.js

@@ -4,7 +4,8 @@ import { Command } from 'commander';
 
 import { runDev } from './tools/dev.js';
 import { runBuild } from './tools/build.js';
-import { createLogger } from './tools/core/logger.js';
+import { runGenerate } from './tools/generate.js';
+import { createLogger } from './tools/infra/logger.js';
 
 const program = new Command();
 
@@ -39,10 +40,12 @@ commonOptions(
     .action(async (packageName, opts) => {
       const log = createLogger({ debug: !!opts?.debug });
       try {
-        await runDev(packageName, opts);
+        const exitCode = await runDev(packageName, opts);
+        if (typeof exitCode === 'number' && exitCode !== 0) process.exit(exitCode);
       } catch (err) {
         log.error(err);
-        process.exit(1);
+        const exitCode = typeof err?.exitCode === 'number' ? err.exitCode : 1;
+        process.exit(exitCode);
       }
     })
 );
@@ -51,14 +54,35 @@ 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)')
+    .option('--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);
+        const exitCode = await runBuild(packageName, opts);
+        if (typeof exitCode === 'number' && exitCode !== 0) process.exit(exitCode);
       } catch (err) {
         log.error(err);
-        process.exit(1);
+        const exitCode = typeof err?.exitCode === 'number' ? err.exitCode : 1;
+        process.exit(exitCode);
+      }
+    })
+);
+
+commonOptions(
+  program
+    .command('generate')
+    .argument('<packageName>', 'NPM package name of the generated bridge (e.g. @acme/backend-bridge)')
+    .option('--version <semver>', 'Version to write in the generated bridge package.json')
+    .option('--out <dir>', 'Output directory (default: projects/<libName>)')
+    .action(async (packageName, opts) => {
+      const log = createLogger({ debug: !!opts?.debug });
+      try {
+        const exitCode = await runGenerate(packageName, opts);
+        if (typeof exitCode === 'number' && exitCode !== 0) process.exit(exitCode);
+      } catch (err) {
+        log.error(err);
+        const exitCode = typeof err?.exitCode === 'number' ? err.exitCode : 1;
+        process.exit(exitCode);
       }
     })
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",

package/templates/_lib_template/src/lib/bridge/rest/api-platform.adapter.ts

@@ -1,6 +1,7 @@
 import {HttpClient} from '@angular/common/http';
 import {Observable} from 'rxjs';
 import {toHttpParams} from './query-builder';
+import {buildHttpRequestOptions} from './http-request.options';
 import {
   Collection,
   HttpCallOptions,
@@ -68,29 +69,10 @@ export class ApiPlatformRestRepository<T extends Item> implements ResourceReposi
 
   request$<R = unknown, B = unknown>(req: HttpRequestConfig<B>): Observable<R> {
     // Low-level escape hatch for non-standard endpoints (custom controllers, uploads, etc.).
-    const {
-      method,
-      url,
-      query,
-      body,
-      headers,
-      responseType,
-      withCredentials,
-      options = {},
-    } = req;
+    const {method, url} = req;
 
     const targetUrl = this.resolveUrl(url ?? this.resourcePath);
-    const mergedOptions: Record<string, unknown> = {...options};
-
-    mergedOptions['responseType'] = (responseType ?? (mergedOptions['responseType'] as any) ?? 'json') as any;
-
-    mergedOptions['withCredentials'] = withCredentials ?? (mergedOptions['withCredentials'] as any) ?? this.withCredentialsDefault;
-
-    if (headers) mergedOptions['headers'] = headers;
-    if (query) mergedOptions['params'] = toHttpParams(query);
-    if (body !== undefined) mergedOptions['body'] = body;
-
-    mergedOptions['observe'] = 'body';
+    const mergedOptions = buildHttpRequestOptions(req, {withCredentialsDefault: this.withCredentialsDefault});
     return this.http.request<R>(method, targetUrl, mergedOptions as {observe: 'body'});
   }
 

package/templates/_lib_template/src/lib/bridge/rest/http-request.options.ts

@@ -0,0 +1,21 @@
+import {HttpRequestConfig} from '../../ports/resource-repository.port';
+import {toHttpParams} from './query-builder';
+
+export function buildHttpRequestOptions(
+  req: HttpRequestConfig,
+  {withCredentialsDefault}: {withCredentialsDefault: boolean}
+): Record<string, unknown> {
+  const {query, body, headers, responseType, withCredentials, options = {}} = req;
+  const mergedOptions: Record<string, unknown> = {...options};
+
+  if (headers) mergedOptions['headers'] = headers;
+  if (query) mergedOptions['params'] = toHttpParams(query);
+  if (body !== undefined) mergedOptions['body'] = body;
+
+  mergedOptions['responseType'] = (responseType ?? (mergedOptions['responseType'] as any) ?? 'json') as any;
+  mergedOptions['withCredentials'] =
+    withCredentials ?? (mergedOptions['withCredentials'] as any) ?? withCredentialsDefault;
+  mergedOptions['observe'] = 'body';
+
+  return mergedOptions;
+}

package/templates/_lib_template/src/lib/facades/bridge.facade.ts

@@ -3,6 +3,7 @@ import {HttpClient} from '@angular/common/http';
 import {Observable} from 'rxjs';
 import {filter, map, share} from 'rxjs/operators';
 import {toHttpParams} from '../bridge/rest/query-builder';
+import {buildHttpRequestOptions} from '../bridge/rest/http-request.options';
 import {MercureRealtimeAdapter} from '../bridge/sse/mercure.adapter';
 import {API_BASE_URL, BRIDGE_WITH_CREDENTIALS} from '../tokens';
 import {AnyQuery, Collection, HttpCallOptions, HttpRequestConfig, Iri, IriRequired, Item} from '../ports/resource-repository.port';
@@ -75,19 +76,10 @@ export class BridgeFacade {
   }
 
   request$<R = unknown, B = unknown>(req: HttpRequestConfig<B>): Observable<R> {
-    const {method, url, query, body, headers, responseType, withCredentials, options = {}} = req;
+    const {method, url} = req;
     const targetUrl = this.resolveUrl(url);
 
-    const mergedOptions: Record<string, unknown> = {...options};
-    if (headers) mergedOptions['headers'] = headers;
-    if (query) mergedOptions['params'] = toHttpParams(query);
-    if (body !== undefined) mergedOptions['body'] = body;
-
-    mergedOptions['responseType'] = (responseType ?? (mergedOptions['responseType'] as any) ?? 'json') as any;
-    mergedOptions['withCredentials'] =
-      withCredentials ?? (mergedOptions['withCredentials'] as any) ?? this.withCredentialsDefault;
-    mergedOptions['observe'] = 'body';
-
+    const mergedOptions = buildHttpRequestOptions(req, {withCredentialsDefault: this.withCredentialsDefault});
     return this.http.request<R>(method, targetUrl, mergedOptions as {observe: 'body'});
   }
 

package/tools/app/bridge-workflow.js

@@ -0,0 +1,85 @@
+import process from 'node:process';
+import path from 'node:path';
+
+import { readOpenApiSpec } from '../infra/spec-loader.js';
+import { generateBridgeWorkspace } from '../infra/generate/bridge.js';
+import { ensureStandaloneWorkspace, ensureToolchainInstalled } from '../infra/standalone-workspace.js';
+import { ExitCodeError, runCommand } from '../infra/exec.js';
+
+export async function runBridgeWorkflow({
+  repoRoot,
+  libName,
+  packageName,
+  version,
+  noModels,
+  spec,
+  specSource,
+  requiredMode,
+  formats,
+  include,
+  exclude,
+  debug,
+  log,
+  tsconfigPath,
+  packRelativeTo,
+  projectReadmePath,
+}) {
+  const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot, log });
+  log?.info?.(`workspace: ${workspaceRoot}`);
+
+  let resolvedSpec = spec;
+  if (!noModels) {
+    if (!resolvedSpec) {
+      if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
+      log?.step?.('lecture de la spec OpenAPI');
+      resolvedSpec = await readOpenApiSpec(specSource);
+      log?.success?.('spec chargée');
+    }
+  }
+
+  await ensureToolchainInstalled({ workspaceRoot, requireFromWs, npmCacheDir, log });
+
+  await generateBridgeWorkspace({
+    cwd: workspaceRoot,
+    libName,
+    packageName,
+    version,
+    noModels,
+    spec: resolvedSpec,
+    requiredMode,
+    formats,
+    include,
+    exclude,
+    debug,
+    log,
+    distRoot,
+    projectReadmePath,
+  });
+
+  const ngPackageJsonPath = path.join(workspaceRoot, 'projects', libName, 'ng-package.json');
+  const tsconfigAbsPath = path.join(workspaceRoot, 'projects', libName, tsconfigPath);
+
+  log?.step?.('ng-packagr');
+  const ngPackagrPath = requireFromWs.resolve('ng-packagr/src/cli/main.js');
+  const packagrCode = await runCommand(process.execPath, [ngPackagrPath, '-p', ngPackageJsonPath, '-c', tsconfigAbsPath], {
+    cwd: workspaceRoot,
+  });
+  if (packagrCode !== 0) throw new ExitCodeError(`ng-packagr failed (exit ${packagrCode})`, packagrCode);
+
+  const distDir = path.join(distRoot, libName);
+  const packRel = packRelativeTo ? path.relative(packRelativeTo, distDir) : distDir;
+  log?.step?.(`npm pack (${packRel})`);
+  const packCode = await runCommand('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) throw new ExitCodeError(`npm pack failed (exit ${packCode})`, packCode);
+
+  return { workspaceRoot, distRoot, distDir, npmCacheDir };
+}

package/tools/app/run-build.js

@@ -0,0 +1,41 @@
+import process from 'node:process';
+import path from 'node:path';
+
+import { normalizeBuildOptions } from '../domain/bridge-options.js';
+import { createLogger } from '../infra/logger.js';
+import { runBridgeWorkflow } from './bridge-workflow.js';
+
+export async function runBuild(packageName, opts) {
+  const cwd = process.cwd();
+  const config = normalizeBuildOptions(packageName, opts);
+  const log = createLogger({ debug: config.debug });
+  const projectReadmePath = path.join(cwd, 'README.md');
+
+  log.title('build — standalone');
+  log.info(`repo: ${cwd}`);
+  log.info(`package: ${config.packageName}@${config.version}`);
+  log.info(`lib: ${config.libName}`);
+  if (config.noModels) log.info('models: désactivés (--no-models)');
+  else log.info(`spec: ${opts.spec} | formats: ${config.formats.join(', ')} | nullableMode: ${config.requiredMode}`);
+
+  const { distDir } = await runBridgeWorkflow({
+    repoRoot: cwd,
+    libName: config.libName,
+    packageName: config.packageName,
+    version: config.version,
+    noModels: config.noModels,
+    specSource: opts.spec,
+    requiredMode: config.requiredMode,
+    formats: config.formats,
+    include: config.include,
+    exclude: config.exclude,
+    debug: config.debug,
+    log,
+    tsconfigPath: 'tsconfig.lib.prod.json',
+    packRelativeTo: cwd,
+    projectReadmePath,
+  });
+
+  log.success(`package prêt: ${path.relative(cwd, distDir)}`);
+  return 0;
+}

package/tools/app/run-dev.js

@@ -0,0 +1,82 @@
+import process from 'node:process';
+import path from 'node:path';
+
+import { normalizeDevOptions } from '../domain/bridge-options.js';
+import { createLogger } from '../infra/logger.js';
+import {
+  findLatestTgz,
+  installPackageFromDist,
+  resolveDevAppRoot,
+  resolveSandboxAppRoot,
+  resolveSpecSource,
+} from '../infra/dev-support.js';
+import { readOpenApiSpec } from '../infra/spec-loader.js';
+import { runBridgeWorkflow } from './bridge-workflow.js';
+
+export async function runDev(packageName, opts) {
+  const startCwd = process.cwd();
+  const config = normalizeDevOptions(packageName, opts);
+  const log = createLogger({ debug: config.debug });
+
+  const appRoot = config.useSandboxDefaults ? await resolveSandboxAppRoot(startCwd) : await resolveDevAppRoot(startCwd);
+  const projectReadmePath = path.join(appRoot, 'README.md');
+
+  const specSource = config.noModels
+    ? undefined
+    : await resolveSpecSource({
+        useSandboxDefaults: config.useSandboxDefaults,
+        appRoot,
+        specArg: opts.spec,
+      });
+  let noModels = config.noModels;
+  let spec;
+  if (!noModels) {
+    if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
+    try {
+      spec = await readOpenApiSpec(specSource);
+    } catch (err) {
+      if (config.useSandboxDefaults && opts.spec == null) {
+        noModels = true;
+        log.warn(
+          "spec OpenAPI indisponible (backend non démarré ?) → génération des models ignorée. " +
+            'Démarrez le backend ou passez `--spec ./openapi.json` (ou `--no-models`).'
+        );
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  log.title('dev — build standalone + install local');
+  log.info(`app: ${appRoot}`);
+  log.info(`package: ${config.packageName}@${config.version}`);
+  log.info(`lib: ${config.libName}`);
+  if (config.useSandboxDefaults) log.info('defaults sandbox appliqués');
+  if (noModels) log.info('models: désactivés (--no-models)');
+  else log.info(`spec: ${specSource} | formats: ${config.formats.join(', ')} | nullableMode: ${config.requiredMode}`);
+
+  const { distDir } = await runBridgeWorkflow({
+    repoRoot: appRoot,
+    libName: config.libName,
+    packageName: config.packageName,
+    version: config.version,
+    noModels,
+    spec,
+    specSource,
+    requiredMode: config.requiredMode,
+    formats: config.formats,
+    include: config.include,
+    exclude: config.exclude,
+    debug: config.debug,
+    log,
+    tsconfigPath: 'tsconfig.lib.json',
+    packRelativeTo: appRoot,
+    projectReadmePath,
+  });
+
+  await findLatestTgz(distDir);
+  await installPackageFromDist({ packageName: config.packageName, distDir, appRoot, log });
+
+  log.success('bridge installé (node_modules) ✅');
+  return 0;
+}

package/tools/app/run-generate.js

@@ -0,0 +1,58 @@
+import process from 'node:process';
+import path from 'node:path';
+
+import { normalizeGenerateOptions } from '../domain/bridge-options.js';
+import { createLogger } from '../infra/logger.js';
+import { readOpenApiSpec } from '../infra/spec-loader.js';
+import { generateBridgeWorkspace } from '../infra/generate/bridge.js';
+
+function resolveProjectDir({ cwd, libName, outDir }) {
+  if (outDir && outDir.length > 0) return path.resolve(cwd, outDir);
+  return path.resolve(cwd, 'projects', libName);
+}
+
+export async function runGenerate(packageName, opts) {
+  const cwd = process.cwd();
+  const config = normalizeGenerateOptions(packageName, opts);
+  const log = createLogger({ debug: config.debug });
+  const projectReadmePath = path.join(cwd, 'README.md');
+
+  const projectDir = resolveProjectDir({ cwd, libName: config.libName, outDir: config.outDir });
+  const specSource = opts?.spec;
+
+  log.title('generate — workspace files');
+  log.info(`repo: ${cwd}`);
+  log.info(`package: ${config.packageName}@${config.version}`);
+  log.info(`lib: ${config.libName}`);
+  log.info(`target: ${path.relative(cwd, projectDir)}`);
+  if (config.noModels) log.info('models: désactivés (--no-models)');
+  else log.info(`spec: ${specSource} | formats: ${config.formats.join(', ')} | nullableMode: ${config.requiredMode}`);
+
+  let spec;
+  if (!config.noModels) {
+    if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
+    log.step('lecture de la spec OpenAPI');
+    spec = await readOpenApiSpec(specSource);
+    log.success('spec chargée');
+  }
+
+  await generateBridgeWorkspace({
+    cwd,
+    projectDir,
+    libName: config.libName,
+    packageName: config.packageName,
+    version: config.version,
+    noModels: config.noModels,
+    spec,
+    requiredMode: config.requiredMode,
+    formats: config.formats,
+    include: config.include,
+    exclude: config.exclude,
+    debug: config.debug,
+    log,
+    projectReadmePath,
+  });
+
+  log.success(`bridge généré: ${path.relative(cwd, projectDir)}`);
+  return 0;
+}

package/tools/build.js

@@ -1,105 +1 @@
-#!/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 { 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 formats = splitListArgs(opts.formats);
-  const include = splitListArgs(opts.include);
-  const exclude = splitListArgs(opts.exclude);
-
-  const libName = deriveLibName(packageName);
-  const requiredMode = 'spec';
-  const effectiveFormats = formats.length > 0 ? formats : ['application/ld+json'];
-
-  // Standalone mode: 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} | formats: ${effectiveFormats.join(', ')} | nullableMode: ${requiredMode}`);
-
-  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,
-    formats: effectiveFormats,
-    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.');
-}
+export { runBuild } from './app/run-build.js';

package/tools/dev.js

@@ -1,219 +1 @@
-#!/usr/bin/env node
-import process from 'node:process';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { spawn } from 'node:child_process';
-
-import { deriveLibName } from './core/lib-name.js';
-import { 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));
-  });
-}
-
-async function pathIsFile(p) {
-  try {
-    const st = await fs.stat(p);
-    return st.isFile();
-  } catch {
-    return false;
-  }
-}
-
-async function readPackageJsonName(dir) {
-  try {
-    const raw = await fs.readFile(path.join(dir, 'package.json'), 'utf8');
-    const parsed = JSON.parse(raw);
-    return typeof parsed?.name === 'string' ? parsed.name : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-async function resolveDevAppRoot(startCwd) {
-  if (await pathIsFile(path.join(startCwd, 'package.json'))) return startCwd;
-  throw new Error('No package.json found. Run `meridiane dev` from your Angular app root.');
-}
-
-async function isMeridianeSandboxApp(appRoot) {
-  const name = await readPackageJsonName(appRoot);
-  return name === '@obsidiane/meridiane-sandbox';
-}
-
-async function resolveSandboxAppRoot(startCwd) {
-  // Allow running from apps/sandbox directly
-  if (await isMeridianeSandboxApp(startCwd)) return startCwd;
-
-  // Allow running from this repo root (monorepo) and target apps/sandbox
-  const sandboxApp = path.join(startCwd, 'apps', 'sandbox');
-  if (await pathIsFile(path.join(sandboxApp, 'package.json')) && (await isMeridianeSandboxApp(sandboxApp))) {
-    return sandboxApp;
-  }
-
-  throw new Error('Missing <packageName>. Run from the sandbox app (`apps/sandbox`) or provide a package name.');
-}
-
-async function findLatestTgz(distDir) {
-  const entries = await fs.readdir(distDir, { withFileTypes: true }).catch(() => []);
-  const tgzFiles = [];
-  for (const e of entries) {
-    if (!e.isFile()) continue;
-    if (!e.name.endsWith('.tgz')) continue;
-    const full = path.join(distDir, e.name);
-    const st = await fs.stat(full);
-    tgzFiles.push({ full, mtimeMs: st.mtimeMs });
-  }
-  tgzFiles.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return tgzFiles[0]?.full;
-}
-
-function splitPackageName(packageName) {
-  const s = String(packageName || '').trim();
-  if (!s) throw new Error('Missing packageName');
-  if (s.startsWith('@')) {
-    const [scope, name] = s.split('/');
-    if (!scope || !name) throw new Error(`Invalid packageName: ${packageName}`);
-    return { scope, name };
-  }
-  return { scope: undefined, name: s };
-}
-
-async function resolveNodeModulesRoot(startDir) {
-  let cur = startDir;
-  for (;;) {
-    const candidate = path.join(cur, 'node_modules');
-    try {
-      const st = await fs.stat(candidate);
-      if (st.isDirectory()) return candidate;
-    } catch {
-      // ignore
-    }
-    const parent = path.dirname(cur);
-    if (parent === cur) break;
-    cur = parent;
-  }
-
-  const nm = path.join(startDir, 'node_modules');
-  await fs.mkdir(nm, { recursive: true });
-  return nm;
-}
-
-async function installPackageFromDist({ packageName, distDir, appRoot, log }) {
-  const nmRoot = await resolveNodeModulesRoot(appRoot);
-  const { scope, name } = splitPackageName(packageName);
-  const pkgDir = scope ? path.join(nmRoot, scope, name) : path.join(nmRoot, name);
-
-  log?.step?.(`installation locale dans node_modules (${scope ? `${scope}/${name}` : name})`);
-
-  await fs.rm(pkgDir, { recursive: true, force: true });
-  await fs.mkdir(path.dirname(pkgDir), { recursive: true });
-
-  await fs.cp(distDir, pkgDir, {
-    recursive: true,
-    filter: (src) => !src.endsWith('.tgz'),
-  });
-
-  return pkgDir;
-}
-
-export async function runDev(packageName, opts) {
-  const startCwd = process.cwd();
-  const debug = !!opts.debug;
-  const log = createLogger({ debug });
-
-  const useSandboxDefaults = packageName === undefined;
-  const appRoot = useSandboxDefaults ? await resolveSandboxAppRoot(startCwd) : await resolveDevAppRoot(startCwd);
-
-  const effectivePackageName = packageName ?? '@obsidiane/bridge-sandbox';
-  const libName = deriveLibName(effectivePackageName);
-
-  const noModels = opts.models === false;
-  const formats = splitListArgs(opts.formats);
-  const include = splitListArgs(opts.include);
-  const exclude = splitListArgs(opts.exclude);
-
-  const version = '0.0.0-dev';
-  const requiredMode = 'all';
-  const effectiveFormats = formats.length > 0 ? formats : ['application/ld+json'];
-  const specSource = useSandboxDefaults ? (opts.spec ?? 'http://localhost:8000/api/docs.json') : opts.spec;
-
-  log.title('dev — build standalone + install local');
-  log.info(`app: ${appRoot}`);
-  log.info(`package: ${effectivePackageName}@${version}`);
-  log.info(`lib: ${libName}`);
-  if (useSandboxDefaults) log.info('defaults sandbox appliqués');
-  if (noModels) log.info('models: désactivés (--no-models)');
-  else log.info(`spec: ${specSource} | formats: ${effectiveFormats.join(', ')} | nullableMode: ${requiredMode}`);
-
-  const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot: appRoot, log });
-  log.info(`workspace: ${workspaceRoot}`);
-
-  let spec;
-  if (!noModels) {
-    log.step('lecture de la spec OpenAPI');
-    spec = await readOpenApiSpec(specSource);
-    log.success('spec chargée');
-  }
-
-  await ensureToolchainInstalled({ workspaceRoot, requireFromWs, npmCacheDir, log });
-
-  await generateBridgeWorkspace({
-    cwd: workspaceRoot,
-    libName,
-    packageName: effectivePackageName,
-    version,
-    noModels,
-    spec,
-    requiredMode,
-    formats: effectiveFormats,
-    include,
-    exclude,
-    debug,
-    log,
-    distRoot,
-  });
-
-  const ngPackageJsonPath = path.join(workspaceRoot, 'projects', libName, 'ng-package.json');
-  const tsconfigDevPath = path.join(workspaceRoot, 'projects', libName, 'tsconfig.lib.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', tsconfigDevPath], {
-    cwd: workspaceRoot,
-  });
-  if (packagrCode !== 0) process.exit(packagrCode);
-
-  const distDir = path.join(distRoot, libName);
-  log.step(`npm pack (${path.relative(appRoot, 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) process.exit(packCode);
-
-  await findLatestTgz(distDir); // keep producing the tgz in dist for inspection/use
-  await installPackageFromDist({ packageName: effectivePackageName, distDir, appRoot, log });
-
-  log.success('bridge installé (node_modules) ✅');
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  throw new Error('This module is not meant to be executed directly.');
-}
+export { runDev } from './app/run-dev.js';

package/tools/domain/bridge-options.js

@@ -0,0 +1,85 @@
+import { deriveLibName } from './lib-name.js';
+import { splitListArgs } from './paths.js';
+
+const DEFAULT_FORMATS = ['application/ld+json'];
+const SANDBOX_PACKAGE_NAME = '@obsidiane/bridge-sandbox';
+
+function normalizeCommonOptions(opts) {
+  const noModels = opts?.models === false;
+  const formats = splitListArgs(opts?.formats);
+  const include = splitListArgs(opts?.include);
+  const exclude = splitListArgs(opts?.exclude);
+  const debug = !!opts?.debug;
+
+  return { noModels, formats, include, exclude, debug };
+}
+
+function normalizeFormats(formats) {
+  return formats.length > 0 ? formats : [...DEFAULT_FORMATS];
+}
+
+function normalizeVersion(version) {
+  const raw = typeof version === 'string' ? version.trim() : '';
+  return raw || '0.0.0';
+}
+
+export function normalizeBuildOptions(packageName, opts) {
+  const common = normalizeCommonOptions(opts);
+  const normalizedPackageName = String(packageName || '').trim();
+  if (!normalizedPackageName) throw new Error('Missing packageName');
+
+  return {
+    mode: 'build',
+    packageName: normalizedPackageName,
+    libName: deriveLibName(normalizedPackageName),
+    version: normalizeVersion(opts?.version),
+    requiredMode: 'spec',
+    formats: normalizeFormats(common.formats),
+    include: common.include,
+    exclude: common.exclude,
+    noModels: common.noModels,
+    debug: common.debug,
+  };
+}
+
+export function normalizeGenerateOptions(packageName, opts) {
+  const common = normalizeCommonOptions(opts);
+  const normalizedPackageName = String(packageName || '').trim();
+  if (!normalizedPackageName) throw new Error('Missing packageName');
+
+  const outDir = typeof opts?.out === 'string' ? opts.out.trim() : '';
+
+  return {
+    mode: 'generate',
+    packageName: normalizedPackageName,
+    libName: deriveLibName(normalizedPackageName),
+    version: normalizeVersion(opts?.version),
+    requiredMode: 'spec',
+    formats: normalizeFormats(common.formats),
+    include: common.include,
+    exclude: common.exclude,
+    noModels: common.noModels,
+    debug: common.debug,
+    outDir,
+  };
+}
+
+export function normalizeDevOptions(packageName, opts) {
+  const common = normalizeCommonOptions(opts);
+  const useSandboxDefaults = packageName === undefined;
+  const effectivePackageName = String(packageName ?? SANDBOX_PACKAGE_NAME).trim();
+
+  return {
+    mode: 'dev',
+    useSandboxDefaults,
+    packageName: effectivePackageName,
+    libName: deriveLibName(effectivePackageName),
+    version: '0.0.0-dev',
+    requiredMode: 'all',
+    formats: normalizeFormats(common.formats),
+    include: common.include,
+    exclude: common.exclude,
+    noModels: common.noModels,
+    debug: common.debug,
+  };
+}

package/tools/generate.js

@@ -0,0 +1 @@
+export { runGenerate } from './app/run-generate.js';

package/tools/infra/dev-support.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+async function pathIsFile(p) {
+  try {
+    const st = await fs.stat(p);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function readPackageJsonName(dir) {
+  try {
+    const raw = await fs.readFile(path.join(dir, 'package.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.name === 'string' ? parsed.name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function isMeridianeSandboxApp(appRoot) {
+  const name = await readPackageJsonName(appRoot);
+  return name === '@obsidiane/meridiane-sandbox';
+}
+
+export async function resolveDevAppRoot(startCwd) {
+  if (await pathIsFile(path.join(startCwd, 'package.json'))) return startCwd;
+  throw new Error('No package.json found. Run `meridiane dev` from your Angular app root.');
+}
+
+export async function resolveSandboxAppRoot(startCwd) {
+  if (await isMeridianeSandboxApp(startCwd)) return startCwd;
+
+  const sandboxApp = path.join(startCwd, 'apps', 'sandbox');
+  if (await pathIsFile(path.join(sandboxApp, 'package.json')) && (await isMeridianeSandboxApp(sandboxApp))) {
+    return sandboxApp;
+  }
+
+  throw new Error('Missing <packageName>. Run from the sandbox app (`apps/sandbox`) or provide a package name.');
+}
+
+export async function resolveSpecSource({ useSandboxDefaults, appRoot, specArg }) {
+  if (!useSandboxDefaults) return specArg;
+  if (specArg) return specArg;
+  const localSpec = path.resolve(appRoot, '..', 'backend', 'var', 'openapi.json');
+  return (await pathIsFile(localSpec)) ? localSpec : 'http://localhost:8000/api/docs.json';
+}
+
+export async function findLatestTgz(distDir) {
+  const entries = await fs.readdir(distDir, { withFileTypes: true }).catch(() => []);
+  const tgzFiles = [];
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    if (!e.name.endsWith('.tgz')) continue;
+    const full = path.join(distDir, e.name);
+    const st = await fs.stat(full);
+    tgzFiles.push({ full, mtimeMs: st.mtimeMs });
+  }
+  tgzFiles.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return tgzFiles[0]?.full;
+}
+
+function splitPackageName(packageName) {
+  const s = String(packageName || '').trim();
+  if (!s) throw new Error('Missing packageName');
+  if (s.startsWith('@')) {
+    const [scope, name] = s.split('/');
+    if (!scope || !name) throw new Error(`Invalid packageName: ${packageName}`);
+    return { scope, name };
+  }
+  return { scope: undefined, name: s };
+}
+
+async function resolveNodeModulesRoot(startDir) {
+  let cur = startDir;
+  for (;;) {
+    const candidate = path.join(cur, 'node_modules');
+    try {
+      const st = await fs.stat(candidate);
+      if (st.isDirectory()) return candidate;
+    } catch {
+      // ignore
+    }
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+
+  const nm = path.join(startDir, 'node_modules');
+  await fs.mkdir(nm, { recursive: true });
+  return nm;
+}
+
+export async function installPackageFromDist({ packageName, distDir, appRoot, log }) {
+  const nmRoot = await resolveNodeModulesRoot(appRoot);
+  const { scope, name } = splitPackageName(packageName);
+  const pkgDir = scope ? path.join(nmRoot, scope, name) : path.join(nmRoot, name);
+
+  log?.step?.(`installation locale dans node_modules (${scope ? `${scope}/${name}` : name})`);
+
+  await fs.rm(pkgDir, { recursive: true, force: true });
+  await fs.mkdir(path.dirname(pkgDir), { recursive: true });
+
+  await fs.cp(distDir, pkgDir, {
+    recursive: true,
+    filter: (src) => !src.endsWith('.tgz'),
+  });
+
+  return pkgDir;
+}

package/tools/infra/exec.js

@@ -0,0 +1,21 @@
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+
+export class ExitCodeError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.name = 'ExitCodeError';
+    this.exitCode = exitCode;
+  }
+}
+
+export function runCommand(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));
+  });
+}

package/tools/{core/generate.js → infra/generate/bridge.js}

@@ -3,15 +3,44 @@ 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';
+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
+const pkgRoot = path.resolve(__dirname, '../../..'); // packages/meridiane
+
+async function readTextIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+async function appendProjectReadme({targetReadmePath, projectReadmePath, debug, log}) {
+  if (!projectReadmePath) return;
+
+  const projectReadme = await readTextIfExists(projectReadmePath);
+  if (!projectReadme || projectReadme.trim().length === 0) return;
+
+  const targetReadme = await readTextIfExists(targetReadmePath);
+  if (!targetReadme || targetReadme.trim().length === 0) {
+    await fs.writeFile(targetReadmePath, projectReadme);
+    if (debug) log?.debug?.('[meridiane] project README copied', {source: projectReadmePath});
+    return;
+  }
+
+  const combined =
+    `${targetReadme.trimEnd()}\n\n---\n\n` +
+    `## Documentation du projet\n\n` +
+    `${projectReadme.trimStart()}`;
+  await fs.writeFile(targetReadmePath, combined);
+  if (debug) log?.debug?.('[meridiane] project README appended', {source: projectReadmePath});
+}
 
 async function replacePlaceholdersInDir(dir, placeholders) {
   const entries = await fs.readdir(dir, {withFileTypes: true});
@@ -29,16 +58,18 @@ async function replacePlaceholdersInDir(dir, placeholders) {
   }
 }
 
-async function generateLibrary({cwd, libName, packageName, version, debug}) {
+async function generateLibrary({projectDir, libName, packageName, version, debug, log, projectReadmePath}) {
   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)
-  });
+  const targetDir = projectDir;
+
+  if (debug) {
+    log?.debug?.('[meridiane] generate lib', {
+      libName,
+      packageName,
+      version,
+      targetDir
+    });
+  }
 
   await fs.rm(targetDir, {recursive: true, force: true});
   await fs.mkdir(targetDir, {recursive: true});
@@ -57,21 +88,29 @@ async function generateLibrary({cwd, libName, packageName, version, debug}) {
     await writeJsonIfChanged(libPackageJsonPath, libPkg);
   }
 
-  // angular.json / workspace patching is intentionally not done here (Meridiane is standalone).
+  await appendProjectReadme({
+    targetReadmePath: path.join(targetDir, 'README.md'),
+    projectReadmePath,
+    debug,
+    log,
+  });
+
+  // angular.json / workspace patching is intentionally not done here.
 }
 
-async function generateModels({cwd, libName, spec, requiredMode, formats, include, exclude, debug}) {
-  const outDir = path.resolve(cwd, 'projects', libName, 'src', 'models');
+async function generateModels({projectDir, spec, requiredMode, formats, include, exclude, debug, log}) {
+  const outDir = path.resolve(projectDir, 'src', 'models');
   const templatesDir = path.resolve(pkgRoot, 'tools', 'generator', 'models', 'templates');
 
-  if (debug)
-    console.log('[meridiane] generate models', {
-      outDir: path.relative(cwd, outDir),
+  if (debug) {
+    log?.debug?.('[meridiane] generate models', {
+      outDir,
       requiredMode,
       formats: Array.isArray(formats) ? formats : [],
       includeCount: include.length,
       excludeCount: exclude.length,
     });
+  }
 
   await ensureCleanDir(outDir);
 
@@ -103,7 +142,7 @@ async function generateModels({cwd, libName, spec, requiredMode, formats, includ
     ctx: {models: models.map((m) => ({name: m.name}))},
   });
 
-  if (debug) console.log(`[meridiane] ${models.length} model(s) generated`);
+  if (debug) log?.debug?.(`[meridiane] ${models.length} model(s) generated`);
 }
 
 /**
@@ -122,6 +161,8 @@ async function generateModels({cwd, libName, spec, requiredMode, formats, includ
  *   log?: { step?: (msg: string) => void, info?: (msg: string) => void, success?: (msg: string) => void, debug?: (msg: string, data?: any) => void },
  *   workspaceMode?: 'angular'|'standalone',
  *   distRoot?: string,
+ *   projectDir?: string,
+ *   projectReadmePath?: string,
  * }} params
  */
 export async function generateBridgeWorkspace(params) {
@@ -139,30 +180,33 @@ export async function generateBridgeWorkspace(params) {
     debug,
     log,
     distRoot,
+    projectDir: projectDirInput,
+    projectReadmePath,
   } = params;
 
-  log?.step?.(`génération de la librairie (projects/${libName})`);
-  await generateLibrary({cwd, libName, packageName, version, debug});
+  const projectDir = projectDirInput ?? path.resolve(cwd, 'projects', libName);
+  log?.step?.(`génération de la librairie (${path.relative(cwd, projectDir)})`);
+  await generateLibrary({projectDir, libName, packageName, version, debug, log, projectReadmePath});
 
   // 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 ngPackagePath = path.resolve(projectDir, '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('/');
+    const projectRoot = path.dirname(ngPackagePath);
+    ngPkg.dest = path.relative(projectRoot, 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');
+    if (debug) log?.debug?.('[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, formats, include, exclude, debug});
+  await generateModels({projectDir, spec, requiredMode, formats, include, exclude, debug, log});
   log?.success?.('génération terminée');
 }

package/tools/{core/standalone.js → infra/standalone-workspace.js}

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 
+import { runCommand } from './exec.js';
 import { writeJsonIfChanged } from './json.js';
 
 async function ensureDir(p) {
@@ -62,7 +63,8 @@ export async function ensureStandaloneWorkspace({ repoRoot, log }) {
   await ensureDir(distRoot);
   await ensureDir(workspaceRoot);
 
-  const angularVersion = '20.1.7';
+  const angularVersion = (await detectAngularVersion(repoRoot)) ?? '20.1.7';
+  log?.debug?.('[meridiane] angular version', { angularVersion });
   await writeJsonIfChanged(path.join(workspaceRoot, 'package.json'), toolchainPackageJson({ angularVersion }));
   await writeJsonIfChanged(path.join(workspaceRoot, 'tsconfig.json'), rootTsconfigJson());
 
@@ -74,6 +76,21 @@ export async function ensureStandaloneWorkspace({ repoRoot, log }) {
   return { workspaceRoot, distRoot, npmCacheDir, requireFromWs };
 }
 
+async function detectAngularVersion(repoRoot) {
+  const pkgPath = path.join(repoRoot, 'package.json');
+  try {
+    const raw = await fs.readFile(pkgPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const deps = parsed?.dependencies || {};
+    const devDeps = parsed?.devDependencies || {};
+    const peerDeps = parsed?.peerDependencies || {};
+    const v = deps['@angular/core'] ?? devDeps['@angular/core'] ?? peerDeps['@angular/core'];
+    return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function ensureToolchainInstalled({ workspaceRoot, requireFromWs, npmCacheDir, log }) {
   // Prefer using existing (hoisted) deps during local dev; in CI this will trigger installation.
   const canResolve = (id) => {
@@ -101,12 +118,7 @@ export async function ensureToolchainInstalled({ workspaceRoot, requireFromWs, n
   // We avoid generating a lockfile in the backend repo by keeping everything under dist/.
   const npmCmd = 'npm';
   const args = ['install', '--silent', '--no-progress'];
-  const { spawn } = await import('node:child_process');
-
-  const code = await new Promise((resolve) => {
-    const child = spawn(npmCmd, args, { cwd: workspaceRoot, stdio: 'inherit', env });
-    child.on('exit', (c) => resolve(c ?? 0));
-  });
+  const code = await runCommand(npmCmd, args, { cwd: workspaceRoot, env });
 
   if (code !== 0) throw new Error(`Toolchain install failed (npm exit ${code})`);
   if (!(await exists(path.join(workspaceRoot, 'node_modules')))) {
@@ -114,4 +126,3 @@ export async function ensureToolchainInstalled({ workspaceRoot, requireFromWs, n
   }
   return true;
 }
-