@obsidiane/meridiane 2.0.13 → 3.0.0

package/README.md

@@ -1,85 +1,47 @@
 # @obsidiane/meridiane
 
-CLI pour générer un bridge Angular (runtime + models TypeScript) depuis une spec OpenAPI (API Platform + Mercure).
+Génère, depuis le contrat OpenAPI d'API Platform, une librairie Angular (« le bridge ») :
 
-Documentation complète du repo : `docs/guide-bridge.md`.
+- les **modèles TypeScript** de vos ressources ;
+- un **client HTTP** aux conventions API Platform (JSON-LD, Hydra, merge-patch) ;
+- le **temps réel Mercure 1.0** : abonnement à une ressource ou à un item, connexions partagées, autorisation par cookie.
 
-## Installation
+Le bridge gère la connexion ; la gestion des données reste dans votre application. Il est compatible avec Angular 20, 21 et 22.
 
-```bash
-npm i -D @obsidiane/meridiane
-```
-
-## Commandes
-
-### `meridiane generate <packageName>`
-
-Génère uniquement les sources du bridge dans le workspace courant.
+## En bref
 
 ```bash
-npx meridiane generate @acme/backend-bridge --spec ./openapi.json
+npx @obsidiane/meridiane@3 generate @app/bridge --spec http://localhost:8000/api/docs.json --out bridge
 ```
 
-Sortie par défaut : `projects/<libName>/` (modifiable via `--out`).
+```ts
+// app.config.ts
+provideBridge({
+  baseUrl: '/',
+  mercure: {hubUrl: '/.well-known/mercure', authorize: '/api/mercure/authorization'},
+});
 
-### `meridiane dev [packageName]`
+// project.repository.ts
+private readonly projects = inject(FacadeFactory).create<Project>({url: '/api/projects'});
 
-Génération + build standalone + `npm pack` + installation locale dans `node_modules`.
-
-```bash
-npx meridiane dev @acme/backend-bridge --spec http://localhost:8000/api/docs.json
+list$ = this.projects.getCollection$({page: 1, itemsPerPage: 20});   // Collection<Project>
+changes$ = this.projects.watch$();                                    // Project | ResourceDeletion, en direct
 ```
 
-Sorties :
-- `dist/<libName>/` + `dist/<libName>/*.tgz`
-- `node_modules/<packageName>/`
-
-### `meridiane build <packageName>`
-
-Génération + build standalone + `npm pack` (artefact publiable).
-
-```bash
-npx meridiane build @acme/backend-bridge --version 1.2.3 --spec https://staging.example/api/docs.json
-```
-
-Sorties :
-- `dist/<libName>/`
-- `dist/<libName>/*.tgz`
-
-## Options
-
-- `--spec <url|file>` : URL OpenAPI ou fichier JSON local (requis sauf `--no-models`)
-- `--formats <mimeTypes>` : répétable ou liste `,` ; défaut `application/ld+json`
-- `--include <substr>` / `--exclude <substr>` : filtres de noms de schémas (répétables, support `,`)
-- `--no-models` : runtime only
-- `--version <semver>` : `build` et `generate` (défaut `0.0.0`)
-- `--out <dir>` : uniquement `generate`
-- `--debug` : logs détaillés
-
-## Notes importantes
-
-- fallback automatique `.../api/docs.json` -> `.../api/docs.jsonopenapi` si nécessaire
-- mode contract-driven : uniquement les schémas atteignables via `paths` et `webhooks` pour les formats sélectionnés
-- modèles `*jsonMergePatch*` non générés (`PATCH` typé `Partial<T>`)
-- Meridiane ne publie pas : publication via `npm publish` côté CI
-
-## Couverture des schémas
-
-Le compilateur suit les types d’[OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.4.html) et le dialecte
-[JSON Schema 2020-12 d’OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0.html#schema-object) :
+## Commandes
 
-- primitives, unions de `type`, objets, propriétés requises, dictionnaires et schémas booléens ;
-- tableaux homogènes, tuples `prefixItems`, tuples historiques et bornes de longueur des tuples ;
-- `enum` et `const`, y compris les valeurs JSON structurées ;
-- `allOf`, `oneOf`, `anyOf`, `nullable` et références locales vers `components.schemas` ou `$defs` ;
-- schémas racine objets sous forme d’interfaces et autres schémas sous forme d’aliases TypeScript ;
-- contrats atteignables depuis les bodies, paramètres, en-têtes, callbacks et webhooks.
+| Commande | Produit |
+|---|---|
+| `generate <package>` | les sources du bridge dans le projet (`--out`) |
+| `build <package>` | un package compilé et son `.tgz` dans `dist/`, prêt à publier |
+| `dev <package>` | le package compilé, installé dans `node_modules` |
 
-Les règles de validation sans équivalent structurel TypeScript (`pattern`, bornes numériques,
-`uniqueItems`, `contains`, `not`, conditions, fermeture exacte des propriétés, etc.) restent à la
-charge de la validation runtime. Les références externes doivent être préalablement regroupées dans
-le document OpenAPI fourni à Meridiane.
+Options : `--spec`, `--include`, `--exclude`, `--no-models`, `--version`, `--out`, `--debug`. Node.js ≥ 24.
 
-## Spécifique à ce repo
+## Documentation
 
-Dans ce monorepo, `meridiane dev` peut être exécuté sans `packageName` et cible alors `@obsidiane/bridge-sandbox` (app `playground/angular-app`).
+- [Démarrage](https://github.com/obsidiane-lab/meridiane/blob/master/docs/demarrage.md)
+- [Configuration (cookies, auth, Mercure)](https://github.com/obsidiane-lab/meridiane/blob/master/docs/configuration.md)
+- [HTTP](https://github.com/obsidiane-lab/meridiane/blob/master/docs/http.md) · [Temps réel](https://github.com/obsidiane-lab/meridiane/blob/master/docs/temps-reel.md) · [Backend](https://github.com/obsidiane-lab/meridiane/blob/master/docs/backend.md)
+- [Recettes](https://github.com/obsidiane-lab/meridiane/blob/master/docs/recettes.md) · [Référence](https://github.com/obsidiane-lab/meridiane/blob/master/docs/reference.md) · [CLI](https://github.com/obsidiane-lab/meridiane/blob/master/docs/cli.md)
+- [Dépannage](https://github.com/obsidiane-lab/meridiane/blob/master/docs/depannage.md) · [Migration 2.x → 3.0](https://github.com/obsidiane-lab/meridiane/blob/master/docs/migration-3.0.md)

package/cli.js

@@ -18,12 +18,6 @@ function collect(value, previous = []) {
 function commonOptions(cmd) {
   return cmd
     .option('--spec <urlOrFile>', 'OpenAPI spec source (URL or local JSON file)')
-    .option(
-      '--formats <mimeTypes>',
-      'Generate only selected media types (repeatable, supports commas). Enables contract-driven mode from paths.',
-      collect,
-      []
-    )
     .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)')
@@ -47,10 +41,7 @@ function action(run) {
 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).'
-    )
+    .argument('<packageName>', 'NPM package name of the generated bridge (e.g. @acme/backend-bridge)')
     .action(action(runDev))
 );
 

package/package.json

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

package/src/application/bridge-workflow.js

@@ -3,75 +3,42 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 
-import { generateBridgeWorkspace } from './generate-bridge.js';
-import { readOpenApiSpec } from '../infrastructure/spec-loader.js';
+import { generateBridge } from './generate-bridge.js';
 import { ExitCodeError, runCommand } from '../infrastructure/exec.js';
+import { ensureCleanDir } from '../infrastructure/files.js';
 
 const ngPackagrPath = fileURLToPath(import.meta.resolve('ng-packagr/src/cli/main.js'));
+/** `node_modules` holding the CLI's Angular toolchain (wherever npx installed it). */
+const toolchainModules = path.resolve(fileURLToPath(import.meta.resolve('@angular/core/package.json')), '../../..');
 
-export async function runBridgeWorkflow({
-  repoRoot,
-  libName,
-  packageName,
-  version,
-  noModels,
-  spec,
-  specSource,
-  requiredMode,
-  formats,
-  include,
-  exclude,
-  debug,
-  log,
-  tsconfigPath,
-  packRelativeTo,
-  projectReadmePath,
-}) {
+/** Generates the bridge in an isolated workspace under `dist/`, builds it with ng-packagr and packs it. */
+export async function buildBridgePackage({ config, repoRoot, tsconfigPath, log }) {
   const distRoot = path.join(repoRoot, 'dist');
   const buildRoot = path.join(distRoot, '.meridiane-workspace');
-  const npmCacheDir = path.join(buildRoot, '.npm-cache');
-  await fs.rm(buildRoot, { recursive: true, force: true });
-  await fs.mkdir(buildRoot, { recursive: true });
-  log?.info?.(`workspace: ${buildRoot}`);
-
-  const resolvedSpec = await loadSpecIfNeeded({ noModels, spec, specSource, log });
-
-  await generateBridgeWorkspace({
-    cwd: buildRoot,
-    libName,
-    packageName,
-    version,
-    noModels,
-    spec: resolvedSpec,
-    requiredMode,
-    formats,
-    include,
-    exclude,
-    debug,
-    log,
-    distRoot,
-    projectReadmePath,
-  });
-
-  const projectDir = path.join(buildRoot, 'projects', libName);
-  const ngPackageJsonPath = path.join(projectDir, 'ng-package.json');
-  const tsconfigAbsPath = path.join(projectDir, tsconfigPath);
-
-  log?.step?.('ng-packagr');
-  const packagrCode = await runCommand(process.execPath, [ngPackagrPath, '-p', ngPackageJsonPath, '-c', tsconfigAbsPath], {
-    cwd: buildRoot,
-  });
+  const projectDir = path.join(buildRoot, 'projects', config.libName);
+  await ensureCleanDir(buildRoot);
+  // The bridge compiles against the CLI's Angular and RxJS, not the dependencies of the current project.
+  await fs.symlink(toolchainModules, path.join(buildRoot, 'node_modules'), 'junction');
+  log.info(`workspace: ${path.relative(repoRoot, buildRoot)}`);
+
+  await generateBridge({ config, root: repoRoot, projectDir, distRoot, log });
+
+  log.step('ng-packagr');
+  const packagrCode = await runCommand(
+    process.execPath,
+    [ngPackagrPath, '-p', path.join(projectDir, 'ng-package.json'), '-c', path.join(projectDir, tsconfigPath)],
+    { cwd: buildRoot }
+  );
   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 distDir = path.join(distRoot, config.libName);
+  log.step(`npm pack (${path.relative(repoRoot, distDir)})`);
   await cleanupPackedTarballs(distDir);
   const packCode = await runCommand('npm', ['pack'], {
     cwd: distDir,
     env: {
       ...process.env,
-      npm_config_cache: npmCacheDir,
+      npm_config_cache: path.join(buildRoot, '.npm-cache'),
       npm_config_update_notifier: 'false',
       npm_config_fund: 'false',
       npm_config_audit: 'false',
@@ -82,16 +49,6 @@ export async function runBridgeWorkflow({
   return { distDir };
 }
 
-async function loadSpecIfNeeded({ noModels, spec, specSource, log }) {
-  if (noModels || spec) return spec;
-  if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
-
-  log?.step?.('lecture de la spec OpenAPI');
-  const loadedSpec = await readOpenApiSpec(specSource);
-  log?.success?.('spec chargée');
-  return loadedSpec;
-}
-
 async function cleanupPackedTarballs(distDir) {
   const entries = await fs.readdir(distDir, {withFileTypes: true});
   const tarballs = entries.filter((entry) => entry.isFile() && entry.name.endsWith('.tgz'));

package/src/application/generate-bridge.js

@@ -2,49 +2,45 @@ import path from 'node:path';
 
 import { configureBridgeOutput, writeBridgeFiles } from '../generators/bridge/write-bridge-files.js';
 import { writeModelFiles } from '../generators/models/write-model-files.js';
+import { readOpenApiSpec } from '../infrastructure/spec-loader.js';
 
-/** Generates the Angular bridge sources in a workspace project. */
-export async function generateBridgeWorkspace({
-  cwd,
-  libName,
-  packageName,
-  version,
-  noModels,
-  spec,
-  requiredMode,
-  formats,
-  include,
-  exclude,
-  debug,
-  log,
-  distRoot,
-  projectDir: configuredProjectDir,
-  projectReadmePath,
-}) {
-  const projectDir = configuredProjectDir ?? path.resolve(cwd, 'projects', libName);
+/** Logs the command title and its configuration. */
+export function logConfig(log, title, config, details) {
+  log.title(title);
+  for (const [label, value] of Object.entries(details)) log.info(`${label}: ${value}`);
+  log.info(`package: ${config.packageName}@${config.version}`);
+  log.info(`lib: ${config.libName}`);
+  log.info(config.noModels ? 'models: désactivés (--no-models)' : `spec: ${config.specSource}`);
+}
+
+/**
+ * Generates the Angular bridge sources (library files and models) in `projectDir`.
+ * The project README of `root` is appended to the bridge README.
+ */
+export async function generateBridge({ config, root, projectDir, distRoot, log }) {
+  const spec = config.noModels ? undefined : await loadSpec(config.specSource, log);
 
-  log?.step?.(`génération de la librairie (${path.relative(cwd, projectDir)})`);
+  log.step(`génération de la librairie (${path.relative(root, projectDir)})`);
   await writeBridgeFiles({
     projectDir,
-    libName,
-    packageName,
-    version,
-    projectReadmePath,
-    debug,
+    libName: config.libName,
+    packageName: config.packageName,
+    version: config.version,
+    projectReadmePath: path.join(root, 'README.md'),
     log,
   });
+  if (distRoot) await configureBridgeOutput({ projectDir, distRoot, libName: config.libName, log });
 
-  if (distRoot) await configureBridgeOutput({ projectDir, distRoot, libName, log });
-
-  if (noModels) {
-    log?.info?.('models ignorés (--no-models)');
-    if (debug) log?.debug?.('[meridiane] --no-models enabled, skipping models generation');
-    return;
-  }
+  if (!spec) return;
+  log.step('génération des models (OpenAPI)');
+  await writeModelFiles({ projectDir, spec, include: config.include, exclude: config.exclude, log });
+}
 
-  if (!spec) throw new Error('Internal error: spec is required when noModels=false');
+async function loadSpec(specSource, log) {
+  if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
 
-  log?.step?.('génération des models (OpenAPI)');
-  await writeModelFiles({ projectDir, spec, requiredMode, formats, include, exclude, debug, log });
-  log?.success?.('génération terminée');
+  log.step('lecture de la spec OpenAPI');
+  const spec = await readOpenApiSpec(specSource);
+  log.success('spec chargée');
+  return spec;
 }

package/src/application/run-build.js

@@ -1,41 +1,19 @@
 import process from 'node:process';
 import path from 'node:path';
 
-import { normalizeBuildOptions } from '../domain/bridge-options.js';
+import { normalizeOptions } from '../domain/bridge-options.js';
 import { createLogger } from '../infrastructure/logger.js';
-import { runBridgeWorkflow } from './bridge-workflow.js';
+import { buildBridgePackage } from './bridge-workflow.js';
+import { logConfig } from './generate-bridge.js';
 
 export async function runBuild(packageName, opts) {
-  const cwd = process.cwd();
-  const config = normalizeBuildOptions(packageName, opts);
+  const repoRoot = process.cwd();
+  const config = normalizeOptions(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}`);
+  logConfig(log, 'build — standalone', config, { repo: repoRoot });
+  const { distDir } = await buildBridgePackage({ config, repoRoot, tsconfigPath: 'tsconfig.lib.prod.json', log });
 
-  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)}`);
+  log.success(`package prêt: ${path.relative(repoRoot, distDir)}`);
   return 0;
 }

package/src/application/run-dev.js

@@ -1,74 +1,19 @@
 import process from 'node:process';
-import path from 'node:path';
 
-import { normalizeDevOptions } from '../domain/bridge-options.js';
+import { normalizeOptions } from '../domain/bridge-options.js';
 import { createLogger } from '../infrastructure/logger.js';
-import {resolveDevAppRoot, resolveSandboxAppRoot, resolveSpecSource} from '../infrastructure/dev-project.js';
+import {resolveDevAppRoot} from '../infrastructure/dev-project.js';
 import {installPackageFromDist} from '../infrastructure/local-package-install.js';
-import { readOpenApiSpec } from '../infrastructure/spec-loader.js';
-import { runBridgeWorkflow } from './bridge-workflow.js';
-
-async function loadDevSpec({config, opts, appRoot, log}) {
-  if (config.noModels) return {noModels: true};
-
-  const specSource = await resolveSpecSource({
-    useSandboxDefaults: config.useSandboxDefaults,
-    appRoot,
-    specArg: opts.spec,
-  });
-
-  if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
-
-  try {
-    return {noModels: false, specSource, spec: await readOpenApiSpec(specSource)};
-  } catch (error) {
-    const canSkipModels = config.useSandboxDefaults && opts.spec == null;
-    if (!canSkipModels) throw error;
-
-    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`).'
-    );
-    return {noModels: true, specSource};
-  }
-}
+import { buildBridgePackage } from './bridge-workflow.js';
+import { logConfig } from './generate-bridge.js';
 
 export async function runDev(packageName, opts) {
-  const startCwd = process.cwd();
-  const config = normalizeDevOptions(packageName, opts);
+  const config = { ...normalizeOptions(packageName, opts), version: '0.0.0-dev' };
   const log = createLogger({ debug: config.debug });
+  const appRoot = await resolveDevAppRoot(process.cwd());
 
-  const appRoot = config.useSandboxDefaults ? await resolveSandboxAppRoot(startCwd) : await resolveDevAppRoot(startCwd);
-  const projectReadmePath = path.join(appRoot, 'README.md');
-  const {noModels, specSource, spec} = await loadDevSpec({config, opts, appRoot, log});
-
-  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,
-  });
-
+  logConfig(log, 'dev — build standalone + install local', config, { app: appRoot });
+  const { distDir } = await buildBridgePackage({ config, repoRoot: appRoot, tsconfigPath: 'tsconfig.lib.json', log });
   await installPackageFromDist({ packageName: config.packageName, distDir, appRoot, log });
 
   log.success('bridge installé (node_modules) ✅');

package/src/application/run-generate.js

@@ -1,58 +1,19 @@
 import process from 'node:process';
 import path from 'node:path';
 
-import { normalizeGenerateOptions } from '../domain/bridge-options.js';
-import { generateBridgeWorkspace } from './generate-bridge.js';
+import { normalizeOptions } from '../domain/bridge-options.js';
 import { createLogger } from '../infrastructure/logger.js';
-import { readOpenApiSpec } from '../infrastructure/spec-loader.js';
-
-function resolveProjectDir({ cwd, libName, outDir }) {
-  if (outDir && outDir.length > 0) return path.resolve(cwd, outDir);
-  return path.resolve(cwd, 'projects', libName);
-}
+import { generateBridge, logConfig } from './generate-bridge.js';
 
 export async function runGenerate(packageName, opts) {
-  const cwd = process.cwd();
-  const config = normalizeGenerateOptions(packageName, opts);
+  const root = process.cwd();
+  const config = normalizeOptions(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');
-  }
+  const projectDir = path.resolve(root, config.outDir || path.join('projects', config.libName));
 
-  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,
-  });
+  logConfig(log, 'generate — workspace files', config, { repo: root, target: path.relative(root, projectDir) });
+  await generateBridge({ config, root, projectDir, log });
 
-  log.success(`bridge généré: ${path.relative(cwd, projectDir)}`);
+  log.success(`bridge généré: ${path.relative(root, projectDir)}`);
   return 0;
 }

package/src/domain/bridge-options.js

@@ -1,72 +1,19 @@
 import { deriveLibName } from './lib-name.js';
 import {splitListArgs} from './list-values.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';
-}
-
-function normalizeNamedOptions(packageName, opts) {
-  const common = normalizeCommonOptions(opts);
-  const normalizedPackageName = String(packageName || '').trim();
-  if (!normalizedPackageName) throw new Error('Missing packageName');
+/** Normalizes the arguments of `generate`, `build` and `dev` into one configuration. */
+export function normalizeOptions(packageName, opts = {}) {
+  const normalizedPackageName = String(packageName ?? '').trim();
 
   return {
     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 normalizeBuildOptions(packageName, opts) {
-  return normalizeNamedOptions(packageName, opts);
-}
-
-export function normalizeGenerateOptions(packageName, opts) {
-  return {
-    ...normalizeNamedOptions(packageName, opts),
-    outDir: typeof opts?.out === 'string' ? opts.out.trim() : '',
-  };
-}
-
-export function normalizeDevOptions(packageName, opts) {
-  const common = normalizeCommonOptions(opts);
-  const useSandboxDefaults = packageName === undefined;
-  const effectivePackageName = String(packageName ?? SANDBOX_PACKAGE_NAME).trim();
-
-  return {
-    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,
+    version: (typeof opts.version === 'string' && opts.version.trim()) || '0.0.0',
+    specSource: opts.spec,
+    include: splitListArgs(opts.include),
+    exclude: splitListArgs(opts.exclude),
+    noModels: opts.models === false,
+    debug: !!opts.debug,
+    outDir: typeof opts.out === 'string' ? opts.out.trim() : '',
   };
 }