@deveye/types 0.15.0

package/src/domain/note.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+
+/**
+ * A note's body is a modular list of typed blocks rather than free text. This
+ * keeps the editor "à la Apple" (one clean surface) while still supporting
+ * paragraphs and checklists in any order:
+ *  - `text`  → a paragraph.
+ *  - `check` → a checklist item, with its own `done` state.
+ *
+ *  - `bullet` → a bulleted (unordered) list item.
+ *  - `number` → a numbered (ordered) list item; its visible index is derived
+ *    from its position in the run of consecutive `number` blocks (not stored).
+ *  - `heading` → a section title, `level` 1 (largest) to 5 (smallest).
+ *  - `divider` → a horizontal separator; carries no text.
+ *
+ * Inline emphasis (bold `**`, italic `*`, underline `__`, strikethrough `~~`)
+ * is kept as markdown markers inside a block's `text`, not as separate blocks.
+ *
+ * The shape is intentionally small and forward-compatible: adding a new block
+ * kind later (heading, divider, …) only widens this union.
+ */
+/**
+ * Named colour palette shared by the two colouring features:
+ *  - inline text colour, carried as `{c:name}…{/c}` markers inside a block's
+ *    `text` (so it lives in the freeform string, not the schema);
+ *  - the block-level `color` below, which tints a marker (bullet dot, ordinal,
+ *    checkbox, divider rule).
+ *
+ * A *named* palette (not a free hex) keeps the stored value tied to a theme
+ * token (`--note-<name>`), so colours stay coherent with the app's design and
+ * adapt if the palette is retuned. Widen this enum to add a colour.
+ */
+export const noteColorSchema = z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']);
+
+export type NoteColor = z.infer<typeof noteColorSchema>;
+
+export const noteTextBlockSchema = z.object({
+    type: z.literal('text'),
+    text: z.string()
+});
+
+export const noteCheckBlockSchema = z.object({
+    type: z.literal('check'),
+    text: z.string(),
+    done: z.boolean(),
+    /** Optional tint for the checkbox marker (theme token `--note-<color>`). */
+    color: noteColorSchema.optional()
+});
+
+export const noteBulletBlockSchema = z.object({
+    type: z.literal('bullet'),
+    text: z.string(),
+    /** Optional tint for the bullet dot (theme token `--note-<color>`). */
+    color: noteColorSchema.optional()
+});
+
+export const noteNumberBlockSchema = z.object({
+    type: z.literal('number'),
+    text: z.string(),
+    /** Optional tint for the ordinal marker (theme token `--note-<color>`). */
+    color: noteColorSchema.optional()
+});
+
+export const noteHeadingBlockSchema = z.object({
+    type: z.literal('heading'),
+    text: z.string(),
+    /** Heading level, 1 (largest) to 5 (smallest). */
+    level: z.number().int().min(1).max(5)
+});
+
+export const noteDividerBlockSchema = z.object({
+    type: z.literal('divider'),
+    /** Optional tint for the horizontal rule (theme token `--note-<color>`). */
+    color: noteColorSchema.optional()
+});
+
+export const noteBlockSchema = z.discriminatedUnion('type', [
+    noteTextBlockSchema,
+    noteCheckBlockSchema,
+    noteBulletBlockSchema,
+    noteNumberBlockSchema,
+    noteHeadingBlockSchema,
+    noteDividerBlockSchema
+]);
+
+export type NoteTextBlock = z.infer<typeof noteTextBlockSchema>;
+export type NoteCheckBlock = z.infer<typeof noteCheckBlockSchema>;
+export type NoteBulletBlock = z.infer<typeof noteBulletBlockSchema>;
+export type NoteNumberBlock = z.infer<typeof noteNumberBlockSchema>;
+export type NoteHeadingBlock = z.infer<typeof noteHeadingBlockSchema>;
+export type NoteDividerBlock = z.infer<typeof noteDividerBlockSchema>;
+export type NoteBlock = z.infer<typeof noteBlockSchema>;
+
+/** Upper bounds, enforced both client- and server-side, to keep rows sane. */
+export const NOTE_TITLE_MAX_LENGTH = 200;
+export const NOTE_FOLDER_MAX_LENGTH = 80;
+export const NOTE_BLOCK_TEXT_MAX_LENGTH = 5_000;
+export const NOTE_MAX_BLOCKS = 500;
+
+/**
+ * A folder is a first-class, server-persisted bucket. Its `name` is stored
+ * encrypted server-side (with the open key, so the folder tree is readable
+ * without a password); only the linkage (`folderId` on notes) is kept in clear.
+ * `id` is stable across renames, so notes reference it directly.
+ */
+export const noteFolderSchema = z.object({
+    id: z.number().int().positive(),
+    name: z.string().max(NOTE_FOLDER_MAX_LENGTH),
+    /** Rank within the user's folders; lower comes first. Manually reorderable. */
+    sortOrder: z.number().int().nonnegative()
+});
+
+export type NoteFolder = z.infer<typeof noteFolderSchema>;
+
+/**
+ * A full note as exchanged with the client. `folderId` references a
+ * {@link noteFolderSchema}; `null` means "no folder" (Sans dossier).
+ *
+ * A **private** note is encrypted with the password-wrapped DEK, so reading or
+ * writing it requires the session to be unlocked; a regular note is encrypted
+ * with the user's open key, which the server can always resolve — that's what
+ * lets the feature open without any prompt.
+ */
+export const noteSchema = z.object({
+    id: z.number().int().nonnegative(),
+    title: z.string().max(NOTE_TITLE_MAX_LENGTH),
+    folderId: z.number().int().positive().nullable(),
+    blocks: z.array(noteBlockSchema).max(NOTE_MAX_BLOCKS),
+    /** Rank within its folder; lower comes first. Only drag & drop changes it. */
+    sortOrder: z.number().int().nonnegative(),
+    /** True when the note is encrypted with the password-protected key. */
+    private: z.boolean(),
+    /** Epoch seconds; set by the server, surfaced for sorting/display. */
+    updated: z.number().int().nonnegative(),
+    /** Epoch seconds the note was first created. */
+    created: z.number().int().nonnegative()
+});
+
+export type Note = z.infer<typeof noteSchema>;
+
+/**
+ * Lightweight list variant. A private note listed while the session is locked
+ * comes back **masked** — metadata only, no `title`/`preview` — so the UI can
+ * render a padlock placeholder without the body ever being decrypted.
+ */
+export const noteSummarySchema = z.object({
+    id: z.number().int().nonnegative(),
+    title: z.string(),
+    folderId: z.number().int().positive().nullable(),
+    /** Rank within its folder; lower comes first. Only drag & drop changes it. */
+    sortOrder: z.number().int().nonnegative(),
+    /** Present only when the body is readable; absent for masked notes. */
+    preview: z.string().optional(),
+    /** Total checklist items / how many are done — for an at-a-glance summary. */
+    checkTotal: z.number().int().nonnegative(),
+    checkDone: z.number().int().nonnegative(),
+    /** True when the note is encrypted with the password-protected key. */
+    private: z.boolean(),
+    /** True when the body stayed encrypted for this response (private + locked). */
+    masked: z.boolean(),
+    /** Epoch seconds the note was archived, or `null` while it is active. */
+    archivedAt: z.number().int().nonnegative().nullable(),
+    updated: z.number().int().nonnegative(),
+    /** Epoch seconds the note was first created. */
+    created: z.number().int().nonnegative()
+});
+
+export type NoteSummary = z.infer<typeof noteSummarySchema>;
+
+export interface NoteRow {
+    id: number;
+    user_id: number;
+    workspace_id: number | null;
+    folder_id: number | null;
+    /**
+     * Encrypted JSON payload (title + blocks), keyed by the private DEK when
+     * `is_private`, by the user's open DEK otherwise.
+     */
+    content: string;
+    /** Manual rank within its folder; lower comes first. */
+    sort_order: number;
+    /** 1 when the body is encrypted with the password-protected key. */
+    is_private: number;
+    /**
+     * Epoch seconds the note was archived; `NULL` while active. Deleting a note
+     * archives it — only an already-archived note can be destroyed for good.
+     */
+    archived_at: number | null;
+    updated: number;
+    created: number;
+}
+
+export interface NoteFolderRow {
+    id: number;
+    user_id: number;
+    workspace_id: number | null;
+    /** Encrypted JSON payload (`{ name }`). */
+    content: string;
+    /** Manual rank within the user's folders; lower comes first. */
+    sort_order: number;
+    created: number;
+}

package/src/domain/notifications.ts

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+
+import { NOTIFYING_FEATURES } from './featureRegistry';
+import { externalFeatureIdSchema } from './workspaceRole';
+
+/**
+ * Les canaux d'alerte d'un espace — **une liste, et des liaisons vers elle**.
+ *
+ * ## Ce que le modèle précédent ne savait pas faire
+ *
+ * Il portait deux canaux binaires — un mail, un webhook — par couple
+ * `(espace, feature)`. Trois conséquences, toutes rencontrées :
+ *
+ * 1. **Le même salon Discord était redéclaré cinq fois.** Le corriger demandait
+ *    d'ouvrir cinq écrans, et en oublier un ne se voyait qu'à la première alerte
+ *    qui n'arrivait plus.
+ * 2. **Deux destinataires étaient impossibles.** Une équipe pour la production,
+ *    une autre pour la recette : il fallait choisir.
+ * 3. **Aucun routage par élément.** Toutes les bases d'un espace prévenaient les
+ *    mêmes gens, quel que soit le projet derrière.
+ *
+ * ## La forme retenue
+ *
+ * Un **canal** est une destination nommée : un type, un libellé, une cible. Il
+ * appartient à **une fonctionnalité** (091) : c'est une source de cette
+ * fonctionnalité, au même titre qu'un jeton Dokploy pour le Déploiement, et il
+ * se gère dans ses réglages à elle. La 087 l'avait fait vivre à l'échelle de
+ * l'espace, partagé par les cinq émetteurs ; on retrouvait alors une liste
+ * commune gérée depuis cinq endroits, l'inverse du patron des sources. Le prix
+ * assumé du retour : deux features qui préviennent le même salon le déclarent
+ * deux fois. On en déclare autant qu'on veut, et on les corrige **à un seul
+ * endroit** : les réglages de leur fonctionnalité.
+ *
+ * Une **route** dit qui écrit vers quels canaux, et la sélection vit **sur
+ * l'élément** (092) : chaque cible coche un ou plusieurs canaux de sa feature
+ * dans ses propres réglages, et sans sélection rien ne part. L'héritage
+ * d'une « route de la fonctionnalité » a été essayé (087) puis retiré : cocher
+ * un canal à l'échelle de la feature ne visait aucun élément nommable, et les
+ * cases des éléments, grisées tant qu'ils « suivaient » la feature, semblaient
+ * ne jamais pouvoir se cocher. Une route de fonctionnalité (`itemId` absent)
+ * ne subsiste que pour les émetteurs **sans éléments** (Sentinelle), dont les
+ * alertes ne visent rien de plus fin.
+ *
+ * Ce qui n'a pas changé, et qui compte : **tout est éteint par défaut.** Sans
+ * canal ni route, rien ne part. Une fonctionnalité qui se met à écrire à des
+ * gens sans qu'ils l'aient demandé reste le travers que ce modèle refuse.
+ */
+
+/**
+ * Le type d'un canal, et ce qu'il change à l'envoi.
+ *
+ * `webhook` et `discord` **séparent ce que l'URL devinait**. Le module d'envoi
+ * reconnaissait Discord en analysant l'adresse, ce qui marchait mais décidait à
+ * la place de l'utilisateur : un point d'entrée maison hébergé derrière un
+ * domaine Discord aurait reçu des embeds au lieu de son texte, et rien ne
+ * permettait de demander l'inverse. C'est désormais une déclaration.
+ *
+ *  - `email`   — un compte Mail « open » de l'espace expédie vers une adresse.
+ *  - `webhook` — un POST JSON générique : le message lisible est répété dans
+ *    `content` (Discord) et `text` (Slack), les champs structurés suivent pour
+ *    un point d'entrée maison. Aucune des trois têtes ne gêne les autres.
+ *  - `discord` — la mise en page riche de Discord (embeds, couleurs, champs),
+ *    et pour le déploiement le **suivi vivant** : un seul message qui se met à
+ *    jour du début à la fin.
+ */
+export const notificationChannelKindSchema = z.enum(['email', 'webhook', 'discord']);
+export type NotificationChannelKind = z.infer<typeof notificationChannelKindSchema>;
+
+export const NOTIFICATION_CHANNEL_KINDS = notificationChannelKindSchema.options;
+
+/**
+ * Les fonctionnalités **natives** qui savent prévenir.
+ *
+ * Enum fermé plutôt que chaîne libre : c'est lui qui garde une route d'être
+ * posée sur une fonctionnalité qui n'écrira jamais. Il double le drapeau
+ * `notifies` du registre, et le contrôle en bas de fichier interdit qu'ils
+ * divergent.
+ */
+export const nativeNotificationFeatureSchema = z.enum([
+    'uptime',
+    'sentinel',
+    'database',
+    'deploy',
+    'backup'
+]);
+export type NativeNotificationFeature = z.infer<typeof nativeNotificationFeatureSchema>;
+
+/**
+ * Un module externe peut prévenir aussi. Le schéma n'atteste que la **forme**
+ * de l'id : la garde de fond (« ce module déclare bien `notifies` ») ne peut
+ * pas vivre ici, elle dépend de l'installation ; le serveur la tient contre le
+ * registre fusionné, au même endroit que `assertChannels`.
+ */
+export const notificationFeatureSchema = z.union([
+    nativeNotificationFeatureSchema,
+    externalFeatureIdSchema
+]);
+export type NotificationFeature = z.infer<typeof notificationFeatureSchema>;
+
+export const NOTIFICATION_LABEL_MAX = 64;
+export const NOTIFICATION_TARGET_MAX = 2048;
+export const NOTIFICATION_EMAIL_MAX = 320;
+
+/**
+ * Un canal tel que le client le reçoit.
+ *
+ * `target` sort **en clair** : c'est une adresse que son auteur a saisie et doit
+ * pouvoir relire pour la corriger. Elle est chiffrée au repos (étage ouvert),
+ * comme l'étaient déjà les réglages qu'elle remplace.
+ */
+export const notificationChannelSchema = z.object({
+    id: z.number().int().positive(),
+    kind: notificationChannelKindSchema,
+    /** Nom donné par l'utilisateur — « Astreinte », « #ops », « Webhook Grafana ». */
+    label: z.string().min(1).max(NOTIFICATION_LABEL_MAX),
+    /**
+     * Adresse destinataire (`email`) ou URL appelée en POST (`webhook`,
+     * `discord`) : **vide pour qui n'a pas la gestion des canaux de la
+     * fonctionnalité** (le champ `channels` de son grant, migration 093).
+     *
+     * La liste est lisible avec la fonctionnalité, parce qu'il faut voir les
+     * destinations pour router vers l'une d'elles. Leur *contenu* ne l'est
+     * pas : confier le réglage d'Uptime ne confie pas l'adresse de l'astreinte
+     * ni l'URL du salon de production. On voit donc « Astreinte · e-mail », on
+     * peut y router, et on ne peut ni la lire ni la modifier.
+     */
+    target: z.string().max(NOTIFICATION_TARGET_MAX),
+    /** Le compte Mail expéditeur ; `null` hors des canaux `email`. */
+    mailAccountId: z.number().int().positive().nullable(),
+    /**
+     * Ce canal partirait-il **maintenant** ?
+     *
+     * Faux quand le compte expéditeur manque, a disparu, est désactivé ou n'est
+     * pas au palier « open ». L'interface le dit au lieu de laisser croire à un
+     * canal actif — l'avertissement n'existait à l'origine que dans Uptime, et
+     * son absence ailleurs faisait passer un canal muet pour un canal réglé.
+     */
+    ready: z.boolean(),
+    /** Éteint sans être supprimé : ses routes restent, rien ne part. */
+    enabled: z.boolean(),
+    position: z.number().int().nonnegative(),
+    /**
+     * Combien de routes le désignent — ce que l'écran affiche en « utilisé par
+     * N ». Compté côté serveur : le client n'a pas les routes des éléments sous
+     * la main, et les demander toutes pour afficher un nombre serait une
+     * requête par ligne.
+     */
+    usageCount: z.number().int().nonnegative()
+});
+export type NotificationChannel = z.infer<typeof notificationChannelSchema>;
+
+/** Ce qu'accepte `notify.channelAdd` / `channelUpdate`. */
+export const notificationChannelInputSchema = z.object({
+    kind: notificationChannelKindSchema,
+    label: z.string().min(1).max(NOTIFICATION_LABEL_MAX),
+    /** Adresse ou URL. Vide sur un `email` = l'adresse du compte expéditeur. */
+    target: z.string().max(NOTIFICATION_TARGET_MAX),
+    mailAccountId: z.number().int().positive().nullable()
+});
+export type NotificationChannelInput = z.infer<typeof notificationChannelInputSchema>;
+
+/**
+ * La cible d'une route : une fonctionnalité, ou un de ses éléments.
+ *
+ * `itemId` absent vaut « la fonctionnalité elle-même ». En base il devient `0`,
+ * parce qu'une colonne d'une clé primaire ne peut pas être nulle ; le contrat,
+ * lui, n'a pas à porter cette contrainte de stockage.
+ */
+export const notificationRouteTargetSchema = z.object({
+    feature: notificationFeatureSchema,
+    itemId: z.number().int().positive().optional()
+});
+export type NotificationRouteTarget = z.infer<typeof notificationRouteTargetSchema>;
+
+/**
+ * Où écrit une cible : sa sélection de canaux, rien de plus.
+ *
+ * Vide, elle ne prévient personne — il n'y a plus d'héritage à distinguer
+ * (092), donc plus de drapeau `inherits` : une sélection vide et une sélection
+ * jamais faite disent la même chose, le silence.
+ */
+export const notificationRouteSchema = z.object({
+    channelIds: z.array(z.number().int().positive())
+});
+export type NotificationRoute = z.infer<typeof notificationRouteSchema>;
+
+/** Ce qu'accepte `notify.routeSet`. Une sélection vide efface la route. */
+export const notificationRouteInputSchema = notificationRouteTargetSchema.extend({
+    channelIds: z.array(z.number().int().positive()).max(32)
+});
+export type NotificationRouteInput = z.infer<typeof notificationRouteInputSchema>;
+
+/**
+ * Ce que rend un envoi d'essai : parti, ou pourquoi non.
+ *
+ * `sent: false` avec un `error` n'est pas une exception — « aucun canal activé »
+ * est une réponse, pas une panne, et la remonter comme telle laisserait l'écran
+ * afficher « échec » là où il n'y a rien à échouer.
+ */
+export const notificationTestSchema = z.object({ sent: z.boolean(), error: z.string().nullable() });
+export type NotificationTest = z.infer<typeof notificationTestSchema>;
+
+/**
+ * Ce qu'une suppression de canal emporte avec elle.
+ *
+ * Rendu **avant** la suppression pour que la confirmation nomme ce qui va
+ * cesser de prévenir, plutôt que de demander « êtes-vous sûr ? » sans dire de
+ * quoi. Une liste vide veut dire qu'aucune route ne le désigne.
+ */
+export const notificationChannelUsageSchema = z.object({
+    channelId: z.number().int().positive(),
+    routes: z.array(
+        z.object({
+            feature: notificationFeatureSchema,
+            itemId: z.number().int().positive().nullable(),
+            /** Nom de l'élément, déchiffré par le serveur ; `null` sur une route de feature. */
+            itemLabel: z.string().nullable()
+        })
+    )
+});
+export type NotificationChannelUsage = z.infer<typeof notificationChannelUsageSchema>;
+
+/** Ligne de `notification_channels` (serveur uniquement). */
+export interface NotificationChannelRow {
+    id: number;
+    workspace_id: number;
+    /** La fonctionnalité propriétaire : un canal est une source de SA feature (091). */
+    feature: NotificationFeature;
+    kind: NotificationChannelKind;
+    label_enc: string;
+    target_enc: string;
+    mail_account_id: number | null;
+    enabled: number;
+    position: number;
+    created: number;
+}
+
+/** Ligne de `notification_routes` (serveur uniquement). */
+export interface NotificationRouteRow {
+    id: number;
+    workspace_id: number;
+    feature: NotificationFeature;
+    /** `0` = la fonctionnalité elle-même. */
+    item_id: number;
+}
+
+/**
+ * Contrôle de cohérence, au chargement du module.
+ *
+ * `notifies` dans le registre et cet enum répondent à la même question ; les
+ * tenir séparés est un choix (l'un décrit, l'autre valide), les laisser diverger
+ * n'en est pas un. Une fonctionnalité marquée `notifies` mais absente de l'enum
+ * afficherait un onglet Notifications dont toutes les commandes seraient
+ * refusées — un écran qui ment, découvert à la première alerte attendue.
+ *
+ * Même esprit que le contrôle des sujets `mutates` côté serveur : attraper
+ * l'oubli au démarrage plutôt qu'en production.
+ */
+{
+    const registry = [...NOTIFYING_FEATURES].sort().join(', ');
+    const declared = [...nativeNotificationFeatureSchema.options].sort().join(', ');
+    if (registry !== declared) {
+        throw new Error(
+            `nativeNotificationFeatureSchema et FEATURE_REGISTRY.notifies divergent : ` +
+                `registre : [${registry}], enum : [${declared}]`
+        );
+    }
+}

package/src/domain/packages.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+/**
+ * Update tooling DevEye can detect and drive on a monitored machine. Covers OS
+ * package managers and the two heavyweight system updaters (macOS softwareupdate,
+ * Windows Update). The agent only reports the ones actually present on the host.
+ */
+export const packageManagerIdSchema = z.enum([
+    'apt',
+    'dnf',
+    'pacman',
+    'pamac',
+    'flatpak',
+    'snap',
+    'zypper',
+    'brew',
+    'softwareupdate',
+    'winget',
+    'windowsupdate'
+]);
+
+export type PackageManagerId = z.infer<typeof packageManagerIdSchema>;
+
+/** One detected manager + its pending-update state. */
+export const packageManagerSchema = z.object({
+    id: packageManagerIdSchema,
+    /** Pending update count; `null` when unknown (slow/best-effort probe). */
+    pendingCount: z.number().int().nonnegative().nullable(),
+    /** Applying this manager's updates requires root/admin. */
+    needsRoot: z.boolean(),
+    /** A reboot is pending for updates this manager already applied. */
+    rebootRequired: z.boolean().default(false)
+});
+
+export type PackageManager = z.infer<typeof packageManagerSchema>;

package/src/domain/password.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+export const passwordStatusSchema = z.enum(['active', 'inactive', 'none']);
+export type PasswordStatus = z.infer<typeof passwordStatusSchema>;
+
+export const passwordEntrySchema = z.object({
+    id: z.number().int().nonnegative(),
+    category: z.string(),
+    service: z.string(),
+    email: z.string(),
+    password: z.string(),
+    status: passwordStatusSchema
+});
+
+export type PasswordEntry = z.infer<typeof passwordEntrySchema>;
+
+/**
+ * Variant without the secret payload, used when listing entries before unlock.
+ * `hasPassword` tells the UI whether a (still hidden) secret actually exists, so
+ * a genuinely empty password renders as a blank cell instead of fake dots with
+ * reveal/copy controls that would yield nothing.
+ */
+export const passwordEntryMaskedSchema = passwordEntrySchema.extend({
+    password: z.literal(''),
+    hasPassword: z.boolean()
+});
+
+export type PasswordEntryMasked = z.infer<typeof passwordEntryMaskedSchema>;
+
+export interface PasswordRow {
+    id: number;
+    user_id: number;
+    workspace_id: number | null;
+    content: string;
+    date: number;
+}

package/src/domain/presence.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+/**
+ * Agent connectivity history. The server records a transition each time an agent
+ * connects or disconnects; the UI replays these to draw an online/offline
+ * timeline (the "frise") and compute uptime over a window.
+ */
+export const presenceEventSchema = z.object({
+    /** Unix ms of the transition. */
+    ts: z.number().int().positive(),
+    online: z.boolean()
+});
+
+export type PresenceEvent = z.infer<typeof presenceEventSchema>;
+
+export interface PresenceRow {
+    id: number;
+    device_id: string;
+    ts: number;
+    online: 0 | 1;
+}