@egen-civitas/esm-platform 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @egen-civitas/esm-platform
 
+## 1.2.0
+
+### Minor Changes
+
+- c5d96c9: Client du protocole Host v1 (C5) : `createBridgeClient` (handshake mémorisé, délais, concurrence, messages invalides ignorés et comptés), `getHostInfo()`, `getHostBridge()`, `createMockHost()` (testing). En natif, `getPlatform().ready` attend désormais le handshake et rejette `INCOMPATIBLE` si le Host est de version incompatible ou annonce une autre plateforme. Aucun changement en Web.
+- 340f5fe: Registre de capacités (C6).
+
+  - `esm-platform` : `src/registry.ts` devient l'unique description des capacités (version, méthodes, adaptateurs Web et natif) ; le gabarit « indisponible », les adaptateurs, le handshake et la disponibilité en sont dérivés. Une capacité n'est disponible que si le Host l'annonce dans une version supérieure ou égale à celle du registre. `Platform` est dérivé de `CapabilityInterfaces`, extensible par fusion de déclaration. Procédure « ajouter une capacité » dans le README ; comportement des 9 capacités v1 inchangé.
+  - `esm-globals` : `EgenCapabilityExtensions` permet d'étendre `CapabilityName` sans modifier ce paquet. Les 9 noms v1 restent une union fermée.
+
+### Patch Changes
+
+- Updated dependencies [340f5fe]
+  - @egen-civitas/esm-globals@2.2.0
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -42,6 +42,56 @@ getPlatform.mockReturnValue(createMockPlatform({ capabilities: { openExternal: {
 le reste reste `UNAVAILABLE`. Le mock et l'implémentation passent les **mêmes** tests de contrat (`src/platform.test.ts`).
 `createMockHost()` (simulation de `window.egenHostBridge`) viendra avec le client de pont (C5/C9).
 
+## Capacités v1
+
+Tout ce qui énumère les capacités (gabarit « indisponible », handshake avec le Host, adaptateurs Web et natif, mocks) lit **un seul registre** :
+`src/registry.ts`. Il associe à chaque nom une `version`, la liste exhaustive de ses `methods` (`async` ou `subscribe`) et ses adaptateurs `web` / `native`.
+
+| Capacité | Version | Web | Natif | Priorité | Remarque |
+|---|---|---|---|---|---|
+| `session` | 1 | fournisseur vide (cookie) | à faire (C7) | P0 | chemin critique du chantier D |
+| `secureStorage` | 1 | **jamais** (pas de faux coffre) | à faire (C7) | P0 | valeurs `string` uniquement |
+| `openExternal` | 1 | `https:`, `mailto:`, `tel:` | à faire (C7) | P0 | allowlist de schémas |
+| `lifecycle` | 1 | `visibilitychange` | à faire (C7) | P0 | abonnements avec désabonnement |
+| `permissions` | 1 | API Permissions si présente | à faire (C7) | P1 | noms normalisés |
+| `files` | 1 | `select` seul | à faire (C7) | P1 | *handle*, jamais de binaire inline |
+| `camera` | 1 | `<input capture>` | à faire (C7) | P1 | *handle* de fichier |
+| `push` | 1 | **jamais** | à faire (C7) | P2 | |
+| `biometric` | 1 | **jamais** | à faire (C7) | P2 | déverrouillage local uniquement |
+
+Une capacité n'est disponible (`has()` vrai) que si un adaptateur la fournit **et**, en natif, que le Host l'annonce dans une version **supérieure ou égale** à celle du registre.
+
+## Ajouter une capacité
+
+Règle (N9) : une capacité P1/P2 n'est implémentée que lorsqu'**une app l'utilise**. La procédure ne modifie **aucun autre fichier du framework**
+que ceux listés ci-dessous : le critère est vérifié par `src/registry.test.ts`, qui ajoute une capacité fictive entièrement depuis un fichier de test.
+
+1. **Interface TypeScript** dans son propre fichier (`src/extensions/<nom>.ts`), avec les **deux fusions de déclaration** qui l'enregistrent côté types
+   (ni `types.ts` ni `esm-globals` ne sont modifiés) :
+   ```ts
+   export interface MaCapacite {
+     faire(entree: string): Promise<string>;
+     onEvenement(callback: () => void): Unsubscribe;
+   }
+   declare module '@egen-civitas/esm-globals' {
+     interface EgenCapabilityExtensions {
+       maCapacite: true; // la rend valide comme `CapabilityName` (donc dans `requiredCapabilities`)
+     }
+   }
+   declare module '../types.js' {
+     interface CapabilityInterfaces {
+       maCapacite: MaCapacite; // la rend accessible : `platform.maCapacite`
+     }
+   }
+   ```
+2. **Entrée du registre** (`registerCapability('maCapacite', { version, methods, web, native })`). `methods` est vérifié **à la compilation** : un oubli ne compile pas.
+3. **Adaptateur Web** (`src/adapters/web/<nom>.ts`) : une fabrique qui retourne `undefined` si le navigateur ne sait pas faire. Une méthode non fournie reste `UNAVAILABLE`. **Jamais de simulation de sécurité.**
+4. **Adaptateur natif** : un simple *appelant* du pont (`client.call('maCapacite', 'faire', args)`, `client.onEvent(...)`), sans logique métier.
+5. **Mock** : `createMockPlatform({ capabilities: { maCapacite: { … } } })` fonctionne sans rien ajouter ; ajouter ses valeurs par défaut dans `src/testing/` seulement si utile.
+6. **Tests** : ajouter les lignes de la capacité aux tables de `src/platform.test.ts` (elles servent d'oracle indépendant du registre), un test par méthode de l'adaptateur Web, et un test natif avec `createMockHost`.
+7. **Changeset** *minor* (`esm-platform`, et `esm-globals` si une extension de `CapabilityName` est publiée).
+8. **Ligne ajoutée au tableau des capacités** ci-dessus.
+
 ## État d'avancement
 | Élément | Tâche | État |
 |---|---|---|
@@ -52,5 +102,17 @@ le reste reste `UNAVAILABLE`. Le mock et l'implémentation passent les **mêmes*
 | `getPlatform()` sûr par défaut (aucune capacité simulée) | C1 | fait |
 | `createMockPlatform` | C9 | partiel (`createMockHost` à faire avec C5) |
 | Adaptateur Web | C4 | fait |
-| Client de pont / protocole v1 | C5 | à faire |
-| Registre et procédure d'ajout d'une capacité | C6 | à faire |
+| Client de pont / protocole v1 (`createBridgeClient`, handshake, `getHostInfo`) | C5 | fait |
+| Registre et procédure d'ajout d'une capacité | C6 | fait |
+
+## Tester sans Host
+`createMockHost()` (`@egen-civitas/esm-platform/testing`) simule `window.egenHostBridge` : handshake automatique, méthodes
+programmables (`handlers: { 'secureStorage.get': () => 'valeur' }`), latence, silence (tests de timeout), version de
+protocole incompatible, messages bruts arbitraires. Il rejoue le **contrat** du protocole v1, pas du code natif.
+
+```ts
+const host = createMockHost({ capabilities: { secureStorage: { v: 1 } }, handlers: { 'secureStorage.get': () => 'v' } });
+host.install(); // window.egenHostBridge
+window.egenTarget = 'android';
+await getPlatform().ready; // handshake
+```

package/dist/adapters/web/index.d.ts

@@ -1,7 +1,9 @@
-import type { CapabilityOverrides } from '../../capabilities.js';
 /**
- * Capacités fournies par le navigateur. PRINCIPE (doc C4) : ne jamais simuler de la sécurité. Sont donc ABSENTES
- * (`has()` faux, méthodes `UNAVAILABLE`) : `secureStorage` (pas de faux coffre dans `localStorage`), `push` et
- * `biometric` (v1), ainsi que `permissions` quand l'API Permissions n'existe pas.
+ * Capacités fournies par le navigateur. PRINCIPE (doc C4) : ne jamais simuler de la sécurité.
+ *
+ * La liste de ce qui est fourni ne vit plus ici : chaque capacité déclare son adaptateur Web dans `registry.ts`
+ * (tâche C6), et `createWebCapabilities()` ne fait que lire le registre. Sont ABSENTES (`has()` faux, méthodes
+ * `UNAVAILABLE`) : `secureStorage` (pas de faux coffre dans `localStorage`), `push` et `biometric` (v1), ainsi que
+ * `permissions` quand l'API Permissions n'existe pas.
  */
-export declare function createWebCapabilities(): CapabilityOverrides;
+export { createWebCapabilities } from '../../registry.js';

package/dist/adapters/web/index.js

@@ -1,24 +1,9 @@
-import { createWebCamera } from './camera.js';
-import { createWebFiles } from './files.js';
-import { createWebLifecycle } from './lifecycle.js';
-import { createWebOpenExternal } from './open-external.js';
-import { createWebPermissions, isWebPermissionsAvailable } from './permissions.js';
-import { createWebSession } from './session.js';
 /**
- * Capacités fournies par le navigateur. PRINCIPE (doc C4) : ne jamais simuler de la sécurité. Sont donc ABSENTES
- * (`has()` faux, méthodes `UNAVAILABLE`) : `secureStorage` (pas de faux coffre dans `localStorage`), `push` et
- * `biometric` (v1), ainsi que `permissions` quand l'API Permissions n'existe pas.
+ * Capacités fournies par le navigateur. PRINCIPE (doc C4) : ne jamais simuler de la sécurité.
+ *
+ * La liste de ce qui est fourni ne vit plus ici : chaque capacité déclare son adaptateur Web dans `registry.ts`
+ * (tâche C6), et `createWebCapabilities()` ne fait que lire le registre. Sont ABSENTES (`has()` faux, méthodes
+ * `UNAVAILABLE`) : `secureStorage` (pas de faux coffre dans `localStorage`), `push` et `biometric` (v1), ainsi que
+ * `permissions` quand l'API Permissions n'existe pas.
  */
-export function createWebCapabilities() {
-    const capabilities = {
-        session: createWebSession(),
-        openExternal: createWebOpenExternal(),
-        lifecycle: createWebLifecycle(),
-        files: createWebFiles(),
-        camera: createWebCamera(),
-    };
-    if (isWebPermissionsAvailable()) {
-        capabilities.permissions = createWebPermissions();
-    }
-    return capabilities;
-}
+export { createWebCapabilities } from '../../registry.js';

package/dist/bridge/client.d.ts

@@ -0,0 +1,48 @@
+import type { CapabilityName } from '@egen-civitas/esm-globals';
+import type { PlatformEnvironment, Unsubscribe } from '../types.js';
+import { type HostBridge } from './protocol.js';
+/** Ce que le Host annonce lors du handshake (contenu validé par le client). */
+export interface HostInfo {
+    /** Version du protocole retenue par le Host. */
+    protocol: number;
+    /** Version de l'application hôte. */
+    host: string;
+    platform: PlatformEnvironment;
+    /** Capacités que le Host accepte de servir (le Host contrôle ce qui est accessible). */
+    capabilities: Partial<Record<CapabilityName, {
+        v: number;
+    }>>;
+}
+export interface BridgeClientOptions {
+    bridge: HostBridge;
+    /** Cible de ce build : le Host doit annoncer la même plateforme. */
+    environment: PlatformEnvironment;
+    /** Version du framework, transmise au Host dans le `hello`. */
+    framework?: string;
+    /** Délai par défaut avant `TIMEOUT`. @default 30000 */
+    timeoutMs?: number;
+}
+export interface CallOptions {
+    /** Remplace le délai par défaut pour cet appel. */
+    timeoutMs?: number;
+}
+export interface BridgeClient {
+    /** Handshake obligatoire (règle 1 du protocole). Mémorisé : les appels suivants retournent le même résultat. */
+    hello(): Promise<HostInfo>;
+    /** Appelle une méthode d'une capacité. Rejette avec `PlatformError` ; exige un handshake réussi. */
+    call<T = unknown>(namespace: string, method: string, args?: unknown, options?: CallOptions): Promise<T>;
+    /** S'abonne à un événement du Host (ex. `lifecycle.resume`). */
+    onEvent(name: string, callback: (data: unknown) => void): Unsubscribe;
+    /** `null` tant que le handshake n'a pas réussi. */
+    readonly hostInfo: HostInfo | null;
+    /** Compteurs de diagnostic : messages ignorés (invalides, orphelins, version inconnue) et appels en vol. */
+    stats(): {
+        ignoredMessages: number;
+        inFlight: number;
+    };
+}
+/**
+ * Client du protocole Host v1 (côté Shell). Sécurité : aucune évaluation dynamique, seuls les champs attendus sont
+ * lus, tout message invalide / orphelin / de version inconnue est ignoré et compté, jamais exécuté.
+ */
+export declare function createBridgeClient(options: BridgeClientOptions): BridgeClient;

package/dist/bridge/client.js

@@ -0,0 +1,212 @@
+import { PlatformError } from '../errors.js';
+import { isKnownCapability } from '../registry.js';
+import { DEFAULT_TIMEOUT_MS, HOST_PROTOCOL_NAME, KNOWN_ERROR_CODES, MAX_MESSAGE_LENGTH, SUPPORTED_PROTOCOL, isSupportedProtocolVersion, parseHostMessage, } from './protocol.js';
+const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9]*$/;
+const MAX_ERROR_MESSAGE_LENGTH = 500;
+/**
+ * Client du protocole Host v1 (côté Shell). Sécurité : aucune évaluation dynamique, seuls les champs attendus sont
+ * lus, tout message invalide / orphelin / de version inconnue est ignoré et compté, jamais exécuté.
+ */
+export function createBridgeClient(options) {
+    const { bridge, environment, framework, timeoutMs: defaultTimeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    const pending = new Map();
+    const listeners = new Map();
+    let info = null;
+    let helloPromise = null;
+    let ignored = 0;
+    let counter = 0;
+    const nextId = () => {
+        for (;;) {
+            const id = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+                ? crypto.randomUUID()
+                : `${Date.now().toString(36)}-${(counter++).toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+            if (!pending.has(id)) {
+                return id;
+            }
+        }
+    };
+    function toPlatformError(failure, namespace, method) {
+        const { code, message, retryable } = failure.e;
+        const known = typeof code === 'string' && KNOWN_ERROR_CODES.has(code);
+        const text = typeof message === 'string' && message.length > 0
+            ? message.slice(0, MAX_ERROR_MESSAGE_LENGTH)
+            : `Le Host a refusé l'appel ${namespace}.${method}.`;
+        return new PlatformError((known ? code : 'HOST_ERROR'), text, {
+            retryable: retryable === true,
+            capability: namespace,
+            method,
+        });
+    }
+    function handleIncoming(raw) {
+        const message = parseHostMessage(raw);
+        if (!message) {
+            ignored++;
+            return;
+        }
+        if ('ev' in message) {
+            if (!isSupportedProtocolVersion(message.v)) {
+                ignored++;
+                return;
+            }
+            listeners.get(message.ev)?.forEach((callback) => {
+                try {
+                    callback(message.d);
+                }
+                catch (error) {
+                    console.error(`[egen-platform] Un abonné de l'événement "${message.ev}" a levé une erreur :`, error);
+                }
+            });
+            return;
+        }
+        const entry = pending.get(message.id);
+        if (!entry) {
+            ignored++; // réponse orpheline : id inconnu, déjà traitée ou expirée
+            return;
+        }
+        pending.delete(message.id);
+        clearTimeout(entry.timer);
+        if (!isSupportedProtocolVersion(message.v)) {
+            entry.reject(new PlatformError('INCOMPATIBLE', `Le Host répond avec la version de protocole ${String(message.v)}, non supportée.`, {
+                capability: entry.namespace,
+                method: entry.method,
+            }));
+            return;
+        }
+        if (message.ok) {
+            entry.resolve(message.r);
+        }
+        else {
+            entry.reject(toPlatformError(message, entry.namespace, entry.method));
+        }
+    }
+    bridge.subscribe(handleIncoming);
+    function request(namespace, method, args, version, timeoutMs) {
+        const reject = (code, message) => Promise.reject(new PlatformError(code, message, { capability: namespace, method }));
+        if (!NAME_PATTERN.test(namespace) || !NAME_PATTERN.test(method)) {
+            return reject('INVALID_ARGS', `Nom d'appel invalide : "${namespace}.${method}".`);
+        }
+        const id = nextId();
+        const envelope = { p: HOST_PROTOCOL_NAME, v: version, id, ns: namespace, m: method };
+        if (args !== undefined) {
+            envelope.a = args;
+        }
+        let json;
+        try {
+            json = JSON.stringify(envelope);
+        }
+        catch {
+            return reject('INVALID_ARGS', `Les arguments de ${namespace}.${method} ne sont pas sérialisables en JSON.`);
+        }
+        if (json.length > MAX_MESSAGE_LENGTH) {
+            return reject('INVALID_ARGS', `Message trop volumineux pour ${namespace}.${method} (${json.length} caractères, maximum ${MAX_MESSAGE_LENGTH}) : utiliser une référence de fichier.`);
+        }
+        return new Promise((resolve, rejectPromise) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                rejectPromise(new PlatformError('TIMEOUT', `Le Host n'a pas répondu à ${namespace}.${method} en ${timeoutMs} ms.`, {
+                    retryable: true,
+                    capability: namespace,
+                    method,
+                }));
+            }, timeoutMs);
+            pending.set(id, { namespace, method, resolve, reject: rejectPromise, timer });
+            try {
+                bridge.send(json);
+            }
+            catch (error) {
+                pending.delete(id);
+                clearTimeout(timer);
+                rejectPromise(new PlatformError('HOST_ERROR', `Échec de l'envoi au Host : ${error instanceof Error ? error.message : String(error)}`, {
+                    capability: namespace,
+                    method,
+                }));
+            }
+        });
+    }
+    function parseHelloResult(result) {
+        const incompatible = (reason) => new PlatformError('INCOMPATIBLE', `Handshake refusé : ${reason}`, { capability: 'host', method: 'hello' });
+        if (typeof result !== 'object' || result === null || Array.isArray(result)) {
+            throw incompatible('réponse invalide.');
+        }
+        const value = result;
+        if (!isSupportedProtocolVersion(value.protocol)) {
+            throw incompatible(`le Host parle le protocole ${String(value.protocol)}, ce client supporte ${SUPPORTED_PROTOCOL.min}–${SUPPORTED_PROTOCOL.max}.`);
+        }
+        if (value.platform !== environment) {
+            throw incompatible(`le Host annonce la plateforme "${String(value.platform)}", ce build cible "${environment}".`);
+        }
+        if (typeof value.host !== 'string' || value.host.length === 0 || value.host.length > 64) {
+            throw incompatible('version du Host absente ou invalide.');
+        }
+        const capabilities = {};
+        if (typeof value.capabilities === 'object' && value.capabilities !== null && !Array.isArray(value.capabilities)) {
+            for (const [name, descriptor] of Object.entries(value.capabilities)) {
+                const version = descriptor?.v;
+                // Capacité inconnue de ce client = ignorée (compatibilité ascendante) ; descripteur invalide = ignoré.
+                if (isKnownCapability(name) && Number.isInteger(version) && version >= 1) {
+                    capabilities[name] = { v: version };
+                }
+            }
+        }
+        return { protocol: value.protocol, host: value.host, platform: environment, capabilities };
+    }
+    return {
+        hello() {
+            if (!helloPromise) {
+                const attempt = request('host', 'hello', { protocol: { ...SUPPORTED_PROTOCOL }, ...(framework ? { framework } : {}) }, SUPPORTED_PROTOCOL.max, defaultTimeoutMs).then((result) => {
+                    info = parseHelloResult(result);
+                    return info;
+                });
+                helloPromise = attempt;
+                attempt.catch((error) => {
+                    // Un échec passager (timeout, envoi) peut être retenté ; une incompatibilité est définitive.
+                    if (error instanceof PlatformError && error.retryable && helloPromise === attempt) {
+                        helloPromise = null;
+                    }
+                });
+            }
+            return helloPromise;
+        },
+        call(namespace, method, args, callOptions = {}) {
+            if (namespace === 'host') {
+                return Promise.reject(new PlatformError('INVALID_ARGS', 'Le namespace "host" est réservé au handshake.', { method }));
+            }
+            if (!NAME_PATTERN.test(namespace) || !NAME_PATTERN.test(method)) {
+                return Promise.reject(new PlatformError('INVALID_ARGS', `Nom d'appel invalide : "${namespace}.${method}".`, {
+                    capability: namespace,
+                    method,
+                }));
+            }
+            if (!info) {
+                return Promise.reject(new PlatformError('INCOMPATIBLE', `Appel ${namespace}.${method} refusé : le handshake avec le Host n'est pas terminé.`, {
+                    capability: namespace,
+                    method,
+                }));
+            }
+            if (!info.capabilities[namespace]) {
+                return Promise.reject(new PlatformError('UNAVAILABLE', `Le Host n'annonce pas la capacité "${namespace}".`, {
+                    capability: namespace,
+                    method,
+                }));
+            }
+            return request(namespace, method, args, info.protocol, callOptions.timeoutMs ?? defaultTimeoutMs);
+        },
+        onEvent(name, callback) {
+            let set = listeners.get(name);
+            if (!set) {
+                set = new Set();
+                listeners.set(name, set);
+            }
+            set.add(callback);
+            return () => {
+                set.delete(callback);
+            };
+        },
+        get hostInfo() {
+            return info;
+        },
+        stats() {
+            return { ignoredMessages: ignored, inFlight: pending.size };
+        },
+    };
+}