@obsidiane/meridiane 0.0.6 → 0.0.7

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,15 +19,32 @@ npm i -g @obsidiane/meridiane
 ## Usage
 
 ```bash
+# Générer des fichiers d'init (config + snippets)
+npx meridiane init
+
 # 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]
+npx meridiane models <SPEC_OPENAPI_URL_OU_FICHIER_JSON> [--out=<dir>] [--item-import=../lib/ports/resource-repository.port] [--required-mode=all-optional|spec] [--preset=all|native] [--include=<substr>] [--exclude=<substr>] [--index=1|0]
+
+# Dev: regen lib + models depuis un backend (localhost par défaut)
+npx meridiane dev-bridge <lib-name> <npm-package-name> [version]
+
+# Dev (repo meridiane): met à jour le bridge du sandbox
+npx meridiane sandbox-bridge
 ```
 
+Options :
+- `--debug` : active des logs supplémentaires (CLI).
+
 `url-registry` est optionnel. Recommandé : gérer le registry via `.npmrc` / variables CI plutôt que de le passer au générateur.
 
+Bonnes pratiques :
+- exécuter `meridiane init` une fois au début du repo du bridge (pour `models.config.js`, `.env.example`, snippets Angular)
+- committer `models.config.js` et `.env.example`, ne pas committer `.env`
+- générer les modèles dans `projects/<lib-name>/src/models` pour publier les types avec le package
+
 ## Exemple CI (générer + build + publish)
 
 ```bash
@@ -45,7 +64,7 @@ npm i -D ng-packagr
 
 ## Configuration (models.config.js)
 
-Le générateur de modèles charge automatiquement un fichier `models.config.js` s’il existe dans le répertoire courant (CWD).
+Le générateur de modèles charge automatiquement un fichier `models.config.js` s’il existe dans le répertoire courant (CWD) ou dans un dossier parent.
 
 Copie rapide (après installation) :
 
@@ -53,6 +72,27 @@ Copie rapide (après installation) :
 cp node_modules/@obsidiane/meridiane/models.config.example.js ./models.config.js
 ```
 
+Exécuter `meridiane init` est généralement plus simple (ça pose aussi `.env.example` et un snippet Angular).
+
+## Configuration via `.env`
+
+Le CLI charge automatiquement un fichier `.env` (CWD ou dossier parent) avant d’exécuter `lib/models`.
+
+Variables utiles :
+- `MERIDIANE_DEBUG=1`
+- `MERIDIANE_LIB_VERSION=0.1.0`
+- `MERIDIANE_NPM_REGISTRY_URL=https://…`
+- `MERIDIANE_MODELS_OUT=projects/<lib>/src/models`
+- `MERIDIANE_MODELS_REQUIRED_MODE=spec`
+- `MERIDIANE_MODELS_ITEM_IMPORT=../lib/ports/resource-repository.port`
+- `MERIDIANE_MODELS_INDEX=1`
+
+Ordre de priorité :
+1) flags CLI
+2) `models.config.js`
+3) `.env`
+4) valeurs par défaut
+
 Sans installation préalable :
 
 ```bash

package/cli.js

@@ -10,6 +10,7 @@ function runTool(scriptName, args) {
   const scriptPath = path.join(__dirname, 'tools', scriptName);
   const child = spawn(process.execPath, [scriptPath, ...args], {
     stdio: 'inherit',
+    env: process.env,
   });
 
   child.on('exit', (code) => {
@@ -20,24 +21,49 @@ function runTool(scriptName, args) {
 function printHelp() {
   console.log(`
 Usage:
+  meridiane init [--force]
   meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
   meridiane models <SPEC_OPENAPI_URL_OU_FICHIER_JSON> [options]
+  meridiane dev-bridge <lib-name> <npm-package-name> [version] [options]
+  meridiane sandbox-bridge [options]
+
+Options:
+  --debug  Active les logs (CLI et runtime)
 
 Examples:
+  npx -y @obsidiane/meridiane init
   npx -y @obsidiane/meridiane lib backend-bridge @acme/backend-bridge 0.1.0
   npx -y @obsidiane/meridiane models http://localhost:8000/api/docs.json --out=projects/backend-bridge/src/models
+  npx -y @obsidiane/meridiane dev-bridge bridge-sandbox @obsidiane/bridge-sandbox 0.1.0
+  npx -y @obsidiane/meridiane sandbox-bridge
 `);
 }
 
-const [, , cmd, ...rest] = process.argv;
+const argv = process.argv.slice(2);
+const debugIndex = argv.indexOf('--debug');
+if (debugIndex >= 0) {
+  argv.splice(debugIndex, 1);
+  process.env.MERIDIANE_DEBUG = process.env.MERIDIANE_DEBUG || '1';
+}
+
+const [cmd, ...rest] = argv;
 
 switch (cmd) {
+  case 'init':
+    runTool('init.js', rest);
+    break;
   case 'lib':
     runTool('generate-lib.js', rest);
     break;
   case 'models':
     runTool('generate-models.js', rest);
     break;
+  case 'dev-bridge':
+    runTool('dev-bridge.js', rest);
+    break;
+  case 'sandbox-bridge':
+    runTool('sandbox-bridge.js', rest);
+    break;
   case '-h':
   case '--help':
   case undefined:

package/models.config.example.js

@@ -18,6 +18,21 @@ module.exports = {
   // Valeurs possibles: 'jsonld' | 'jsonapi' | 'none'
   preferFlavor: 'jsonld',
 
+  // Preset de génération:
+  // - 'all' (défaut): génère tout ce qui ressemble à un objet
+  // - 'native': exclut les schémas "techniques" (Hydra*, jsonMergePatch…)
+  preset: 'all',
+
+  // Générer `index.ts` dans le dossier des models
+  writeIndex: true,
+
+  // Filtres additionnels (sur les noms OpenAPI des schémas, ex: "User-user.read", "Conversation.jsonMergePatch")
+  // - includeSchemaNames: si non vide, ne garde que les matchs
+  // - excludeSchemaNames: supprime les matchs
+  // Règles possibles: RegExp, string (substring), ou (name) => boolean.
+  includeSchemaNames: [],
+  excludeSchemaNames: [],
+
   // Hydra: regex pour les schémas de base à ignorer (merge allOf / filtrage)
   // Peut être une RegExp ou une string passée à `new RegExp(...)`
   hydraBaseRegex: /^Hydra(?:Item|Collection)BaseSchema$/,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",
@@ -29,9 +29,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "fs-extra": "^11.3.1",
     "handlebars": "^4.7.8",
-    "openapi-typescript-codegen": "^0.29.0",
     "tslib": "^2.3.0"
   }
 }

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();
   }