Mergerie
Sommaire

Référence de l’API du ctx

Cette page est générée depuis docs/plugins/API.md · Modifier cette page sur GitLab

Généré depuis sdk/contract.js (API 1) par sdk/scripts/generer-docs-api.js — ne pas éditer à la main. Les exemples cités sont des fichiers de docs/plugins/examples/, exécutés par la CI.

Un plugin exporte activate(ctx) et deactivate(). Le ctx est la liste fermée de ce qu'il peut faire : il ne porte que les primitives couvertes par les permissions de son plugin.json, et rien d'autre (il est gelé). Un plugin embarqué, un plugin tiers dans son worker et un plugin sous test (createTestContext) reçoivent le même ctx, construit par le même code (sdk/lib/contexte.js).

Toujours présents, sans permission : ctx.name, ctx.version, ctx.apiVersion, ctx.log, ctx.i18n.

Permissions

Déclarées dans plugin.json → permissions. Réglages → Plugins les affiche avant l’activation ; exec déclenche un avertissement explicite pour un plugin tiers.

PermissionCe qu’elle ouvre
eventsécouter et émettre des événements (ctx.events)
settingslire et écrire ses réglages, validés par settingsSchema (ctx.settings)
secretslire et écrire ses secrets, masqués comme ceux du cœur (ctx.secrets)
dbses tables SQLite, préfixées plugin_<name>_ (ctx.db)
httpdes routes HTTP sous /api/plugins/<name>/ (ctx.http.router)
sseun flux Server-Sent Events sous /api/plugins/<name>/ (ctx.http.sse)
scheduledes tâches périodiques (ctx.schedule / ctx.unschedule)
execlancer un binaire SANS shell, avec liste blanche de sous-commandes (ctx.exec)
netdes requêtes HTTP(S) sortantes, avec la convention TLS du cœur (ctx.net)
reposlire le registre des dépôts suivis (ctx.repos)
ui.tabun onglet, un sous-onglet de réglages, des pastilles (ctx.ui.registerTab, registerSettingsTab, setBadge)
ui.actionsdes actions et décorations sur les objets du cœur (ctx.ui.registerAction, registerDecorator, registerBriefSection, registerLinkKind)
ui.palettedes entrées dans la palette Ctrl+K (ctx.ui.registerPaletteProvider)
notifydes notifications bureau (ctx.notify)
demosemer le mode démo (ctx.demo)
envlire les variables d’environnement préfixées par son nom (ctx.env)
servicesexposer et appeler des services nommés entre plugins et cœur (ctx.services)
jobsdes jobs dans la file du cœur : journal en direct, progression, arrêt, écran des jobs (ctx.jobs)
storageun dossier privé où écrire des fichiers — un profil de navigateur, un cache — qui survit aux mises à jour du plugin (ctx.dataDir)

Primitives

PrimitivePermissionSignatureRôle
ctx.log—(message: string, ...args) => voidécrit dans le journal du serveur, préfixé du nom du plugin
ctx.i18n.register—(locale: "fr" | "en", dict: Record<string, string>) => voidajoute des libellés au dictionnaire du serveur ET du navigateur
ctx.i18n.t—(key: string, params?: Record<string, unknown>) => stringtraduit dans la langue courante de l’écran
ctx.events.onevents(name: string, handler: (payload) => void | Promise<void>) => () => voids’abonne ; rend la fonction de désabonnement
ctx.events.offevents(name: string, handler) => voidse désabonne
ctx.events.emitevents(name: string, payload: object) => Promise<EmitResult>émet un événement déclaré dans plugin.json (events.emits)
ctx.settings.getsettings(key?: string) => unknownun réglage, ou tous (défauts du schéma appliqués)
ctx.settings.setsettings(patch: Record<string, unknown>) => Record<string, unknown>écrit, après validation par settingsSchema
ctx.settings.onChangesettings(handler: (settings) => void) => () => voidappelé après chaque écriture (écran ou plugin)
ctx.secrets.getsecrets(key: string) => stringla valeur en clair (jamais rendue au navigateur)
ctx.secrets.setsecrets(key: string, value: string) => void"***" = inchangé, "" = effacé
ctx.secrets.hassecrets(key: string) => booleany a-t-il une valeur ?
ctx.db.preparedb(sql: string) => Statementune requête sur les tables plugin_<name>_* uniquement
ctx.db.execdb(sql: string) => voidDDL/DML sur les tables du plugin uniquement
ctx.db.transactiondb(fn: () => T) => Tune transaction
ctx.db.migratedb(migrations: { version: number, up: string | ((db) => void) }[]) => numberrejoue en avant les migrations non encore appliquées ; rend le nombre jouées
ctx.db.classifydb(table: string, family: "P" | "L" | "C") => voiddéclare le classement P/L/C d’une table (V1 : L et C seulement)
ctx.http.routerhttpRouterget/post/put/delete/patch(path, handler(req, reply)) montés sous /api/plugins/<name>/
ctx.http.ssesse(path: string, producer: (req, send, close) => () => void) => voidun flux SSE sous /api/plugins/<name>/ (non éprouvé en V1)
ctx.scheduleschedule(intervalMs: number, fn: () => void | Promise<void>, options?: { immediate?: boolean, inDemo?: boolean }) => numberune tâche périodique ; arrêtée à la désactivation, jamais en recouvrement, inactive en démo sauf inDemo
ctx.unscheduleschedule(id: number) => voidarrête une tâche
ctx.execexec(bin: string, args: string[], options: { cwd?: string, timeoutMs?: number, allowlist: string[], denyFlags?: string[], env?: Record<string, string> }) => Promise<{ stdout, stderr, code }>lance SANS shell, sous-commande en liste blanche ; env s’ajoute à un environnement minimal, sans PATH, HOME, LD_*, DYLD_*, NODE_OPTIONS, GIT_*, SHELL, BASH_ENV…
ctx.execStreamexec(bin: string, args: string[], options: { cwd?: string, allowlist: string[], denyFlags?: string[], env?: Record<string, string> }, onLine: (stream: "stdout" | "stderr", line: string) => void, onClose?: (result: { code: number } | { error: string }) => void) => { close(): void }un processus qui dure, SANS shell, mêmes gardes que exec : ses lignes arrivent au fil de l’eau, close() l’arrête (un docker logs -f) ; aucun délai, c’est à celui qui lance de fermer
ctx.net.requestnet(url: string, options?: { method?, headers?, body? }) => Promise<{ status, statusText, headers, body }>HTTP(S) sortant, agent TLS du plugin (<NAME>_CA_CERT / <NAME>_INSECURE_TLS), délai 30 s
ctx.repos.listrepos() => Repo[]les dépôts suivis sur ce poste
ctx.repos.byIdrepos(id: number) => Repo | nullun dépôt
ctx.repos.localRootsrepos() => { id: number, path: string, label: string }[]les répertoires locaux déclarés dans Réglages → Dépôts (là où l’on cherche des projets, des fichiers compose…)
ctx.repos.onRemovedrepos(handler: (repo: { id: number, project: string }) => void) => () => voidappelé quand un dépôt est retiré (remplace une FK ON DELETE CASCADE)
ctx.jobs.registerjobs(kind: string, runner: (job: JobHandle, payload: unknown) => void | Promise<void>) => voidinscrit un genre de job ; runner reçoit un job (log(line), message(text), progress(done, total), exec(bin, args, options) → { code, tail }, dont la sortie va au journal et que « Stop » arrête, isCancelled()) ; une exception met le job en erreur
ctx.jobs.startjobs(kind: string, payload?: unknown, options?: { label?: string, repoIds?: number[], dirs?: string[] }) => { id: number, status: string }met un job du plugin dans la file du cœur (voie séquentielle ; repoIds et dirs DÉCLARENT les dépôts et dossiers qu’il va toucher — il est alors sérialisé avec les reviews, sessions et vérifications du même clone ; sans déclaration il ne touche aucun clone et tourne avec tout) ; le journal, le « Stop » et l’écran des jobs sont ceux du cœur
ctx.ui.registerTabui.tab(tab: TabSpec) => voidun onglet dans la barre (icône, position, replié d’office, recherche, raccourci, onboarding)
ctx.ui.registerSettingsTabui.tab(tab: SettingsTabSpec) => voidun sous-onglet de Réglages : formulaire généré du schéma + rendu libre
ctx.ui.setBadgeui.tab(tabId: string, value: { count?: number, failed?: number, warn?: number } | number | null) => voidles pastilles de l’onglet (côté serveur : poussé au navigateur au prochain état)
ctx.ui.registerActionui.actions(action: { id: string, target: Target, label: string }) => voidune action sur un objet du cœur ; le rendu et le clic sont écrits côté navigateur (mergerie.ui.onAction)
ctx.ui.registerDecoratorui.actions(decorator: { id: string, target: Target }) => voidune décoration (badge, texte) sur un objet du cœur, rendue côté navigateur
ctx.ui.registerBriefSectionui.actions(section: { id: string, label: string }) => voidune section du brief « Aujourd’hui », rendue côté navigateur
ctx.ui.registerLinkKindui.actions(kind: { kind: string, label: string }) => voidun genre de lien de todo (ouvert côté navigateur)
ctx.ui.registerPaletteProviderui.palette(provider: (query: string, limit: number) => PaletteEntry[]) => voiddes entrées de la palette Ctrl+K, calculées sans réseau
ctx.notify.registerKindnotify(kind: { type: string, label: string, default: boolean }) => voidun genre de notification, avec sa case dans Réglages → Notifications
ctx.notify.pushnotify(type: string, data: object) => voidun fait, que le navigateur affiche selon les préférences
ctx.demo.isDemodemo() => booleanMERGERIE_DEMO=1 ?
ctx.demo.seeddemo(fn: (ctx) => void) => voidce que le plugin sème dans une base de démo
ctx.dataDirstoragestringle dossier privé du plugin (<dataDir>/plugin-data/<name>/), créé à l’activation ; ni son code, ni celui d’un autre plugin — supprimé avec ses données à la désinstallation si on le demande
ctx.env.getenv(name: string) => string | undefinedune variable <NAME>_* de l’environnement du serveur
ctx.services.registerservices(name: string, fn: (payload) => unknown) => voidexpose un service nommé <plugin>.<nom>
ctx.services.callservices(name: string, payload?) => Promise<unknown>appelle un service du cœur ou d’un autre plugin
ctx.services.hasservices(name: string) => booleanle service existe-t-il ?

Cibles d’action et de décoration

target d'une action ou d'une décoration, et l'objet que le navigateur passe au rendu :

CibleOùObjet reçu par render(obj, ctx)
mrle menu « ⋯ » d'une carte de merge requestla merge request (id, iid, repo_id, source_branch, verification… (mr, mr-badge, session-target, session-target-badge, branch, branch-badge, verification, repo-sheet, repo-row, verify-launch, mr-detail, jira-ticket))
mr-badgeles badges d'une carte de merge requestidem
session-targetle formulaire de suivi d'un projet d'une session{ task, target }
session-target-badgeles badges d'un projet d'une session{ task, target }
branchune ligne de l'explorateur Git{ branch, repo_id }
branch-badgeles badges d'une ligne de l'explorateur Git{ branch, repo_id }
verificationla suite d'un verdict vert, dans le rapport de vérificationla merge request, ctx.verification
repo-sheetla fiche d'un dépôt dans Réglages → Dépôtsla fiche (id, project, verifiers…)

Erreurs

Chaque primitive lève (ou rejette) avec un message qui nomme le plugin et la règle enfreinte :

  • ctx.db.* : requête refusée : la table « x » n'appartient pas au plugin (préfixe attendu : plugin_<nom>_) — aussi pour sqlite_master, ATTACH, PRAGMA hors table_info/index_*/foreign_key_list ;
  • ctx.http.router.* : un plugin ne monte rien hors de /api/plugins/<nom>/ — un chemin doit être relatif et commencer par / ;
  • ctx.settings.set : réglage inconnu : x, x : nombre attendu, x : adresse http(s) attendue… (statut 400 quand l'écran l'appelle) ;
  • ctx.events.emit : non déclaré dans plugin.json (events.emits) ;
  • ctx.notify.push : genre non déclaré (notify.registerKind) ;
  • ctx.schedule : intervalle ≥ 1000 ms requis ;
  • ctx.exec : sous-commande « x » hors liste blanche, drapeau refusé : --exec ;
  • ctx.env.get : seules les variables <NOM>_* sont lisibles ;
  • ctx.ui.register* : id en kebab-case requis, target hors de …, déjà déclaré ;
  • un require qui mène dans src/ ou dans un autre plugin : require('…') refusé — un plugin n'importe rien de src/, il passe par le ctx.

Une erreur dans activate(ctx) met le plugin en erreur (le message est affiché dans Réglages → Plugins) et n'empêche pas Mergerie de démarrer. Un activate qui ne répond pas en 10 s est abandonné (et, pour un plugin tiers, son worker est tué).

Exemples

Chaque exemple est chargé par test/unit-plugins-docs.test.js sur un createTestContext() : s'il cesse de fonctionner, la CI le dit.