Mergerie
Contents

The ctx API reference

This page is generated from docs/plugins/en/API.md · Edit this page on GitLab

Generated from sdk/contract.js (API 1) by sdk/scripts/generer-docs-api.js — do not edit by hand. The examples cited are files under docs/plugins/examples/, run by the CI.

A plugin exports activate(ctx) and deactivate(). The ctx is the closed list of what it can do: it only carries the primitives covered by the permissions of its plugin.json, nothing else (it is frozen). A built-in plugin, a third-party plugin in its worker and a plugin under test (createTestContext) receive the same ctx, built by the same code (sdk/lib/contexte.js).

Always present, no permission needed: ctx.name, ctx.version, ctx.apiVersion, ctx.log, ctx.i18n.

Permissions

Declared in plugin.json → permissions. Settings → Plugins shows them before activation; exec triggers an explicit warning for a third-party plugin.

PermissionWhat it opens
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

PrimitivePermissionSignatureRole
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 ?

Action and decoration targets

The target of an action or a decoration, and the object the browser passes to the render:

TargetWhereObject received by render(obj, ctx)
mrthe "⋯" menu of a merge request cardthe 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-badgethe badges of a merge request cardsame
session-targetthe follow-up form of a session's project{ task, target }
session-target-badgethe badges of a session's project{ task, target }
brancha row of the Git explorer{ branch, repo_id }
branch-badgethe badges of a Git explorer row{ branch, repo_id }
verificationwhat follows a green verdict, in the verification reportthe merge request, ctx.verification
repo-sheeta repository's sheet in Settings → Repositoriesthe sheet (id, project, verifiers…)

Errors

Every primitive throws (or rejects) with a message naming the plugin and the rule it broke:

  • ctx.db.*: requête refusée : la table « x » n'appartient pas au plugin (préfixe attendu : plugin_<name>_) — also for sqlite_master, ATTACH, any PRAGMA other than table_info/index_*/foreign_key_list;
  • ctx.http.router.*: un plugin ne monte rien hors de /api/plugins/<name>/ — a path must be relative and start with /;
  • ctx.settings.set: réglage inconnu : x, x : nombre attendu, x : adresse http(s) attendue… (status 400 when called from the screen);
  • 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 <NAME>_* sont lisibles;
  • ctx.ui.register*: id en kebab-case requis, target hors de …, déjà déclaré;
  • a require that leads into src/ or into another plugin: require('…') refusé — un plugin n'importe rien de src/, il passe par le ctx.

An error in activate(ctx) puts the plugin in error (the message shows in Settings → Plugins) and does not stop Mergerie from starting. An activate that does not answer within 10 s is abandoned (and, for a third-party plugin, its worker is killed).

Examples

Every example is loaded by test/unit-plugins-docs.test.js on a createTestContext(): if it stops working, the CI says so.