@obsidiane/meridiane 0.0.6 → 0.0.10

package/README.md

@@ -2,6 +2,8 @@
 
 CLI pour générer une librairie Angular “bridge” (Symfony / API Platform / Mercure) et générer des modèles TypeScript depuis une spec OpenAPI.
 
+Documentation détaillée (repo) : `docs/index.md`.
+
 ## Installation
 
 ```bash
@@ -17,44 +19,30 @@ npm i -g @obsidiane/meridiane
 ## Usage
 
 ```bash
-# 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] [--no-index]
-```
-
-`url-registry` est optionnel. Recommandé : gérer le registry via `.npmrc` / variables CI plutôt que de le passer au générateur.
+# 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]
 
-## Exemple CI (générer + build + publish)
-
-```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
+# 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]
 ```
 
-Si votre workspace ne contient pas `ng-packagr` (souvent le cas dans une app Angular “pure”), installez-le :
+Options :
+- `--debug` : active des logs supplémentaires (CLI).
 
-```bash
-npm i -D ng-packagr
-```
+Bonnes pratiques :
+- 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 …`)
 
-## Configuration (models.config.js)
+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`).
 
-Le générateur de modèles charge automatiquement un fichier `models.config.js` s’il existe dans le répertoire courant (CWD).
-
-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
 ```
 
-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,50 +1,70 @@
 #!/usr/bin/env node
-import {fileURLToPath} from 'node:url';
-import path from 'node:path';
-import {spawn} from 'node:child_process';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-function runTool(scriptName, args) {
-  const scriptPath = path.join(__dirname, 'tools', scriptName);
-  const child = spawn(process.execPath, [scriptPath, ...args], {
-    stdio: 'inherit',
-  });
-
-  child.on('exit', (code) => {
-    process.exit(code ?? 0);
-  });
-}
+import process from 'node:process';
+import { Command } from 'commander';
+
+import { runDev } from './tools/dev.js';
+import { runBuild } from './tools/build.js';
+import { createLogger } from './tools/core/logger.js';
+
+const program = new Command();
+
+program
+  .name('meridiane')
+  .description('Generate an Angular bridge + models from an API Platform OpenAPI spec.')
+  .showHelpAfterError()
+  .showSuggestionAfterError();
 
-function printHelp() {
-  console.log(`
-Usage:
-  meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
-  meridiane models <SPEC_OPENAPI_URL_OU_FICHIER_JSON> [options]
+function presetParser(value, previous) {
+  if (value === undefined && previous === undefined) return true; // `--preset` (no value) => native
+  return value ?? previous;
+}
 
-Examples:
-  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
-`);
+function collect(value, previous = []) {
+  return [...previous, value];
 }
 
-const [, , cmd, ...rest] = process.argv;
-
-switch (cmd) {
-  case 'lib':
-    runTool('generate-lib.js', rest);
-    break;
-  case 'models':
-    runTool('generate-models.js', rest);
-    break;
-  case '-h':
-  case '--help':
-  case undefined:
-    printHelp();
-    break;
-  default:
-    console.error(`Unknown command: ${cmd}`);
-    printHelp();
-    process.exit(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');
 }
+
+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);
+      }
+    })
+);
+
+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.6",
+  "version": "0.0.10",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",
@@ -14,24 +14,20 @@
     "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": {
-    "fs-extra": "^11.3.1",
+    "commander": "^14.0.2",
     "handlebars": "^4.7.8",
-    "openapi-typescript-codegen": "^0.29.0",
     "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/lib/bridge/rest/api-platform.adapter.ts

@@ -3,60 +3,71 @@ import {Observable} from 'rxjs';
 import {toHttpParams} from './query-builder';
 import {
   Collection,
-  CreateCommand,
+  HttpCallOptions,
   HttpRequestConfig,
-  Iri, Item,
-  Query,
+  Iri,
+  IriRequired,
+  Item,
+  AnyQuery,
   ResourceRepository,
-  UpdateCommand
 } from '../../ports/resource-repository.port';
-import {CredentialsPolicy} from '../credentials.policy';
-
+import {resolveUrl} from '../../utils/url';
 
 export class ApiPlatformRestRepository<T extends Item> implements ResourceRepository<T> {
-  private readonly credentialsPolicy: CredentialsPolicy;
-
   constructor(
     private readonly http: HttpClient,
     private readonly apiBase: string,
     private readonly resourcePath: Iri,
-    readonly init: string,
+    private readonly withCredentialsDefault: boolean,
   ) {
-    this.credentialsPolicy = new CredentialsPolicy(init);
   }
 
-  list$(query?: Query): Observable<Collection<T>> {
-    return this.http.get<any>(`${this.apiBase}${this.resourcePath}`, {
-      params: toHttpParams(query),
-      withCredentials: this.credentialsPolicy.withCredentials()
+  getCollection$(query?: AnyQuery, opts?: HttpCallOptions): Observable<Collection<T>> {
+    const params = toHttpParams(query);
+    return this.http.get<Collection<T>>(this.resolveUrl(this.resourcePath), {
+      params,
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
     });
   }
 
-  get$(iri: Iri): Observable<T> {
-    return this.http.get<T>(`${this.apiBase}${iri}`, {
-      withCredentials: this.credentialsPolicy.withCredentials()
+  get$(iri: IriRequired, opts?: HttpCallOptions): Observable<T> {
+    return this.http.get<T>(this.resolveUrl(iri), {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
     });
   }
 
-  create$(cmd: CreateCommand<T>): Observable<T> {
-    return this.http.post<T>(`${this.apiBase}${this.resourcePath}`, cmd.payload, {
-      withCredentials: this.credentialsPolicy.withCredentials()
+  post$(payload: Partial<T>, opts?: HttpCallOptions): Observable<T> {
+    return this.http.post<T>(this.resolveUrl(this.resourcePath), payload, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
     });
   }
 
-  update$(cmd: UpdateCommand<T>): Observable<T> {
-    return this.http.patch<T>(`${this.apiBase}${cmd.iri}`, cmd.changes, {
-      withCredentials: this.credentialsPolicy.withCredentials()
+  patch$(iri: IriRequired, changes: Partial<T>, opts?: HttpCallOptions): Observable<T> {
+    return this.http.patch<T>(this.resolveUrl(iri), changes, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
     });
   }
 
-  delete$(iri: Iri): Observable<void> {
-    return this.http.delete<void>(`${this.apiBase}${iri}`, {
-      withCredentials: this.credentialsPolicy.withCredentials()
+  put$(iri: IriRequired, payload: Partial<T>, opts?: HttpCallOptions): Observable<T> {
+    return this.http.put<T>(this.resolveUrl(iri), payload, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  delete$(iri: IriRequired, opts?: HttpCallOptions): Observable<void> {
+    return this.http.delete<void>(this.resolveUrl(iri), {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
     });
   }
 
   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,
@@ -65,37 +76,27 @@ export class ApiPlatformRestRepository<T extends Item> implements ResourceReposi
       headers,
       responseType,
       withCredentials,
-      options = {}
+      options = {},
     } = req;
 
-    const mergedOptions: any = {...options};
     const targetUrl = this.resolveUrl(url ?? this.resourcePath);
+    const mergedOptions: Record<string, unknown> = {...options};
 
-    const computedResponseType = responseType ?? mergedOptions.responseType ?? 'json';
-    mergedOptions.responseType = computedResponseType as any;
+    mergedOptions['responseType'] = (responseType ?? (mergedOptions['responseType'] as any) ?? 'json') as any;
 
-    const credentials = withCredentials ?? mergedOptions.withCredentials ?? this.credentialsPolicy.withCredentials();
-    mergedOptions.withCredentials = credentials;
+    mergedOptions['withCredentials'] = withCredentials ?? (mergedOptions['withCredentials'] as any) ?? this.withCredentialsDefault;
 
-    if (headers) mergedOptions.headers = headers;
-    if (query) mergedOptions.params = toHttpParams(query as any);
-    if (body !== undefined) mergedOptions.body = body;
+    if (headers) mergedOptions['headers'] = headers;
+    if (query) mergedOptions['params'] = toHttpParams(query);
+    if (body !== undefined) mergedOptions['body'] = body;
 
-    mergedOptions.observe = 'body';
-    return this.http.request<R>(method, targetUrl, mergedOptions as { observe: 'body' });
+    mergedOptions['observe'] = 'body';
+    return this.http.request<R>(method, targetUrl, mergedOptions as {observe: 'body'});
   }
 
   private resolveUrl(path?: Iri): string {
     const effectivePath = path ?? this.resourcePath;
-    if (!effectivePath) throw new Error('ApiPlatformRestRepository.resolveUrl: missing url and resourcePath');
-    if (/^https?:\/\//i.test(effectivePath)) return effectivePath;
-    if (effectivePath.startsWith('//')) return effectivePath;
-    return joinUrl(this.apiBase, effectivePath);
+    if (!effectivePath) throw new Error('ApiPlatformRestRepository: missing url and resourcePath');
+    return resolveUrl(this.apiBase, effectivePath);
   }
 }
-
-function joinUrl(base: string, path: string): string {
-  const normalizedBase = base.endsWith('/') ? base.slice(0, -1) : base;
-  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-  return `${normalizedBase}${normalizedPath}`;
-}

package/templates/_lib_template/src/lib/bridge/rest/query-builder.ts

@@ -2,42 +2,42 @@ import {HttpParams} from '@angular/common/http';
 import {AnyQuery, Query, QueryParamValue} from '../../ports/resource-repository.port';
 
 export function toHttpParams(q: AnyQuery | undefined): HttpParams {
-    if (!q) return new HttpParams();
-    if (q instanceof HttpParams) return q;
+  if (!q) return new HttpParams();
+  if (q instanceof HttpParams) return q;
 
-    const fromObject: Record<string, string | string[]> = {};
+  const fromObject: Record<string, string | string[]> = {};
 
-    const consumed = new Set<string>();
-    const maybeQuery = q as Query;
-    if (maybeQuery.page != null) {
-        fromObject['page'] = String(maybeQuery.page);
-        consumed.add('page');
-    }
-    if (maybeQuery.itemsPerPage != null) {
-        fromObject['itemsPerPage'] = String(maybeQuery.itemsPerPage);
-        consumed.add('itemsPerPage');
-    }
+  const consumed = new Set<string>();
+  const maybeQuery = q as Query;
+  if (maybeQuery.page != null) {
+    fromObject['page'] = String(maybeQuery.page);
+    consumed.add('page');
+  }
+  if (maybeQuery.itemsPerPage != null) {
+    fromObject['itemsPerPage'] = String(maybeQuery.itemsPerPage);
+    consumed.add('itemsPerPage');
+  }
 
-    if (q.filters) {
-        consumed.add('filters');
-        for (const [k, v] of Object.entries(q.filters)) {
-            assign(fromObject, k, v);
-        }
+  if (q.filters) {
+    consumed.add('filters');
+    for (const [k, v] of Object.entries(q.filters)) {
+      assign(fromObject, k, v);
     }
+  }
 
-    for (const [k, v] of Object.entries(q as Record<string, QueryParamValue>)) {
-        if (consumed.has(k)) continue;
-        assign(fromObject, k, v);
-    }
+  for (const [k, v] of Object.entries(q as Record<string, QueryParamValue>)) {
+    if (consumed.has(k)) continue;
+    assign(fromObject, k, v);
+  }
 
-    return new HttpParams({fromObject});
+  return new HttpParams({fromObject});
 }
 
 function assign(target: Record<string, string | string[]>, key: string, value: QueryParamValue | undefined) {
-    if (value == null) return;
-    if (Array.isArray(value)) {
-        target[key] = value.map(String);
-    } else {
-        target[key] = String(value);
-    }
+  if (value == null) return;
+  if (Array.isArray(value)) {
+    target[key] = value.map(String);
+  } else {
+    target[key] = String(value);
+  }
 }

package/templates/_lib_template/src/lib/bridge/sse/eventsource-wrapper.ts

@@ -1,74 +1,70 @@
 import {ReplaySubject, Subject} from 'rxjs';
 import {SseEvent, SseOptions, RealtimeStatus} from '../../ports/realtime.port';
+import {BridgeLogger} from '../../bridge.types';
 
 export class EventSourceWrapper {
-    private es?: EventSource;
+  private es?: EventSource;
 
-    private readonly statusSub = new ReplaySubject<RealtimeStatus>(1);
-    private readonly eventSub = new Subject<SseEvent>();
+  private readonly statusSub = new ReplaySubject<RealtimeStatus>(1);
+  private readonly eventSub = new Subject<SseEvent>();
 
-    readonly status$ = this.statusSub.asObservable();
-    readonly events$ = this.eventSub.asObservable();
+  readonly status$ = this.statusSub.asObservable();
+  readonly events$ = this.eventSub.asObservable();
 
-    /** Activer pour conversations local */
-    private readonly debug = false;
+  constructor(
+    private readonly url: string,
+    private readonly opts: SseOptions = {},
+    private readonly logger?: BridgeLogger,
+  ) {
+    this.setState('closed');
+    this.log('[SSE] init', {url, withCredentials: !!opts.withCredentials});
+  }
 
-    constructor(
-        private readonly url: string,
-        private readonly opts: SseOptions = {}
-    ) {
-        this.setState('closed');
-        this.log('[SSE] initialized', url, opts);
+  open(): void {
+    if (this.es) {
+      this.log('[SSE] open() ignored: already open');
+      return;
     }
 
-    open(): void {
-        if (this.es) {
-            this.log('[SSE] open() ignored: already open');
-            return;
-        }
+    this.setState('connecting');
+    this.log('[SSE] open', {url: this.url});
 
-        this.setState('connecting');
-        this.log('[SSE] creating EventSource');
+    const es = new EventSource(this.url, {
+      withCredentials: !!this.opts.withCredentials,
+    });
+    this.es = es;
 
-        const es = new EventSource(this.url, {
-            withCredentials: !!this.opts.withCredentials,
-        });
-        this.es = es;
+    es.onopen = () => {
+      this.setState('connected');
+    };
 
-        es.onopen = () => {
-            this.setState('connected');
-        };
+    es.onmessage = (ev) => {
+      this.eventSub.next({type: 'message', data: ev.data, lastEventId: ev.lastEventId || undefined});
+    };
 
-        es.onmessage = (ev) => {
-            this.log('[SSE] event', ev);
-            this.log('[SSE] message', ev.data);
-            this.eventSub.next({type: 'message', data: ev.data, lastEventId: ev.lastEventId || undefined});
-        };
+    es.onerror = () => {
+      // The browser will retry automatically. We stay in "connecting".
+      this.log('[SSE] error');
+      this.setState('connecting');
+    };
+  }
 
-        es.onerror = () => {
-            // Le navigateur va retenter. On reste en "connecting".
-            this.log('[SSE] error → retrying (browser)');
-            this.setState('connecting');
-        };
+  close(): void {
+    if (this.es) {
+      this.es.close();
+      this.es = undefined;
+      this.log('[SSE] closed');
     }
+    this.setState('closed');
+  }
 
-    close(): void {
-        if (this.es) {
-            this.es.close();
-            this.es = undefined;
-            this.log('[SSE] closed');
-        }
-        this.setState('closed');
-    }
-
-    // ──────────────── internals ────────────────
+  // ──────────────── internals ────────────────
 
-    private setState(state: RealtimeStatus): void {
-        this.log('[SSE] state', state);
-        this.statusSub.next(state);
-    }
+  private setState(state: RealtimeStatus): void {
+    this.statusSub.next(state);
+  }
 
-    private log(...args: unknown[]): void {
-        if (this.debug) console.log(...args);
-    }
+  private log(...args: unknown[]): void {
+    this.logger?.debug?.(...args);
+  }
 }

package/templates/_lib_template/src/lib/bridge/sse/mercure-topic.mapper.ts

@@ -0,0 +1,48 @@
+import {MercureTopicMode} from '../../bridge.types';
+
+export class MercureTopicMapper {
+  private readonly apiBaseUrl: URL;
+
+  constructor(
+    apiBase: string,
+    private readonly mode: MercureTopicMode,
+  ) {
+    this.apiBaseUrl = new URL(apiBase);
+  }
+
+  /**
+   * Canonical value used for ref-counting and as the "topic" query param value.
+   * - mode "url": always absolute, same-origin resolved
+   * - mode "iri": same-origin path+query+hash ("/api/..."), otherwise keep as-is
+   */
+  toTopic(input: string): string {
+    if (this.mode === 'url') return this.toAbsoluteUrl(input);
+    return this.toRelativeIriIfSameOrigin(input);
+  }
+
+  /**
+   * Canonical value used to compare incoming payload IRIs with subscribed IRIs.
+   * We keep payload matching stable by using same-origin relative IRIs ("/api/...").
+   */
+  toPayloadIri(input: string): string {
+    return this.toRelativeIriIfSameOrigin(input);
+  }
+
+  private toAbsoluteUrl(input: string): string {
+    try {
+      return new URL(input, this.apiBaseUrl).toString();
+    } catch {
+      return input;
+    }
+  }
+
+  private toRelativeIriIfSameOrigin(input: string): string {
+    try {
+      const url = new URL(input, this.apiBaseUrl);
+      if (url.origin !== this.apiBaseUrl.origin) return input;
+      return `${url.pathname}${url.search}${url.hash}`;
+    } catch {
+      return input;
+    }
+  }
+}

package/templates/_lib_template/src/lib/bridge/sse/mercure-url.builder.ts

@@ -1,16 +1,16 @@
 export class MercureUrlBuilder {
-  constructor(private readonly apiBase: string) {
-  }
-
-
-  build(hubUrl: string, iris: ReadonlySet<string>, lastEventId?: string): string {
+  /**
+   * Builds the Mercure hub URL with one `topic=` parameter per topic.
+   * The adapter is responsible for canonicalising topics beforehand.
+   */
+  build(hubUrl: string, topics: ReadonlySet<string>, lastEventId?: string): string {
     const url = new URL(hubUrl);
     if (lastEventId) {
       url.searchParams.set('lastEventID', lastEventId);
     }
     url.searchParams.delete('topic');
-    for (const iri of iris) {
-      url.searchParams.append('topic', this.apiBase + iri);
+    for (const topic of topics) {
+      url.searchParams.append('topic', topic);
     }
     return url.toString();
   }