@deveye/types 0.15.2 → 0.16.0

package/src/domain/workspaceRole.ts

@@ -22,11 +22,6 @@ export const workspaceCapabilitySchema = z.enum([
     'workspace.appearance',
     /** Modifier la disposition de l'accueil de l'espace. */
     'workspace.layout'
-    // « Gérer les canaux d'alerte » a vécu ici (`workspace.notifications`)
-    // puis est passée PAR FONCTIONNALITÉ (migration 093) : depuis que chaque
-    // émetteur possède ses canaux (091), une capacité d'espace accordait d'un
-    // bloc l'astreinte d'Uptime et le salon des sauvegardes. Voir le champ
-    // `channels` du grant de feature.
 ]);
 
 export type WorkspaceCapability = z.infer<typeof workspaceCapabilitySchema>;
@@ -34,14 +29,9 @@ export type WorkspaceCapability = z.infer<typeof workspaceCapabilitySchema>;
 export const WORKSPACE_CAPABILITIES = workspaceCapabilitySchema.options;
 
 /**
- * Features qu'un rôle peut ouvrir. Surensemble de `HomeFeatureId` : `devices`
- * s'y ajoute, parce que voir la flotte d'un espace est un droit comme un autre
- * (lecture = voir les appareils et leur supervision, écriture = les appairer,
- * approuver, renommer, supprimer).
- *
- * `monitoring` n'y figure pas : la carte d'agrégat du même nom est réservée à
- * l'administrateur global dans son espace personnel, donc aucun rôle d'espace
- * ne peut l'accorder. Les vues d'appareil, elles, relèvent de `devices`.
+ * Features qu'un rôle peut ouvrir. `devices` en fait partie : voir la flotte
+ * d'un espace est un droit comme un autre (lecture = voir les appareils et leur
+ * supervision, écriture = les appairer, approuver, renommer, supprimer).
  */
 export const workspaceFeatureIdSchema = z.enum([
     'devices',
@@ -61,56 +51,32 @@ export const workspaceFeatureIdSchema = z.enum([
     'projects',
     'git',
     /**
-     * Déploiement. `read` = voir les cibles de l'espace et leur historique,
-     * `write` = déclarer une cible, poser la clé d'API de l'instance, et
-     * **déclencher une mise en production**.
-     *
-     * ⚠️ Le droit le plus lourd de conséquences hors de DevEye : c'est le seul
-     * qui pousse quelque chose chez un tiers. Distinct de `projects` exprès —
-     * piloter le travail et livrer ne se confondent pas, et tout le monde n'a
-     * pas à pouvoir faire les deux.
+     * Déploiement. `read` = voir les cibles et leur historique, `write` =
+     * déclarer une cible, poser la clé d'API et déclencher une mise en
+     * production : le seul droit qui pousse quelque chose chez un tiers, d'où
+     * sa séparation de `projects`.
      */
     'deploy',
     'database',
     /**
-     * Sauvegardes. Les destinations de l'espace (dossier serveur, dossier d'une
-     * machine enrôlée, bucket S3) et les travaux qui y écrivent.
-     *
-     * `read` = voir les destinations, les travaux et leur historique, `write` =
-     * déclarer une destination, poser sa clé secrète, créer un travail et le
-     * déclencher.
-     *
-     * ⚠️ Le droit le plus lourd en lecture après `finance`, et pour une raison
-     * différente: la liste des destinations dit **où sont les copies de tout**.
-     * Qui la lit sait quel bucket viser pour obtenir la base entière sans jamais
-     * toucher à DevEye. Distinct de `database` exprès — superviser une base et
-     * savoir où en dorment les vidages ne se confondent pas.
+     * Sauvegardes. `read` = voir destinations, travaux et historique, `write` =
+     * déclarer une destination, poser sa clé, créer et déclencher un travail.
+     * La lecture est lourde : la liste des destinations dit où sont les copies
+     * de tout, d'où sa séparation de `database`.
      */
     'backup',
     /**
-     * Finances. Le grand livre de l'espace: comptes, opérations, budgets,
-     * échéances.
-     *
-     * `read` = consulter soldes, journal et tableau de bord, `write` = saisir et
-     * corriger des opérations, tenir comptes, catégories, budgets et échéances.
-     *
-     * ⚠️ Le droit dont la lecture seule est déjà lourde: un livre de comptes dit
-     * ce qu'une structure gagne, ce qu'elle doit et à qui elle paie quoi. Le
-     * distinguer de `projects` n'est donc pas une commodité de rangement, c'est
-     * la raison d'être de la séparation.
+     * Finances. `read` = consulter soldes, journal et tableau de bord, `write` =
+     * saisir et corriger des opérations, tenir comptes, catégories, budgets et
+     * échéances. La lecture seule est déjà lourde, d'où sa séparation de
+     * `projects`.
      */
     'finance',
     /**
-     * Audience. Le suivi d'usage des sites livrés — dernier maillon de la même
-     * famille que `projects`, `git` et `database` : un objet de l'**espace**
-     * qu'un projet ne fait que pointer.
-     *
-     * `read` = consulter les statistiques, `write` = déclarer un site, changer
-     * ses origines autorisées, sa rétention, le supprimer.
-     *
-     * ⚠️ Distinct de `projects` exprès, comme `git` l'est déjà : voir les
-     * chiffres d'un site livré et piloter le travail qui le produit ne se
-     * confondent pas, et tout le monde n'a pas à voir les deux.
+     * Audience. `read` = consulter les statistiques, `write` = déclarer un site,
+     * changer ses origines autorisées, sa rétention, le supprimer. Distinct de
+     * `projects`, comme `git` : un objet de l'espace qu'un projet ne fait que
+     * pointer.
      */
     'audience',
     /**
@@ -125,15 +91,11 @@ export type WorkspaceFeatureId = z.infer<typeof workspaceFeatureIdSchema>;
 export const WORKSPACE_FEATURE_IDS = workspaceFeatureIdSchema.options;
 
 /**
- * Identifiant d'une feature **externe** (module tiers compilé dans l'app).
- *
- * Le préfixe `x-` porte trois garanties d'un coup : aucune collision possible
- * avec les seize ids natifs ni avec les sujets réservés (`workspace`, `home`,
- * `account`, `notify`, `projectsChat`), aucune confusion avec un UUID
- * d'appareil dans une disposition d'accueil (un UUID commence par un chiffre
- * hexadécimal, jamais par `x`), et un tri visuel immédiat dans un grant ou un
- * journal. Pas de tiret intérieur : l'id sert tel quel de préfixe de commande
- * (`x-crypto.list`) et de valeur de segment live.
+ * Identifiant d'une feature externe (module tiers compilé dans l'app). Le
+ * préfixe `x-` exclut toute collision avec les ids natifs, les sujets réservés
+ * (`workspace`, `home`, `account`, `notify`) et les UUID d'appareil d'une
+ * disposition (un UUID commence par un chiffre hexadécimal). Pas de tiret
+ * intérieur : l'id sert tel quel de préfixe de commande (`x-crypto.list`).
  */
 export const EXTERNAL_FEATURE_ID_PATTERN = /^x-[a-z][a-z0-9]{1,24}$/;
 
@@ -173,29 +135,19 @@ export const workspaceFeatureGrantSchema = z.object({
     feature: featureIdSchema,
     access: featureAccessSchema,
     /**
-     * Gérer les **canaux d'alerte** de cette fonctionnalité : en déclarer,
-     * corriger une adresse ou une URL, en supprimer, lire leurs destinations.
-     *
-     * Par fonctionnalité et non par espace (migration 093) : depuis que chaque
-     * émetteur possède ses canaux (091), l'adresse de l'astreinte d'Uptime et
-     * le salon des sauvegardes ne se confient pas d'un bloc. Distinct de
-     * `access` exprès : régler où Uptime écrit relève de `access: write`, et
-     * se donne sans livrer les destinations elles-mêmes. Sans effet sur une
-     * fonctionnalité qui n'émet pas de notifications.
+     * Gérer les canaux d'alerte de cette fonctionnalité : en déclarer, corriger
+     * une adresse ou une URL, en supprimer, lire leurs destinations. Distinct de
+     * `access` : régler où Uptime écrit relève de `access: write` et se donne
+     * sans livrer les destinations. Sans effet sur une fonctionnalité qui
+     * n'émet pas de notifications.
      */
     channels: z.boolean(),
     /**
-     * Permissions **déclarées par la feature elle-même** (module externe, ou
-     * native modernisée) au-delà de lecture/écriture : la clé vient de son
-     * manifest (`extraPermissions`), la valeur est un booléen (`toggle`) ou la
-     * valeur d'un choix (`choice`).
-     *
-     * Fermeture par défaut, une seule règle : une clé **absente** vaut « refusé »
-     * pour un toggle et « valeur par défaut du manifest » (la moins privilégiée)
-     * pour un choix. Le propriétaire, qui a tout, reçoit `true` / la valeur
-     * `ownerValue`. Une clé inconnue du manifest courant est rejetée à
-     * l'écriture du rôle et ignorée à la lecture ; un grant survivant à la
-     * dépose d'un module reste donc inerte, jamais dangereux.
+     * Permissions déclarées par la feature elle-même (`extraPermissions` du
+     * manifest) : booléen pour un `toggle`, valeur d'un `choice`. Une clé
+     * absente vaut « refusé » pour un toggle et « valeur par défaut du manifest »
+     * pour un choix ; le propriétaire reçoit `true` / `ownerValue`. Une clé
+     * inconnue du manifest est rejetée à l'écriture et ignorée à la lecture.
      */
     extras: z.record(z.string().max(24), z.union([z.boolean(), z.string().max(32)])).default({})
 });

package/src/features/agent.ts

@@ -0,0 +1,306 @@
+import { z } from 'zod';
+import { deviceSchema } from '../domain/device';
+import { fileMutateOpSchema, fileSearchFilterSchema } from '../domain/deviceFiles';
+import { deviceLogFilterSchema, DEVICE_LOG_PAGE_MAX } from '../domain/deviceLogs';
+import { packageManagerIdSchema } from '../domain/packages';
+import { agentLifecycleActionSchema, agentPowerActionSchema } from '../protocol/agent';
+
+/**
+ * Le transport des agents : les commandes WS qui relaient un ordre du
+ * `MonitorHub` à l'agent d'un appareil (abonnement aux métriques, fichiers,
+ * terminal, journaux, paquets, alimentation, service, mise à jour).
+ * Infrastructure native ; un module s'en sert par la capacité `agents`.
+ *
+ * Deux espaces de noms `agent.*` coexistent : les TRAMES du protocole agent
+ * (`protocol/agent.ts`, entre le serveur et le binaire) et les COMMANDES
+ * ci-dessous, envoyées par le client sur la socket de session. Quatre noms
+ * existent des deux côtés (`agent.collect`, `agent.update`, `agent.lifecycle`,
+ * `agent.power`) : la commande est ce que demande l'utilisateur, la trame ce
+ * que reçoit l'agent.
+ */
+
+const deviceId = z.uuid();
+
+/** Subscribe to live metric pushes for one or more devices. */
+export const agentSubscribe = {
+    command: 'agent.subscribe' as const,
+    input: z.object({ deviceIds: z.array(deviceId).min(1).max(50) }),
+    output: z.object({ deviceIds: z.array(deviceId) })
+};
+
+export const agentUnsubscribe = {
+    command: 'agent.unsubscribe' as const,
+    input: z.object({ deviceIds: z.array(deviceId).min(1).max(50) }),
+    output: z.object({ deviceIds: z.array(deviceId) })
+};
+
+/** Ask an online device to push a fresh sample + report right now. */
+export const agentCollect = {
+    command: 'agent.collect' as const,
+    input: z.object({ deviceId }),
+    /** `requested` is false when the device isn't currently connected. */
+    output: z.object({ deviceId, requested: z.boolean() })
+};
+
+/**
+ * Run a system power action on the device (shutdown / reboot / suspend / hibernate
+ * / lock). Owner-or-admin; the agent must be online. The command only acknowledges
+ * the request — the agent applies it best-effort and the outcome streams back as a
+ * `device.powerResult` push event (the caller must be subscribed to the device).
+ */
+export const agentPower = {
+    command: 'agent.power' as const,
+    input: z.object({ deviceId, action: agentPowerActionSchema }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Stop or cleanly restart the agent process on the device (not the machine).
+ * `stop`: a supervised agent is relaunched by its manager, a standalone one
+ * stays offline until relaunched on the machine. `restart`: exit-and-relaunch.
+ * Owner-or-admin; the agent must be online. Fire-and-forget: the outcome is
+ * observed through presence.
+ */
+export const agentLifecycle = {
+    command: 'agent.lifecycle' as const,
+    input: z.object({ deviceId, action: agentLifecycleActionSchema }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Enable/disable the agent's per-user autostart (survives reboot, no privilege).
+ * Pushes `agent.service` to the connected agent (`install-user`/`uninstall-user`).
+ */
+export const agentSetAutostart = {
+    command: 'agent.setAutostart' as const,
+    input: z.object({ deviceId, enabled: z.boolean() }),
+    output: z.object({ device: deviceSchema })
+};
+
+/**
+ * Ask the agent to become a root/system service. Hybrid: the agent pops an OS auth
+ * prompt if it has an interactive session, else replies `needsManualCommand` and the
+ * UI shows `manualCommand` (always returned, deterministic per platform) to run on
+ * the device. The new privilege/scope is observed on the agent's next report.
+ */
+export const agentElevate = {
+    command: 'agent.elevate' as const,
+    input: z.object({ deviceId }),
+    output: z.object({ device: deviceSchema, manualCommand: z.string() })
+};
+
+/** Ask a root/system agent to drop back to a per-user service. */
+export const agentDropPrivileges = {
+    command: 'agent.dropPrivileges' as const,
+    input: z.object({ deviceId }),
+    output: z.object({ device: deviceSchema, manualCommand: z.string() })
+};
+
+/**
+ * Push a self-update to a connected device's agent: the server resolves the newer
+ * signed binary for the device's build target and sends the `agent.update` frame.
+ * Admin-only (Appareils page). Fails if the agent is offline, has no known target,
+ * the binary is missing/unsigned, or it's already up to date.
+ */
+export const agentUpdate = {
+    command: 'agent.update' as const,
+    input: z.object({ deviceId }),
+    output: z.object({ device: deviceSchema })
+};
+
+/**
+ * Ask the agent to enumerate its package managers + pending updates. The result
+ * arrives asynchronously as a `package.list` push event (the caller must be
+ * subscribed to the device). The command itself only acknowledges the request.
+ */
+export const agentListPackages = {
+    command: 'agent.listPackages' as const,
+    input: z.object({ deviceId }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Apply all pending updates of one manager. Progress streams as `package.progress`
+ * events, ending with `package.done`. Fails if the agent is offline or the manager
+ * needs root and the agent isn't privileged (elevate it first, see `agent.elevate`).
+ */
+export const agentUpgradePackages = {
+    command: 'agent.upgradePackages' as const,
+    input: z.object({ deviceId, manager: packageManagerIdSchema }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Ask the agent to enumerate the log sources present on the device (system journal,
+ * Docker containers, log files…). Owner-or-admin + agent online. The command only
+ * acknowledges; the list arrives as a `device.logSources` push event (the caller
+ * must be subscribed to the device).
+ */
+export const agentLogSources = {
+    command: 'agent.logSources' as const,
+    input: z.object({ deviceId }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Query one source with an advanced filter. `queryId` correlates the streamed
+ * result back to this request (results have no requestId). Lines arrive as one or
+ * more `device.logLines` push events, the last carrying `done: true`.
+ */
+export const agentLogQuery = {
+    command: 'agent.logQuery' as const,
+    input: z.object({
+        deviceId,
+        sourceId: z.string().min(1).max(512),
+        /** Client-generated id echoed back on every `device.logLines` for this query. */
+        queryId: z.string().min(1).max(64),
+        filter: deviceLogFilterSchema.optional(),
+        limit: z.number().int().positive().max(DEVICE_LOG_PAGE_MAX).optional()
+    }),
+    output: z.object({ ok: z.boolean() })
+};
+
+const sessionId = z.string().min(1).max(64);
+const cols = z.number().int().min(1).max(2000);
+const rows = z.number().int().min(1).max(2000);
+/** Base64-encoded terminal bytes, capped per frame (~1.5 MB). */
+const termData = z.string().max(2_000_000);
+/**
+ * Optional OS account to open the session under. Restricted to safe username
+ * characters (no shell metacharacters), since it reaches a `su` on the device.
+ */
+export const terminalUser = z
+    .string()
+    .regex(/^[A-Za-z0-9._-]+$/, 'Nom d’utilisateur invalide')
+    .max(32);
+
+/**
+ * Open an interactive terminal (PTY) on the device. Owner-or-admin + agent online.
+ * `sessionId` is client-generated and ties every later input/resize/close and the
+ * streamed `device.termOutput` / `device.termExit` push events together (the caller
+ * must be subscribed). `user` runs the shell under that account (`su -l`); omitted
+ * → the account the agent itself runs as.
+ */
+export const agentTermOpen = {
+    command: 'agent.termOpen' as const,
+    input: z.object({ deviceId, sessionId, cols, rows, user: terminalUser.optional() }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/** Send input (keystrokes / paste) to a terminal session. `data` is base64 bytes. */
+export const agentTermInput = {
+    command: 'agent.termInput' as const,
+    input: z.object({ deviceId, sessionId, data: termData }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/** Resize a terminal session's PTY to match the client viewport. */
+export const agentTermResize = {
+    command: 'agent.termResize' as const,
+    input: z.object({ deviceId, sessionId, cols, rows }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/** Close a terminal session (kills the shell and frees the PTY). */
+export const agentTermClose = {
+    command: 'agent.termClose' as const,
+    input: z.object({ deviceId, sessionId }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/** Correlates a request to its streamed result (results carry no requestId). */
+const opId = z.string().min(1).max(64);
+const path = z.string().min(1).max(4096);
+
+/**
+ * List a directory. Owner-or-admin + agent online. The listing arrives as a
+ * `device.filesListing` push event keyed by `opId` (the caller must be subscribed).
+ */
+export const agentFilesList = {
+    command: 'agent.filesList' as const,
+    input: z.object({ deviceId, opId, path }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Analyse a directory's recursive disk usage (ncdu-style): the total size of each
+ * immediate child. Result arrives as a `device.filesUsage` push event.
+ */
+export const agentFilesAnalyze = {
+    command: 'agent.filesAnalyze' as const,
+    input: z.object({ deviceId, opId, path }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Recursively search a directory with an advanced filter (name/extension/content,
+ * date & size windows). Matches arrive as a `device.filesMatches` push event.
+ */
+export const agentFilesSearch = {
+    command: 'agent.filesSearch' as const,
+    input: z.object({ deviceId, opId, path, filter: fileSearchFilterSchema }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Mutate the filesystem: `delete` (file or directory, recursive), `mkdir`, or
+ * `rename` (needs `dest`). The outcome arrives as a `device.filesOp` push event.
+ */
+export const agentFilesMutate = {
+    command: 'agent.filesMutate' as const,
+    input: z.object({ deviceId, opId, op: fileMutateOpSchema, path, dest: path.optional() }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Download a file. Bytes stream back as `device.filesChunk` push events keyed by
+ * `opId` (base64, the last with `done: true`); the client reassembles them.
+ */
+export const agentFilesDownload = {
+    command: 'agent.filesDownload' as const,
+    input: z.object({ deviceId, opId, path }),
+    output: z.object({ ok: z.boolean() })
+};
+
+/**
+ * Upload one chunk of a file at `offset` (0 truncates/creates it). The completion
+ * (on `done`) arrives as a `device.filesOp` push event (op `upload`).
+ */
+export const agentFilesUpload = {
+    command: 'agent.filesUpload' as const,
+    input: z.object({
+        deviceId,
+        opId,
+        path,
+        offset: z.number().int().nonnegative(),
+        data: z.string().max(1_400_000),
+        done: z.boolean()
+    }),
+    output: z.object({ ok: z.boolean() })
+};
+
+export const agentCommands = [
+    agentSubscribe,
+    agentUnsubscribe,
+    agentCollect,
+    agentPower,
+    agentLifecycle,
+    agentSetAutostart,
+    agentElevate,
+    agentDropPrivileges,
+    agentUpdate,
+    agentListPackages,
+    agentUpgradePackages,
+    agentLogSources,
+    agentLogQuery,
+    agentTermOpen,
+    agentTermInput,
+    agentTermResize,
+    agentTermClose,
+    agentFilesList,
+    agentFilesAnalyze,
+    agentFilesSearch,
+    agentFilesMutate,
+    agentFilesDownload,
+    agentFilesUpload
+] as const;

package/src/features/live.ts

@@ -2,16 +2,11 @@ import { z } from 'zod';
 import { liveCursorSchema, livePathSchema, livePeerSchema, liveTopicSchema } from '../domain/live';
 
 /**
- * Déclare où je suis, et récupère l'état de la salle.
- *
- * L'espace **n'est pas dans l'entrée** : il voyage sur l'enveloppe comme toute
- * commande, donc il est résolu et son appartenance vérifiée par le dispatcheur
- * avant que le handler ne s'exécute. L'entrée en salle est ainsi autorisée
- * gratuitement, par le même chemin que tout le reste.
- *
- * La réponse porte l'instantané de la salle — même motif que
- * `cloudSync.subscribe` : aucun trou entre l'inscription et la première
- * diffusion, et une reconnexion se resynchronise par ce seul appel.
+ * Déclare où je suis, et récupère l'état de la salle. L'espace n'est pas dans
+ * l'entrée : il voyage sur l'enveloppe, résolu et vérifié par le dispatcheur.
+ * La réponse porte l'instantané de la salle : aucun trou entre l'inscription
+ * et la première diffusion, et une reconnexion se resynchronise par ce seul
+ * appel.
  */
 export const liveHere = {
     command: 'live.here' as const,
@@ -22,42 +17,27 @@ export const liveHere = {
 export const liveCommands = [liveHere] as const;
 
 /**
- * Les positions de curseur, **hors du registre des commandes**.
- *
- * Délibérément absente de `featureCommandRegistry` : `ws.send` y trouverait un
- * descripteur, ouvrirait une promesse en attente et armerait un délai de 15 s —
- * pour une trame émise vingt fois par seconde dont on n'attend aucune réponse.
- * Le client la poste par `ws.post`, le serveur la traite sur une voie rapide
- * avant la recherche de commande.
+ * Les positions de curseur, hors du registre des commandes : `ws.send` y
+ * ouvrirait une promesse et armerait un délai pour une trame émise vingt fois
+ * par seconde sans réponse. Le client la poste par `ws.post`, le serveur la
+ * traite sur une voie rapide.
  */
 export const LIVE_CURSOR_COMMAND = 'live.cursor' as const;
 
 /**
- * Ce que porte une trame de curseur : des coordonnées, et rien d'autre.
- *
- * Ni chemin ni espace : la voie rapide court-circuite la résolution
- * d'autorisation, elle ne peut donc rien accepter du client qui déciderait de
- * *qui verra* la trame. Le lieu vient du dernier `live.here`, lui passé par le
- * dispatcheur. `cursor: null` = le pointeur a quitté la surface.
+ * Ce que porte une trame de curseur : des coordonnées, rien d'autre. Ni chemin
+ * ni espace : la voie rapide court-circuite l'autorisation, le lieu vient du
+ * dernier `live.here`. `cursor: null` = le pointeur a quitté la surface.
  */
 export const liveCursorFrameSchema = z.object({ cursor: liveCursorSchema.nullable() });
 export type LiveCursorFrame = z.infer<typeof liveCursorFrameSchema>;
 
 /**
- * « Untel est en train d'écrire… », sur la même voie rapide que les curseurs.
- *
- * Hors du registre des commandes, pour exactement la même raison : c'est une
- * trame sans réponse, émise par `ws.post`, qu'il serait absurde de faire passer
- * par une promesse en attente, un journal d'audit et une validation d'accès.
- *
- * Volontairement **générique** : la trame ne dit pas *quoi* est en train d'être
- * écrit. Le lieu vient du dernier `live.here`, comme pour les curseurs, donc
- * n'importe quelle feature peut s'en servir sans toucher au moteur — un fil de
- * discussion de projet aujourd'hui, une note à plusieurs demain.
- *
- * Le serveur applique une péremption : sans rafraîchissement, un pair cesse
- * d'être « en train d'écrire » tout seul. C'est ce qui empêche un onglet fermé
- * brutalement de laisser un fantôme à l'écran.
+ * « Untel est en train d'écrire… », sur la même voie rapide que les curseurs et
+ * hors du registre pour la même raison. Générique : la trame ne dit pas quoi,
+ * le lieu vient du dernier `live.here`. Le serveur applique une péremption :
+ * sans rafraîchissement, un pair cesse d'écrire tout seul (pas de fantôme
+ * après un onglet fermé brutalement).
  */
 export const LIVE_TYPING_COMMAND = 'live.typing' as const;
 export const liveTypingFrameSchema = z.object({ typing: z.boolean() });

package/src/features/notify.ts

@@ -12,31 +12,15 @@ import {
 } from '../domain/notifications';
 
 /**
- * Les canaux d'alerte de l'espace, et les routes qui pointent vers eux.
+ * Les canaux d'alerte de l'espace, et les routes qui pointent vers eux. Un
+ * module à part : la fonctionnalité est un argument, pas un préfixe de
+ * commande, et un émetteur de plus ne coûte qu'une valeur dans
+ * `notificationFeatureSchema`.
  *
- * ## Pourquoi un module à part, et pas trois commandes par émetteur
- *
- * Il y en avait quinze — `getSettings`, `setSettings`, `testNotification`, pour
- * chacun des cinq émetteurs — strictement identiques à leur préfixe près. Le
- * dialogue client les reconstituait déjà par concaténation
- * (`` `${feature}.getSettings` ``), ce qui disait tout : la fonctionnalité
- * n'était pas dans la commande, elle était dans un **argument**. Elle l'est
- * désormais pour de bon.
- *
- * Conséquence directe : brancher un sixième émetteur ne coûte plus trois
- * commandes, trois entrées de registre et trois handlers, mais une valeur de
- * plus dans `notificationFeatureSchema`.
- *
- * ## Deux étages d'autorisation, et ils ne sont pas les mêmes
- *
- * Gérer les **canaux** d'une fonctionnalité relève du champ `channels` de son
- * grant de rôle (migration 093) : un canal appartient à une fonctionnalité
- * (091), et son adresse ne se livre qu'à qui gère les canaux de celle-ci. Les
- * **routes**, elles, relèvent de la fonctionnalité visée (`{ feature, level:
- * 'write' }`) : décider où Uptime écrit fait partie du réglage d'Uptime, et n'a
- * pas à ouvrir la gestion des destinations. C'est la séparation qui permet de
- * confier le routage d'une fonctionnalité sans confier l'adresse de
- * l'astreinte.
+ * Deux étages d'autorisation : gérer les canaux d'une fonctionnalité relève du
+ * champ `channels` de son grant ; les routes relèvent de la fonctionnalité
+ * visée (`{ feature, level: 'write' }`). On peut confier le routage sans
+ * confier l'adresse de l'astreinte.
  */
 
 const channelId = z.number().int().positive();
@@ -62,11 +46,8 @@ export const notifyChannelUpdate = {
 };
 
 /**
- * Ce qu'une suppression emporterait, **sans rien supprimer**.
- *
- * Lue par la confirmation pour nommer les routes qui vont cesser de prévenir.
- * Séparée de la suppression elle-même parce qu'un écran qui demande « êtes-vous
- * sûr ? » sans dire de quoi ne fait pas confirmer, il fait cliquer.
+ * Ce qu'une suppression emporterait, sans rien supprimer : lue par la
+ * confirmation pour nommer les routes qui vont cesser de prévenir.
  */
 export const notifyChannelUsage = {
     command: 'notify.channelUsage' as const,
@@ -86,14 +67,7 @@ export const notifyChannelReorder = {
     output: z.object({ ok: z.literal(true) })
 };
 
-/**
- * Un envoi d'essai **sur un seul canal**, tel qu'il est enregistré.
- *
- * L'ancien dialogue devait enregistrer avant de tester, faute de quoi l'essai
- * partait sur les réglages précédents. Un canal étant une entité à part entière,
- * l'essai vise directement son identifiant : plus d'enregistrement forcé, et
- * plus de doute sur ce qui vient d'être éprouvé.
- */
+/** Un envoi d'essai sur un seul canal, tel qu'il est enregistré. */
 export const notifyChannelTest = {
     command: 'notify.channelTest' as const,
     input: z.object({ id: channelId }),
@@ -107,31 +81,19 @@ export const notifyRouteGet = {
     output: z.object({
         route: notificationRouteSchema,
         /**
-         * Les canaux de la route qui **n'appartiennent pas à cet espace**.
-         *
-         * Le cas d'un élément projeté depuis ailleurs : ses destinations vivent
-         * dans son espace d'origine. Sans cette liste, l'écran afficherait
-         * « aucun canal » sur un élément qui prévient bel et bien — le mensonge
-         * exact que la projection devait éviter.
-         *
-         * Rendus **masqués** : leur genre (« Salon Discord d'un autre espace »),
-         * jamais leur identité ni leur adresse.
+         * Les canaux de la route qui n'appartiennent pas à cet espace (élément
+         * projeté depuis ailleurs). Rendus masqués : leur genre, jamais leur
+         * identité ni leur adresse.
          */
         foreign: z.array(notificationChannelSchema),
         /**
-         * Cette route se règle-t-elle **d'ici** ?
-         *
-         * Faux sur un élément projeté depuis un autre espace : ses canaux
-         * appartiennent à cet espace-là, et l'ordonnanceur qui le sonde y
-         * tourne. Laisser l'écran proposer le réglage produirait un geste que
-         * le serveur refuse — un écran qui ment, pas une garde.
+         * Cette route se règle-t-elle d'ici ? Faux sur un élément projeté
+         * depuis un autre espace : ses canaux appartiennent à cet espace-là.
          */
         managedHere: z.boolean(),
         /**
-         * L'espace **où cette route se règle** : le domicile de l'élément.
-         * Égal à l'espace de l'enveloppe quand `managedHere` est vrai. C'est ce
-         * qui permet à l'écran, sur un élément projeté, de proposer d'aller
-         * régler chez lui plutôt que d'expliquer un refus.
+         * L'espace où cette route se règle : le domicile de l'élément (égal à
+         * l'espace de l'enveloppe quand `managedHere` est vrai).
          */
         homeWorkspaceId: z.number().int().positive()
     })
@@ -143,7 +105,7 @@ export const notifyRouteSet = {
     output: z.object({ route: notificationRouteSchema })
 };
 
-/** Un essai sur la route entière, héritage compris — ce que verrait une vraie alerte. */
+/** Un essai sur la route entière : ce que verrait une vraie alerte. */
 export const notifyRouteTest = {
     command: 'notify.routeTest' as const,
     input: notificationRouteTargetSchema,